REGISTRY Object
Updated: Apr 13, 2005

One or more REGISTRY objects may be dimensioned.

  DIM Reg as REGISTRY

.RootKey from &H80000000 to &H80000007 selects a section of the Registry.

  $DEFINE HKEY_CLASSES_ROOT     &H80000000
  $DEFINE HKEY_CURRENT_USER     &H80000001
  $DEFINE HKEY_LOCAL_MACHINE    &H80000002
  $DEFINE HKEY_USERS            &H80000003
  $DEFINE HKEY_PERFORMANCE_DATA &H80000004
  $DEFINE HKEY_CURRENT_CONFIG   &H80000005
  $DEFINE HKEY_DYN_DATA         &H80000006

At this point, .OpenKey with a valid key$ (or key$=NULL) establishes a
.CurrentKey handle for key$ of .RootKey.  A key$ may have one or more subkeys
accessed with .KeyItem(index) and one or more .Name/.Type/.Value entries
accessed with .ValueItem(index).

In a rough analogy, one might think of the .RootKey as the "drive" and the
key$ as a "path" on a "drive".

Note that the possible index ranges for a particular key$ are most often
different, ranging from 0 to .KeyItemCount-1 and 0 to .ValueItemCount-1
respectively.

In our "directory tree" analogy, the foregoing is like saying a particular
"path" may or may not have subdirectories (.KeyItemCount) and also may or may
not contain files (.ValueItemCount).

Once a particular .KeyItem and .ValueItem is accessed, various properties of
this specific Registry item can be retrieved.

It is suggested that Registry keys be closed as soon as possible.  .CloseKey
can be used at any time without error.  If .CurrentKey <> 0, then the handle
is closed.  Always, the REGISTRY object properties are cleared to avoid
confusion regarding the key$ to which they pertain.

Robust programs should always check values such as .Error and .CurrentKey 
before proceeding or assuming a procedure was successful.  The key$ argument
does not include the root key strings in the $DEFINE statements above and
is usually terminated with a "\".


PROPERTIES (Read/Write):
~~~~~~~~~~ ~~~~~~~~~~~~~
RootKey    Set/Get DWORD value.  Default=&H80000001


PROPERTIES (Read Only String):
~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~
Binary     Value of last accessed KeyItem and ValueItem
           Return String$ can hold binary data (same as .Value)

Class      Class of open key.  KeyClass$ = MyReg.Class

CurrentPath
           Path of open key (same as .Path)

Date       Local date of open key

KeyItem    (index) Subkey index of open key

Name       Name of current key data item

Path       Path of open key; same as .CurrentPath

ReadString (key$) Value of first data item in key$.

           PRINT Reg.ReadString("Environment")

Time       Local time of open key

Value      Value of last accessed .KeyItem and .ValueItem

ValueItem  (index) Value index of last accessed .KeyItem


PROPERTIES (Read Only Numeric):
~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~
CurrentKey Handle of open key (dword)

Error      Error (1) in last method call

Dword      Value of last .KeyItem/.ValueItem as DWORD

GetDataSize
           Length of .ValueItem data in .Binary or .Value

GetDataType
           Data type of last .KeyItem/.ValueItem; same as .Type

HasSubKeys Reports number of subkeys; same as .KeyItemCount

Index      Index of last .KeyItem

KeyExists  (key$) Returns non-zero if subkey exists

KeyItemCount
           Number of subkeys in .CurrentKey; same as .HasSubKeys

ReadBinary (key$,index) Returns data byte index

ReadFloat  (key$) Returns floating numeric data as floating value

ReadInteger
           (key$) Returns INTEGER/LONG value

RegistryConnect
           (computer$) Connects to remote registry

Type       Data type of last .KeyItem/.ValueItem; same as .GetDataType
                   Type = 1,2,other (text); 3,8,9,10 (binary string);
                   4,5 (DWORD)  [as used in hotreg.bas]
ValueExists
           (v$) Returns non-zero if value v$ exists in .CurrentKey

ValueItemCount
           Number of values (.Name/.Type/.Value) of .CurrentKey


METHODS    Arguments & Comments
~~~~~~~    ~~~~~~~~~~~~~~~~~~~~
CloseKey   Closes any currently open key and clears REGISTRY object buffers

           Reg.CloseKey

CreateKey +
           (key$) Creates new key path

           After .CreateKey, .Index indicates whether the key already existed
           (1) or was created (2).

DeleteKey  (key$) Deletes key path

DeleteValue
           (name$) Deletes .Name/.Type/.Value item in open key

OpenKey    (key$,mode) where mode = 0 (Read Only) or 1 (Create/Write +)

           Reg.OpenKey("Environment",0)

WriteBinary +
           (key$,v$) where v$ = text or binary data for new key value

WriteFloat +
           (key$,x) where x = SINGLE, DOUBLE or REAL10 value stored as DOUBLE

WriteInteger +
           (key$,x) where x = non-floating 4-byte binary value

           Reg.WriteInteger("HotBabe",10)

WriteString +
           (key$,v$) where v$ = text or binary data for new key value

           Reg.OpenKey("SOFTWARE\HotBasic\",1)  
           Reg.WriteString("HotBabe","Rated 10")
           PRINT Reg.ReadString("Software\HotBasic")


Note: In HotBasic, strings, like arrays and memory streams, are "low level"
objects which may contain binary data.  For example, a string may contain null
bytes and its length property will still report the correct length of the data
it contains.  In brief, the functions correctly return text-only or binary data
as might be used in particular registry keys.  Thus, a "binary" value may be
assigned to a string variable, or if you are more comfortable, to an array or
memory stream.

This applies for string arguments or return values.


###########
HotReg and regwrite.bas in HotThing show REGISTRY examples.


+ PentHouse (registered) version

Copyright 2003-2005 James J Keene PhD
Original Publication: Sep 28, 2003
