gcc/ada/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-2009, 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
  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 (Read_Only, Read_Write);
  58    --  Access mode for the registry key
  59
  60    Registry_Error : exception;
  61    --  Registry_Error is raises by all routines below if a problem occurs
  62    --  (key cannot be opened, key cannot be found etc).
  63
  64    function Create_Key
  65      (From_Key : HKEY;
  66       Sub_Key  : String;
  67       Mode     : Key_Mode := Read_Write) return HKEY;
  68    --  Open or create a key (named Sub_Key) in the Windows registry database.
  69    --  The key will be created under key From_Key. It returns the key handle.
  70    --  From_Key must be a valid handle to an already opened key or one of
  71    --  the standard keys identified by HKEY declarations above.
  72
  73    function Open_Key
  74      (From_Key : HKEY;
  75       Sub_Key  : String;
  76       Mode     : Key_Mode := Read_Only) return HKEY;
  77    --  Return a registry key handle for key named Sub_Key opened under key
  78    --  From_Key. It is possible to open a key at any level in the registry
  79    --  tree in a single call to Open_Key.
  80
  81    procedure Close_Key (Key : HKEY);
  82    --  Close registry key handle. All resources used by Key are released
  83
  84    function Key_Exists (From_Key : HKEY; Sub_Key : String) return Boolean;
  85    --  Returns True if Sub_Key is defined under From_Key in the registry
  86
  87    function Query_Value
  88      (From_Key : HKEY;
  89       Sub_Key  : String;
  90       Expand   : Boolean := False) return String;
  91    --  Returns the registry key's value associated with Sub_Key in From_Key
  92    --  registry key. If Expand is set to True and the Sub_Key is a
  93    --  REG_EXPAND_SZ the returned value will have the %name% variables
  94    --  replaced by the corresponding environment variable value.
  95
  96    procedure Set_Value
  97       (From_Key : HKEY;
  98        Sub_Key  : String;
  99        Value    : String;
 100        Expand   : Boolean := False);
 101    --  Add the pair (Sub_Key, Value) into From_Key registry key.
 102    --  By default the value created is of type REG_SZ, unless
 103    --  Expand is True in which case it is of type REG_EXPAND_SZ
 104
 105    procedure Delete_Key (From_Key : HKEY; Sub_Key : String);
 106    --  Remove Sub_Key from the registry key From_Key
 107
 108    procedure Delete_Value (From_Key : HKEY; Sub_Key : String);
 109    --  Remove the named value Sub_Key from the registry key From_Key
 110
 111    generic
 112       with procedure Action
 113         (Index    : Positive;
 114          Key      : HKEY;
 115          Key_Name : String;
 116          Quit     : in out Boolean);
 117    procedure For_Every_Key (From_Key : HKEY; Recursive : Boolean := False);
 118    --  Iterates over all the keys registered under From_Key, recursively if
 119    --  Recursive is set to True. Index will be set to 1 for the first key and
 120    --  will be incremented by one in each iteration. The current key of an
 121    --  iteration is set in Key, and its name - in Key_Name. Quit can be set
 122    --  to True to stop iteration; its initial value is False.
 123
 124    generic
 125       with procedure Action
 126         (Index   : Positive;
 127          Sub_Key : String;
 128          Value   : String;
 129          Quit    : in out Boolean);
 130    procedure For_Every_Key_Value (From_Key : HKEY; Expand : Boolean := False);
 131    --  Iterates over all the pairs (Sub_Key, Value) registered under
 132    --  From_Key. Index will be set to 1 for the first key and will be
 133    --  incremented by one in each iteration. Quit can be set to True to
 134    --  stop iteration; its initial value is False.
 135    --
 136    --  Key value that are not of type string (i.e. not REG_SZ / REG_EXPAND_SZ)
 137    --  are skipped. In this case, the iterator behaves exactly as if the key
 138    --  were not present. Note that you must use the Win32.Winreg API to deal
 139    --  with this case. Furthermore, if Expand is set to True and the Sub_Key
 140    --  is a REG_EXPAND_SZ the returned value will have the %name% variables
 141    --  replaced by the corresponding environment variable value.
 142    --
 143    --  This iterator can be used in conjunction with For_Every_Key in
 144    --  order to analyze all subkeys and values of a given registry key.
 145
 146 private
 147
 148    type HKEY is mod 2 ** Integer'Size;
 149
 150    HKEY_CLASSES_ROOT     : constant HKEY := 16#80000000#;
 151    HKEY_CURRENT_USER     : constant HKEY := 16#80000001#;
 152    HKEY_LOCAL_MACHINE    : constant HKEY := 16#80000002#;
 153    HKEY_USERS            : constant HKEY := 16#80000003#;
 154    HKEY_PERFORMANCE_DATA : constant HKEY := 16#80000004#;
 155    HKEY_CURRENT_CONFIG   : constant HKEY := 16#80000005#;
 156
 157 end GNAT.Registry;