RegEnumKeyExA 函式（winreg.h）

發行項
11/20/2024

列舉指定之開啟登錄機碼的子機碼。函式會在每次呼叫子機碼時擷取一個子機碼的相關信息。

語法

LSTATUS RegEnumKeyExA(
  [in]                HKEY      hKey,
  [in]                DWORD     dwIndex,
  [out]               LPSTR     lpName,
  [in, out]           LPDWORD   lpcchName,
                      LPDWORD   lpReserved,
  [in, out]           LPSTR     lpClass,
  [in, out, optional] LPDWORD   lpcchClass,
  [out, optional]     PFILETIME lpftLastWriteTime
);

參數

[in] hKey

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

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

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_PERFORMANCE_DATA

HKEY_USERS

[in] dwIndex

要擷取之子機碼的索引。第一次呼叫 RegEnumKeyEx 函式時，此參數應該是零，然後針對後續呼叫遞增。

因為子機碼不會排序，因此任何新的子機碼都會有任意索引。這表示函式可以依任何順序傳回子機碼。

[out] lpName

接收子機碼名稱之緩衝區的指標，包括終止 null 字元。函式只會將子機碼的名稱，而非完整金鑰階層複製到緩衝區。

如果函式失敗，則不會將任何資訊複製到此緩衝區。

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

[in, out] lpcchName

變數的指標，以字元為單位，指定 lpName 參數所指定的緩衝區大小。此大小應包含終止 null 字元。如果函式成功，lpcchName 所指向的變數 包含儲存在緩衝區中的字元數，不包括終止 null 字元。

若要判斷所需的緩衝區大小，請使用 RegQueryInfoKey 函式來判斷 hKey 參數所識別之索引鍵的最大子機碼大小。

lpReserved

此參數是保留的，而且必須 NULL。

[in, out] lpClass

接收列舉子機碼之使用者定義類別之緩衝區的指標。此參數可以是 NULL。

[in, out, optional] lpcchClass

變數的指標，以字元指定 lpClass 參數所指定的緩衝區大小。大小應包含終止 null 字元。如果函式成功，lpcchClass 包含儲存在緩衝區中的字元數，不包括終止 null 字元。只有當 lpClassNULL時，這個參數才能 NULL。

[out, optional] lpftLastWriteTime

FILETIME 結構的指標，會接收上次寫入列舉子機碼的時間。此參數可以是 NULL。

傳回值

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

如果函式失敗，傳回值是系統錯誤碼。如果沒有可用的子機碼，函式會傳回ERROR_NO_MORE_ITEMS。

如果 lpName 緩衝區太小而無法接收索引鍵的名稱，則函式會傳回ERROR_MORE_DATA。

言論

若要列舉子機碼，應用程式應該一開始呼叫 RegEnumKeyEx 函式，並將 dwIndex 參數設定為零。然後，應用程式應該遞增 dwIndex dwIndex 參數，並呼叫 RegEnumKeyEx，直到沒有其他子機碼（這表示函式會傳回ERROR_NO_MORE_ITEMS）。

應用程式也可以將 dwIndex 設定為函式第一次呼叫時最後一個子機碼的索引，並遞減索引，直到列舉索引 0 的子機碼為止。若要擷取最後一個子機碼的索引，請使用 RegQueryInfoKey 函式。

當應用程式使用 RegEnumKeyEx 函式時，它不應該呼叫任何可能變更所列舉密鑰的註冊函式。

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

注意

在舊版 Windows 上，此 API 也會由 kernel32.dll公開。

例子

如需範例，請參閱列舉登錄子機碼。

注意

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

要求

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