basic_reg_key Class Template Reference
[Windows Registry Library]

#include <winstl/registry/reg_key.hpp>

Detailed Description

template<typename C, typename T = reg_traits<C>, typename A = processheap_allocator<C>>
class winstl::basic_reg_key< C, T, A >

Represents a registry key, and provides methods for manipulating its values and sub-keys.

This class acts as the value type of classes that manipulate registry keys and encapsulates the concept of a registry key.

Parameters:

	C	The character type
	T	The traits type. On translators that support default template arguments this defaults to reg_traits<C>
	A	The allocator type. On translators that support default template arguments this defaults to processheap_allocator<C>


Member Types
typedef C	char_type
	The character type.
typedef T	traits_type
	The traits type.
typedef A	allocator_type
	The allocator type.
typedef basic_reg_key< C, T, A >	class_type
	The current parameterisation of the type.
typedef traits_type::size_type	size_type
	The size type.
typedef traits_type::string_type	string_type
	The string type.
typedef traits_type::hkey_type	hkey_type
	The key type.
typedef bool	bool_type
	The Boolean type.
typedef basic_reg_value< C, T, A >	key_value_type
	The type of the key's values.
typedef hkey_type	resource_type
Construction
	basic_reg_key ()
	Default constructor.
	basic_reg_key (hkey_type hkeyParent, char_type const *keyName, REGSAM accessMask=KEY_ALL_ACCESS)
	Construct from the named sub-key of the given parent.
template<typename S>
	basic_reg_key (hkey_type hkeyParent, S const &keyName, REGSAM accessMask=KEY_ALL_ACCESS)
	Construct from the named sub-key of the given parent.
	basic_reg_key (class_type const &keyParent, char_type const *keyName, REGSAM accessMask=KEY_ALL_ACCESS)
	Construct from the named sub-key of the given parent.
template<typename S>
	basic_reg_key (class_type const &keyParent, S const &keyName, REGSAM accessMask=KEY_ALL_ACCESS)
	Construct from the named sub-key of the given parent.
	basic_reg_key (class_type const &rhs)
	Constructs an instance as a (logical) copy of another.
	basic_reg_key (class_type const &rhs, REGSAM accessMask)
	Constructs an instance as a (logical) copy of another, but with different permissions.
	~basic_reg_key () throw ()
	Destructor.
class_type &	operator= (class_type const &rhs)
	Copy assignment operator.
Sub-key operations
class_type	open_sub_key (char_type const *subKeyName, REGSAM accessMask=KEY_ALL_ACCESS)
	Opens the named sub-key of this key.
template<typename S>
class_type	open_sub_key (S const &subKeyName, REGSAM accessMask=KEY_ALL_ACCESS)
class_type	create_sub_key (char_type const *subKeyName, REGSAM accessMask=KEY_ALL_ACCESS)
	Creates a named sub-key of this key.
template<typename S>
class_type	create_sub_key (S const &subKeyName, REGSAM accessMask=KEY_ALL_ACCESS)
	Creates a named sub-key of this key.
bool_type	delete_sub_key (char_type const *subKeyName)
	Deletes the named sub-key of this key.
template<typename S>
class_type	delete_sub_key (S const &subKeyName)
	Deletes the named sub-key of this key.
static class_type	create_key (HKEY hkey, char_type const *subKeyName, REGSAM accessMask=KEY_ALL_ACCESS)
	Creates a named sub-key of a given key.
template<typename H, typename S>
static class_type	create_key (H const &key, S const &subKeyName, REGSAM accessMask=KEY_ALL_ACCESS)
	Creates a named sub-key of this key.
Public Member Functions
hkey_type	dup_key_handle (REGSAM accessMask=KEY_ALL_ACCESS, result_type *res=NULL)
	Returns a duplicate of the key's handle, if any.
Attributes
string_type const &	name () const
	The name of the key.
string_type	reg_class () const
	The registry class of the key.
size_type	num_sub_keys () const
	The number of sub-keys.
size_type	num_values () const
	The number of values.
template<typename S>
bool_type	has_sub_key (S const &subKeyName)
	Indicates whether the sub-key exists.
template<typename S>
bool_type	has_value (S const &valueName)
	Indicates whether the value exists.
hkey_type	get_key_handle () const
	The handle to the underlying Registry API key.
hkey_type	get () const
	The handle to the underlying Registry API key.
REGSAM	get_access_mask () const
	The access mask associated with the key.
Value operations
bool_type	set_value (char_type const *valueName, DWORD value)
	Sets the named value to the value of the given 32-bit integer.
bool_type	set_value (char_type const valueName, char_type const value, ws_uint_t type=REG_SZ)
	Sets the named value to the value of the given string.
bool_type	set_value (char_type const valueName, char_type const *values, size_type numValues)
	Sets the named value to the values of the given string array.
bool_type	set_value (char_type const valueName, void const value, size_type cbValue)
	Sets the named value to the given binary value.
template<typename S>
bool_type	set_value (S const &valueName, DWORD value)
	Sets the named value to the value of the given 32-bit integer.
template<typename S>
bool_type	set_value (S const &valueName, char_type const *value, ws_uint_t type=REG_SZ)
	Sets the named value to the value of the given string.
template<typename S>
bool_type	set_value (S const &valueName, char_type const **values, size_type numValues)
	Sets the named value to the values of the given string array.
template<typename S>
bool_type	set_value (S const &valueName, void const *value, size_type cbValue)
	Sets the named value to the given binary value.
bool_type	set_value (char_type const *valueName, int value)
	Sets the named value to the given integer (stored as an unsigned value).
template<typename S>
bool_type	set_value (S const &valueName, int value)
	Sets the named value to the given integer (stored as an unsigned value).
bool_type	delete_value (char_type const *valueName)
	Deletes the named value.
template<typename S>
bool_type	delete_value (S const &valueName)
	Deletes the named value.
key_value_type	get_value (char_type const *valueName) const
	Returns the named value.
template<typename S>
key_value_type	get_value (S const &valueName) const
	Returns the named value.
Operations
void	swap (class_type &rhs) throw ()
	Efficiently swaps the contents between two instances / /.

Member Typedef Documentation

typedef C char_type

The character type.

typedef T traits_type

The traits type.

typedef A allocator_type

The allocator type.

typedef basic_reg_key<C, T, A> class_type

The current parameterisation of the type.

typedef traits_type::size_type size_type

The size type.

typedef traits_type::string_type string_type

The string type.

typedef traits_type::hkey_type hkey_type

The key type.

typedef bool bool_type

The Boolean type.

typedef basic_reg_value<C, T, A> key_value_type

The type of the key's values.

Constructor & Destructor Documentation

basic_reg_key ( )

Default constructor.

basic_reg_key	(	hkey_type	hkeyParent,
		char_type const *	keyName,
		REGSAM	accessMask = `KEY_ALL_ACCESS`
	)			`[inline]`

Construct from the named sub-key of the given parent.

Parameters:

	hkeyParent	A handle to the parent key, whose named subkey is to be opened.
	keyName	The name of the subkey to open. If `NULL` or the empty string, then a copy of `hkeyParent` will be opened.
	accessMask	A mask of `KEY_*` flags that define the required access to the key. Defaults to KEY_ALL_ACCESS.

Exceptions:

winstl::registry_exception If exception handling is enabled, an instance of registry_exception will be thrown indicating why the given key could not be opened. If not, then the instance constructed will be empty, as denoted by a NULL value returned from the get_key_handle() method.

basic_reg_key	(	hkey_type	hkeyParent,
		S const &	keyName,
		REGSAM	accessMask = `KEY_ALL_ACCESS`
	)			`[inline]`

Construct from the named sub-key of the given parent.

Parameters:

	hkeyParent	A handle to the parent key, whose named subkey is to be opened.
	keyName	The name of the subkey to open. If `NULL` or the empty string, then a copy of `hkeyParent` will be opened.
	accessMask	A mask of `KEY_*` flags that define the required access to the key. Defaults to KEY_ALL_ACCESS.

Exceptions:

winstl::registry_exception If exception handling is enabled, an instance of registry_exception will be thrown indicating why the given key could not be opened. If not, then the instance constructed will be empty, as denoted by a NULL value returned from the get_key_handle() method.

basic_reg_key	(	class_type const &	keyParent,
		char_type const *	keyName,
		REGSAM	accessMask = `KEY_ALL_ACCESS`
	)			`[inline]`

Construct from the named sub-key of the given parent.

Parameters:

	keyParent	A handle to the parent key, whose named subkey is to be opened.
	keyName	The name of the subkey to open. If `NULL` or the empty string, then a copy of `keyParent` will be opened.
	accessMask	A mask of `KEY_*` flags that define the required access to the key. Defaults to KEY_ALL_ACCESS.

Exceptions:

winstl::registry_exception If exception handling is enabled, an instance of registry_exception will be thrown indicating why the given key could not be opened. If not, then the instance constructed will be empty, as denoted by a NULL value returned from the get_key_handle() method.

basic_reg_key	(	class_type const &	keyParent,
		S const &	keyName,
		REGSAM	accessMask = `KEY_ALL_ACCESS`
	)			`[inline]`

Construct from the named sub-key of the given parent.

Parameters:

	keyParent	A handle to the parent key, whose named subkey is to be opened.
	keyName	The name of the subkey to open. If `NULL` or the empty string, then a copy of `keyParent` will be opened.
	accessMask	A mask of `KEY_*` flags that define the required access to the key. Defaults to KEY_ALL_ACCESS.

Exceptions:

winstl::registry_exception If exception handling is enabled, an instance of registry_exception will be thrown indicating why the given key could not be opened. If not, then the instance constructed will be empty, as denoted by a NULL value returned from the get_key_handle() method.

basic_reg_key ( class_type const & rhs )

Constructs an instance as a (logical) copy of another.

Parameters:

rhs

Instance whose key will be opened by the new instance.

Note:: The instance will hold a different handle to the same registry key.

Exceptions:

winstl::registry_exception If exception handling is enabled, an instance of registry_exception will be thrown indicating why the given key could not be opened. If not, then the instance constructed will be empty, as denoted by a NULL value returned from the get_key_handle() method.

basic_reg_key	(	class_type const &	rhs,
		REGSAM	accessMask
	)

Constructs an instance as a (logical) copy of another, but with different permissions.

Parameters:

	rhs	Instance whose key will be opened by the new instance.
	accessMask	The permissions for the new instance.

Note:: The instance will hold a different handle to the same registry key.

Exceptions:

winstl::registry_exception If exception handling is enabled, an instance of registry_exception will be thrown indicating why the given key could not be opened. If not, then the instance constructed will be empty, as denoted by a NULL value returned from the get_key_handle() method.

~basic_reg_key ( ) throw ()

Destructor.

Releases any resources allocated by the instance, including closing the underlying registry key.

Member Function Documentation

class_type& operator= ( class_type const & rhs )

Copy assignment operator.

string_type const& name ( ) const

The name of the key.

string_type reg_class ( ) const

The registry class of the key.

size_type num_sub_keys ( ) const

The number of sub-keys.

Note:: This is not a constant-time operation

size_type num_values ( ) const

The number of values.

Note:: This is not a constant-time operation

bool_type has_sub_key ( S const & subKeyName ) [inline]

Indicates whether the sub-key exists.

Parameters:

subKeyName

The name of the sub-key to test

References stlsoft_ns_qual.

bool_type has_value ( S const & valueName ) [inline]

Indicates whether the value exists.

Parameters:

valueName

The name of the value to test

References stlsoft_ns_qual.

hkey_type get_key_handle ( ) const

The handle to the underlying Registry API key.

Note:: If exception handling is not enabled, then this method will return NULL in the case where an instance constructor failed to open the key with the requested permissions.

Referenced by winstl::get_handle(), and winstl::get_HKEY().

hkey_type get ( ) const

The handle to the underlying Registry API key.

Note:: Equivalent to get_key_handle()

REGSAM get_access_mask ( ) const

The access mask associated with the key.

class_type open_sub_key	(	char_type const *	subKeyName,
		REGSAM	accessMask = `KEY_ALL_ACCESS`
	)

Opens the named sub-key of this key.

class_type create_sub_key	(	char_type const *	subKeyName,
		REGSAM	accessMask = `KEY_ALL_ACCESS`
	)

Creates a named sub-key of this key.

Parameters:

	subKeyName	Name of the subkey to created. If `NULL` or the empty string, then the function returns a copy of the callee.
	accessMask	A mask of `KEY_*` flags that define the required access to the key. Defaults to KEY_ALL_ACCESS.

Exceptions:

winstl::registry_exception If exception handling is enabled, an instance of registry_exception will be thrown indicating why the given key could not be created. If not, then the instance constructed will be empty, as denoted by a NULL value returned from the get_key_handle() method.

class_type create_sub_key	(	S const &	subKeyName,
		REGSAM	accessMask = `KEY_ALL_ACCESS`
	)			`[inline]`

Creates a named sub-key of this key.

Parameters:

	subKeyName	Name of the subkey to created. If `NULL` or the empty string, then the function returns a copy of the callee.
	accessMask	A mask of `KEY_*` flags that define the required access to the key. Defaults to KEY_ALL_ACCESS.

Exceptions:

winstl::registry_exception If exception handling is enabled, an instance of registry_exception will be thrown indicating why the given key could not be created. If not, then the instance constructed will be empty, as denoted by a NULL value returned from the get_key_handle() method.

References stlsoft_ns_qual.

static class_type create_key	(	HKEY	hkey,
		char_type const *	subKeyName,
		REGSAM	accessMask = `KEY_ALL_ACCESS`
	)			`[static]`

Creates a named sub-key of a given key.

Parameters:

	hkey	The parent registry key.
	subKeyName	Name of the subkey to created. If `NULL` or the empty string, then the function returns a copy of the callee.
	accessMask	A mask of `KEY_*` flags that define the required access to the key. Defaults to KEY_ALL_ACCESS.

Exceptions:

winstl::registry_exception If exception handling is enabled, an instance of registry_exception will be thrown indicating why the given key could not be created. If not, then the instance constructed will be empty, as denoted by a NULL value returned from the get_key_handle() method.

static class_type create_key	(	H const &	key,
		S const &	subKeyName,
		REGSAM	accessMask = `KEY_ALL_ACCESS`
	)			`[inline, static]`

Creates a named sub-key of this key.

Parameters:

	key	The parent registry key.
	subKeyName	Name of the subkey to created. If `NULL` or the empty string, then the function returns a copy of the callee.
	accessMask	A mask of `KEY_*` flags that define the required access to the key. Defaults to KEY_ALL_ACCESS.

Exceptions:

winstl::registry_exception If exception handling is enabled, an instance of registry_exception will be thrown indicating why the given key could not be created. If not, then the instance constructed will be empty, as denoted by a NULL value returned from the get_key_handle() method.

References winstl::get_HKEY(), and stlsoft_ns_qual.

bool_type delete_sub_key ( char_type const * subKeyName )

Deletes the named sub-key of this key.

Parameters:

subKeyName

The name of the sub-key to be deleted.

Returns:: Indicates whether the sub-key was deleted.

Return values:

	true	The sub-key existed and was successfully deleted.
	false	The sub-key does not exist. (Note: if exception handling is not enabled, then false will also be returned for any other reason, and the reason will be available via `GetLastError()`.)

Exceptions:

winstl::registry_exception

If exception handling is enabled, an instance of registry_exception will be thrown if the sub-key exists but cannot be deleted.

class_type delete_sub_key ( S const & subKeyName ) [inline]

Deletes the named sub-key of this key.

Parameters:

subKeyName

The name of the sub-key to be deleted.

Returns:: Indicates whether the sub-key was deleted.

Return values:

	true	The sub-key existed and was successfully deleted.
	false	The sub-key does not exist. (Note: if exception handling is not enabled, then false will also be returned for any other reason, and the reason will be available via `GetLastError()`.)

Exceptions:

winstl::registry_exception

If exception handling is enabled, an instance of registry_exception will be thrown if the sub-key exists but cannot be deleted.

References stlsoft_ns_qual.

hkey_type dup_key_handle	(	REGSAM	accessMask = `KEY_ALL_ACCESS`,
		result_type *	res = `NULL`
	)

Returns a duplicate of the key's handle, if any.

Parameters:

	accessMask	The access mask for the
	res	A pointer to a variable (of type result_type) into which will be written the result of the underlying registry API call.

Returns:

Note:: The handle returned from this method must be closed with RegCloseKey()

bool_type set_value	(	char_type const *	valueName,
		DWORD	value
	)

Sets the named value to the value of the given 32-bit integer.

Exceptions:

winstl::registry_exception

If exception handling is enabled, an instance of registry_exception will be thrown if the value cannot be set.

bool_type set_value	(	char_type const *	valueName,
		char_type const *	value,
		ws_uint_t	type = `REG_SZ`
	)

Sets the named value to the value of the given string.

/ /

Parameters:

	valueName	The name of the value. /
	value	The value of the value /
	type	The type of the value. Must be one of REG_SZ, REG_EXPAND_SZ or REG_MULTI_SZ.

Exceptions:

winstl::registry_exception

If exception handling is enabled, an instance of registry_exception will be thrown if the value cannot be set.

bool_type set_value	(	char_type const *	valueName,
		char_type const **	values,
		size_type	numValues
	)

Sets the named value to the values of the given string array.

/ /

Parameters:

	valueName	The name of the value. /
	values	The string array. /
	numValues	Number of elements in the string array.

Exceptions:

winstl::registry_exception

If exception handling is enabled, an instance of registry_exception will be thrown if the value cannot be set.

bool_type set_value	(	char_type const *	valueName,
		void const *	value,
		size_type	cbValue
	)

Sets the named value to the given binary value.

Exceptions:

winstl::registry_exception

If exception handling is enabled, an instance of registry_exception will be thrown if the value cannot be set.

bool_type set_value	(	S const &	valueName,
		DWORD	value
	)			`[inline]`

Sets the named value to the value of the given 32-bit integer.

Exceptions:

winstl::registry_exception

If exception handling is enabled, an instance of registry_exception will be thrown if the value cannot be set.

References stlsoft_ns_qual.

bool_type set_value	(	S const &	valueName,
		char_type const *	value,
		ws_uint_t	type = `REG_SZ`
	)			`[inline]`

Sets the named value to the value of the given string.

/ /

Parameters:

	valueName	The name of the value. /
	value	The value of the value /
	type	The type of the value. Must be one of REG_SZ, REG_EXPAND_SZ or REG_MULTI_SZ.

Exceptions:

winstl::registry_exception

If exception handling is enabled, an instance of registry_exception will be thrown if the value cannot be set.

References stlsoft_ns_qual.

bool_type set_value	(	S const &	valueName,
		char_type const **	values,
		size_type	numValues
	)			`[inline]`

Sets the named value to the values of the given string array.

/ /

Parameters:

	valueName	The name of the value. /
	values	The string array. /
	numValues	Number of elements in the string array.

Exceptions:

winstl::registry_exception

If exception handling is enabled, an instance of registry_exception will be thrown if the value cannot be set.

References stlsoft_ns_qual.

bool_type set_value	(	S const &	valueName,
		void const *	value,
		size_type	cbValue
	)			`[inline]`

Sets the named value to the given binary value.

Exceptions:

winstl::registry_exception

If exception handling is enabled, an instance of registry_exception will be thrown if the value cannot be set.

References stlsoft_ns_qual.

bool_type set_value	(	char_type const *	valueName,
		int	value
	)

Sets the named value to the given integer (stored as an unsigned value).

/ /

Note:: This method is provided solely to disambiguate between the DWORD and ws_uint64_t overloads / when using integer literals.

Exceptions:

winstl::registry_exception

If exception handling is enabled, an instance of registry_exception will be thrown if the value cannot be set.

bool_type set_value	(	S const &	valueName,
		int	value
	)			`[inline]`

Sets the named value to the given integer (stored as an unsigned value).

/ /

Note:: This method is provided solely to disambiguate between the DWORD and ws_uint64_t overloads / when using integer literals.

Exceptions:

winstl::registry_exception

If exception handling is enabled, an instance of registry_exception will be thrown if the value cannot be set.

References stlsoft_ns_qual.

bool_type delete_value ( char_type const * valueName )

Deletes the named value.

Parameters:

valueName

The name of the value to be deleted.

Returns:: Indicates whether the value was deleted.

Return values:

	true	The value existed and was successfully deleted.
	false	The value does not exist. (Note: if exception handling is not enabled, then false will also be returned for any other reason, and the reason will be available via `GetLastError()`.)

Exceptions:

winstl::registry_exception

If exception handling is enabled, an instance of registry_exception will be thrown if the value exists but cannot be deleted.

bool_type delete_value ( S const & valueName ) [inline]

Deletes the named value.

Parameters:

valueName

The name of the value to be deleted.

Returns:: Indicates whether the value was deleted.

Return values:

	true	The value existed and was successfully deleted.
	false	The value does not exist. (Note: if exception handling is not enabled, then false will also be returned for any other reason, and the reason will be available via `GetLastError()`.)

Exceptions:

winstl::registry_exception

If exception handling is enabled, an instance of registry_exception will be thrown if the value exists but cannot be deleted.

References stlsoft_ns_qual.

key_value_type get_value ( char_type const * valueName ) const

Returns the named value.

/ /

Returns:: An instance of basic_reg_value.

key_value_type get_value ( S const & valueName ) const [inline]

Returns the named value.

/ /

Returns:: An instance of basic_reg_value.

References stlsoft_ns_qual.

void swap ( class_type & rhs ) throw ()

Efficiently swaps the contents between two instances / /.

Parameters:

rhs

The parameter whose contents will be swapped.

The documentation for this class was generated from the following file:

winstl/registry/reg_key.hpp

basic_reg_key Class Template Reference [Windows Registry Library]

Detailed Description

template<typename C, typename T = reg_traits<C>, typename A = processheap_allocator<C>> class winstl::basic_reg_key< C, T, A >

Member Types

Construction

Sub-key operations

Public Member Functions

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

basic_reg_key Class Template Reference
[Windows Registry Library]

template<typename C, typename T = reg_traits<C>, typename A = processheap_allocator<C>>
class winstl::basic_reg_key< C, T, A >