RegEnumValueA 函式 (winreg.h)
列舉指定之開啟登錄機碼的值。 函式會在每次呼叫索引鍵時,複製一個索引值名稱和資料區塊。
語法
LSTATUS RegEnumValueA(
[in] HKEY hKey,
[in] DWORD dwIndex,
[out] LPSTR lpValueName,
[in, out] LPDWORD lpcchValueName,
LPDWORD lpReserved,
[out, optional] LPDWORD lpType,
[out, optional] LPBYTE lpData,
[in, out, optional] LPDWORD lpcbData
);
參數
[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
[in] dwIndex
要擷取之值的索引。 第一次呼叫 RegEnumValue 函式時,此參數應該是零,然後針對後續呼叫遞增。
因為值未排序,所以任何新值都會有任意索引。 這表示函式可以依任何順序傳回值。
[out] lpValueName
緩衝區的指標,接收值的名稱做為 Null終止字串。
這個緩衝區必須夠大,才能包含終止 的 Null 字元。
如需詳細資訊,請參閱 登錄專案大小限制。
[in, out] lpcchValueName
變數的指標,指定 lpValueName 參數所指向的緩衝區大小,以字元表示。 當函式傳回時,變數會收到儲存在緩衝區中的字元數,不包括終止 的 Null 字元。
如果 lpValueName 指定的緩衝區不足以保存資料,則函式會傳回ERROR_MORE_DATA, 而且 lpValueName 所指向之變數中的緩衝區大小不會變更。 在此情況下, 未定義 lpcchValueName 的內容。
登錄值名稱限制為 32,767 個位元組。 此函式的 ANSI 版本會將此參數視為 SHORT 值。 因此,如果您指定大於 32,767 個位元組的值,就會發生溢位,而且函式可能會傳回ERROR_MORE_DATA。
lpReserved
此參數是保留的,而且必須是 Null。
[out, optional] lpType
接收程式碼的變數指標,指出儲存在指定值中的資料類型。 如需可能的類型代碼清單,請參閱 登錄實數值型別。 如果不需要類型代碼, lpType 參數可以是 Null 。
[out, optional] lpData
接收值專案資料的緩衝區指標。 如果不需要資料,此參數可以是 Null 。
如果 lpData 為 Null 且 lusbData 為非Null,則函式會將資料的大小儲存在 lusbData所指向的變數中,以位元組為單位。 這可讓應用程式判斷為數據配置緩衝區的最佳方式。
[in, out, optional] lpcbData
變數的指標,指定 lpData 參數所指向的緩衝區大小,以位元組為單位。 當函式傳回時,變數會接收儲存在緩衝區中的位元組數目。
只有當lpData為Null時,此參數才能為Null。
如果資料具有REG_SZ、REG_MULTI_SZ或REG_EXPAND_SZ類型,則此大小會包含任何終止 的 Null 字元或字元。 如需詳細資訊,請參閱<備註>。
如果 lpData 指定的緩衝區不夠大,無法保存資料,則函式會傳回ERROR_MORE_DATA,並將所需的緩衝區大小儲存在 lーData所指向的變數中。 在此情況下, lpData 的內容未定義。
傳回值
如果函式成功,傳回值會ERROR_SUCCESS。
如果函式失敗,則傳回值是 系統錯誤碼。 如果沒有其他可用的值,函式會傳回ERROR_NO_MORE_ITEMS。
如果 lpValueName 或 lpData 指定的緩衝區太小而無法接收值,則函式會傳回ERROR_MORE_DATA。
備註
若要列舉值,應用程式一開始應該呼叫 RegEnumValue 函式, 並將 dwIndex 參數設定為零。 然後,應用程式應該遞增 dwIndex 並呼叫 RegEnumValue 函式,直到函式傳回ERROR_NO_MORE_ITEMS) 為止, (沒有其他值。
應用程式也可以在第一次呼叫函式時,將 dwIndex 設定為最後一個值的索引,並遞減索引,直到列舉具有索引 0 的值為止。 若要擷取最後一個值的索引,請使用 RegQueryInfoKey 函式。
使用 RegEnumValue時,應用程式不應該呼叫任何可能會變更所查詢金鑰的登錄函式。
如果資料具有REG_SZ、REG_MULTI_SZ或REG_EXPAND_SZ類型,字串可能尚未以適當的 null終止字元儲存。 因此,即使函式傳回ERROR_SUCCESS,應用程式也應該確保字串在使用之前已正確終止;否則,它可能會覆寫緩衝區。 (請注意,REG_MULTI_SZ字串應該有兩個 null終止字元。)
若要判斷名稱和資料緩衝區的大小上限,請使用 RegQueryInfoKey 函式。
注意
在舊版 Windows 上,此 API 也會由 kernel32.dll 公開。
範例
如需範例,請參閱 列舉登錄子機碼。
注意
winreg.h 標頭會將 RegEnumValue 定義為別名,根據 UNICODE 預處理器常數的定義,自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程式碼,可能會導致編譯或執行時間錯誤不符。 如需詳細資訊,請參閱 函式原型的慣例。
規格需求
最低支援的用戶端 | Windows 2000 專業版 [僅限傳統型應用程式] |
最低支援的伺服器 | Windows 2000 Server [僅限傳統型應用程式] |
目標平台 | Windows |
標頭 | winreg.h (包括 Windows.h) |
程式庫 | Advapi32.lib |
Dll | Advapi32.dll |