Borland Programmer's Resource/Borland_Programmers_Resource_CD_1995.iso/ntcode/ntperlb/nt/registry.txt

Text File | 1995-05-19 | 10.5 KB | 307 lines

-----------------------------------------------------------------------------
Registry.txt
-----------------------------------------------------------------------------

This file documents the extentions to Perl for NT that allow perl
scripts access to the NT registry database. All Registry API's have
been duplicated as user defined perl subroutines, with the exception
of RegNotifyChangeKeyValue. This routine was not implemented due to
time constraints and due to it's usefulness in perl scripts not being
immediately apparent. It may be implemented in the future.

IMPORTANT NOTE: It is possible to make your system unbootable by
corrupting the registry database! Use EXTREME caution when writing a
perl script that updates the registry! Also note that none of the
routines that actually modify the files that comprise the registry
have been tested. Only the routines that read or write keys/values in
the existing registry have been tested.

The Perl registry access subroutines nearly duplicate the Win32 API
for registry calls.  Although they are not perl-like, it was felt that
the perl calls should look as nearly like the documentation provided
with NT as possible. Hopefully this will minimize confusion when using
them.

The main difference between the C registry routines and the perl
versions of them is that whenever a size option is specified as an
argument to a C routine, that parameter is omitted from the perl
version, since perl already knows how big a scalar is and will
dynamically size a parameter used to return a value. If a registry
access routine is called incorrectly in a perl script, it will print a
usage message and the perl script will abort.

Note that all arguments to the perl registry routines are SCALARS.
Passing in arrays to the enumeration functions would be convienent, so
that it would not be nessesary to iterate when enumerating keys or
values, but again, time constraints interferred. This feature may be
implemented in a later release.

Some routines are documented in the Win32 API help file as having been
provided only for Windows 3.1 compatiblity. These routines include
RegCreateKey, RegOpenKey, RegEnumKey, RegQueryValue, and RegSetValue.
All of these routines have new versions with "Ex" appended to their
names which are the preferred version for use in new applications. In
implementing these routines in the Perl interpreter, all calls were
made to the new and improved versions of these routines so that
compatibility problems will be avoided when Microsoft upgrades
software. So, a perl script making the call:

    &RegOpenKey($HKEY_LOCAL_MACHINE, "SOFTWARE\\Intergraph", $h);

actually boils down to a call to RegOpenKeyEx with appropriate
defaults in the perl interpreter.

For more information on the contents of the registry and on accessing
the registry, see the help file for the registry editor (RegEdit), the
API documentation in the Win32 API help file, and the Microsoft
Windows NT Resource Guide (Preliminary March 1993).

   Conventions:

        $hkey: refers to a key handle value. Either one of the
               predefined variables or a value returned from
               RegOpenKey[Ex] or RegCreateKey[Ex].

        $newhkey: the parameter where a new handle will be returned.

        $subkey: a string used as a subkey of the specified key
                 handle.

        $sam: a security access mask (on of the $KEY_* variables).

        $valname: a scalar that either specifies a value name or
                  receives a value name.

        $index: a unsigned integer used when enumerating subkeys or
                values of a key.

        $reserved: a parameter that Microsoft has reserved for future
                   use. Should be zero, but in fact is ignored.

    All of the Registry access routines return a success or failure
    status with the actual return value from the routine in $!. This
    allows you to write code such as this:

        $keystring = "SOFTWARE\\Description\\Intergraph\\Perl";
        &RegCreateKey($HKEY_LOCAL_MACHINE, $keystring, $newhkey) ||
                die "Can't open $keystring: $!\n";

    If the call to RegCreateKeyEx fails then it's error code is
    stored in $!. The failure status causes the die routine to be
    called which prints the string corresponding to the error number
    and then terminates the perl process.



Variables:

All of the variables needed for accessing the NT registry are now
defined in the file registry.pl, in the perl library directory. To
access these values, put a require statment in your perl script, i.e.:

    require "registry.pl";


 Pre-defined key handles

    $HKEY_CLASSES_ROOT
    $HKEY_CURRENT_USER
    $HKEY_LOCAL_MACHINE
    $HKEY_USERS

 Security Access Mask values

    $KEY_ALL_ACCESS
    $KEY_CREATE_SUB_KEY
    $KEY_ENUMERATE_SUB_KEYS
    $KEY_EXECUTE
    $KEY_NOTIFY
    $KEY_QUERY_VALUE
    $KEY_READ
    $KEY_SET_VALUE
    $KEY_WRITE

 Data types from the registry

    $REG_BINARY  - binary data
    $REG_DWORD - 32 bit value
    $REG_DWORD_LITTLE_ENDIAN - 32 bit value in little endian byte order
    $REG_DWORD_BIG_ENDIAN - 32 bit value in big endian (network) byte order
    $REG_EXPAND_SZ - null terminated string with environment variables
    $REG_LINK - symbolic link within registry
    $REG_MULTI_SZ - multiple null terminated strings
    $REG_NONE - no type associated with this value
    $REG_RESOURCE_LIST - device resource list
    $REG_SZ - null terminated string

 Open/Create Options

    $REG_OPTION_RESERVED
    $REG_OPTION_NON_VOLATILE
    $REG_OPTION_VOLATILE
    $REG_OPTION_CREATE_LINK

 Key creation/open disposition

    $REG_CREATED_NEW_KEY
    $REG_OPENED_EXISTING_KEY

 Key restore flags

    $REG_WHOLE_HIVE_VOLATILE
    $REG_REFRESH_HIVE


Subroutines:

The following routines have been tested:

&RegCloseKey ($hkey)
    $hkey - an open key handle from a call to RegCreateKey,
            RegCreateKeyEx, RegOpenKey, or RegOpenKeyEx.

&RegCreateKey ($hkey, $subkey, $newhkey)
    $hkey - open key handle.
    $subkey - string value specifying subkey of currently open key.
    $newhkey - new handle.

&RegCreateKeyEx ($hkey, $subkey, $reserved, $class, $options, $sam,
                 $SecAttrib, $newhkey, $disposition)
    $hkey - open key handle.
    $subkey - string identifying the subkey to create/open
    $reserved - ignored
    $class - class name for new key
    $options - indicates if new key is volatile or not
    $sam - security access mask.
    $SecAttrib - security attributes structure (packed data)
    $newhkey - new handle.
    $disposition -

&RegDeleteKey ($hkey, $subkey)
    $hkey - open key handle
    $subkey - string identifying the subkey to delete

&RegDeleteValue ($hkey, $valname);
    $hkey - open key handle
    $valname - name of value to delete

&RegEnumKey ($hkey, $index, $subkey)
    $hkey - open key handle
    $index - numeric index of key to enumerate
    $subkey - returned key name

&RegEnumKeyEx ($hkey, $index, $subkey, $reserved, $class, $time)
    $hkey - open key handle
    $index - numeric index of key to enumerate
    $subkey - returned key name
    $reserved - must be zero
    $class - returned class name of $subkey
    $time - time of last modification of $subkey

&RegEnumValue ($hkey, $index, $valname, $reserved, $type, $data)
    $hkey - open key handle
    $index - numeric index of key to enumerate
    $valname - returned value name
    $reserved - must be zero
    $type - returned type of $valname
    $data - data associated with $valname (of data type $type)

&RegFlushKey ($hkey)
    $hkey - open key handle

&RegGeyKeySecurity ($hkey, $SecInf, $SecDesc)
    $hkey - open key handle
    $SecInf - Security information structure (packed)
    $SecDesc - returned Security Descriptor data (packed)

&RegLoadKey ($hkey, $subkey, $file)
    $hkey - open key handle
    $subkey - string identifying subkey of $key
    $file - string identifying filename to load information from

&RegOpenKey ($hkey, $subkey, $newhkey)
    $hkey - open key handle
    $subkey - string identifying subkey of $key
    $newhkey - returned key handle

&RegOpenKeyEx ($hkey, $subkey, $reserved, $sam, $newhkey)
    $hkey - open key handle
    $subkey - string identifying subkey of $key
    $reserved - must be zero
    $sam - requested security access mask
    $newhkey - returned key handle

&RegQueryInfoKey ($hkey, $class, $reserved, $nsubkeys, $maxsubkey,
                  $maxclass, $nvalues, $maxvalname, $maxvaldata,
                  $SecDesc, $time)
    $hkey - open key handle
    $class - returned key class (string)
    $reserved - must be zero
    $nsubkey - number of subkeys for this key
    $maxsubkey - size of largest subkey
    $maxclass - size of largest class name
    $nvalues - number of values associated with this key
    $maxvalname - size of largest value name
    $manvaldata - size of largest value data
    $SecDesc - Security Descriptor (packed data)
    $time - time of last write

&RegQueryValue ($hkey, $subkey, $value)
    $hkey - open key handle
    $subkey - string identifying the subkey of key to query
    $value - returned value for first NULL valname

&RegQueryValueEx ($hkey, $valname, $reserved, $type, $data)
    $hkey - open key handle
    $valname - string identifying value to retreive
    $reserved - must be zero
    $type - returned type of $data
    $data - returned data associated with $valname

&RegReplaceKey ($hkey, $subkey, $newfile, $oldfile)
    $hkey - open key handle
    $subkey - string identifying subkey of $key
    $newfile - file to put into registry
    $oldfile - name for old registry file

&RegRestoreKey ($hkey, $file, $flags)
    $hkey - open key handle
    $file - name of file to restore key from
    $flags - indicates if key data is volatile

&RegSaveKey ($hkey, $file, $SecAttrib)
    $hkey - open key handle
    $file - file in which to save key and subkeys.
    $SecAttrib - security attributes for new file (packed data)

&RegSetKeySecurity ($hkey, $SecInf, $SecDesc);
    $hkey - open key handle
    $SecInf - Security Information structure (packed data)
    $SecDesc - Security Descriptor structure (packed data)

&RegSetValue ($hkey, $subkey, $type, $data)
    $hkey - open key handle
    $subkey - string indentifying subkey
    $type - data type of $data
    $data - data to associate with $subkey (NULL name)

&RegSetValueEx ($hkey, $valname, $reserved, $type, $data)
    $hkey - open key handle
    $valname - name of value to set
    $reserved - must be zero
    $type - data type of $data
    $data - data to associate with valname

The following routine have NOT been tested:

&RegConnectRegistry ($machine, $hkey, $newhkey)
    $machine - name of an NT system.
    $hkey - one of $HKEY_LOCAL_MACHINE or $HKEY_USERS.
    $newkey - new handle for access on remote machine.

&RegUnLoadKey ($hkey, $subkey)
    $hkey - open key handle
    $subkey - string that identifies subkey tree to be unloaded