From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- lib/stdlib/doc/src/win32reg.xml | 276 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 276 insertions(+) create mode 100644 lib/stdlib/doc/src/win32reg.xml (limited to 'lib/stdlib/doc/src/win32reg.xml') diff --git a/lib/stdlib/doc/src/win32reg.xml b/lib/stdlib/doc/src/win32reg.xml new file mode 100644 index 0000000000..d8055047b0 --- /dev/null +++ b/lib/stdlib/doc/src/win32reg.xml @@ -0,0 +1,276 @@ + + + + +
+ + 20002009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + win32reg + Bjorn Gustavsson + NN + + nobody + no + 2000-08-10 + PA1 + win32reg.sgml +
+ win32reg + win32reg provides access to the registry on Windows + +

win32reg 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.

+

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.

+

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.

+

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: "\\\\hkey_local_machine\\\\software\\\\Ericsson\\\\Erlang\\\\5.0" is the key + for the installation data for the latest Erlang release.

+

There are six entry points in the Windows registry, top level keys. They can be + abbreviated in the win32reg module as:

+ 
+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
+

The key above could be written as "\\\\hklm\\\\software\\\\ericsson\\\\erlang\\\\5.0".

+

The win32reg 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.

+

Under a key, any number of named values can be stored. They have name, and + types, and data.

+

Currently, the win32reg 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.

+

There is also a "default" value, which has the empty string as name. It is read and + written with the atom default instead of the name.

+

Some registry values are stored as strings with references to environment variables, + e.g. "%SystemRoot%Windows". SystemRoot is an environment variable, and should be + replaced with its value. A function expand/1 is provided, so that environment + variables surrounded in % can be expanded to their values.

+

For additional information on the Windows registry consult the Win32 + Programmer's Reference.

+ + + + change_key(RegHandle, Key) -> ReturnValue + Move to a key in the registry + + RegHandle = term() + Key = string() + + +

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 \\.

+ + + + change_key_create(RegHandle, Key) -> ReturnValue + Move to a key, create it if it is not there + + RegHandle = term() + Key = string() + + +

Creates a key, or just changes to it, if it is already there. Works + like a combination of mkdir and cd. Calls the Win32 API function + RegCreateKeyEx().

+

The registry must have been opened in write-mode.

+ + + + close(RegHandle)-> ReturnValue + Close the registry. + + RegHandle = term() + + +

Closes the registry. After that, the RegHandle cannot + be used.

+ + + + current_key(RegHandle) -> ReturnValue + Return the path to the current key. + + RegHandle = term() + ReturnValue = {ok, string()} + + +

Returns the path to the current key. This is the equivalent of pwd.

+

Note that the current key is stored in the driver, and might be + invalid (e.g. if the key has been removed).

+ + + + delete_key(RegHandle) -> ReturnValue + Delete the current key + + RegHandle = term() + ReturnValue = ok | {error, ErrorId} + + +

Deletes the current key, if it is valid. Calls the Win32 API + function RegDeleteKey(). Note that this call does not change the current key, + (unlike change_key_create/2.) This means that after the call, the + current key is invalid.

+ + + + delete_value(RegHandle, Name) -> ReturnValue + Delete the named value on the current key. + + RegHandle = term() + ReturnValue = ok | {error, ErrorId} + + +

Deletes a named value on the current key. The atom default is + used for the the default value.

+

The registry must have been opened in write-mode.

+ + + + expand(String) -> ExpandedString + Expand a string with environment variables + + String = string() + ExpandedString = string() + + +

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 %.

+

A variable name that is not in the environment, will result in an error.

+ + + + format_error(ErrorId) -> ErrorString + Convert an POSIX errorcode to a string + + ErrorId = atom() + ErrorString = string() + + +

Convert an POSIX errorcode to a string (by calling erl_posix_msg:message).

+ + + + open(OpenModeList)-> ReturnValue + Open the registry for reading or writing + + OpenModeList = [OpenMode] + OpenMode = read | write + + +

Opens the registry for reading or writing. The current key will be the root + (HKEY_CLASSES_ROOT). The read flag in the mode list can be omitted.

+

Use change_key/2 with an absolute path after open.

+ + + + set_value(RegHandle, Name, Value) -> ReturnValue + Set value at the current registry key with specified name. + + Name = string() | default + Value = string() | integer() | binary() + + +

Sets the named (or default) value to value. Calls the Win32 + API function RegSetValueEx(). The value can be of three types, and + the corresponding registry type will be used. Currently the types supported + are: REG_DWORD for integers, REG_SZ for strings and + REG_BINARY for binaries. Other types cannot currently be added + or changed.

+

The registry must have been opened in write-mode.

+ + + + sub_keys(RegHandle) -> ReturnValue + Get subkeys to the current key. + + ReturnValue = {ok, SubKeys} | {error, ErrorId} + SubKeys = [SubKey] + SubKey = string() + + +

Returns a list of subkeys to the current key. Calls the Win32 + API function EnumRegKeysEx().

+

Avoid calling this on the root keys, it can be slow.

+ + + + value(RegHandle, Name) -> ReturnValue + Get the named value on the current key. + + Name = string() | default + ReturnValue = {ok, Value} + Value = string() | integer() | binary() + + +

Retrieves the named value (or default) on the current key. + Registry values of type REG_SZ, are returned as strings. Type REG_DWORD + values are returned as integers. All other types are returned as binaries.

+ + + + values(RegHandle) -> ReturnValue + Get all values on the current key. + + ReturnValue = {ok, ValuePairs} | {ok, ErrorId} + ValuePairs = [ValuePair] + ValuePair = {Name, Value} + Name = string | default + Value = string() | integer() | binary() + + +

Retrieves a list of all values on the current key. The values + have types corresponding to the registry types, see value. + Calls the Win32 API function EnumRegValuesEx().

+ + + + +
+ SEE ALSO +

Win32 Programmer's Reference (from Microsoft)

+

erl_posix_msg

+

The Windows 95 Registry (book from O'Reilly)

+
+ + -- cgit v1.2.3