Interaction With The Operating System > Registry Access >

# Registry Structure

The Registry struct provides methods to access the Windows OS' Registry Keys.

These methods are available in 3ds Max 2008 and higher.

They were previously available in the Avguard Extensions.

WARNING!
Messing with the Windows Registry can destabilize your operating system and should be performed only by professionals who know what they are doing!

    registry.closeKey <HKey>

Closes the open HKey. Returns true if successful, false if error. Use registry.getLastError() to get error message.

A HKey should not be used after it has been closed, because it will no longer be valid.

HKeys should not be left open any longer than necessary.

The closeKey method does not necessarily write information to the registry before returning; it can take as much as several seconds for the cache to be flushed to the hard disk.

If an application must explicitly write registry information to the hard disk, it can use registry.flushKey() .That method, however, uses many system resources and should be called only when necessary.

    registry.flushKey <HKey>

Writes all the attributes of the open HKey into the registry. Returns true if successful, false if error. Use registry.getLastError() to get error message.

It is not necessary to call registry.flushKey() method to change a key. Registry changes are flushed to disk by the registry using its lazy flusher. Lazy flushing occurs automatically and regularly after a system-specified interval of time. Registry changes are also flushed to disk at system shutdown. Unlike registry.closeKey() , registry.flushKey() returns only when all the data has been written to the registry . registry.flushKey() may also write out parts of or all of the other keys.

Calling this function excessively can have a negative effect on an application's performance. An application should only call registry.flushKe() if it requires absolute certainty that registry changes are on disk.

In general , registry.flushKey() rarely, if ever, need be used.

    registry.deleteSubKey <HKey> <string subKeyName> recurse:<bool>

Deletes the specified subkey of the open HKey. The entire key, including all of its values, is removed. Returns true if successful, false if error. Use registry.getLastError() to get error message.

If recurse is false or not specified, the subkey to be deleted must not have subkeys. If recurse is true, the subkey and all its descendants are deleted.

    registry.deleteKey <HKey> recurse:<bool>

Deletes the HKey. The parent HKey of the specified HKey must be open. The entire key, including all of its values, is removed. Returns true if successful, false if error. Use registry.getLastError() to get error message.

If recurse is false or not specified, the HKey to be deleted must not have subkeys. If recurse is true, the HKey and all its descendants are deleted.

    registry.createKey <HKey> <string subKeyName> accessRights:<{#readOnly|#writeOnly|#all| <int>}> newKeyCreated:<&bool>Key:<&HKey>volatile:<bool>

Creates a new HKey as a subkey of the specified open HKey. If the subkey already exists, the function opens it.

Returns true if successful, false if error. Use registry.getLastError() to get error message.

See "HKey Values" for a description of the <int> values for accessRights. The default accessRights is #all

If a new key is created, a true value will be written to the newKeyCreated: keyword variable.

If a new key is created or an existing key is opened, the HKey value will be written to the Key: keyword variable.

If volatile: is false or not specified, the key information will be written to the registry file. If true , the information is stored only in memory and is not preserved when the corresponding registry hive is unloaded.

EXAMPLE
    registry.createKey HKEY_CLASSES_ROOT ".123" accessRights:#all newKeyCreated:&newKeyCreated key:&key1

    registry.openKey <HKey> <string subKeyName> accessRights:<{#readOnly |#writeOnly|#all| <int>}> key:<&HKey>

Opens an existing HKey.

Returns true if successful, false if error. Use registry.getLastError() to get error message.

registry.openKey does not create the specified key if the key does not exist in the registry.

See "HKey Values" for a description of the <int> values for accessRights . The default accessRights is #readOnly

If a HKey is successfully opened, the HKey value will be written to the Key keyword variable.

EXAMPLE
    registry.openKey HKEY_CLASSES_ROOT ".123" accessRights:#all key:&key1

    registry.deleteValue <HKey> <string valueName>

Deletes the specified value of the open HKey.

Returns true if successful, false if error.

Use registry.getLastError() to get error message.

If valueName is an empty string (""), the default value on the HKey is deleted.

    registry.setValue <HKey> <string valueName> <name valueType> <value data>

Sets the data type and value of the specified value of the open HKey.

Returns true if successful, false if error.

Use registry.getLastError() to get error message.

If valueName is an empty string (""), the default value on the HKey is set.

The valid valueType values for setValue, and the corresponding MXS data type are:

#REG_DWORD - integer

#REG_SZ - string

#REG_EXPAND_SZ - string that contains unexpanded references to environment variables

#REG_MULTI_SZ - array of strings

EXAMPLE
    registry.setvalue key1 "" #multiSZ #("zz","ww")

    registry.queryValue <HKey> <string valueName> type:<&name> value:<&value> expand:<bool>

Gets the data type and value of the specified value of the open HKey.

Returns true if successful, false if error.

Use registry.getLastError() to get error message.

If the query is successful, the data type will be written to the type keyword variable.

If the query is successful and the data type is one of the following supported data types, the data value will be written to the value keyword variable.

#REG_DWORD -integer

#REG_SZ - string

#REG_EXPAND_SZ - string that contains unexpanded references to environment variables

#REG_MULTI_SZ- array of strings

If the data type is REG_EXPAND_SZ, and expand is true, the environment variables are expanded in the returned data value.

Other data types that may be returned, but are not currently supported, are:

#REG_BINARY

#REG_DWORD_LITTLE_ENDIAN

#REG_DWORD_BIG_ENDIAN

#REG_LINK

#REG_NONE

#REG_QWORD

#REG_RESOURCE_LIST

EXAMPLE
    registry.queryValue key2 "Notepad.exe" type:&type value:&val

    registry.queryInfoKey <HKey> numSubKeys:<&int> numValues:<&int>

Gets the number of subkeys and values of the open HKey.

Returns true if successful, false if error.

Use registry.getLastError() to get error message.

If the query is successful, the number of subKeys and values will be written to the numSubKeys: and numValues: keyword variable, respectively.

EXAMPLE
    registry.queryInfoKey key2 numSubKeys:&numSubKeys numValues:&numValues

    registry.isKeyOpen <HKey>

Returns true of the specified HKey is open.

    registry.isParentKeyOpen <HKey>

Returns true of the parent HKey of the specified HKey is open.

    registry.isKeyConstant <HKey>

Returns true if the HKey is a constant (root) HKey.

    registry.getParentKey <HKey>

Returns the parent HKey of the specified HKey.

    registry.getSubKeyName <HKey> <index> name:<&name>

Get a subkey name of the open HKey by index. Returns true if successful, false if error. Use registry.getLastError() to get error message.

If successful, the name will be written to the name: keyword variable.

EXAMPLE
    registry.getSubKeyName key2 i name:&vname

    registry.getSubKeyNames <HKey> names:<&array>

Get array of subkey names of the open HKey by index. Returns true if successful, false if error. Use registry.getLastError() to get error message.

If successful, an array of the subkey names as strings name will be written to the names: keyword variable.

EXAMPLE
    registry.getSubKeyNames key2 names:&vnames

    registry.getValueName <HKey> <index> name:<&name>

Get a value name of the open HKey by index. Returns true if successful, false if error. Use registry.getLastError() to get error message.

If successful, the name will be written to the name: keyword variable.

EXAMPLE
    registry.getValueName key2 i name:&vname

    registry.getValueNames <HKey> names:<&array>

Get array of value names of the open HKey by index. Returns true if successful, false if error. Use registry.getLastError() to get error message.

If successful, an array of the value names as strings name will be written to the names: keyword variable.

EXAMPLE
    registry.getSubKeyNames key2 names:&vnames

    registry.getLastError()

return string describing the last registry error that occurred\n"));

EXAMPLES:
    registry.openKey HKEY_CLASSES_ROOT"*"accessRights:#readOnly key:&key2

    registry.queryInfoKey key2 numSubKeys:&numSubKeys numValues:&numValues;numSubKeys;numValues
    for i = 1 to 2 do
    (registry.getSubKeyName key2 i name:&vname;print vname)

    registry.isKeyOpen key2

    registry.setvalue key2 "" #REG_SZ "123123" -- fails because opened with #readOnly access
    registry.getLastError()

    registry.getSubKeyNames key2 names:&names;names
    registry.getvalueNames key2 names:&names;names
    registry.queryValue key2 "InfoTip" type:&type value:&val;type;val

    registry.createKey HKEY_CLASSES_ROOT ".123x" accessRights:#all key:&key1
    registry.setvalue key1 "" #REG_MULTI_SZ #("zz","ww")
    registry.queryValue key1 "" type:&type value:&val;type;val
    registry.setvalue key1 "" #REG_SZ"123123"
    registry.queryValue key1 "" type:&type value:&val;type;val
    registry.deleteKey key1

## Registry-related global variables:

    HKEY_CLASSES_ROOT HKEY_CURRENT_CONFIG HKEY_CURRENT_USER HKEY_LOCAL_MACHINE HKEY_USERS HKEY_PERFORMANCE_DATA

#### See Also

- HKey Values

- Interaction With The Operating System