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-- As a special exception under Section 7 of GPL version 3, you are granted --
19-- additional permissions described in the GCC Runtime Library Exception,   --
20-- version 3.1, as published by the Free Software Foundation.               --
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
43package 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
150private
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
161end GNAT.Registry;
162