www.digitalmars.com

D Programming Language 2.0

Last update Wed Apr 11 21:24:38 2012

std.windows.registry

This library provides Win32 Registry facilities.

License:

Author:
Matthew Wilson, Kenji Hara

Histry:
Created 15th March 2003, Updated 25th April 2004,

Source:
std/windows/registry.d

class Win32Exception: object.Exception;

class RegistryException: std.windows.registry.Win32Exception;
Exception class thrown by the std.windows.registry classes.

this(string message, string fn = __FILE__, uint ln = cast(uint)__LINE__, Throwable next = null);
Creates an instance of the exception.

Parameters:
string message The message associated with the exception.

this(string message, int error, string fn = __FILE__, uint ln = cast(uint)__LINE__, Throwable next = null);
Creates an instance of the exception, with the given.

Parameters:
string message The message associated with the exception.
int error The Win32 error number associated with the exception.

enum REGSAM;
Enumeration of the recognised registry access modes.

KEY_QUERY_VALUE
Permission to query subkey data

KEY_SET_VALUE
Permission to set subkey data

KEY_CREATE_SUB_KEY
Permission to create subkeys

KEY_ENUMERATE_SUB_KEYS
Permission to enumerate subkeys

KEY_NOTIFY
Permission for change notification

KEY_CREATE_LINK
Permission to create a symbolic link

KEY_WOW64_32KEY
Enables a 64- or 32-bit application to open a 32-bit key

KEY_WOW64_64KEY
Enables a 64- or 32-bit application to open a 64-bit key

KEY_WOW64_RES

KEY_WRITE
Combines the STANDARD_RIGHTS_READ, KEY_QUERY_VALUE, KEY_ENUMERATE_SUB_KEYS, and KEY_NOTIFY access rights

KEY_EXECUTE
Combines the STANDARD_RIGHTS_WRITE, KEY_SET_VALUE, and KEY_CREATE_SUB_KEY access rights

KEY_ALL_ACCESS
Permission for read access

enum REG_VALUE_TYPE;
Enumeration of the recognised registry value types.

REG_UNKNOWN

REG_NONE
The null value type. (In practise this is treated as a zero-length binary array by the Win32 registry)

REG_SZ
A zero-terminated string

REG_EXPAND_SZ
A zero-terminated string containing expandable environment variable references

REG_BINARY
A binary blob

REG_DWORD
A 32-bit unsigned integer

REG_DWORD_LITTLE_ENDIAN
A 32-bit unsigned integer, stored in little-endian byte order

REG_DWORD_BIG_ENDIAN
A 32-bit unsigned integer, stored in big-endian byte order

REG_LINK
A registry link

REG_MULTI_SZ
A set of zero-terminated strings

REG_RESOURCE_LIST
A hardware resource list

REG_FULL_RESOURCE_DESCRIPTOR
A hardware resource descriptor

REG_RESOURCE_REQUIREMENTS_LIST
A hardware resource requirements list

REG_QWORD
A 64-bit unsigned integer

REG_QWORD_LITTLE_ENDIAN
A 64-bit unsigned integer, stored in little-endian byte order

class Key;
This class represents a registry key.

const pure nothrow @property @safe string name();
The name of the key

const @property size_t keyCount();
The number of sub keys.

pure @property @safe KeySequence keys();
An enumerable sequence of all the sub-keys of this key.

pure @property @safe KeyNameSequence keyNames();
An enumerable sequence of the names of all the sub-keys of this key.

const @property size_t valueCount();
The number of values.

pure @property @safe ValueSequence values();
An enumerable sequence of all the values of this key.

pure @property @safe ValueNameSequence valueNames();
An enumerable sequence of the names of all the values of this key.

Key createKey(string name, REGSAM access = (REGSAM).KEY_ALL_ACCESS);
Returns the named sub-key of this key.

Parameters:
string name The name of the subkey to create. May not be null.

Returns:
The created key.

Throws:
RegistryException is thrown if the key cannot be created.

Key getKey(string name, REGSAM access = (REGSAM).KEY_READ);
Returns the named sub-key of this key.

Parameters:
string name The name of the subkey to aquire. If name is the empty string, then the called key is duplicated.
REGSAM access The desired access; one of the REGSAM enumeration.

Returns:
The aquired key.

Throws:
This function never returns null. If a key corresponding to the requested name is not found, RegistryException is thrown.

void deleteKey(string name, REGSAM access = cast(REGSAM)0);
Deletes the named key.

Parameters:
string name The name of the key to delete. May not be null.

Value getValue(string name);
Returns the named value. If name is the empty string, then the default value is returned.

Returns:
This function never returns null. If a value corresponding to the requested name is not found, RegistryException is thrown.

void setValue(string name, uint value);
Sets the named value with the given 32-bit unsigned integer value.

Parameters:
string name The name of the value to set. If it is the empty string, sets the default value.
uint value The 32-bit unsigned value to set.

Throws:
If a value corresponding to the requested name is not found, RegistryException is thrown.

void setValue(string name, uint value, Endian endian);
Sets the named value with the given 32-bit unsigned integer value, according to the desired byte-ordering.

Parameters:
string name The name of the value to set. If it is the empty string, sets the default value.
uint value The 32-bit unsigned value to set.
Endian endian Can be Endian.BigEndian or Endian.LittleEndian.

Throws:
If a value corresponding to the requested name is not found, RegistryException is thrown.

void setValue(string name, ulong value);
Sets the named value with the given 64-bit unsigned integer value.

Parameters:
string name The name of the value to set. If it is the empty string, sets the default value.
ulong value The 64-bit unsigned value to set.

Throws:
If a value corresponding to the requested name is not found, RegistryException is thrown.

void setValue(string name, string value);
Sets the named value with the given string value.

Parameters:
string name The name of the value to set. If it is the empty string, sets the default value.
string value The string value to set.

Throws:
If a value corresponding to the requested name is not found, RegistryException is thrown.

void setValue(string name, string value, bool asEXPAND_SZ);
Sets the named value with the given string value.

Parameters:
string name The name of the value to set. If it is the empty string, sets the default value.
string value The string value to set.
bool asEXPAND_SZ If true, the value will be stored as an expandable environment string, otherwise as a normal string.

Throws:
If a value corresponding to the requested name is not found, RegistryException is thrown.

void setValue(string name, string[] value);
Sets the named value with the given multiple-strings value.

Parameters:
string name The name of the value to set. If it is the empty string, sets the default value.
string[] value The multiple-strings value to set.

Throws:
If a value corresponding to the requested name is not found, RegistryException is thrown.

void setValue(string name, byte[] value);
Sets the named value with the given binary value.

Parameters:
string name The name of the value to set. If it is the empty string, sets the default value.
byte[] value The binary value to set.

Throws:
If a value corresponding to the requested name is not found, RegistryException is thrown.

void deleteValue(string name);
Deletes the named value.

Parameters:
string name The name of the value to delete. May not be null.

Throws:
If a value of the requested name is not found, RegistryException is thrown.

void flush();
Flushes any changes to the key to disk.

class Value;
This class represents a value of a registry key.

const pure nothrow @property @safe string name();
The name of the value. If the value represents a default value of a key, which has no name, the returned string will be of zero length.

const pure nothrow @property @safe REG_VALUE_TYPE type();
The type of value.

const @property string value_SZ();
Obtains the current value of the value as a string. If the value's type is REG_EXPAND_SZ the returned value is not expanded; value_EXPAND_SZ should be called

Returns:
The contents of the value.

Throws:
RegistryException if the type of the value is not REG_SZ, REG_EXPAND_SZ, REG_DWORD, or REG_QWORD.

const @property string value_EXPAND_SZ();
Obtains the current value as a string, within which any environment variables have undergone expansion. This function works with the same value-types as value_SZ.

Returns:
The contents of the value.

const @property string[] value_MULTI_SZ();
Obtains the current value as an array of strings.

Returns:
The contents of the value.

Throws:
RegistryException if the type of the value is not REG_MULTI_SZ.

const @property uint value_DWORD();
Obtains the current value as a 32-bit unsigned integer, ordered correctly according to the current architecture.

Returns:
The contents of the value.

Throws:
RegistryException is thrown for all types other than REG_DWORD, REG_DWORD_LITTLE_ENDIAN and REG_DWORD_BIG_ENDIAN.

const @property ulong value_QWORD();
Obtains the value as a 64-bit unsigned integer, ordered correctly according to the current architecture.

Returns:
The contents of the value.

Throws:
RegistryException if the type of the value is not REG_QWORD.

const @property byte[] value_BINARY();
Obtains the value as a binary blob.

Returns:
The contents of the value.

Throws:
RegistryException if the type of the value is not REG_BINARY.

class Registry;
Represents the local system registry.

static @property Key classesRoot();
Returns the root key for the HKEY_CLASSES_ROOT hive

static @property Key currentUser();
Returns the root key for the HKEY_CURRENT_USER hive

static @property Key localMachine();
Returns the root key for the HKEY_LOCAL_MACHINE hive

static @property Key users();
Returns the root key for the HKEY_USERS hive

static @property Key performanceData();
Returns the root key for the HKEY_PERFORMANCE_DATA hive

static @property Key currentConfig();
Returns the root key for the HKEY_CURRENT_CONFIG hive

static @property Key dynData();
Returns the root key for the HKEY_DYN_DATA hive

class KeyNameSequence;
An enumerable sequence representing the names of the sub-keys of a registry Key.

Example:
Key key = ...
foreach (string subkeyName; key.keyNames)
{
    // using subkeyName
}

const @property size_t count();
The number of keys.

string getKeyName(size_t index);
The name of the key at the given index.

Parameters:
size_t index The 0-based index of the key to retrieve.

Returns:
The name of the key corresponding to the given index.

Throws:
RegistryException if no corresponding key is retrieved.

string opIndex(size_t index);
The name of the key at the given index.

Parameters:
size_t index The 0-based index of the key to retrieve.

Returns:
The name of the key corresponding to the given index.

Throws:
RegistryException if no corresponding key is retrieved.

int opApply(scope int delegate(ref string name) dg);

class KeySequence;
An enumerable sequence representing the sub-keys of a registry Key.

Example:
Key key = ...
foreach (Key subkey; key.keys)
{
    // using subkey
}

const @property size_t count();
The number of keys.

Key getKey(size_t index);
The key at the given index.

Parameters:
size_t index The 0-based index of the key to retrieve.

Returns:
The key corresponding to the given index.

Throws:
RegistryException if no corresponding key is retrieved.

Key opIndex(size_t index);
The key at the given index.

Parameters:
size_t index The 0-based index of the key to retrieve.

Returns:
The key corresponding to the given index.

Throws:
RegistryException if no corresponding key is retrieved.

int opApply(scope int delegate(ref Key key) dg);

class ValueNameSequence;
An enumerable sequence representing the names of the values of a registry Key.

Example:
Key key = ...
foreach (string valueName; key.valueNames)
{
    // using valueName
}

const @property size_t count();
The number of values.

string getValueName(size_t index);
The name of the value at the given index.

Parameters:
size_t index The 0-based index of the value to retrieve.

Returns:
The name of the value corresponding to the given index.

Throws:
RegistryException if no corresponding value is retrieved.

string opIndex(size_t index);
The name of the value at the given index.

Parameters:
size_t index The 0-based index of the value to retrieve.

Returns:
The name of the value corresponding to the given index.

Throws:
RegistryException if no corresponding value is retrieved.

int opApply(scope int delegate(ref string name) dg);

class ValueSequence;
An enumerable sequence representing the values of a registry Key.

Example:
Key key = ...
foreach (Value value; key.values)
{
    // using value
}

const @property size_t count();
The number of values

Value getValue(size_t index);
The value at the given index.

Parameters:
size_t index The 0-based index of the value to retrieve

Returns:
The value corresponding to the given index.

Throws:
RegistryException if no corresponding value is retrieved

Value opIndex(size_t index);
The value at the given index.

Parameters:
size_t index The 0-based index of the value to retrieve.

Returns:
The value corresponding to the given index.

Throws:
RegistryException if no corresponding value is retrieved.

int opApply(scope int delegate(ref Value value) dg);