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

CObject

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

Hierarchy Chart
Classes
CWinAppEx Class