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>
Methods | |
Attach | Attaches a registry key handle to the CRegKey object. |
Close | Releases m_hKey. |
Create | Creates or opens the specified key. |
CRegKey | Constructor. |
DeleteSubKey | Deletes the specified key. |
DeleteValue | Deletes a value field of key identified by m_hKey. |
Detach | Detaches m_hKey from the CRegKey object. |
Open | Opens the specified key. |
QueryValue | Retrieves the data for a specified value field. |
RecurseDeleteKey | Deletes the specified key and explicitly deletes all subkeys. |
SetKeyValue | Stores data in a specified value field of a specified key. |
SetValue | Stores data in a specified value field. |
Operators | |
operator HKEY | Converts a CRegKey object to an HKEY. |
Data Members | |
m_hKey | Contains a handle of the registry key associated with the CRegKey object. |
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
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
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( );
Remarks
The constructor. Sets the m_hKey member handle to NULL. The destructor releases m_hKey.
CRegKey Overview | Class Members
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
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
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
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
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
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
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
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
operator HKEY( ) const;
Remarks
Converts a CRegKey object to an HKEY.
CRegKey Overview | Class Members
HKEY m_hKey;
Remarks
Contains a handle of the registry key associated with the CRegKey object.