RegEnumValueA 函式 (winreg.h)

發行項
08/27/2023

列舉指定之開啟登錄機碼的值。函式會在每次呼叫索引鍵時，複製一個索引值名稱和資料區塊。

語法

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