Registry and ini file functions

Registry functions

The registry is a database where Windows and applications store settings. Macros also can store their settings there.

 

Syntax

int rset(data [name] [key] [hive] [options|datatype])
int rget(variable [name] [key] [hive] [default] [datatype])

 

Parameters

data - data to be stored in the registry. Can be variable or other expression.

variable - variable that receives data stored in the registry.

name - registry value name. Use "" for "(Default)".

key - registry key.

hive - one of HKEY_... constants. Integer.

default - default value to be used if the value does not exist in the registry. Default: "" for strings, 0 for numeric variables. Cannot be used with user-defined types.

options:

0 (default) write data.
-1

delete value.

  • data is not used and can be 0 or "".
-2

delete subkey.

  • data - not used and can be 0 or "".
  • name - subkey name.
  • key - parent key.
  • QM 2.3.5. Can be used only key, like rset "" "" "ParentKey\KeyToDelete" 0 -2
-3 delete subkey, but only if it does not contain subkeys.
-4 (QM 2.2.0) delete subkey, but only if it is empty (does not contain subkeys and values).

datatype - registry data type. Can be used only with strings. Can be one of REG_... constants, for example REG_BINARY. Default: REG_SZ.

 

Remarks

rset writes data to the registry. If the specified key does not exist, creates it. Also used to delete values and keys.

rget reads data from the registry and stores it into the variable.

 

Each of these functions returns a nonzero value on success. For strings, it is string length+1. For data of other type, it is registry data length. If fails (e.g., key or value does not exist, access denied, etc), returns 0. You can get error description using str.dllerror.

 

When deleting, rset returns 1 if successful, 0 if failed. Returns 0 if the value or key did not exist; then if(GetLastError=ERROR_FILE_NOT_FOUND) will be true, unless it failed for some other reason, for example if access is denied (ERROR_ACCESS_DENIED).

 

Warning: You should not use rset if you are not sure that this will not damage something. You can safely use rget. It is quite safe to use rset if key is omitted, "", or begins with \, because then you deal only with the key dedicated for QM macros.

 

Hive HKEY_CURRENT_USER (default) is used for current user's settings. Other hives are used for settings common to all users.

 

For security reasons, rset usually cannot write to hives other than HKEY_CURRENT_USER on non-administrator user accounts. On Windows Vista/7/8/10, it fails to write to these hives even on the administrator account if QM is running not as administrator.

 

Registry data format:

expression/variable type registry data format
str, lpstr REG_SZ or datatype
int, byte, word REG_DWORD
other REG_BINARY

 

QM 2.3.0. If variable is a str variable, and datatype is REG_SZ or 0 or omitted, rget succeeds even if data type in registry is not of REG_SZ type. REG_EXPAND_SZ strings are automatically expanded. REG_MULTI_SZ strings are correctly retrieved too. REG_DWORD and REG_QWORD values are converted to string. Data of other nonstring types is copied to the str variable unmodified. In older QM versions, rget would fail if registry data type is not a string type. String types are REG_SZ, REG_MULTI_SZ and REG_EXPAND_SZ.

 

If variable is a str variable, and datatype other than 0 or REG_SZ is specified, rget fails if data type of the value in the registry is other. With variables of other types, data type in the registry must match too.

 

Variables of composite types except str cannot be used. These are ARRAY, BSTR, VARIANT, interface pointer, and types containing these types or str. With rget also cannot be used pointers and lpstr. Types containing str can be used if you convert them from/to string. See str.getstruct/str.setstruct.

 

rset and rget can be used with single argument. Then the argument must be a variable, in simplest form (without ., [], etc). The variable name is used for the registry value name. For example, rset v is the same as rset v "v".

 

Tips

If your macro has many settings, try class __Settings. It makes easier to manage them. Displays in grid control, where user can change them.

 

Examples

 retrieves value "Logon User Name" from HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer
str s
if(rget(s "Logon User Name" "Software\Microsoft\Windows\CurrentVersion\Explorer"))
	out s
else
	out "the value or the key does not exist"

 retrieves the default value from HKEY_CLASSES_ROOT\mp3file\shell\play\command
str s
if(rget(s "" "mp3file\shell\play\command" HKEY_CLASSES_ROOT))
	out s

 sets value "test" in HKEY_CURRENT_USER\software\gindi\qm2\user\MyFunctionSettings
rset "data" "test" "\MyFunctionSettings"

 retrieves value "test" from HKEY_CURRENT_USER\software\gindi\qm2\user\MyFunctionSettings
str s
rget s "test" "\MyFunctionSettings"
out s

 sets value "test" in HKEY_CURRENT_USER\software\gindi\qm2\user
int test = 100
rset test

 retrieves value "test" from HKEY_CURRENT_USER\software\gindi\qm2\user
int test
rget test
out test

 deletes value "test" in HKEY_CURRENT_USER\software\gindi\qm2\user\MyFunctionSettings
rset "" "test" "\MyFunctionSettings" 0 -1

 deletes key "MyFunctionSettings" in HKEY_CURRENT_USER\software\gindi\qm2\user
rset "" "MyFunctionSettings" "" 0 -2

 


Ini file functions

Ini files can be used to store settings. However it is not recommended because is too limited. No Unicode, not all characters allowed, no hierarchy, etc. To store small-size settings, instead use the registry. For bigger-size settings and other data you can use XML, CSV or Sqlite.

 

Syntax

int rset(data name section inifile [options])
int rget(variable name section inifile [default])

 

Parameters

data - data to be stored in the ini file. Can be variable or other expression.

variable - variable that receives data stored in the ini file.

name - ini value name (also called key). Everything is the same as with the registry.

section - ini section name. In ini files section names are in [ ].

inifile - ini file. Default: "$my qm$\User.ini.

default - default value to be used if the value does not exist. Everything is the same as with the registry.

options:

0 (default) write data.
-1

delete value.

  • data is not used and can be "".
-2

delete section.

  • data and name are not used and can be "".

 

Remarks

rset writes data to the ini file. If the file or section does not exist, creates.

rget reads data from the ini file and stores it into the variable.

 

Each of these functions returns 1 on success, 0 on failure. If rset failed, you can get error description using str.dllerror.

 

Example

 write to ini file
rset "data" "a" "section" "$desktop$\test.ini"