RegQueryMultipleValuesA 函式 (winreg.h)
擷取與開啟登錄機碼相關聯之值名稱清單的類型和資料。
語法
LSTATUS RegQueryMultipleValuesA(
[in] HKEY hKey,
[out] PVALENTA val_list,
[in] DWORD num_vals,
[out, optional] LPSTR lpValueBuf,
[in, out, optional] LPDWORD ldwTotsize
);
參數
[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_USERS
[out] val_list
陣列的指標
描述一或多個值專案的VALENT結構。 在輸入時,每個結構的 ve_valuename 成員都必須包含要擷取之值名稱的指標。 如果指定的值不存在於指定的索引鍵中,則函式會失敗。
如果函式成功,陣列的每個元素都會包含指定值的資訊。
[in] num_vals
val_list陣列中的專案數目。
[out, optional] lpValueBuf
緩衝區的指標。 如果函式成功,緩衝區會接收每個值的資料。
如果 lpValueBuf 為 Null, ldwTotsize 參數所指向的值必須是零,在此情況下,函式會傳回ERROR_MORE_DATA ldwTotsize 接收所需的緩衝區大小,以位元組為單位。
[in, out, optional] ldwTotsize
變數的指標,指定 lpValueBuf 參數所指向的緩衝區大小,以位元組為單位。 如果函式成功, ldwTotsize 會收到複製到緩衝區的位元組數目。 如果函式因為緩衝區太小而失敗, ldwTotsize 會收到所需的大小,以位元組為單位。
傳回值
如果函式成功,傳回值會ERROR_SUCCESS。
如果函式失敗,傳回值就是下列其中一個錯誤碼。
傳回碼 | 描述 |
---|---|
|
RegQueryMultipleValues 無法具現化或存取動態金鑰的提供者。 |
|
lpValueBuf指向的緩衝區太小。 在此情況下, ldwTotsize 會收到所需的緩衝區大小。 |
|
要求的資料大小總計 (val_list 陣列 + ldwTotSize) 的大小超過一 MB 的系統限制。 |
備註
RegQueryMultipleValues函式可讓應用程式查詢靜態或動態索引鍵的一或多個值。 如果目標索引鍵是靜態索引鍵,系統會以不可部分完成的方式提供所有值。 若要防止過度序列化,函數傳回的匯總資料不能超過一 MB。
如果目標索引鍵是動態索引鍵,則其提供者必須以不可部分完成的方式提供所有值。 這表示提供者應該同步填入結果緩衝區,同時提供緩衝區中所有值的一致檢視,同時避免過度序列化。 提供者可以在此函式的不可部分完成呼叫期間,提供最多一 MB 的總輸出資料。
遠端支援RegQueryMultipleValues;也就是說,傳遞至函式的hKey參數可以參考遠端電腦。
注意
winreg.h 標頭會根據 UNICODE 預處理器常數的定義,將 RegQueryMultipleValues 定義為別名,自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程式碼,可能會導致編譯或執行時間錯誤不符。 如需詳細資訊,請參閱 函式原型的慣例。
規格需求
最低支援的用戶端 | Windows 2000 Professional [僅限傳統型應用程式] |
最低支援的伺服器 | Windows 2000 Server [僅限桌面應用程式] |
目標平台 | Windows |
標頭 | winreg.h (包含 Windows.h) |
程式庫 | Advapi32.lib |
Dll | Advapi32.dll |