RegSetValueExA 函式（winreg.h）

發行項
11/20/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-terminated。使用 REG_MULTI_SZ 數據類型時，字串必須以兩個 null 字元終止。

Note 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，或是在包含 Windows.h 檔案之前未定義 UNICODE，則 lpData 參數所指向的數據必須是 ANSI 字符字串。字串會先轉換成 Unicode，再儲存在登錄中。

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

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

注意

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

要求

要求	價值
最低支援的用戶端	Windows 2000 Professional [僅限傳統型應用程式]
支援的最低伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平臺	窗戶
標頭	winreg.h （包括 Windows.h）
連結庫	Advapi32.lib
DLL	Advapi32.dll