`CRegKey` 類別

發行項
07/05/2024

這個類別提供在系統登錄中操作專案的方法。

重要

這個類別及其成員不能用於在 Windows 執行階段中執行的應用程式。

語法

class CRegKey

成員

公用建構函式

名稱	描述
`CRegKey::CRegKey`	建構函式。
`CRegKey::~CRegKey`	解構函式。

公用方法

名稱	描述
`CRegKey::Attach`	呼叫這個方法，將成員句柄設定`m_hKey`為，將 HKEY 附加至 `CRegKey` `hKey`物件。
`CRegKey::Close`	呼叫此方法以釋放成員句柄， `m_hKey` 並將它設定為 `NULL`。
`CRegKey::Create`	如果指定的索引鍵不存在為的子機碼，請呼叫這個方法來建立指定的索引鍵 `hKeyParent`。
`CRegKey::DeleteSubKey`	呼叫這個方法，以從登錄中移除指定的機碼。
`CRegKey::DeleteValue`	呼叫這個方法，以從 `m_hKey`中移除值欄位。
`CRegKey::Detach`	呼叫這個方法，將成員句柄與物件中斷連結 `m_hKey` ， `CRegKey` 並將設定 `m_hKey` 為 `NULL`。
`CRegKey::EnumKey`	呼叫此方法以列舉開啟登錄機碼的子機碼。
`CRegKey::Flush`	呼叫這個方法，將開啟登錄機碼的所有屬性寫入登錄機碼。
`CRegKey::GetKeySecurity`	呼叫這個方法，以擷取保護開啟登錄機碼的安全性描述元複本。
`CRegKey::NotifyChangeKeyValue`	這個方法會通知呼叫者變更開啟登錄機碼的屬性或內容。
`CRegKey::Open`	呼叫這個方法以開啟指定的索引鍵，並將設定 `m_hKey` 為此密鑰的句柄。
`CRegKey::QueryBinaryValue`	呼叫這個方法，以擷取指定值名稱的二進位數據。
`CRegKey::QueryDWORDValue`	呼叫此方法以擷取 `DWORD` 指定值名稱的數據。
`CRegKey::QueryGUIDValue`	呼叫這個方法，以擷取指定值名稱的 GUID 數據。
`CRegKey::QueryMultiStringValue`	呼叫這個方法，以擷取指定值名稱的多字串數據。
`CRegKey::QueryQWORDValue`	呼叫此方法以擷取 `QWORD` 指定值名稱的數據。
`CRegKey::QueryStringValue`	呼叫這個方法，以擷取指定值名稱的字串數據。
`CRegKey::QueryValue`	呼叫這個方法，以擷取指定值欄位 `m_hKey`的數據。不再支援舊版的這個方法，並標示為 `ATL_DEPRECATED`。
`CRegKey::RecurseDeleteKey`	呼叫這個方法，從登錄中移除指定的機碼，並明確移除任何子機碼。
`CRegKey::SetBinaryValue`	呼叫此方法以設定登錄機碼的二進位值。
`CRegKey::SetDWORDValue`	呼叫此方法以設定 `DWORD` 登錄機碼的值。
`CRegKey::SetGUIDValue`	呼叫此方法以設定登錄機碼的 GUID 值。
`CRegKey::SetKeySecurity`	呼叫此方法以設定登錄機碼的安全性。
`CRegKey::SetKeyValue`	呼叫這個方法，將數據儲存在指定索引鍵的指定值欄位中。
`CRegKey::SetMultiStringValue`	呼叫此方法以設定登錄機碼的多字串值。
`CRegKey::SetQWORDValue`	呼叫此方法以設定 `QWORD` 登錄機碼的值。
`CRegKey::SetStringValue`	呼叫此方法以設定登錄機碼的字串值。
`CRegKey::SetValue`	呼叫這個方法，將數據儲存在的指定值欄位中 `m_hKey`。不再支援舊版的這個方法，並標示為 `ATL_DEPRECATED`。

公用運算子

名稱	描述
`CRegKey::operator HKEY`	將 `CRegKey` 物件轉換成 `HKEY`。
`CRegKey::operator =`	指派運算子。

公用資料成員

名稱	描述
`CRegKey::m_hKey`	包含與 `CRegKey` 對象相關聯的登錄機碼句柄。
`CRegKey::m_pTM`	`CAtlTransactionManager`物件的指標

備註

CRegKey 提供在系統登錄中建立和刪除機碼和值的方法。登錄包含系統元件的安裝特定定義集，例如軟體版本號碼、已安裝硬體的邏輯對實體對應，以及 COM 物件。

CRegKey 提供指定電腦之系統登錄的程式設計介面。例如，若要開啟特定的登錄機碼，請呼叫 CRegKey::Open。若要分別擷取或修改資料值，請分別呼叫 CRegKey::QueryValue 或 CRegKey::SetValue。若要關閉索引鍵，請呼叫 CRegKey::Close。

當您關閉機碼時，其登錄數據會寫入硬碟（已排清）。這個程序可能需要幾秒鐘。如果您的應用程式必須明確地將登錄數據寫入硬碟，您可以呼叫 RegFlushKey Win32 函式。不過，會使用許多系統資源， RegFlushKey 而且只有在絕對必要時才應該呼叫。

重要

允許呼叫端指定登錄位置的任何方法，都有可能讀取無法信任的數據。使用 RegQueryValueEx 的方法應考慮此函式不會明確處理以 Null 終止的字串。呼叫程式代碼應該檢查這兩個條件。

需求

頁眉： atlbase.h

`CRegKey::Attach`

呼叫這個方法，將成員句柄設定m_hKey為，以附加HKEY至 CRegKey hKey物件。

void Attach(HKEY hKey) throw();

參數

hKey
登錄機碼的句柄。

備註

Attach 如果 m_hKey 不是，NULL將會判斷提示。

`CRegKey::Close`

呼叫此方法以釋放成員句柄， m_hKey 並將它設定為 NULL。

LONG Close() throw();

傳回值

如果成功，會傳 ERROR_SUCCESS回，否則會傳回錯誤值。

`CRegKey::Create`

如果指定的索引鍵不存在為的子機碼，請呼叫這個方法來建立指定的索引鍵 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();

參數

hKeyParent
開啟索引鍵的句柄。

lpszKeyName
指定要建立或開啟之金鑰的名稱。此名稱必須是的 hKeyParent子機碼。

lpszClass
指定要建立或開啟之索引鍵的類別。預設值為 REG_NONE。

dwOptions
索引鍵的選項。預設值是 REG_OPTION_NON_VOLATILE。如需可能的值和描述清單，請參閱 RegCreateKeyEx Windows SDK。

samDesired
金鑰的安全性存取。預設值是 KEY_READ | KEY_WRITE。如需可能的值和描述清單，請參閱 RegCreateKeyEx。

lpSecAttr
結構的指標 SECURITY_ATTRIBUTES ，指出子進程是否可以繼承索引鍵的句柄。根據預設，此參數為 NULL （表示無法繼承句柄）。

lpdwDisposition
[out]如果不是NULL，則擷取或擷取 REG_CREATED_NEW_KEY （如果索引鍵不存在且已建立）或 REG_OPENED_EXISTING_KEY （如果索引鍵存在且已開啟）。

傳回值

如果成功，會傳 ERROR_SUCCESS 回並開啟密鑰。如果方法失敗，傳回值是中 WINERROR.H定義的非零錯誤碼。

備註

Create 會將 m_hKey 成員設定為此索引鍵的句柄。

`CRegKey::CRegKey`

建構函式。

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

參數

key
對 CRegKey 物件的參考。

hKey
登錄機碼的句柄。

pTM
CAtlTransactionManager物件的指標

備註

建立新的 CRegKey 物件。物件可以從現有的 CRegKey 物件，或從登錄機碼的句柄建立。

`CRegKey::~CRegKey`

解構函式。

~CRegKey() throw();

備註

解構函式會 m_hKey釋放。

`CRegKey::DeleteSubKey`

呼叫這個方法，以從登錄中移除指定的機碼。

LONG DeleteSubKey(LPCTSTR lpszSubKey) throw();

參數

lpszSubKey
指定要刪除的索引鍵名稱。此名稱必須是的 m_hKey子機碼。

傳回值

如果成功，則傳回 ERROR_SUCCESS。如果方法失敗，傳回值是中 WINERROR.H定義的非零錯誤碼。

備註

DeleteSubKey 只能刪除沒有子機碼的索引鍵。如果機碼有子機碼，請改為呼叫 RecurseDeleteKey 。

`CRegKey::DeleteValue`

呼叫這個方法，以從 m_hKey中移除值欄位。

LONG DeleteValue(LPCTSTR lpszValue) throw();

參數

lpszValue
指定要移除的值欄位。

傳回值

如果成功，則傳回 ERROR_SUCCESS。如果方法失敗，傳回值是中 WINERROR.H定義的非零錯誤碼。

`CRegKey::Detach`

呼叫這個方法，將成員句柄與物件中斷連結 m_hKey ， CRegKey 並將設定 m_hKey 為 NULL。

HKEY Detach() throw();

傳回值

與 CRegKey 對象相關聯的 HKEY。

`CRegKey::EnumKey`

呼叫此方法以列舉開啟登錄機碼的子機碼。

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

參數

iIndex
子機碼索引。第一次呼叫時，此參數應該是零，然後針對後續呼叫遞增

pszName
接收子機碼名稱之緩衝區的指標，包括終止的 Null 字元。只有子機碼的名稱會複製到緩衝區，而不是完整金鑰階層。

pnNameLength
指定參數所pszName指定之緩衝區大小之TCHARs變數的指標。這個大小應該包含終止的 Null 字元。方法傳回時，所 pnNameLength 指向的變數會包含儲存在緩衝區中的字元數。傳回的計數不包含終止的 Null 字元。

pftLastWriteTime
接收上次寫入列舉子機碼時間之變數的指標。

傳回值

如果方法成功，傳回值為 ERROR_SUCCESS。如果方法失敗，傳回值是中 WINERROR.H定義的非零錯誤碼。

備註

若要列舉子機碼，請使用零的索引呼叫 CRegKey::EnumKey 。遞增索引值並重複，直到方法傳 ERROR_NO_MORE_ITEMS回為止。如需詳細資訊，請參閱 RegEnumKeyEx Windows SDK 中的。

`CRegKey::Flush`

呼叫這個方法，將開啟登錄機碼的所有屬性寫入登錄機碼。

LONG Flush() throw();

傳回值

如果方法成功，傳回值為 ERROR_SUCCESS。如果方法失敗，傳回值是中 WINERROR.H定義的非零錯誤碼。

備註

如需詳細資訊，請參閱 RegEnumFlush Windows SDK 中的。

`CRegKey::GetKeySecurity`

呼叫這個方法，以擷取保護開啟登錄機碼的安全性描述元複本。

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

參數

si
SECURITY_INFORMATION值，表示要求的安全性資訊。

psd
接收所要求之安全性描述元複本之緩衝區的指標。

pnBytes
所 psd指向之緩衝區的大小，以位元組為單位。

傳回值

如果方法成功，傳回值為 ERROR_SUCCESS。如果方法失敗，傳回值是中 WINERROR.H定義的非零錯誤碼。

備註

如需詳細資訊，請參閱RegGetKeySecurity。

`CRegKey::m_hKey`

包含與 CRegKey 對象相關聯的登錄機碼句柄。

HKEY m_hKey;

`CRegKey::m_pTM`

指向 CAtlTransactionManager 物件的指標。

CAtlTransactionManager* m_pTM;

備註

`CRegKey::NotifyChangeKeyValue`

這個方法會通知呼叫者變更開啟登錄機碼的屬性或內容。

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

參數

bWatchSubtree
指定旗標，指出是否要報告指定索引鍵及其所有子機碼中的變更，或只在指定的索引鍵中報告變更。如果此參數為 TRUE，則方法會報告索引鍵及其子機碼中的變更。如果參數為 FALSE，則方法只會報告索引鍵中的變更。

dwNotifyFilter
指定一組旗標，控制應該報告哪些變更。此參數可以是下列值的組合：

值	意義
`REG_NOTIFY_CHANGE_NAME`	如果新增或刪除子機碼，請通知呼叫端。
`REG_NOTIFY_CHANGE_ATTRIBUTES`	通知呼叫端密鑰屬性的變更，例如安全性描述元資訊。
`REG_NOTIFY_CHANGE_LAST_SET`	通知呼叫端對索引鍵值所做的變更。這包括新增或刪除值，或變更現有的值。
`REG_NOTIFY_CHANGE_SECURITY`	通知呼叫端金鑰之安全性描述元的變更。

hEvent
事件的控制代碼。 bAsync如果參數為 TRUE，則方法會立即傳回，並透過發出此事件的訊號來報告變更。如果 bAsync 為 FALSE， hEvent 則會忽略。

bAsync
指定旗標，指出方法報告變更的方式。如果此參數為 TRUE，則方法會立即傳回，併發出指定事件的訊號來報告變更。當此參數為 FALSE時，方法不會傳回，直到發生變更為止。如果未 hEvent 指定有效的事件， bAsync 參數就不能是 TRUE。

傳回值

如果方法成功，傳回值為 ERROR_SUCCESS。如果方法失敗，傳回值是中 WINERROR.H定義的非零錯誤碼。

備註

注意

如果刪除指定的索引鍵，這個方法不會通知呼叫端。

如需詳細資訊和範例程式，請參閱 RegNotifyChangeKeyValue。

`CRegKey::Open`

呼叫這個方法以開啟指定的索引鍵，並將設定 m_hKey 為此密鑰的句柄。

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

參數

hKeyParent
開啟索引鍵的句柄。

lpszKeyName
指定要建立或開啟之金鑰的名稱。此名稱必須是的 hKeyParent子機碼。

samDesired
金鑰的安全性存取。預設值是 KEY_ALL_ACCESS。如需可能的值和描述清單，請參閱 RegCreateKeyEx Windows SDK。

傳回值

如果成功，會傳 ERROR_SUCCESS回，否則為中 WINERROR.H定義的非零錯誤值。

備註

lpszKeyName如果參數是 NULL 或指向空字串，請開啟所hKeyParent識別之索引鍵的新句柄，Open但不會關閉任何先前開啟的句柄。

不同於 CRegKey::Create， Open 如果指定的索引鍵不存在，則不會建立指定的索引鍵。

`CRegKey::operator HKEY`

將 CRegKey 物件轉換成 HKEY。

operator HKEY() const throw();

`CRegKey::operator =`

指派運算子。

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

參數

key
要複製的金鑰。

傳回值

傳回新索引鍵的參考。

備註

這個運算符會 key 與其目前對象中斷連結，並改為將它指派給 CRegKey 物件。

`CRegKey::QueryBinaryValue`

呼叫這個方法，以擷取指定值名稱的二進位數據。

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

參數

pszValueName
NULL包含要查詢之值名稱之終止字串的指標。

pValue
接收值數據之緩衝區的指標。

pnBytes
變數的指標，指定參數所 pValue 指向之緩衝區的大小，以位元組為單位。當方法傳回時，這個變數會包含複製到緩衝區的數據大小。

傳回值

如果方法成功， ERROR_SUCCESS 則會傳回。如果方法無法讀取值，它會傳回中 WINERROR.H定義的非零錯誤碼。如果參考的資料不是型 REG_BINARY別， ERROR_INVALID_DATA 則會傳回。

備註

這個方法會使用 RegQueryValueEx 並確認傳回正確的數據類型。如需詳細資訊，請參閱 RegQueryValueEx。

重要

這個方法可讓呼叫端指定任何登錄位置，並可能讀取無法信任的數據。此外， RegQueryValueEx 這個方法所使用的函式不會明確處理以 Null 結尾的字串。呼叫程式代碼應該檢查這兩個條件。

`CRegKey::QueryDWORDValue`

呼叫此方法以擷取 DWORD 指定值名稱的數據。

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

參數

pszValueName
NULL包含要查詢之值名稱之終止字串的指標。

dwValue
接收之緩衝區的 DWORD指標。

傳回值

如果方法成功， ERROR_SUCCESS 則會傳回。如果方法無法讀取值，它會傳回中 WINERROR.H定義的非零錯誤碼。如果參考的資料不是型 REG_DWORD別， ERROR_INVALID_DATA 則會傳回。

備註

這個方法會使用 RegQueryValueEx 並確認傳回正確的數據類型。如需詳細資訊，請參閱 RegQueryValueEx。

重要

`CRegKey::QueryGUIDValue`

呼叫這個方法，以擷取指定值名稱的 GUID 數據。

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

參數

pszValueName
NULL包含要查詢之值名稱之終止字串的指標。

guidValue
接收 GUID 之變數的指標。

傳回值

如果方法成功， ERROR_SUCCESS 則會傳回。如果方法無法讀取值，它會傳回中 WINERROR.H定義的非零錯誤碼。如果參考的資料不是有效的 GUID， ERROR_INVALID_DATA 則會傳回。

備註

這個方法會使用 CRegKey::QueryStringValue ，並使用將字串轉換成 GUID CLSIDFromString。

重要

這個方法可讓呼叫端指定任何登錄位置，並可能讀取無法信任的數據。

`CRegKey::QueryMultiStringValue`

呼叫這個方法，以擷取指定值名稱的多字串數據。

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

參數

pszValueName
NULL包含要查詢之值名稱之終止字串的指標。

pszValue
接收多字串數據的緩衝區指標。多字串是以兩個 Null 字元結尾的 NULL字串數位。

pnChars
在中 TCHARs，由所 pszValue指向之緩衝區的大小。當方法傳回時， pnChars 會包含擷取之多字串的大小 TCHARs，包括終止的 Null 字元。

傳回值

如果方法成功， ERROR_SUCCESS 則會傳回。如果方法無法讀取值，它會傳回中 WINERROR.H定義的非零錯誤碼。如果參考的資料不是型 REG_MULTI_SZ別， ERROR_INVALID_DATA 則會傳回。

備註

這個方法會使用 RegQueryValueEx 並確認傳回正確的數據類型。如需詳細資訊，請參閱 RegQueryValueEx。

重要

`CRegKey::QueryQWORDValue`

呼叫此方法以擷取 QWORD 指定值名稱的數據。

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

參數

pszValueName
NULL包含要查詢之值名稱之終止字串的指標。

qwValue
接收之緩衝區的 QWORD指標。

傳回值

如果方法成功， ERROR_SUCCESS 則會傳回。如果方法無法讀取值，它會傳回中 WINERROR.H定義的非零錯誤碼。如果參考的資料不是型 REG_QWORD別， ERROR_INVALID_DATA 則會傳回。

備註

這個方法會使用 RegQueryValueEx 並確認傳回正確的數據類型。如需詳細資訊，請參閱 RegQueryValueEx。

重要

`CRegKey::QueryStringValue`

呼叫這個方法，以擷取指定值名稱的字串數據。

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

參數

pszValueName
NULL包含要查詢之值名稱之終止字串的指標。

pszValue
接收字串數據的緩衝區指標。

pnChars
以 TCHAR 表示之緩衝區 pszValue的大小。當方法傳回時， pnChars 會包含所擷取字串的大小 TCHARs，包括終止的 Null 字元。

傳回值

如果方法成功， ERROR_SUCCESS 則會傳回。如果方法無法讀取值，它會傳回中 WINERROR.H定義的非零錯誤碼。如果參考的資料不是型 REG_SZ別， ERROR_INVALID_DATA 則會傳回。如果方法傳 ERROR_MORE_DATA回， pnChars 則等於零，而不是位元組中所需的緩衝區大小。

備註

這個方法會使用 RegQueryValueEx 並確認傳回正確的數據類型。如需詳細資訊，請參閱 RegQueryValueEx。

重要

`CRegKey::QueryValue`

呼叫這個方法，以擷取指定值欄位 m_hKey的數據。不再支援舊版的這個方法，並標示為 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);

參數

pszValueName
NULL包含要查詢之值名稱之終止字串的指標。如果 pszValueName 是 NULL 或空字串， ""則方法會擷取索引鍵未命名或預設值的類型和數據，如果有的話。

pdwType
接收程式代碼的變數指標，指出儲存在指定值中的數據類型。 pdwType如果不需要型別程式代碼，則參數可以是 NULL 。

pData
接收值數據之緩衝區的指標。如果不需要資料，這個參數可以是 NULL 。

pnBytes
變數的指標，指定參數所 pData 指向之緩衝區的大小，以位元組為單位。當方法傳回時，這個變數會包含複製到 pData的數據大小。

dwValue
值欄位的數值數據。

lpszValueName
指定要查詢的值欄位。

szValue
值欄位的字串數據。

pdwCount
字串數據的大小。其值一開始會設定為緩衝區的大小 szValue 。

傳回值

如果成功，會傳 ERROR_SUCCESS回，否則為中 WINERROR.H定義的非零錯誤碼。

備註

不再支援和的兩個原始版本 QueryValue ，會標示為 ATL_DEPRECATED。如果使用這些窗體，編譯程式將會發出警告。

其餘的方法會呼叫 RegQueryValueEx。

重要

`CRegKey::RecurseDeleteKey`

呼叫這個方法，從登錄中移除指定的機碼，並明確移除任何子機碼。

LONG RecurseDeleteKey(LPCTSTR lpszKey) throw();

參數

lpszKey
指定要刪除的索引鍵名稱。此名稱必須是的 m_hKey子機碼。

傳回值

如果成功，會傳 ERROR_SUCCESS回，否則為中 WINERROR.H定義的非零錯誤值。

備註

如果機碼有子機碼，您必須呼叫此方法來刪除密鑰。

`CRegKey::SetBinaryValue`

呼叫此方法以設定登錄機碼的二進位值。

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

參數

pszValueName
字串的指標，其中包含要設定的值名稱。如果這個名稱的值尚未存在，方法會將它新增至索引鍵。

pValue
緩衝區的指標，其中包含要以指定值名稱儲存的數據。

nBytes
指定參數所 pValue 指向之資訊的大小，以位元組為單位。

傳回值

如果方法成功，傳回值為 ERROR_SUCCESS。如果方法失敗，傳回值是中 WINERROR.H定義的非零錯誤碼。

備註

這個方法會使用 RegSetValueEx 將值寫入登錄。

`CRegKey::SetDWORDValue`

呼叫此方法以設定 DWORD 登錄機碼的值。

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

參數

pszValueName
字串的指標，其中包含要設定的值名稱。如果這個名稱的值尚未存在，方法會將它新增至索引鍵。

dwValue
要 DWORD 以指定值名稱儲存的數據。

傳回值

如果方法成功，傳回值為 ERROR_SUCCESS。如果方法失敗，傳回值是中 WINERROR.H定義的非零錯誤碼。

備註

這個方法會使用 RegSetValueEx 將值寫入登錄。

`CRegKey::SetGUIDValue`

呼叫此方法以設定登錄機碼的 GUID 值。

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

參數

pszValueName
字串的指標，其中包含要設定的值名稱。如果這個名稱的值尚未存在，方法會將它新增至索引鍵。

guidValue
要以指定值名稱儲存之 GUID 的參考。

傳回值

如果方法成功，傳回值為 ERROR_SUCCESS。如果方法失敗，傳回值是中 WINERROR.H定義的非零錯誤碼。

備註

這個方法會使用 CRegKey::SetStringValue GUID，並使用 StringFromGUID2將 GUID 轉換成字串。

`CRegKey::SetKeyValue`

呼叫這個方法，將數據儲存在指定索引鍵的指定值欄位中。

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

參數

lpszKeyName
指定要建立或開啟之金鑰的名稱。此名稱必須是的 m_hKey子機碼。

lpszValue
指定要儲存的數據。這個參數必須是非NULL 。

lpszValueName
指定要設定的值欄位。如果具有此名稱的值欄位尚未存在於索引鍵中，則會新增。

傳回值

如果成功，會傳 ERROR_SUCCESS回，否則為中 WINERROR.H定義的非零錯誤碼。

備註

呼叫此方法以建立或開啟索引鍵， lpszKeyName 並將數據儲存 lpszValue 在 lpszValueName 值欄位中。

`CRegKey::SetKeySecurity`

呼叫此方法以設定登錄機碼的安全性。

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

參數

si
指定要設定之安全性描述元的元件。此值可以是下列值的組合：

值	意義
`DACL_SECURITY_INFORMATION`	設定金鑰的任意存取控制清單（DACL）。密鑰必須具有 `WRITE_DAC` 存取權，或者呼叫進程必須是對象的擁有者。
`GROUP_SECURITY_INFORMATION`	設定金鑰的主要群組安全組識別碼（SID）。密鑰必須具有 `WRITE_OWNER` 存取權，或者呼叫進程必須是對象的擁有者。
`OWNER_SECURITY_INFORMATION`	設定金鑰的擁有者 SID。密鑰必須具有 `WRITE_OWNER` 存取權，或者呼叫進程必須是對象的擁有者或 `SE_TAKE_OWNERSHIP_NAME` 已啟用許可權。
`SACL_SECURITY_INFORMATION`	設定金鑰的系統存取控制清單（SACL）。金鑰必須具有 `ACCESS_SYSTEM_SECURITY` 存取權。取得此存取權的適當方式是在呼叫端目前的存取令牌中啟用`SE_SECURITY_NAME`許可權、開啟存取句`ACCESS_SYSTEM_SECURITY`柄，然後停用許可權。

psd
SECURITY_DESCRIPTOR結構的指標，指定要為指定之索引鍵設定的安全性屬性。

傳回值

如果方法成功，傳回值為 ERROR_SUCCESS。如果方法失敗，傳回值是中 WINERROR.H定義的非零錯誤碼。

備註

設定金鑰的安全性屬性。如需詳細資訊，請參閱 RegSetKeySecurity。

`CRegKey::SetMultiStringValue`

呼叫此方法以設定登錄機碼的多字串值。

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

參數

pszValueName
字串的指標，其中包含要設定的值名稱。如果這個名稱的值尚未存在，方法會將它新增至索引鍵。

pszValue
要以指定值名稱儲存之多字串數據的指標。多字串是以兩個 Null 字元結尾的 NULL字串數位。

傳回值

如果方法成功，傳回值為 ERROR_SUCCESS。如果方法失敗，傳回值是中 WINERROR.H定義的非零錯誤碼。

備註

這個方法會使用 RegSetValueEx 將值寫入登錄。

`CRegKey::SetQWORDValue`

呼叫此方法以設定 QWORD 登錄機碼的值。

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

參數

pszValueName
字串的指標，其中包含要設定的值名稱。如果這個名稱的值尚未存在，方法會將它新增至索引鍵。

qwValue
要 QWORD 以指定值名稱儲存的數據。

傳回值

如果方法成功，傳回值為 ERROR_SUCCESS。如果方法失敗，傳回值是中 WINERROR.H定義的非零錯誤碼。

備註

這個方法會使用 RegSetValueEx 將值寫入登錄。

`CRegKey::SetStringValue`

呼叫此方法以設定登錄機碼的字串值。

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

參數

pszValueName
字串的指標，其中包含要設定的值名稱。如果這個名稱的值尚未存在，方法會將它新增至索引鍵。

pszValue
要以指定值名稱儲存之字串數據的指標。

dwType
要寫入登錄的字串類型： REG_SZ [預設值] 或 REG_EXPAND_SZ [多字串]。

傳回值

如果方法成功，傳回值為 ERROR_SUCCESS。如果方法失敗，傳回值是中 WINERROR.H定義的非零錯誤碼。

備註

這個方法會使用 RegSetValueEx 將值寫入登錄。

`CRegKey::SetValue`

呼叫這個方法，將數據儲存在的指定值欄位中 m_hKey。不再支援舊版的這個方法，並標示為 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);

參數

pszValueName
字串的指標，其中包含要設定的值名稱。如果索引鍵中還沒有具有這個名稱的值，方法會將它新增至索引鍵。如果 pszValueName 是 NULL 或空字串， ""則方法會設定索引鍵未命名或預設值的類型和數據。

dwType
指定程式代碼，指出參數所 pValue 指向的數據類型。

pValue
緩衝區的指標，其中包含要以指定值名稱儲存的數據。

nBytes
指定參數所 pValue 指向之資訊的大小，以位元組為單位。如果數據的類型 REG_SZ為、 REG_EXPAND_SZ或 REG_MULTI_SZ， nBytes 則必須包含終止 Null 字元的大小。

hKeyParent
開啟索引鍵的句柄。

lpszKeyName
指定要建立或開啟之金鑰的名稱。此名稱必須是的 hKeyParent子機碼。

lpszValue
指定要儲存的數據。這個參數必須是非NULL 。

lpszValueName
指定要設定的值欄位。如果具有此名稱的值欄位尚未存在於索引鍵中，則會新增。

dwValue
指定要儲存的數據。

bMulti
如果為 false，表示字串的類型為 REG_SZ。如果為 true，表示字串是類型的 REG_MULTI_SZ多字串。

nValueLen
如果 bMulti 為 true， nValueLen 則為字元中的字串長度 lpszValue 。如果 bMulti 為 false，則值為 -1 表示方法會自動計算長度。

傳回值

如果成功，會傳 ERROR_SUCCESS回，否則為中 WINERROR.H定義的非零錯誤碼。

備註

的兩個原始版本 SetValue 標示為 ATL_DEPRECATED ，不應再使用。如果使用這些窗體，編譯程式將會發出警告。

第三個方法會呼叫 RegSetValueEx。

另請參閱

DCOM 範例
 類別概觀

共用方式為

CRegKey 類別

語法

成員

公用建構函式

公用方法

公用運算子

公用資料成員

備註

需求

CRegKey::Attach

參數

備註

CRegKey::Close

傳回值

CRegKey::Create

參數

傳回值

備註

CRegKey::CRegKey

參數

備註

CRegKey::~CRegKey

備註

CRegKey::DeleteSubKey

參數

傳回值

備註

CRegKey::DeleteValue

參數

傳回值

CRegKey::Detach

傳回值

CRegKey::EnumKey

參數

傳回值

備註

CRegKey::Flush

傳回值

備註

CRegKey::GetKeySecurity

參數

傳回值

備註

CRegKey::m_hKey

CRegKey::m_pTM

備註

CRegKey::NotifyChangeKeyValue

參數

傳回值

備註

CRegKey::Open

參數

傳回值

備註

CRegKey::operator HKEY

CRegKey::operator =

參數

傳回值

備註

CRegKey::QueryBinaryValue

參數

傳回值

備註

CRegKey::QueryDWORDValue

參數

傳回值

備註

CRegKey::QueryGUIDValue

參數

傳回值

備註

CRegKey::QueryMultiStringValue

參數

傳回值

備註

CRegKey::QueryQWORDValue

參數

傳回值

備註

`CRegKey` 類別

`CRegKey::Attach`

`CRegKey::Close`

`CRegKey::Create`

`CRegKey::CRegKey`

`CRegKey::~CRegKey`

`CRegKey::DeleteSubKey`

`CRegKey::DeleteValue`

`CRegKey::Detach`

`CRegKey::EnumKey`

`CRegKey::Flush`

`CRegKey::GetKeySecurity`

`CRegKey::m_hKey`

`CRegKey::m_pTM`

`CRegKey::NotifyChangeKeyValue`

`CRegKey::Open`

`CRegKey::operator HKEY`

`CRegKey::operator =`

`CRegKey::QueryBinaryValue`

`CRegKey::QueryDWORDValue`

`CRegKey::QueryGUIDValue`

`CRegKey::QueryMultiStringValue`

`CRegKey::QueryQWORDValue`

`CRegKey::QueryStringValue`

`CRegKey::QueryValue`

`CRegKey::RecurseDeleteKey`

`CRegKey::SetBinaryValue`

`CRegKey::SetDWORDValue`

`CRegKey::SetGUIDValue`

`CRegKey::SetKeyValue`

`CRegKey::SetKeySecurity`

`CRegKey::SetMultiStringValue`

`CRegKey::SetQWORDValue`

`CRegKey::SetStringValue`

`CRegKey::SetValue`