RegQueryValueA 函式（winreg.h）

發行項
11/20/2024

擷取與指定登錄機碼之預設或未命名值相關聯的數據。數據必須是 null終止字串。

注意此函式僅供與 16 位版本的 Windows 相容。應用程式應該使用 RegQueryValueEx 函式。

語法

LSTATUS RegQueryValueA(
  [in]                HKEY   hKey,
  [in, optional]      LPCSTR lpSubKey,
  [out, optional]     LPSTR  lpData,
  [in, out, optional] PLONG  lpcbData
);

參數

[in] hKey

開啟登錄機碼的句柄。金鑰必須使用KEY_QUERY_VALUE訪問許可權開啟。如需詳細資訊，請參閱登入機碼安全性和存取權限。

此句柄是由 RegCreateKeyEx、RegCreateKeyTransacted、RegOpenKeyEx或 RegOpenKeyTransacted 函式所傳回。它也可以是下列其中一個預先定義的索引鍵：

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_USERS

[in, optional] lpSubKey

擷取預設值之 hKey 參數的子機碼名稱。

索引鍵名稱不區分大小寫。

如果此參數 NULL 或指向空字串，則函式會擷取由 hKey識別的索引鍵預設值。

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

[out, optional] lpData

接收指定索引鍵之預設值之緩衝區的指標。

如果 lpValue 為 NULL，且 l 為非NULL，則函式會傳回ERROR_SUCCESS，並以位元組為單位儲存數據的大小，以位元組為單位，以 lusbValue所指向的變數中。這可讓應用程式判斷為值數據配置緩衝區的最佳方式。

[in, out, optional] lpcbData

變數的指標，指定 lpValue 參數所指向的緩衝區大小，以位元組為單位。當函式傳回時，此變數會包含複製到 lpValue的數據大小，包括任何終止 null 字元。

如果數據具有REG_SZ、REG_MULTI_SZ或REG_EXPAND_SZ類型，則此大小包含任何終止 null 字元或字元。如需詳細資訊，請參閱。

如果指定的緩衝區 lpValue 不夠大而無法保存數據，函式會傳回ERROR_MORE_DATA，並將所需的緩衝區大小儲存在 l所指向的變數中。在此情況下，未定義 lpValue 緩衝區的內容。

傳回值

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

如果函式失敗，傳回值是系統錯誤碼。

如果 lpValue 緩衝區太小而無法接收值，函式會傳回ERROR_MORE_DATA。

言論

如果使用此函式的 ANSI 版本（藉由明確呼叫 RegQueryValueA，或是在包含 Windows.h 檔案之前未定義 UNICODE，則此函式會將預存的 Unicode 字串轉換為 ANSI 字串串，然後再將它複製到 lpValue 參數指定的緩衝區。

如果數據具有REG_SZ、REG_MULTI_SZ或REG_EXPAND_SZ類型，字串可能尚未以適當的 null終止字元儲存。因此，即使函式傳回ERROR_SUCCESS，應用程式也應該確保字串在使用之前已正確終止;否則，它可能會覆寫緩衝區。（請注意，REG_MULTI_SZ字串應該有兩個 null-terminating 字元。

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

注意

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

要求

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