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 --                            $Revision: 1.5 $
  10 --                                                                          --
  11 --              Copyright (C) 2001 Free Software Foundation, Inc.           --
  12 --                                                                          --
  13 -- GNAT is free software;  you can  redistribute it  and/or modify it under --
  14 -- terms of the  GNU General Public License as published  by the Free Soft- --
  15 -- ware  Foundation;  either version 2,  or (at your option) any later ver- --
  16 -- sion.  GNAT is distributed in the hope that it will be useful, but WITH- --
  17 -- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --
  18 -- or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License --
  19 -- for  more details.  You should have  received  a copy of the GNU General --
  20 -- Public License  distributed with GNAT;  see file COPYING.  If not, write --
  21 -- to  the Free Software Foundation,  59 Temple Place - Suite 330,  Boston, --
  22 -- MA 02111-1307, USA.                                                      --
  23 --                                                                          --
  24 -- As a special exception,  if other files  instantiate  generics from this --
  25 -- unit, or you link  this unit with other files  to produce an executable, --
  26 -- this  unit  does not  by itself cause  the resulting  executable  to  be --
  27 -- covered  by the  GNU  General  Public  License.  This exception does not --
  28 -- however invalidate  any other reasons why  the executable file  might be --
  29 -- covered by the  GNU Public License.                                      --
  30 --                                                                          --
  31 -- GNAT is maintained by Ada Core Technologies Inc (http://www.gnat.com).   --
  32 --                                                                          --
  33 ------------------------------------------------------------------------------
  34
  35 --  The registry is a Windows database to store key/value pair. It is used
  36 --  to keep Windows operation system and applications configuration options.
  37 --  The database is a hierarchal set of key and for each key a value can
  38 --  be associated. This package provides high level routines to deal with
  39 --  the Windows registry. For full registry API, but at a lower level of
  40 --  abstraction, refer to the Win32.Winreg package provided with the
  41 --  Win32Ada binding. For example this binding handle only key values of
  42 --  type Standard.String.
  43
  44 --  This package is specific to the NT version of GNAT, and is not available
  45 --  on any other platforms.
  46
  47 package GNAT.Registry is
  48
  49    type HKEY is private;
  50    --  HKEY is a handle to a registry key, including standard registry keys:
  51    --  HKEY_CLASSES_ROOT, HKEY_CURRENT_CONFIG, HKEY_CURRENT_USER,
  52    --  HKEY_LOCAL_MACHINE, HKEY_USERS, HKEY_PERFORMANCE_DATA.
  53
  54    HKEY_CLASSES_ROOT     : constant HKEY;
  55    HKEY_CURRENT_USER     : constant HKEY;
  56    HKEY_CURRENT_CONFIG   : constant HKEY;
  57    HKEY_LOCAL_MACHINE    : constant HKEY;
  58    HKEY_USERS            : constant HKEY;
  59    HKEY_PERFORMANCE_DATA : constant HKEY;
  60
  61    type Key_Mode is (Read_Only, Read_Write);
  62    --  Access mode for the registry key.
  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)
  72       return     HKEY;
  73    --  Open or create a key (named Sub_Key) in the Windows registry database.
  74    --  The key will be created under key From_Key. It returns the key handle.
  75    --  From_Key must be a valid handle to an already opened key or one of
  76    --  the standard keys identified by HKEY declarations above.
  77
  78    function Open_Key
  79      (From_Key : HKEY;
  80       Sub_Key  : String;
  81       Mode     : Key_Mode := Read_Only)
  82       return     HKEY;
  83    --  Return a registry key handle for key named Sub_Key opened under key
  84    --  From_Key. It is possible to open a key at any level in the registry
  85    --  tree in a single call to Open_Key.
  86
  87    procedure Close_Key (Key : HKEY);
  88    --  Close registry key handle. All resources used by Key are released.
  89
  90    function Key_Exists (From_Key : HKEY; Sub_Key : String) return Boolean;
  91    --  Returns True if Sub_Key is defined under From_Key in the registry.
  92
  93    function Query_Value (From_Key : HKEY; Sub_Key : String) return String;
  94    --  Returns the registry key's value associated with Sub_Key in From_Key
  95    --  registry key.
  96
  97    procedure Set_Value (From_Key : HKEY; Sub_Key : String; Value : String);
  98    --  Add the pair (Sub_Key, Value) into From_Key registry key.
  99
 100    procedure Delete_Key (From_Key : HKEY; Sub_Key : String);
 101    --  Remove Sub_Key from the registry key From_Key.
 102
 103    procedure Delete_Value (From_Key : HKEY; Sub_Key : String);
 104    --  Remove the named value Sub_Key from the registry key From_Key.
 105
 106    generic
 107       with procedure Action
 108         (Index   : Positive;
 109          Sub_Key : String;
 110          Value   : String;
 111          Quit    : in out Boolean);
 112    procedure For_Every_Key_Value (From_Key : HKEY);
 113    --  Iterates over all the pairs (Sub_Key, Value) registered under
 114    --  From_Key. Index will be set to 1 for the first key and will be
 115    --  incremented by one in each iteration. Quit can be set to True to
 116    --  stop iteration; its initial value is False.
 117    --
 118    --  Key value that are not of type string are skipped. In this case, the
 119    --  iterator behaves exactly as if the key was not present. Note that you
 120    --  must use the Win32.Winreg API to deal with this case.
 121
 122 private
 123
 124    type HKEY is mod 2 ** Integer'Size;
 125
 126    HKEY_CLASSES_ROOT     : constant HKEY := 16#80000000#;
 127    HKEY_CURRENT_USER     : constant HKEY := 16#80000001#;
 128    HKEY_LOCAL_MACHINE    : constant HKEY := 16#80000002#;
 129    HKEY_USERS            : constant HKEY := 16#80000003#;
 130    HKEY_PERFORMANCE_DATA : constant HKEY := 16#80000004#;
 131    HKEY_CURRENT_CONFIG   : constant HKEY := 16#80000005#;
 132
 133 end GNAT.Registry;