File : g-regist.ads
1 ------------------------------------------------------------------------------
2 -- --
3 -- GNAT COMPILER COMPONENTS --
4 -- --
5 -- G N A T . R E G I S T R Y --
6 -- --
7 -- S p e c --
8 -- --
9 -- Copyright (C) 2001-2014, Free Software Foundation, Inc. --
10 -- --
11 -- GNAT is free software; you can redistribute it and/or modify it under --
12 -- terms of the GNU General Public License as published by the Free Soft- --
13 -- ware Foundation; either version 3, or (at your option) any later ver- --
14 -- sion. GNAT is distributed in the hope that it will be useful, but WITH- --
15 -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
16 -- or FITNESS FOR A PARTICULAR PURPOSE. --
17 -- --
18 -- --
19 -- --
20 -- --
21 -- --
22 -- You should have received a copy of the GNU General Public License and --
23 -- a copy of the GCC Runtime Library Exception along with this program; --
24 -- see the files COPYING3 and COPYING.RUNTIME respectively. If not, see --
25 -- <http://www.gnu.org/licenses/>. --
26 -- --
27 -- Extensive contributions were provided by Ada Core Technologies Inc. --
28 -- --
29 ------------------------------------------------------------------------------
30
31 -- The registry is a Windows database to store key/value pair. It is used
32 -- to keep Windows operation system and applications configuration options.
33 -- The database is a hierarchal set of key and for each key a value can
34 -- be associated. This package provides high level routines to deal with
35 -- the Windows registry. For full registry API, but at a lower level of
36 -- abstraction, refer to the Win32.Winreg package provided with the
37 -- Win32Ada binding. For example this binding handle only key values of
38 -- type Standard.String.
39
40 -- This package is specific to the NT version of GNAT, and is not available
41 -- on any other platforms.
42
43 package GNAT.Registry is
44
45 type HKEY is private;
46 -- HKEY is a handle to a registry key, including standard registry keys:
47 -- HKEY_CLASSES_ROOT, HKEY_CURRENT_CONFIG, HKEY_CURRENT_USER,
48 -- HKEY_LOCAL_MACHINE, HKEY_USERS, HKEY_PERFORMANCE_DATA.
49
50 HKEY_CLASSES_ROOT : constant HKEY;
51 HKEY_CURRENT_USER : constant HKEY;
52 HKEY_CURRENT_CONFIG : constant HKEY;
53 HKEY_LOCAL_MACHINE : constant HKEY;
54 HKEY_USERS : constant HKEY;
55 HKEY_PERFORMANCE_DATA : constant HKEY;
56
57 type Key_Mode is
58 (Read_Only, Read_Write, -- operates on 32bit view of the registry
59 Read_Only_64, Read_Write_64); -- operates on 64bit view of the registry
60 -- Access mode for the registry key. The *_64 are only meaningful on
61 -- Windows 64bit and ignored on Windows 32bit where _64 are equivalent to
62 -- the non 64bit versions.
63
64 Registry_Error : exception;
65 -- Registry_Error is raises by all routines below if a problem occurs
66 -- (key cannot be opened, key cannot be found etc).
67
68 function Create_Key
69 (From_Key : HKEY;
70 Sub_Key : String;
71 Mode : Key_Mode := Read_Write) return HKEY;
72 -- Open or create a key (named Sub_Key) in the Windows registry database.
73 -- The key will be created under key From_Key. It returns the key handle.
74 -- From_Key must be a valid handle to an already opened key or one of
75 -- the standard keys identified by HKEY declarations above.
76
77 function Open_Key
78 (From_Key : HKEY;
79 Sub_Key : String;
80 Mode : Key_Mode := Read_Only) return HKEY;
81 -- Return a registry key handle for key named Sub_Key opened under key
82 -- From_Key. It is possible to open a key at any level in the registry
83 -- tree in a single call to Open_Key.
84
85 procedure Close_Key (Key : HKEY);
86 -- Close registry key handle. All resources used by Key are released
87
88 function Key_Exists (From_Key : HKEY; Sub_Key : String) return Boolean;
89 -- Returns True if Sub_Key is defined under From_Key in the registry
90
91 function Query_Value
92 (From_Key : HKEY;
93 Sub_Key : String;
94 Expand : Boolean := False) return String;
95 -- Returns the registry key's value associated with Sub_Key in From_Key
96 -- registry key. If Expand is set to True and the Sub_Key is a
97 -- REG_EXPAND_SZ the returned value will have the %name% variables
98 -- replaced by the corresponding environment variable value.
99
100 procedure Set_Value
101 (From_Key : HKEY;
102 Sub_Key : String;
103 Value : String;
104 Expand : Boolean := False);
105 -- Add the pair (Sub_Key, Value) into From_Key registry key.
106 -- By default the value created is of type REG_SZ, unless
107 -- Expand is True in which case it is of type REG_EXPAND_SZ
108
109 procedure Delete_Key (From_Key : HKEY; Sub_Key : String);
110 -- Remove Sub_Key from the registry key From_Key
111
112 procedure Delete_Value (From_Key : HKEY; Sub_Key : String);
113 -- Remove the named value Sub_Key from the registry key From_Key
114
115 generic
116 with procedure Action
117 (Index : Positive;
118 Key : HKEY;
119 Key_Name : String;
120 Quit : in out Boolean);
121 procedure For_Every_Key (From_Key : HKEY; Recursive : Boolean := False);
122 -- Iterates over all the keys registered under From_Key, recursively if
123 -- Recursive is set to True. Index will be set to 1 for the first key and
124 -- will be incremented by one in each iteration. The current key of an
125 -- iteration is set in Key, and its name - in Key_Name. Quit can be set
126 -- to True to stop iteration; its initial value is False.
127
128 generic
129 with procedure Action
130 (Index : Positive;
131 Sub_Key : String;
132 Value : String;
133 Quit : in out Boolean);
134 procedure For_Every_Key_Value (From_Key : HKEY; Expand : Boolean := False);
135 -- Iterates over all the pairs (Sub_Key, Value) registered under
136 -- From_Key. Index will be set to 1 for the first key and will be
137 -- incremented by one in each iteration. Quit can be set to True to
138 -- stop iteration; its initial value is False.
139 --
140 -- Key value that are not of type string (i.e. not REG_SZ / REG_EXPAND_SZ)
141 -- are skipped. In this case, the iterator behaves exactly as if the key
142 -- were not present. Note that you must use the Win32.Winreg API to deal
143 -- with this case. Furthermore, if Expand is set to True and the Sub_Key
144 -- is a REG_EXPAND_SZ the returned value will have the %name% variables
145 -- replaced by the corresponding environment variable value.
146 --
147 -- This iterator can be used in conjunction with For_Every_Key in
148 -- order to analyze all subkeys and values of a given registry key.
149
150 private
151
152 type HKEY is mod 2 ** Standard'Address_Size;
153
154 HKEY_CLASSES_ROOT : constant HKEY := 16#80000000#;
155 HKEY_CURRENT_USER : constant HKEY := 16#80000001#;
156 HKEY_LOCAL_MACHINE : constant HKEY := 16#80000002#;
157 HKEY_USERS : constant HKEY := 16#80000003#;
158 HKEY_PERFORMANCE_DATA : constant HKEY := 16#80000004#;
159 HKEY_CURRENT_CONFIG : constant HKEY := 16#80000005#;
160
161 end GNAT.Registry;