CSettingsStore Class
Wraps Windows API functions, providing an object-oriented interface that you use to access the registry.
Syntax
class CSettingsStore : public CObject
Members
Public Constructors
| Name | Description |
|---|---|
| CSettingsStore::CSettingsStore | Constructs a CSettingsStore object. |
Public Methods
| Name | Description |
|---|---|
| CSettingsStore::Close | Closes the open registry key. |
| CSettingsStore::CreateKey | Opens the specified key or creates it if it does not exist. |
| CSettingsStore::DeleteKey | Deletes the specified key and all its children. |
| CSettingsStore::DeleteValue | Deletes the specified value of the open key. |
| CSettingsStore::Open | Opens the specified key. |
| CSettingsStore::Read | Retrieves the data for a specified key value. |
| CSettingsStore::Write | Writes a value to the registry under the open key. |
Remarks
The member functions CreateKey and Open are very similar. If the registry key already exists, CreateKey and Open function in the same way. However, if the registry key does not exist, CreateKey will create it whereas Open will return an error value.
Example
The following example demonstrates how to use the Open and Read methods of the CSettingsStore class. This code snippet is part of the Tool Tip Demo sample.
CSettingsStore reg(FALSE, TRUE);
DWORD dwEnableBalloonTips = 1;
if (reg.Open(_T("Software\\Microsoft\\Windows\\CurrentVersion\\Explorer\\Advanced")) &&
reg.Read(_T("EnableBalloonTips"), dwEnableBalloonTips))
{
return dwEnableBalloonTips == 1;
}
Inheritance Hierarchy
CSettingsStore
Requirements
Header: afxsettingsstore.h
CSettingsStore::Close
Closes the open registry key.
virtual void Close();
Remarks
By default, this method is called from the destructor of the CSettingsStore Class.
CSettingsStore::CreateKey
Opens a registry key or creates it if it does not exist.
virtual BOOL CreateKey(LPCTSTR pszPath);
Parameters
pszPath
[in] Specifies the name of a key to be created or opened.
Return Value
0 if successful; otherwise a nonzero value.
Remarks
CreateKey uses m_hKey as the root of registry inquiries. It searches for pszPath as a subkey of m_hKey. If the key does not exist, CreateKey creates it. Otherwise, it opens the key. CreateKey then sets m_hKey to the created or opened key.
CSettingsStore::CSettingsStore
Creates a CSettngsStore object.
CSettingsStore(
BOOL bAdmin,
BOOL bReadOnly);
Parameters
bAdmin
[in] Boolean parameter that specifies whether the CSettingsStore object is acting in administrator mode.
bReadOnly
[in] Boolean parameter that specifies whether the CSettingsStore object is created in read-only mode.
Remarks
If bAdmin is set to TRUE, the m_hKey member variable is set to HKEY_LOCAL_MACHINE. If you set bAdmin to FALSE, m_hKey is set to HKEY_CURRENT_USER.
The security access depends on the bReadOnly parameter. If bReadonly is FALSE, the security access will be set to KEY_ALL_ACCESS. If bReadyOnly is TRUE, the security access will be set to a combination of KEY_QUERY_VALUE, KEY_NOTIFY and KEY_ENUMERATE_SUB_KEYS. For more information about security access together with the registry, see Registry Key Security and Access Rights.
The destructor for CSettingsStore releases m_hKey automatically.
CSettingsStore::DeleteKey
Deletes a key and all its children from the registry.
virtual BOOL DeleteKey(
LPCTSTR pszPath,
BOOL bAdmin = FALSE);
Parameters
pszPath
[in] The name of the key to delete.
bAdmin
[in] Switch that specifies the location of the key to delete.
Return Value
Nonzero if successful; otherwise 0.
Remarks
This method will fail if the CSettingsStore object is in read-only mode.
If the parameter bAdmin is zero, DeleteKey searches for the key to delete under HKEY_CURRENT_USER. If bAdmin is nonzero, DeleteKey searches for the key to delete under HKEY_LOCAL_MACHINE.
CSettingsStore::DeleteValue
Deletes a value from m_hKey.
virtual BOOL DeleteValue(LPCTSTR pszValue);
Parameters
pszValue
[in] Specifies the value field to remove.
Return Value
Nonzero if successful; otherwise 0.
CSettingsStore::Open
Opens a registry key.
virtual BOOL Open(LPCTSTR pszPath);
Parameters
pszPath
[in] The name of a registry key.
Return Value
Nonzero if successful; otherwise 0.
Remarks
After this method successfully opens the specified key, it sets m_hKey to the handle of this key.
CSettingsStore::Read
Reads a value from a key in the registry.
virtual BOOL Read(
LPCTSTR pszKey,
int& iVal);
virtual BOOL Read(
LPCTSTR pszKey,
DWORD& dwVal);
virtual BOOL Read(
LPCTSTR pszKey,
CString& sVal);
virtual BOOL Read(
LPCTSTR pszKey,
CStringList& scStringList);
virtual BOOL Read(
LPCTSTR pszKey,
CStringArray& scArray);
virtual BOOL Read(
LPCTSTR pszKey,
CDWordArray& dwcArray);
virtual BOOL Read(
LPCTSTR pszKey,
CWordArray& wcArray);
virtual BOOL Read(
LPCTSTR pszKey,
CByteArray& bcArray);
virtual BOOL Read(
LPCTSTR pszKey,
LPPOINT& lpPoint);
virtual BOOL Read(
LPCTSTR pszKey,
CRect& rect);
virtual BOOL Read(
LPCTSTR pszKey,
BYTE** ppData,
UINT* pBytes);
virtual BOOL Read(
LPCTSTR pszKey,
CObList& list);
virtual BOOL Read(
LPCTSTR pszKey,
CObject& obj);
virtual BOOL Read(
LPCTSTR pszKey,
CObject*& pObj);
Parameters
pszKey
[in] Pointer to a null-terminated string that contains the name of the value to read from the registry.
iVal
[out] Reference to an integer variable that receives the value read from the registry key.
dwVal
[out] Reference to a 32-bit double word variable that receives the value read from the registry key.
sVal
[out] Reference to a string variable that receives the value read from the registry key.
scStringList
[out] Reference to a string list variable that receives the value read from the registry key.
scArray
[out] Reference to a string array variable that receives the value read from the registry key.
dwcArray
[out] Reference to a 32-bit double word array variable that receives the value read from the registry key.
wcArray
[out] Reference to a 16-bit word array variable that receives the value read from the registry key.
bcArray
[out] Reference to a byte array variable that receives the value read from the registry key.
lpPoint
[out] Reference to a pointer to a POINT structure that receives the value read from the registry key.
rect
[out] Reference to a CRect variable that receives the value read from the registry key.
ppData
[out] Pointer to a pointer to data that receives the value read from the registry key.
pBytes
[out] Pointer to an unsigned integer variable. This variable receives the size of the buffer that ppData points to.
list
[out] Reference to a CObList variable that receives the value read from the registry key.
obj
[out] Reference to a CObject variable that receives the value read from the registry key.
pObj
[out] Reference to a pointer to a CObject variable that receives the value read from the registry key.
Return Value
Nonzero if successful; otherwise 0.
Remarks
Read checks for pszKey as a subkey of m_hKey.
CSettingsStore::Write
Writes a value to the registry under the open key.
virtual BOOL Write(
LPCTSTR pszKey,
int iVal);
virtual BOOL Write(
LPCTSTR pszKey,
DWORD dwVal);
virtual BOOL Write(
LPCTSTR pszKey,
LPCTSTR pszVal);
virtual BOOL Write(
LPCTSTR pszKey,
CStringList& scStringList);
virtual BOOL Write(
LPCTSTR pszKey,
CByteArray& bcArray);
virtual BOOL Write(
LPCTSTR pszKey,
CStringArray& scArray);
virtual BOOL Write(
LPCTSTR pszKey,
CDWordArray& dwcArray);
virtual BOOL Write(
LPCTSTR pszKey,
CWordArray& wcArray);
virtual BOOL Write(
LPCTSTR pszKey,
const CRect& rect);
virtual BOOL Write(
LPCTSTR pszKey,
LPPOINT& lpPoint);
virtual BOOL Write(
LPCTSTR pszKey,
LPBYTE pData,
UINT nBytes);
virtual BOOL Write(
LPCTSTR pszKey,
CObList& list);
virtual BOOL Write(
LPCTSTR pszKey,
CObject& obj);
virtual BOOL Write(
LPCTSTR pszKey,
CObject* pObj);
Parameters
pszKey
[in] Pointer to a string that contains the name of the value to set.
iVal
[in] Reference to an integer variable that contains the data to store.
dwVal
[in] Reference to a 32-bit double word variable that contains the data to store.
pszVal
[in] Pointer to a null-terminated string variable that contains the data to store.
scStringList
[in] Reference to a CStringList variable that contains the data to store.
bcArray
[in] Reference to a byte array variable that contains the data to store.
scArray
[in] Reference to a string array variable that contains the data to store.
dwcArray
[in] Reference to a 32-bit double word array variable that contains the data to store.
wcArray
[in] Reference to a 16-bit word array variable that contains the data to store.
rect
[in] Reference to a CRect variable that contains the data to store.
lpPoint
[in] Reference to a pointer to a POINT variable that contains the data to store.
pData
[in] Pointer to a buffer that contains the data to store.
nBytes
[in] Specifies the size, in bytes, of the data to which the pData parameter points.
list
[in] Reference to a CObList variable that contains the data to store.
obj
[in] Reference to a CObject variable that contains the data to store.
pObj
[in] Pointer to a pointer to a CObject variable that contains the data to store.
Return Value
TRUE if successful; otherwise FALSE.
Remarks
In order to write to the registry, you must set bReadOnly to a nonzero value when you create a CSettingsStore object. For more information, see CSettingsStore::CSettingsStore.
See also
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for