RegSetValueExA 函式 (winreg.h)

發行項
03/04/2024

在登錄機碼下設定指定值的數據和類型。

語法

LSTATUS RegSetValueExA(
  [in]           HKEY       hKey,
  [in, optional] LPCSTR     lpValueName,
                 DWORD      Reserved,
  [in]           DWORD      dwType,
  [in]           const BYTE *lpData,
  [in]           DWORD      cbData
);

參數

[in] hKey

開啟登錄機碼的句柄。金鑰必須已以KEY_SET_VALUE訪問許可權開啟。如需詳細資訊，請參閱登錄機碼安全性和訪問許可權。

RegCreateKeyEx、RegCreateKeyTransacted、RegOpenKeyEx 或 RegOpenKeyTransacted 函式會傳回此句柄。它也可以是下列其中一個預先定義的金鑰：

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_USERS

此函式的 Unicode 版本支援下列額外的預先定義索引鍵：

HKEY_PERFORMANCE_TEXT
HKEY_PERFORMANCE_NLSTEXT

[in, optional] lpValueName

要設定的值名稱。如果此名稱的值尚未出現在機碼中，函式會將它新增至索引鍵。

如果 lpValueName 為 NULL 或空字串 “”，則函式會設定索引鍵未命名或預設值的類型和數據。

如需詳細資訊，請參閱登錄專案大小限制。

登錄機碼沒有預設值，但它們可以有一個未命名的值，可以是任何類型的值。

Reserved

此參數是保留的，而且必須是零。

[in] dwType

lpData 參數所指向的數據類型。如需可能類型的清單，請參閱登錄實值類型。

[in] lpData

要儲存的資料。

對於字串型別，例如 REG_SZ，字串必須以 Null 結尾。使用REG_MULTI_SZ數據類型時，字串必須以兩 個 Null 字元終止。

注意 lpData，指出 null 值有效，不過，如果是這種情況， cbData 必須設定為 '0'。

[in] cbData

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

傳回值

如果函式成功，傳回值會ERROR_SUCCESS。

如果函式失敗，傳回值是 Winerror.h 中定義的非零錯誤碼。您可以使用 FormatMessage 函式搭配 FORMAT_MESSAGE_FROM_SYSTEM 旗標來取得錯誤的泛型描述。

備註

值大小受限於可用的記憶體。不過，將大型值儲存在登錄中可能會影響其效能。長值 (超過 2,048 個字節) 應該儲存為檔案，並儲存在登錄中的檔案位置。

圖示、點陣圖和可執行檔等應用程式元素應該儲存為檔案，而不會放在登錄中。

如果 dwType 是REG_SZ、REG_MULTI_SZ或REG_EXPAND_SZ類型，而且此函式的 ANSI 版本是使用 (，方法是明確呼叫 RegSetValueExA 或未定義 UNICODE，再包含 Windows.h 檔案 ) ，lpData 參數所指向的數據必須是 ANSI 字符字串。字串會先轉換成 Unicode，再儲存在登錄中。

請注意，存取特定登錄機碼的作業會重新導向。如需詳細資訊，請參閱登錄中的登錄虛擬化和 32 位和 64 位應用程式數據。

請考慮使用 RegSetKeyValue 函式，以提供更方便的方式來設定登錄機碼的值。

注意

winreg.h 標頭會將 RegSetValueEx 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

規格需求

需求	值
最低支援的用戶端	Windows 2000 專業版 [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平台	Windows
標頭	winreg.h (包括 Windows.h)
程式庫	Advapi32.lib
Dll	Advapi32.dll