RegGetValueA 函式 (winreg.h)
擷取指定之登錄值的型別和資料。
語法
LSTATUS RegGetValueA(
[in] HKEY hkey,
[in, optional] LPCSTR lpSubKey,
[in, optional] LPCSTR lpValue,
[in, optional] DWORD dwFlags,
[out, optional] LPDWORD pdwType,
[out, optional] PVOID pvData,
[in, out, optional] LPDWORD pcbData
);
參數
[in] hkey
開啟登錄機碼的控制碼。 金鑰必須已以KEY_QUERY_VALUE存取權限開啟。 如需詳細資訊，請參閱 登錄機碼安全性和存取權限。
RegCreateKeyEx、RegCreateKeyTransacted、RegOpenKeyEx 或 RegOpenKeyTransacted函式會傳回此控制碼。 它也可以是下列其中一個 預先定義的索引鍵：
- HKEY_CLASSES_ROOT
- HKEY_CURRENT_CONFIG
- HKEY_CURRENT_USER
- HKEY_LOCAL_MACHINE
- HKEY_PERFORMANCE_DATA
- HKEY_PERFORMANCE_NLSTEXT
- HKEY_PERFORMANCE_TEXT
- HKEY_USERS
[in, optional] lpSubKey
相對於 hkey 參數所指定之機碼的登錄機碼路徑。 此子機碼會擷取登錄值。
路徑不區分大小寫。
如果此參數為 Null 或空字串 「」，則會從 hkey 本身指定的索引鍵讀取值。
[in, optional] lpValue
登錄值的名稱。
如果此參數為 Null 或空字串 「」，則函式會擷取索引鍵未命名或預設值的類型和資料，如果有的話。 索引鍵不會自動具有未命名或預設值，且未命名的值可以是任何類型的值。
如需詳細資訊，請參閱 登錄專案大小限制。
[in, optional] dwFlags
旗標，限制要查詢之值的資料類型。 如果值的資料類型不符合此準則，則函式會失敗。 此參數可以是下列一或多個值。
此參數也可以包含下列一或多個值。
| 值 | 意義 |
|---|---|
|
如果值的類型為 REG_EXPAND_SZ，請勿自動展開環境字串。 |
|
如果 pvData 不是 Null，請在失敗時將緩衝區的內容設定為零。 |
|
如果 lpSubKey 不是 Null，請開啟 lpSubKey 以KEY_WOW64_64KEY存取權限指定的子機碼。
如需這些存取權限的相關資訊，請參閱 登錄機碼安全性和存取權限。
您無法搭配 RRF_SUBKEY_WOW6432KEY 來指定 RRF_SUBKEY_WOW6464KEY。 |
|
如果 lpSubKey 不是 Null，請開啟 lpSubKey 以KEY_WOW64_32KEY存取權限指定的子機碼。
如需這些存取權限的相關資訊，請參閱 登錄機碼安全性和存取權限。
您無法搭配 RRF_SUBKEY_WOW6464KEY 來指定 RRF_SUBKEY_WOW6432KEY。 |
[out, optional] pdwType
變數的指標，接收程式碼，指出儲存在指定值中的資料類型。 如需可能的類型代碼清單，請參閱 登錄實值型別。 如果不需要類型，這個參數可以是 Null 。
[out, optional] pvData
接收值資料之緩衝區的指標。 如果不需要資料，這個參數可以是 Null 。
如果資料是字串，函式會檢查是否有終止 的 Null 字元。 如果找不到字串，如果緩衝區夠大，以容納額外的字元，則會以 Null 結束字元儲存字串。 否則，函式會失敗並傳回ERROR_MORE_DATA。
[in, out, optional] pcbData
變數的指標，指定 pvData 參數所指向的緩衝區大小，以位元組為單位。 當函式傳回時，此變數會包含複製到 pvData的資料大小。
只有當pvData為 Null 時，才能將它設定為Null。
如果資料具有REG_SZ、REG_MULTI_SZ或REG_EXPAND_SZ類型，則此大小包含任何終止 的 Null 字元或字元。 如需詳細資訊，請參閱＜備註＞。
如果 pvData 參數指定的緩衝區不夠大，無法保存資料，函式會傳回ERROR_MORE_DATA，並將所需的緩衝區大小儲存在 由指向的變數中。 在此情況下，如果 dwFlags 指定RRF_ZEROONFAILURE且未定義， pvData 緩衝區的內容會是零。
如果 pvData 為 Null，且 其為 非Null，則函式會傳回ERROR_SUCCESS，並將資料的大小以位元組為單位儲存在 由 azureData指向的變數中。 這可讓應用程式判斷為值資料配置緩衝區的最佳方式。
如果 hKey 指定 HKEY_PERFORMANCE_DATA ，且 pvData 緩衝區不夠大，無法包含所有傳回的資料，則函式會傳回ERROR_MORE_DATA，而且透過 ERROR_MORE_DATA 傳回的值未定義。 這是因為效能資料的大小可以從一個呼叫變更為下一個呼叫。 在此情況下，您必須增加緩衝區大小，並再次呼叫 RegGetValue ，以傳遞 在 azureData 參數中更新的緩衝區大小。 重複此動作，直到函式成功為止。 您需要維護個別的變數，以追蹤緩衝區大小，因為 無法預測由 azuredata 傳回的值。
傳回值
如果函式成功，傳回值會ERROR_SUCCESS。
如果函式失敗，則傳回值是 系統錯誤碼。
如果 pvData 緩衝區太小而無法接收值，函式會傳回ERROR_MORE_DATA。
如果 lpValue 登錄值不存在，函式會傳回ERROR_FILE_NOT_FOUND。
如果 dwFlags 同時指定 RRF_SUBKEY_WOW6464KEY 和 RRF_SUBKEY_WOW6432KEY的組合，則函式會傳回ERROR_INVALID_PARAMETER。
備註
應用程式通常會呼叫 RegEnumValue 來判斷值名稱，然後 RegGetValue 來擷取名稱的資料。
如果資料具有REG_SZ、REG_MULTI_SZ或REG_EXPAND_SZ類型，而且此函式的 ANSI 版本是藉由明確呼叫 RegGetValueA 或未定義 UNICODE，或在包含 Windows.h) 檔案之前未定義 UNICODE，則此函式會在將預存的 Unicode 字串複製到 pvData所指向的緩衝區之前，先 (將預存的 Unicode 字串轉換成 ANSI 字串。
呼叫此函式時，將 hkey設定為HKEY_PERFORMANCE_DATA控制碼和指定物件的值字串時，傳回的資料結構有時會有未查詢的物件。 不要意外;這是一般行為。 您應該一律會預期會逐步執行傳回的資料結構，以尋找要求的物件。
請注意，存取特定登錄機碼的作業會重新導向。 如需詳細資訊，請參閱登錄中的登錄虛擬化和 32 位和 64 位應用程式資料。
若要編譯使用此函式的應用程式，請將_WIN32_WINNT定義為0x0600或更新版本。 如需詳細資訊，請參閱 使用 Windows 標頭。
注意
winreg.h 標頭會將 RegGetValue 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程式碼，可能會導致編譯或執行時間錯誤不符。 如需詳細資訊，請參閱 函式原型的慣例。
規格需求
| 最低支援的用戶端 | Windows Vista、Windows XP Professional x64 Edition |
| 最低支援的伺服器 | Windows Server 2008、Windows Server 2003 SP1 |
| 目標平臺 | Windows |
| 標頭 | winreg.h (包括 Windows.h) |
| 程式庫 | Advapi32.lib |
| DLL | Advapi32.dll |