The registry is a database where Windows and applications store settings. Macros also can store their settings there.
int rset(data [name] [key] [hive] [options|datatype]) int rget(variable [name] [key] [hive] [default] [datatype])
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.
|
| -2 | delete subkey.
|
| -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.
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".
If your macro has many settings, try class __Settings. It makes easier to manage them. Displays in grid control, where user can change them.
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 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.
int rset(data name section inifile [options]) int rget(variable name section inifile [default])
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.
|
| -2 | delete section.
|
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.
write to ini file rset "data" "a" "section" "$desktop$\test.ini"