CRegKey

class CRegKey

CRegKey provides methods for manipulating values in the system registry. The registry contains an installation-specific set of definitions for system components, such as software version numbers, logical-to-physical mappings of installed hardware, and COM objects.

CRegKey provides a programming interface to the system registry for a given machine. For example, to open a particular registry key, call CRegKey::Open. To retrieve or modify a data value, call CRegKey::QueryValue or CRegKey::SetValue, respectively. To close a key, call CRegKey::Close.

When you close a key, its registry data is written (flushed) to the hard disk. This process may take several seconds. If your application must explicitly write registry data to the hard disk, you can call the RegFlushKey Win32 function. However, RegFlushKey uses many system resources and should be called only when absolutely necessary.

#include <atlbase.h>


CRegKey Class Members

Methods
AttachAttaches a registry key handle to the CRegKey object.
CloseReleases m_hKey.
CreateCreates or opens the specified key.
CRegKeyConstructor.
DeleteSubKeyDeletes the specified key.
DeleteValueDeletes a value field of key identified by m_hKey.
DetachDetaches m_hKey from the CRegKey object.
OpenOpens the specified key.
QueryValueRetrieves the data for a specified value field.
RecurseDeleteKeyDeletes the specified key and explicitly deletes all subkeys.
SetKeyValueStores data in a specified value field of a specified key.
SetValueStores data in a specified value field.
Operators
operator HKEYConverts a CRegKey object to an HKEY.
Data Members
m_hKeyContains a handle of the registry key associated with the CRegKey object.

CRegKey Overview


Methods


CRegKey::Attach

void Attach( HKEY hKey );

Parameters

hKey [in] The handle of a registry key.

Remarks

Attaches an HKEY to the CRegKey object by setting the m_hKey member handle to hKey.

Note Attach will assert if m_hKey is non-NULL.

CRegKey Overview | Class Members

See Also CRegKey::Detach


CRegKey::Close

LONG Close( );

Return Value

If successful, returns ERROR_SUCCESS; otherwise, an error value.

Remarks

Releases the m_hKey member handle and sets it to NULL.

CRegKey Overview | Class Members

See Also CRegKey::Open


CRegKey::Create

LONG Create( HKEY hKeyParent, LPCTSTR lpszKeyName, LPTSTR lpszClass = REG_NONE, DWORD dwOptions = REG_OPTION_NON_VOLATILE, REGSAM samDesired = KEY_ALL_ACCESS, LPSECURITY_ATTRIBUTES lpSecAttr = NULL, LPDWORD lpdwDisposition = NULL );

Return Value

If successful, returns ERROR_SUCCESS; otherwise, an error value.

Parameters

hKeyParent [in] The handle of an open key.

lpszKeyName [in] Specifies the name of a key to be created or opened. This name must be a subkey of hKeyParent.

lpszClass [in] Specifies the class of the key to be created or opened. The default value is REG_NONE.

dwOptions [in] Options for the key. The default value is REG_OPTION_NON_VOLATILE. For a list of possible values and descriptions, see RegCreateKeyEx in the Win32 SDK.

samDesired [in] The security access for the key. The default value is KEY_ALL_ACCESS. For a list of possible values and descriptions, see RegCreateKeyEx in the Win32 SDK.

lpSecAttr [in] A pointer to a SECURITY_ATTRIBUTES structure that indicates whether the handle of the key can be inherited by a child process. By default, this parameter is NULL (the handle cannot be inherited).

lpdwDisposition [out] If non-NULL, retrieves either REG_CREATED_NEW_KEY (if the key did not exist and was created) or REG_OPENED_EXISTING_KEY (if the key existed and was opened).

Remarks

Creates the specified key if it does not exist as a subkey of hKeyParent. Otherwise, Create opens the key.

Create sets the m_hKey member to the handle of this key.

CRegKey Overview | Class Members

See Also CRegKey::Open, CRegKey::Close, SECURITY_ATTRIBUTES in the Win32 SDK


CRegKey::CRegKey

CRegKey( );

Remarks

The constructor. Sets the m_hKey member handle to NULL. The destructor releases m_hKey.

CRegKey Overview | Class Members


CRegKey::DeleteSubKey

LONG DeleteSubKey( LPCTSTR lpszSubKey );

Return Value

If successful, returns ERROR_SUCCESS; otherwise, an error value.

Parameters

lpszSubKey [in] Specifies the name of the key to delete. This name must be a subkey of m_hKey.

Remarks

Removes the specified key from the registry. Under Windows 95, DeleteSubKey deletes the key and all its subkeys. Under Windows NT, DeleteSubKey can only delete a key that has no subkeys. If the key has subkeys, call RecurseDeleteKey instead.

CRegKey Overview | Class Members

See Also CRegKey::DeleteValue


CRegKey::DeleteValue

LONG DeleteValue( LPCTSTR lpszValue );

Return Value

If successful, returns ERROR_SUCCESS; otherwise, an error value.

Parameters

lpszValue [in] Specifies the value field to remove.

Remarks

Removes a value field from m_hKey.

CRegKey Overview | Class Members

See Also CRegKey::DeleteSubKey


CRegKey::Detach

HKEY Detach( );

Return Value

The HKEY associated with the CRegKey object.

Remarks

Detaches the m_hKey member handle from the CRegKey object and sets m_hKey to NULL.

CRegKey Overview | Class Members

See Also CRegKey::Attach


CRegKey::Open

LONG Open( HKEY hKeyParent, LPCTSTR lpszKeyName, REGSAM samDesired = KEY_ALL_ACCESS );

Return Value

If successful, returns ERROR_SUCCESS; otherwise, an error value.

Parameters

hKeyParent [in] The handle of an open key.

lpszKeyName [in] Specifies the name of a key to be created or opened. This name must be a subkey of hKeyParent.

samDesired [in] The security access for the key. The default value is KEY_ALL_ACCESS. For a list of possible values and descriptions, see RegCreateKeyEx in the Win32 SDK.

Remarks

Opens the specified key and sets m_hKey to the handle of this key. If the lpszKeyName parameter is NULL or points to an empty string, Open opens a new handle of the key identified by hKeyParent, but does not close any previously opened handle.

Unlike CRegKey::Create, Open will not create the specified key if it does not exist.

CRegKey Overview | Class Members

See Also CRegKey::Close


CRegKey::QueryValue

LONG QueryValue( DWORD& dwValue, LPCTSTR lpszValueName );
LONG QueryValue( LPTSTR szValue, LPCTSTR lpszValueName, DWORD* pdwCount );

Return Value

If successful, returns ERROR_SUCCESS; otherwise, an error value.

Parameters

dwValue [out] The value field's numerical data.

lpszValueName [in] Specifies the value field to be queried.

szValue [out] The value field's string data.

pdwCount [out] The size of the string data.

Remarks

Retrieves the data for the specified value field of m_hKey. The first version of QueryValue allows you to retrieve numerical data. The second version allows you to retrieve string data.

CRegKey Overview | Class Members


CRegKey::RecurseDeleteKey

LONG RecurseDeleteKey( LPCTSTR lpszKey );

Return Value

If successful, returns ERROR_SUCCESS; otherwise, an error value.

Parameters

lpszKey [in] Specifies the name of the key to delete. This name must be a subkey of m_hKey.

Remarks

Removes the specified key from the registry and explicitly removes any subkeys. If the key has subkeys, you must call this method under Windows NT in order to delete the key. Under Windows 95, you can call DeleteSubKey to remove the key and any subkeys.

CRegKey Overview | Class Members


CRegKey::SetKeyValue

LONG SetKeyValue( LPCTSTR lpszKeyName, LPCTSTR lpszValue, LPCTSTR lpszValueName = NULL );

Return Value

If successful, returns ERROR_SUCCESS; otherwise, an error value.

Parameters

lpszKeyName [in] Specifies the name of the key to be created or opened. This name must be a subkey of m_hKey.

lpszValue [in] Specifies the data to be stored. This parameter must be non-NULL.

lpszValueName [in] Specifies the value field to be set. If a value field with this name does not already exist in the key, it is added.

Remarks

Ccreates or opens the lpszKeyName key and stores the lpszValue data in the lpszValueName value field.

CRegKey Overview | Class Members

See Also CRegKey::SetValue


CRegKey::SetValue

LONG SetValue( DWORD dwValue, LPCTSTR lpszValueName );
LONG SetValue( LPCTSTR lpszValue, LPCTSTR lpszValueName = NULL );
LONG SetValue( HKEY hKeyParent, LPCTSTR lpszKeyName, LPCTSTR lpszValue, LPCTSTR lpszValueName = NULL );

Return Value

If successful, returns ERROR_SUCCESS; otherwise, an error value.

Parameters

dwValue [in] Specifies the data to be stored.

lpszValueName [in] Specifies the value field to be set. If a value field with this name does not already exist in the key, it is added.

lpszValue [in] Specifies the data to be stored. This parameter must be non-NULL.

hKeyParent [in] The handle of an open key.

lpszKeyName [in] Specifies the name of a key to be created or opened. This name must be a subkey hKeyParent.

Remarks

Stores data in the specified value field of an open registry key. The first two versions of SetValue use m_hKey as the open key. The third version allows you to create or open a subkey of hKeyParent, and then set the value field of the subkey.

CRegKey Overview | Class Members

See Also CRegKey::SetKeyValue


Operators


CRegKey::operator HKEY

operator HKEY( ) const;

Remarks

Converts a CRegKey object to an HKEY.

CRegKey Overview | Class Members


Data Members


CRegKey::m_hKey

HKEY m_hKey;

Remarks

Contains a handle of the registry key associated with the CRegKey object.

CRegKey Overview | Class Members