.TH win32reg 3 "stdlib  1.15.3" "Ericsson AB" "ERLANG MODULE DEFINITION"
.SH MODULE
win32reg \- win32reg provides access to the registry on Windows
.SH DESCRIPTION
.LP
\fIwin32reg\fR provides read and write access to the registry on Windows\&. It is essentially a port driver wrapped around the Win32 API calls for accessing the registry\&.
.LP
The registry is a hierarchical database, used to store various system and software information in Windows\&. It is available in Windows 95 and Windows NT\&. It contains installation data, and is updated by installers and system programs\&. The Erlang installer updates the registry by adding data that Erlang needs\&.
.LP
The registry contains keys and values\&. Keys are like the directories in a file system, they form a hierarchy\&. Values are like files, they have a name and a value, and also a type\&.
.LP
Paths to keys are left to right, with sub-keys to the right and backslash between keys\&. (Remember that backslashes must be doubled in Erlang strings\&.) Case is preserved but not significant\&. Example: \fI"\e\ehkey_local_machine\e\esoftware\e\eEricsson\e\eErlang\e\e5\&.0"\fR is the key for the installation data for the latest Erlang release\&.
.LP
There are six entry points in the Windows registry, top level keys\&. They can be abbreviated in the \fIwin32reg\fR module as:

.nf
Abbrev\&.          Registry key
=======          ============      
hkcr             HKEY_CLASSES_ROOT
current_user     HKEY_CURRENT_USER
hkcu             HKEY_CURRENT_USER
local_machine    HKEY_LOCAL_MACHINE
hklm             HKEY_LOCAL_MACHINE
users            HKEY_USERS
hku              HKEY_USERS
current_config   HKEY_CURRENT_CONFIG
hkcc             HKEY_CURRENT_CONFIG
dyn_data         HKEY_DYN_DATA
hkdd             HKEY_DYN_DATA
.fi
.LP
The key above could be written as \fI"\e\ehklm\e\esoftware\e\eericsson\e\eerlang\e\e5\&.0"\fR\&.
.LP
The \fIwin32reg\fR module uses a current key\&. It works much like the current directory\&. From the current key, values can be fetched, sub-keys can be listed, and so on\&.
.LP
Under a key, any number of named values can be stored\&. They have name, and types, and data\&.
.LP
Currently, the \fIwin32reg\fR module supports storing only the following types: REG_DWORD, which is an integer, REG_SZ which is a string and REG_BINARY which is a binary\&. Other types can be read, and will be returned as binaries\&.
.LP
There is also a "default" value, which has the empty string as name\&. It is read and written with the atom \fIdefault\fR instead of the name\&.
.LP
Some registry values are stored as strings with references to environment variables, e\&.g\&. \fI"%SystemRoot%Windows"\fR\&. \fISystemRoot\fR is an environment variable, and should be replaced with its value\&. A function \fIexpand/1\fR is provided, so that environment variables surrounded in % can be expanded to their values\&.
.LP
For additional information on the Windows registry consult the Win32 Programmer\&'s Reference\&.

.SH EXPORTS
.LP
.B
change_key(RegHandle, Key) -> ReturnValue
.br
.RS
.TP
Types
RegHandle = term()
.br
Key = string()
.br
.RE
.RS
.LP
Changes the current key to another key\&. Works like cd\&. The key can be specified as a relative path or as an absolute path, starting with \e\&.
.RE
.LP
.B
change_key_create(RegHandle, Key) -> ReturnValue
.br
.RS
.TP
Types
RegHandle = term()
.br
Key = string()
.br
.RE
.RS
.LP
Creates a key, or just changes to it, if it is already there\&. Works like a combination of \fImkdir\fR and \fIcd\fR\&. Calls the Win32 API function \fIRegCreateKeyEx()\fR\&.
.LP
The registry must have been opened in write-mode\&.
.RE
.LP
.B
close(RegHandle)-> ReturnValue
.br
.RS
.TP
Types
RegHandle = term()
.br
.RE
.RS
.LP
Closes the registry\&. After that, the \fIRegHandle\fR cannot be used\&.
.RE
.LP
.B
current_key(RegHandle) -> ReturnValue
.br
.RS
.TP
Types
RegHandle = term()
.br
ReturnValue = {ok, string()}
.br
.RE
.RS
.LP
Returns the path to the current key\&. This is the equivalent of \fIpwd\fR\&.
.LP
Note that the current key is stored in the driver, and might be invalid (e\&.g\&. if the key has been removed)\&.
.RE
.LP
.B
delete_key(RegHandle) -> ReturnValue
.br
.RS
.TP
Types
RegHandle = term()
.br
ReturnValue = ok | {error, ErrorId}
.br
.RE
.RS
.LP
Deletes the current key, if it is valid\&. Calls the Win32 API function \fIRegDeleteKey()\fR\&. Note that this call does not change the current key, (unlike \fIchange_key_create/2\fR\&.) This means that after the call, the current key is invalid\&.
.RE
.LP
.B
delete_value(RegHandle, Name) -> ReturnValue
.br
.RS
.TP
Types
RegHandle = term()
.br
ReturnValue = ok | {error, ErrorId}
.br
.RE
.RS
.LP
Deletes a named value on the current key\&. The atom \fIdefault\fR is used for the the default value\&.
.LP
The registry must have been opened in write-mode\&.
.RE
.LP
.B
expand(String) -> ExpandedString
.br
.RS
.TP
Types
String = string()
.br
ExpandedString = string()
.br
.RE
.RS
.LP
Expands a string containing environment variables between percent characters\&. Anything between two % is taken for a environment variable, and is replaced by the value\&. Two consecutive % is replaced by one %\&.
.LP
A variable name that is not in the environment, will result in an error\&. 
.RE
.LP
.B
format_error(ErrorId) -> ErrorString
.br
.RS
.TP
Types
ErrorId = atom()
.br
ErrorString = string()
.br
.RE
.RS
.LP
Convert an POSIX errorcode to a string (by calling \fIerl_posix_msg:message\fR)\&.
.RE
.LP
.B
open(OpenModeList)-> ReturnValue
.br
.RS
.TP
Types
OpenModeList = [OpenMode]
.br
OpenMode = read | write
.br
.RE
.RS
.LP
Opens the registry for reading or writing\&. The current key will be the root (\fIHKEY_CLASSES_ROOT\fR)\&. The \fIread\fR flag in the mode list can be omitted\&.
.LP
Use \fIchange_key/2\fR with an absolute path after \fIopen\fR\&.
.RE
.LP
.B
set_value(RegHandle, Name, Value) -> ReturnValue
.br
.RS
.TP
Types
Name = string() | default
.br
Value = string() | integer() | binary()
.br
.RE
.RS
.LP
Sets the named (or default) value to value\&. Calls the Win32 API function \fIRegSetValueEx()\fR\&. The value can be of three types, and the corresponding registry type will be used\&. Currently the types supported are: \fIREG_DWORD\fR for integers, \fIREG_SZ\fR for strings and \fIREG_BINARY\fR for binaries\&. Other types cannot currently be added or changed\&.
.LP
The registry must have been opened in write-mode\&.
.RE
.LP
.B
sub_keys(RegHandle) -> ReturnValue
.br
.RS
.TP
Types
ReturnValue = {ok, SubKeys} | {error, ErrorId}
.br
SubKeys = [SubKey]
.br
SubKey = string()
.br
.RE
.RS
.LP
Returns a list of subkeys to the current key\&. Calls the Win32 API function \fIEnumRegKeysEx()\fR\&.
.LP
Avoid calling this on the root keys, it can be slow\&.
.RE
.LP
.B
value(RegHandle, Name) -> ReturnValue
.br
.RS
.TP
Types
Name = string() | default
.br
ReturnValue = {ok, Value}
.br
Value = string() | integer() | binary()
.br
.RE
.RS
.LP
Retrieves the named value (or default) on the current key\&. Registry values of type \fIREG_SZ\fR, are returned as strings\&. Type \fIREG_DWORD\fR values are returned as integers\&. All other types are returned as binaries\&.
.RE
.LP
.B
values(RegHandle) -> ReturnValue
.br
.RS
.TP
Types
ReturnValue = {ok, ValuePairs}
.br
ValuePairs = [ValuePair]
.br
ValuePair = {Name, Value}
.br
Name = string | default
.br
Value = string() | integer() | binary()
.br
.RE
.RS
.LP
Retrieves a list of all values on the current key\&. The values have types corresponding to the registry types, see \fIvalue\fR\&. Calls the Win32 API function \fIEnumRegValuesEx()\fR\&.
.RE
.SH SEE ALSO
.LP
Win32 Programmer\&'s Reference (from Microsoft)
.LP
\fIerl_posix_msg\fR
.LP
The Windows 95 Registry (book from O\&'Reilly)