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