Registry Structure

The Registry struct provides methods to access the Windows registry keys.

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

They were previously available in the Avguard Extensions.

registry.closeKey <HKey>   

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

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

HKeys must 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() . However, this method uses many system resources and must 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 an error occurs. Use registry.getLastError() to get the error message.

It is not necessary to call registry.flushKey() method to change a key. Registry changes are flushed to the 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() might also write out parts or all of the other keys.

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

In general , registry.flushKey() is rarely 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 an error occurs. Use registry.getLastError() to get the 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 an error occurs. Use registry.getLastError() to get the 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 an error occurs. Use registry.getLastError() to get the 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.

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 an error occurs. Use registry.getLastError() to get the 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.

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 an error occurs.

Use registry.getLastError() to get the 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 an error occurs.

Use registry.getLastError() to get the 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

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 open HKey.

Returns true if successful, false if an error occurs.

Use registry.getLastError() to get the 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 might 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_QWORD

#REG_RESOURCE_LIST

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 an error occurs.

Use registry.getLastError() to get the error message.

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

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

registry.isKeyOpen <HKey> 

Returns true if the specified HKey is open.

registry.isParentKeyOpen <HKey> 

Returns true if 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> 

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

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

registry.getSubKeyName key2 i name:&vname

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

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

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

registry.getSubKeyNames key2 names:&vnames

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

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

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

registry.getValueName key2 i name:&vname

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

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

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

registry.getSubKeyNames key2 names:&vnames

registry.getLastError() 

Returns a string describing the last registry error that occurred.

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

HKEY_CLASSES_ROOT HKEY_CURRENT_CONFIG HKEY_CURRENT_USER HKEY_LOCAL_MACHINE HKEY_USERS HKEY_PERFORMANCE_DATA 

 Except where otherwise noted, this work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License. Please see the Autodesk Creative Commons FAQ for more information.