CRegKey Class

 

For the latest documentation on Visual Studio 2017 RC, see Visual Studio 2017 RC Documentation.

This class provides methods for manipulating entries in the system registry.

System_CAPS_ICON_important.jpg Important

This class and its members cannot be used in applications that execute in the Windows Runtime.

class CRegKey

Public Constructors

NameDescription
CRegKey::CRegKeyThe constructor.
CRegKey::~CRegKeyThe destructor.

Public Methods

NameDescription
CRegKey::AttachCall this method to attach an HKEY to the CRegKey object by setting the m_hKey member handle to hKey.
CRegKey::CloseCall this method to release the m_hKey member handle and set it to NULL.
CRegKey::CreateCall this method to create the specified key, if it does not exist as a subkey of hKeyParent.
CRegKey::DeleteSubKeyCall this method to remove the specified key from the registry.
CRegKey::DeleteValueCall this method to remove a value field from m_hKey.
CRegKey::DetachCall this method to detach the m_hKey member handle from the CRegKey object and set m_hKey to NULL.
CRegKey::EnumKeyCall this method to enumerate the subkeys of the open registry key.
CRegKey::FlushCall this method to write all of the attributes of the open registry key into the registry.
CRegKey::GetKeySecurityCall this method to retrieve a copy of the security descriptor protecting the open registry key.
CRegKey::NotifyChangeKeyValueThis method notifies the caller about changes to the attributes or contents of the open registry key.
CRegKey::OpenCall this method to open the specified key and set m_hKey to the handle of this key.
CRegKey::QueryBinaryValueCall this method to retrieve the binary data for a specified value name.
CRegKey::QueryDWORDValueCall this method to retrieve the DWORD data for a specified value name.
CRegKey::QueryGUIDValueCall this method to retrieve the GUID data for a specified value name.
CRegKey::QueryMultiStringValueCall this method to retrieve the multistring data for a specified value name.
CRegKey::QueryQWORDValueCall this method to retrieve the QWORD data for a specified value name.
CRegKey::QueryStringValueCall this method to retrieve the string data for a specified value name.
CRegKey::QueryValueCall this method to retrieve the data for the specified value field of m_hKey. Earlier versions of this method are no longer supported and are marked as ATL_DEPRECATED.
CRegKey::RecurseDeleteKeyCall this method to remove the specified key from the registry and explicitly remove any subkeys.
CRegKey::SetBinaryValueCall this method to set the binary value of the registry key.
CRegKey::SetDWORDValueCall this method to set the DWORD value of the registry key.
CRegKey::SetGUIDValueCall this method to set the GUID value of the registry key.
CRegKey::SetKeySecurityCall this method to set the security of the registry key.
CRegKey::SetKeyValueCall this method to store data in a specified value field of a specified key.
CRegKey::SetMultiStringValueCall this method to set the multistring value of the registry key.
CRegKey::SetQWORDValueCall this method to set the QWORD value of the registry key.
CRegKey::SetStringValueCall this method to set the string value of the registry key.
CRegKey::SetValueCall this method to store data in the specified value field of m_hKey. Earlier versions of this method are no longer supported and are marked as ATL_DEPRECATED.

Public Operators

NameDescription
CRegKey::operator HKEYConverts a CRegKey object to an HKEY.
CRegKey::operator =Assignment operator.

Public Data Members

NameDescription
CRegKey::m_hKeyContains a handle of the registry key associated with the CRegKey object.
CRegKey::m_pTMPointer to CAtlTransactionManager object

CRegKey provides methods for creating and deleting keys and 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.

System_CAPS_ICON_important.jpg Important

Any methods that allow the caller to specify a registry location have the potential to read data that cannot be trusted. Methods that make use of RegQueryValueEx should take into consideration that this function does not explicitly handle strings which are NULL terminated. Both conditions should be checked for by the calling code.

Header: atlbase.h

Call this method to attach an HKEY to the CRegKey object by setting the m_hKey member handle to hKey.

void Attach(HKEY hKey) throw();

Parameters

hKey
The handle of a registry key.

Remarks

Attach will assert if m_hKey is non-NULL.

Call this method to release the m_hKey member handle and set it to NULL.

LONG Close() throw();

Return Value

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

Call this method to create the specified key, if it does not exist as a subkey of hKeyParent.

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

Parameters

hKeyParent
The handle of an open key.

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

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

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

samDesired
The security access for the key. The default value is KEY_READ | KEY_WRITE. For a list of possible values and descriptions, see RegCreateKeyEx.

lpSecAttr
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 (meaning 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).

Return Value

If successful, returns ERROR_SUCCESS and opens the key. If the method fails, the return value is a nonzero error code defined in WINERROR.H.

Remarks

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

The constructor.

CRegKey() throw();
CRegKey(CRegKey& key) throw();
explicit CRegKey(HKEY   hKey) throw();
CRegKey(CAtlTransactionManager* pTM) throw();

Parameters

key
A reference to a CRegKey object.

hKey
A handle to a registry key.

pTM
Pointer to CAtlTransactionManager object

Remarks

Creates a new CRegKey object. The object can be created from an existing CRegKey object, or from a handle to a registry key.

The destructor.

~CRegKey() throw();

Remarks

The destructor releases m_hKey.

Call this method to remove the specified key from the registry.

LONG DeleteSubKey(LPCTSTR lpszSubKey) throw();

Parameters

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

Return Value

If successful, returns ERROR_SUCCESS. If the method fails, the return value is a nonzero error code defined in WINERROR.H.

Remarks

DeleteSubKey can only delete a key that has no subkeys. If the key has subkeys, call RecurseDeleteKey instead.

Call this method to remove a value field from m_hKey.

LONG DeleteValue(LPCTSTR lpszValue) throw();

Parameters

lpszValue
Specifies the value field to remove.

Return Value

If successful, returns ERROR_SUCCESS. If the method fails, the return value is a nonzero error code defined in WINERROR.H.

Call this method to detach the m_hKey member handle from the CRegKey object and set m_hKey to NULL.

HKEY Detach() throw();

Return Value

The HKEY associated with the CRegKey object.

Call this method to enumerate the subkeys of the open registry key.

LONG EnumKey(DWORD iIndex,
    LPTSTR pszName,
    LPDWORD pnNameLength,
    FILETIME* pftLastWriteTime = NULL) throw();

Parameters

iIndex
The subkey index. This parameter should be zero for the first call and then incremented for subsequent calls

pszName
Pointer to a buffer that receives the name of the subkey, including the terminating null character. Only the name of the subkey is copied to the buffer, not the full key hierarchy.

pnNameLength
Pointer to a variable that specifies the size, in TCHARs, of the buffer specified by the pszName parameter. This size should include the terminating null character. When the method returns, the variable pointed to by pnNameLength contains the number of characters stored in the buffer. The count returned does not include the terminating null character.

pftLastWriteTime
Pointer to a variable that receives the time the enumerated subkey was last written to.

Return Value

If the method succeeds, the return value is ERROR_SUCCESS. If the method fails, the return value is a nonzero error code defined in WINERROR.H.

Remarks

To enumerate the subkeys, call CRegKey::EnumKey with an index of zero. Increment the index value and repeat until the method returns ERROR_NO_MORE_ITEMS. For more information, see RegEnumKeyEx in the Windows SDK.

Call this method to write all of the attributes of the open registry key into the registry.

LONG Flush() throw();

Return Value

If the method succeeds, the return value is ERROR_SUCCESS. If the method fails, the return value is a nonzero error code defined in WINERROR.H.

Remarks

For more information, see RegEnumFlush in the Windows SDK.

Call this method to retrieve a copy of the security descriptor protecting the open registry key.

LONG GetKeySecurity(SECURITY_INFORMATION si,
    PSECURITY_DESCRIPTOR psd,
    LPDWORD pnBytes) throw();

Parameters

si
The SECURITY_INFORMATION value that indicates the requested security information.

psd
A pointer to a buffer that receives a copy of the requested security descriptor.

pnBytes
The size, in bytes, of the buffer pointed to by psd.

Return Value

If the method succeeds, the return value is ERROR_SUCCESS. If the method fails, the return value is a nonzero error code is defined in WINERROR.H.

Remarks

For more information, see RegGetKeySecurity.

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

HKEY m_hKey;

Pointer to a CAtlTransactionManager object.

CAtlTransactionManager* m_pTM;

Remarks

This method notifies the caller about changes to the attributes or contents of the open registry key.

LONG NotifyChangeKeyValue(BOOL bWatchSubtree,
    DWORD dwNotifyFilter,
    HANDLE hEvent,
    BOOL bAsync = TRUE) throw();

Parameters

bWatchSubtree
Specifies a flag that indicates whether to report changes in the specified key and all of its subkeys or only in the specified key. If this parameter is TRUE, the method reports changes in the key and its subkeys. If the parameter is FALSE, the method reports changes only in the key.

dwNotifyFilter
Specifies a set of flags that control which changes should be reported. This parameter can be a combination of the following values:

ValueMeaning
REG_NOTIFY_CHANGE_NAMENotify the caller if a subkey is added or deleted.
REG_NOTIFY_CHANGE_ATTRIBUTESNotify the caller of changes to the attributes of the key, such as the security descriptor information.
REG_NOTIFY_CHANGE_LAST_SETNotify the caller of changes to a value of the key. This can include adding or deleting a value, or changing an existing value.
REG_NOTIFY_CHANGE_SECURITYNotify the caller of changes to the security descriptor of the key.

hEvent
Handle to an event. If the bAsync parameter is TRUE, the method returns immediately and changes are reported by signaling this event. If bAsync is FALSE, hEvent is ignored.

bAsync
Specifies a flag that indicates how the method reports changes. If this parameter is TRUE, the method returns immediately and reports changes by signaling the specified event. When this parameter is FALSE, the method does not return until a change has occurred. If hEvent does not specify a valid event, the bAsync parameter cannot be TRUE.

Return Value

If the method succeeds, the return value is ERROR_SUCCESS. If the method fails, the return value is a nonzero error code defined in WINERROR.H.

Remarks

System_CAPS_ICON_note.jpg Note

This method does not notify the caller if the specified key is deleted.

For more details and a sample program, see RegNotifyChangeKeyValue.

Call this method to open the specified key and set m_hKey to the handle of this key.

LONG Open(HKEY hKeyParent,
    LPCTSTR lpszKeyName,
    REGSAM samDesired = KEY_READ | KEY_WRITE) throw();

Parameters

hKeyParent
The handle of an open key.

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

samDesired
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 Windows SDK.

Return Value

If successful, returns ERROR_SUCCESS; otherwise, a non-zero error value defined in WINERROR.H.

Remarks

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.

Converts a CRegKey object to an HKEY.

Assignment operator.

CRegKey& operator= (CRegKey& key) throw();

Parameters

key
The key to copy.

Return Value

Returns a reference to the new key.

Remarks

This operator detaches key from its current object and assigns it to the CRegKey object instead.

Call this method to retrieve the binary data for a specified value name.

LONG QueryBinaryValue(LPCTSTR pszValueName,
    void* pValue,
    ULONG* pnBytes) throw();

Parameters

pszValueName
Pointer to a null-terminated string containing the name of the value to query.

pValue
Pointer to a buffer that receives the value's data.

pnBytes
Pointer to a variable that specifies the size, in bytes, of the buffer pointed to by the pValue parameter. When the method returns, this variable contains the size of the data copied to the buffer.

Return Value

If the method succeeds, ERROR_SUCCESS is returned. If the method fails to read a value, it returns a nonzero error code defined in WINERROR.H. If the data referenced is not of type REG_BINARY, ERROR_INVALID_DATA is returned.

Remarks

This method makes use of RegQueryValueEx and confirms that the correct type of data is returned. See RegQueryValueEx for more details.

System_CAPS_ICON_important.jpg Important

This method allows the caller to specify any registry location, potentially reading data which cannot be trusted. Also, the RegQueryValueEx function used by this method does not explicitly handle strings which are NULL terminated. Both conditions should be checked for by the calling code.

Call this method to retrieve the DWORD data for a specified value name.

LONG QueryDWORDValue(LPCTSTR pszValueName,
    DWORD& dwValue) throw();

Parameters

pszValueName
Pointer to a null-terminated string containing the name of the value to query.

dwValue
Pointer to a buffer that receives the DWORD.

Return Value

If the method succeeds, ERROR_SUCCESS is returned. If the method fails to read a value, it returns a nonzero error code defined in WINERROR.H. If the data referenced is not of type REG_DWORD, ERROR_INVALID_DATA is returned.

Remarks

This method makes use of RegQueryValueEx and confirms that the correct type of data is returned. See RegQueryValueEx for more details.

System_CAPS_ICON_important.jpg Important

This method allows the caller to specify any registry location, potentially reading data which cannot be trusted. Also, the RegQueryValueEx function used by this method does not explicitly handle strings which are NULL terminated. Both conditions should be checked for by the calling code.

Call this method to retrieve the GUID data for a specified value name.

LONG QueryGUIDValue(LPCTSTR pszValueName,
    GUID& guidValue) throw();

Parameters

pszValueName
Pointer to a null-terminated string containing the name of the value to query.

guidValue
Pointer to a variable that receives the GUID.

Return Value

If the method succeeds, ERROR_SUCCESS is returned. If the method fails to read a value, it returns a nonzero error code defined in WINERROR.H. If the data referenced is not a valid GUID, ERROR_INVALID_DATA is returned.

Remarks

This method makes use of CRegKey::QueryStringValue and converts the string into a GUID using CLSIDFromString.

System_CAPS_ICON_important.jpg Important

This method allows the caller to specify any registry location, potentially reading data which cannot be trusted.

Call this method to retrieve the multistring data for a specified value name.

LONG QueryMultiStringValue(LPCTSTR pszValueName,
    LPTSTR pszValue,
    ULONG* pnChars) throw();

Parameters

pszValueName
Pointer to a null-terminated string containing the name of the value to query.

pszValue
Pointer to a buffer that receives the multistring data. A multistring is an array of null-terminated strings, terminated by two null characters.

pnChars
The size, in TCHARs, of the buffer pointed to by pszValue. When the method returns, pnChars contains the size, in TCHARs, of the multistring retrieved, including a terminating null character.

Return Value

If the method succeeds, ERROR_SUCCESS is returned. If the method fails to read a value, it returns a nonzero error code defined in WINERROR.H. If the data referenced is not of type REG_MULTI_SZ, ERROR_INVALID_DATA is returned.

Remarks

This method makes use of RegQueryValueEx and confirms that the correct type of data is returned. See RegQueryValueEx for more details.

System_CAPS_ICON_important.jpg Important

This method allows the caller to specify any registry location, potentially reading data which cannot be trusted. Also, the RegQueryValueEx function used by this method does not explicitly handle strings which are NULL terminated. Both conditions should be checked for by the calling code.

Call this method to retrieve the QWORD data for a specified value name.

LONG QueryQWORDValue(LPCTSTR pszValueName,
    ULONGLONG& qwValue) throw();

Parameters

pszValueName
Pointer to a null-terminated string containing the name of the value to query.

qwValue
Pointer to a buffer that receives the QWORD.

Return Value

If the method succeeds, ERROR_SUCCESS is returned. If the method fails to read a value, it returns a nonzero error code defined in WINERROR.H. If the data referenced is not of type REG_QWORD, ERROR_INVALID_DATA is returned.

Remarks

This method makes use of RegQueryValueEx and confirms that the correct type of data is returned. See RegQueryValueEx for more details.

System_CAPS_ICON_important.jpg Important

This method allows the caller to specify any registry location, potentially reading data which cannot be trusted. Also, the RegQueryValueEx function used by this method does not explicitly handle strings which are NULL terminated. Both conditions should be checked for by the calling code.

Call this method to retrieve the string data for a specified value name.

LONG QueryStringValue(LPCTSTR pszValueName,
    LPTSTR pszValue,
    ULONG* pnChars) throw();

Parameters

pszValueName
Pointer to a null-terminated string containing the name of the value to query.

pszValue
Pointer to a buffer that receives the string data.

pnChars
The size, in TCHARs, of the buffer pointed to by pszValue. When the method returns, pnChars contains the size, in TCHARs, of the string retrieved, including a terminating null character.

Return Value

If the method succeeds, ERROR_SUCCESS is returned. If the method fails to read a value, it returns a nonzero error code defined in WINERROR.H. If the data referenced is not of type REG_SZ, ERROR_INVALID_DATA is returned. If the method returns ERROR_MORE_DATA, pnChars equals zero, not the required buffer size in bytes.

Remarks

This method makes use of RegQueryValueEx and confirms that the correct type of data is returned. See RegQueryValueEx for more details.

System_CAPS_ICON_important.jpg Important

This method allows the caller to specify any registry location, potentially reading data which cannot be trusted. Also, the RegQueryValueEx function used by this method does not explicitly handle strings which are NULL terminated. Both conditions should be checked for by the calling code.

Call this method to retrieve the data for the specified value field of m_hKey. Earlier versions of this method are no longer supported and are marked as ATL_DEPRECATED.

LONG QueryValue(LPCTSTR pszValueName,
    DWORD* pdwType,
    void* pData,
    ULONG* pnBytes) throw();
ATL_DEPRECATED LONG QueryValue(
    DWORD& dwValue,
    LPCTSTR lpszValueName);

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

Parameters

pszValueName
Pointer to a null-terminated string containing the name of the value to query. If pszValueName is NULL or an empty string, "", the method retrieves the type and data for the key's unnamed or default value, if any.

pdwType
Pointer to a variable that receives a code indicating the type of data stored in the specified value. The pdwType parameter can be NULL if the type code is not required.

pData
Pointer to a buffer that receives the value's data. This parameter can be NULL if the data is not required.

pnBytes
Pointer to a variable that specifies the size, in bytes, of the buffer pointed to by the pData parameter. When the method returns, this variable contains the size of the data copied to pData.

dwValue
The value field's numerical data.

lpszValueName
Specifies the value field to be queried.

szValue
The value field's string data.

pdwCount
The size of the string data. Its value is initially set to the size of the szValue buffer.

Return Value

If successful, returns ERROR_SUCCESS; otherwise, a nonzero error code defined in WINERROR.H.

Remarks

The two original versions of QueryValue are no longer supported and are marked as ATL_DEPRECATED. The compiler will issue a warning if these forms are used.

The remaining method calls RegQueryValueEx.

System_CAPS_ICON_important.jpg Important

This method allows the caller to specify any registry location, potentially reading data which cannot be trusted. Also, the RegQueryValueEx function used by this method does not explicitly handle strings which are NULL terminated. Both conditions should be checked for by the calling code.

Call this method to remove the specified key from the registry and explicitly remove any subkeys.

LONG RecurseDeleteKey(LPCTSTR lpszKey) throw();

Parameters

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

Return Value

If successful, returns ERROR_SUCCESS; otherwise, a non-zero error value defined in WINERROR.H.

Remarks

If the key has subkeys, you must call this method to delete the key.

Call this method to set the binary value of the registry key.

LONG SetBinaryValue(LPCTSTR pszValueName,
    const void* pValue,
    ULONG nBytes) throw();

Parameters

pszValueName
Pointer to a string containing the name of the value to set. If a value with this name is not already present, the method adds it to the key.

pValue
Pointer to a buffer containing the data to be stored with the specified value name.

nBytes
Specifies the size, in bytes, of the information pointed to by the pValue parameter.

Return Value

If the method succeeds, the return value is ERROR_SUCCESS. If the method fails, the return value is a nonzero error code defined in WINERROR.H.

Remarks

This method uses RegSetValueEx to write the value to the registry.

Call this method to set the DWORD value of the registry key.

LONG SetDWORDValue(LPCTSTR pszValueName,  DWORD dwValue) throw();

Parameters

pszValueName
Pointer to a string containing the name of the value to set. If a value with this name is not already present, the method adds it to the key.

dwValue
The DWORD data to be stored with the specified value name.

Return Value

If the method succeeds, the return value is ERROR_SUCCESS. If the method fails, the return value is a nonzero error code defined in WINERROR.H.

Remarks

This method uses RegSetValueEx to write the value to the registry.

Call this method to set the GUID value of the registry key.

LONG SetGUIDValue(LPCTSTR pszValueName,  REFGUID guidValue) throw();

Parameters

pszValueName
Pointer to a string containing the name of the value to set. If a value with this name is not already present, the method adds it to the key.

guidValue
Reference to the GUID to be stored with the specified value name.

Return Value

If the method succeeds, the return value is ERROR_SUCCESS. If the method fails, the return value is a nonzero error code defined in WINERROR.H.

Remarks

This method makes use of CRegKey::SetStringValue and converts the GUID into a string using StringFromGUID2.

Call this method to store data in a specified value field of a specified key.

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

Parameters

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

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

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

Return Value

If successful, returns ERROR_SUCCESS; otherwise, a nonzero error code defined in WINERROR.H.

Remarks

Call this method to create or open the lpszKeyName key and store the lpszValue data in the lpszValueName value field.

Call this method to set the security of the registry key.

LONG SetKeySecurity(SECURITY_INFORMATION si,  PSECURITY_DESCRIPTOR psd) throw();

Parameters

si
Specifies the components of the security descriptor to set. The value can be a combination of the following values:

ValueMeaning
DACL_SECURITY_INFORMATIONSets the key's discretionary access-control list (DACL). The key must have WRITE_DAC access, or the calling process must be the object's owner.
GROUP_SECURITY_INFORMATIONSets the key's primary group security identifier (SID). The key must have WRITE_OWNER access, or the calling process must be the object's owner.
OWNER_SECURITY_INFORMATIONSets the key's owner SID. The key must have WRITE_OWNER access, or the calling process must be the object's owner or have the SE_TAKE_OWNERSHIP_NAME privilege enabled.
SACL_SECURITY_INFORMATIONSets the key's system access-control list (SACL). The key must have ACCESS_SYSTEM_SECURITY access. The proper way to get this access is to enable the SE_SECURITY_NAME privilege in the caller's current access token, open the handle for ACCESS_SYSTEM_SECURITY access, and then disable the privilege.

psd
Pointer to a SECURITY_DESCRIPTOR structure that specifies the security attributes to set for the specified key.

Return Value

If the method succeeds, the return value is ERROR_SUCCESS. If the method fails, the return value is a nonzero error code defined in WINERROR.H.

Remarks

Sets the key's security attributes. See RegSetKeySecurity for more details.

Call this method to set the multistring value of the registry key.

LONG SetMultiStringValue(LPCTSTR pszValueName,  LPCTSTR pszValue) throw();

Parameters

pszValueName
Pointer to a string containing the name of the value to set. If a value with this name is not already present, the method adds it to the key.

pszValue
Pointer to the multistring data to be stored with the specified value name. A multistring is an array of null-terminated strings, terminated by two null characters.

Return Value

If the method succeeds, the return value is ERROR_SUCCESS. If the method fails, the return value is a nonzero error code defined in WINERROR.H.

Remarks

This method uses RegSetValueEx to write the value to the registry.

Call this method to set the QWORD value of the registry key.

LONG SetQWORDValue(LPCTSTR pszValueName,  ULONGLONG qwValue) throw();

Parameters

pszValueName
Pointer to a string containing the name of the value to set. If a value with this name is not already present, the method adds it to the key.

qwValue
The QWORD data to be stored with the specified value name.

Return Value

If the method succeeds, the return value is ERROR_SUCCESS. If the method fails, the return value is a nonzero error code defined in WINERROR.H.

Remarks

This method uses RegSetValueEx to write the value to the registry.

Call this method to set the string value of the registry key.

LONG SetStringValue(LPCTSTR pszValueName,
    LPCTSTR pszValue,
    DWORD dwType = REG_SZ) throw();

Parameters

pszValueName
Pointer to a string containing the name of the value to set. If a value with this name is not already present, the method adds it to the key.

pszValue
Pointer to the string data to be stored with the specified value name.

dwType
The type of the string to write to the registry: either REG_SZ (the default) or REG_EXPAND_SZ (for multistrings).

Return Value

If the method succeeds, the return value is ERROR_SUCCESS. If the method fails, the return value is a nonzero error code defined in WINERROR.H.

Remarks

This method uses RegSetValueEx to write the value to the registry.

Call this method to store data in the specified value field of m_hKey. Earlier versions of this method are no longer supported and are marked as ATL_DEPRECATED.

LONG SetValue(LPCTSTR pszValueName,
    DWORD dwType,
    const void* pValue,
    ULONG nBytes) throw();
static LONG WINAPI SetValue(HKEY hKeyParent,
    LPCTSTR lpszKeyName,
    LPCTSTR lpszValue,
    LPCTSTR lpszValueName = NULL);

    ATL_DEPRECATED LONG SetValue(DWORD dwValue,
    LPCTSTR lpszValueName);

    ATL_DEPRECATED LONG SetValue(LPCTSTR lpszValue,
    LPCTSTR lpszValueName = NULL,
    bool bMulti = false,
    int nValueLen = -1);

Parameters

pszValueName
Pointer to a string containing the name of the value to set. If a value with this name is not already present in the key, the method adds it to the key. If pszValueName is NULL or an empty string, "", the method sets the type and data for the key's unnamed or default value.

dwType
Specifies a code indicating the type of data pointed to by the pValue parameter.

pValue
Pointer to a buffer containing the data to be stored with the specified value name.

nBytes
Specifies the size, in bytes, of the information pointed to by the pValue parameter. If the data is of type REG_SZ, REG_EXPAND_SZ, or REG_MULTI_SZ, nBytes must include the size of the terminating null character.

hKeyParent
The handle of an open key.

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

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

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

dwValue
Specifies the data to be stored.

bMulti
If false, indicates the string is of type REG_SZ. If true, indicates the string is a multistring of type REG_MULTI_SZ.

nValueLen
If bMulti is true, nValueLen is the length of the lpszValue string in characters. If bMulti is false, a value of -1 indicates that the method will calculate the length automatically.

Return Value

If successful, returns ERROR_SUCCESS; otherwise, a nonzero error code defined in WINERROR.H.

Remarks

The two original versions of SetValue are marked as ATL_DEPRECATED and should no longer be used. The compiler will issue a warning if these forms are used.

The third method calls RegSetValueEx.

DCOM Sample
Class Overview

Show: