A.3.6.2 Registry Commands

The GUI INF script language provides a set of built-in commands for manipulating the configuration registry. These commands can be used in the shell or install sections of an INF script. For additional information about the registry, refer to the Windows NT Software Development Kit.

The commands that manipulate the registry create an error variable, RegLastError, whose value is set to zero if the operation succeeds, or to a nonzero error code if it fails.

CreateRegKey Command

The CreateRegKey command creates and returns a handle to a new key in the registry under the specified key. If the key already exists, NewHandle contains an empty string, and RegLastError is set to a nonzero value. The syntax is:

CreateRegKey KeyHandle {NewKey} Reserved Access Options NewHandle

KeyHandle
Open handle to the registry key in which the new key is created. The handle must have KEY_WRITE or KEY_CREATE_SUB_KEY access.
NewKey
A list containing: {NewKeyName,Index,Class}
NewKeyName
Name of the new key
Index
Reserved item that should equal zero
Class
Class of the new key
Access
A decimal string specifying the mask that determines the access of NewHandle to the new key. For a list of predefined access constants, see the table at the end of this section.
Options
If “1”, the new key is volatile, and is not preserved when the system is restarted. If “0” or ““, the key is nonvolatile and will be preserved in the registry hives.
NewHandle
Receives an open handle to the new key.

The following example creates an “XYZ” key under the registry key identified by the SoftwareKey variable. If successful, NewHandle has KEY_SET_VALUE access to the new key. 

CreateRegKey $(SoftwareKey) {"XYZ",0,GenericClass} "" +
              $(!REG_KEY_SET_VALUE) "" NewHandle
 
OpenRegKey Command

The OpenRegKey command returns an open handle to a specified registry key. If the key does not exist, NewHandle contains an empty string, and the RegLastError variable is set to a nonzero value. The syntax of the command is:

OpenRegKey KeyHandle Reserved KeyName Access NewHandle

KeyHandle
Open handle to the registry key in which the preferred key is located.
Reserved
Reserved; must be an empty string, ““.
KeyName
Name of the key to open.
Access
A decimal string specifying the mask that determines the access of NewHandle to the new key. Refer to the table of predefined constants.
NewHandle
Receives an open handle to the new key.

For example: 

OpenRegKey $(SoftwareKey) "" "XYZ" $(!REG_KEY_SET_VALUE) NewHandle
 
FlushRegKey Command

The FlushRegKey command writes all attributes of the specified key to the registry hives. The syntax of the command is:

FlushRegKey KeyHandle

KeyHandle
Open handle to the registry key to flush.
CloseRegKey Command

The CloseRegKey command releases the handle of the specified key. Closing a key does not necessarily cause data to be immediately written to the registry hives. The syntax of the command is:

CloseRegKey KeyHandle

KeyHandle
Open handle to the registry key.
DeleteRegKey Command

The DeleteRegKey command deletes a subkey from a key in the registry. The subkey can have values under it, but cannot have any subkeys. The syntax of the command is:

DeleteRegKey KeyHandle SubKeyName

KeyHandle
Open handle to the registry key in which the key to be deleted is located.
SubKeyName
Name of the key to be deleted.
DeleteRegTree Command

The DeleteRegTree command deletes a key and all of its subkeys from a key in the registry. The syntax of the command is:

DeleteRegTree KeyHandle SubKeyName

KeyHandle
Open handle to the registry key in which the key to be deleted is located.
SubKeyName
Name of the key to be deleted.
EnumRegKey Command

The EnumRegKey command creates a list containing information about each subkey of the specified key. The syntax of the command is:

EnumRegKey KeyHandle KeyList

KeyHandle
Open handle to the registry key for which to enumerate keys. The handle must have KEY_READ or KEY_ENUMERATE_SUB_KEYS access.
KeyList
Receives a list containing information about each subkey. The list for each subkey is another list containing the following items: {KeyName,TitleIndex,Class}.
SetRegValue Command

The SetRegValue command stores a name/value pair in the registry under the specified key. If a value with the specified name already exists, the new value replaces the old value. The syntax of the command is:

SetRegValue KeyHandle NewValueList

KeyHandle
Open handle to the registry key in which the name/value pair is to be stored. The handle must have KEY_SET_VALUE access.
NewValueList
A list containing the following items: {ValueName,Index,ValueType,ValueData)
ValueName
Name of the new value
Index
Reserved item that should equal zero
ValueType
Type of data in ValueData. For a list of pre-defined constants for the standard registry data types, refer to the table at the end of this section.
ValueData
The data to be stored.
GetRegValue Command

The GetRegValue command retrieves the value associated with a specified value name under a specified key. The syntax of the command is:

GetRegValue KeyHandle ValueName ValueData

KeyHandle
Open handle to the registry key in which the name/value pair is stored. The handle must have KEY_QUERY_VALUE access.
ValueName
Name that identifies the required value.
ValueData
Receives a list containing the registry data associated with ValueName. The list contains the following items, which are described for the SetRegValue command: {ValueName,Index,ValueType,ValueData}
DeleteRegValue Command

The DeleteRegValue command deletes the name/value pair with a specified value name under a specified key. The syntax of the command is:

DeleteRegValue KeyHandle ValueName

KeyHandle
Open handle to the registry key in which the name/value pair is stored. The handle must have KEY_SET_VALUE access.
ValueName
Name that identifies the name/value pair to delete.
EnumRegValue Command

The EnumRegValue command creates a list containing information about each name/value pair of the specified key. The syntax of the command is:

EnumRegValue KeyHandle ValueList

KeyHandle
Open handle to the registry key in which the name/value pair is stored. The handle must have KEY_QUERY_VALUE access.
ValueList
A list containing an entry for each name/value pair in the key. The entry for each pair is a list containing the following information: {ValueName,Index,ValueType,ValueData}
ValueName
Name of the value
Index
Reserved item that should equal zero
ValueType
Type of data in ValueData. For a list of predefined constants for the standard registry data types, refer to the table at the end of this section.
ValueData
The stored data.
Global Registry Constants

The Windows NT Setup program defines a number of global variables that are useful when calling the registry functions. The values assigned to these variables are the constants that can be specified in the various registry operations. For example, these global keys include a set of constants to specify the required access when opening a registry key using the OpenRegKey and CreateRegKey commands (such as REG_KEY_READ whose value is KEY_READ, a constant defined in winnt.h). You would use the $(!GlobalKey) notation (for example, $(!REG_KEY_READ) ) to use one of these predefined keys. The following is a list of these global keys and their values:

Predefined registry handles

These variables can be used in any of the registry commands that require an open handle to a registry key. 

"REG_H_LOCAL",                   HKEY_LOCAL_MACHINE
"REG_H_CLASSES",                 HKEY_CLASSES_ROOT
"REG_H_USERS",                   HKEY_USERS
"REG_H_CUSER",                   HKEY_CURRENT_USER
 
Registry key creation options
"REG_OPT_VOLATILE",              REG_OPTION_VOLATILE
"REG_OPT_NONVOL",                REG_OPTION_NON_VOLATILE
 
Registry value types
"REG_VT_NONE",                   REG_NONE
"REG_VT_BIN",                    REG_BINARY
"REG_VT_SZ",                     REG_SZ
"REG_VT_EXPAND_SZ",              REG_EXPAND_SZ
"REG_VT_MULTI_SZ",               REG_MULTI_SZ
"REG_VT_DWORD",                  REG_DWORD
 
Registry key access mask bit
"REG_KEY_QUERY_VALUE",           KEY_QUERY_VALUE
"REG_KEY_SET_VALUE",             KEY_SET_VALUE
"REG_KEY_CREATE_SUB_KEY",        KEY_CREATE_SUB_KEY
"REG_KEY_ENUMERATE_SUB_KEYS",    KEY_ENUMERATE_SUB_KEYS
"REG_KEY_NOTIFY",                KEY_NOTIFY
"REG_KEY_READ",                  KEY_READ
"REG_KEY_WRITE",                 KEY_WRITE
"REG_KEY_READWRITE",             KEY_READ | KEY_WRITE
"REG_KEY_EXECUTE",               KEY_EXECUTE
"REG_KEY_ALL_ACCESS",            KEY_ALL_ACCESS
 
Registry errors
"REG_ERROR_SUCCESS",             0L
 

The following global keys are used when creating a Services entry in the registry.

Service Types (Bit Mask)
"SERVICE_KERNEL_DRIVER",        SERVICE_KERNEL_DRIVER
"SERVICE_FILE_SYSTEM_DRIVER",   SERVICE_FILE_SYSTEM_DRIVER
"SERVICE_ADAPTER",              SERVICE_ADAPTER
"SERVICE_WIN32_OWN_PROCESS",    SERVICE_WIN32_OWN_PROCESS
"SERVICE_WIN32_SHARE_PROCESS",  SERVICE_WIN32_SHARE_PROCESS
 
Service Start Type
"SERVICE_BOOT_START",            SERVICE_BOOT_START
"SERVICE_SYSTEM_START",          SERVICE_SYSTEM_START
"SERVICE_AUTO_START",            SERVICE_AUTO_START
"SERVICE_DEMAND_START",          SERVICE_DEMAND_START
"SERVICE_DISABLED",              SERVICE_DISABLED
 
Error control type
"SERVICE_ERROR_IGNORE",          SERVICE_ERROR_IGNORE
"SERVICE_ERROR_NORMAL",          SERVICE_ERROR_NORMAL
"SERVICE_ERROR_SEVERE",          SERVICE_ERROR_SEVERE
"SERVICE_ERROR_CRITICAL",        SERVICE_ERROR_CRITICAL