RegOpenKeyExA 函式 (winreg.h)

發行項
03/13/2024

開啟指定的登錄機碼。請注意，索引鍵名稱不區分大小寫。

若要在機碼上執行交易登錄作業，請呼叫 RegOpenKeyTransacted 函式。

語法

LSTATUS RegOpenKeyExA(
  [in]           HKEY   hKey,
  [in, optional] LPCSTR lpSubKey,
  [in]           DWORD  ulOptions,
  [in]           REGSAM samDesired,
  [out]          PHKEY  phkResult
);

參數

[in] hKey

開啟登錄機碼的句柄。 RegCreateKeyEx 或 RegOpenKeyEx 函式會傳回此句柄，或者它可以是下列其中一個預先定義的索引鍵：

HKEY_CLASSES_ROOTHKEY_CURRENT_CONFIGHKEY_CURRENT_USERHKEY_LOCAL_MACHINE HKEY_USERS

[in, optional] lpSubKey

要開啟的登錄子機碼名稱。

索引鍵名稱不區分大小寫。

如果 lpSubKey 參數為 NULL 或空字串的指標，且 hKey 是預先定義的索引鍵，則系統會重新整理預先定義的索引鍵，而 phkResult 會接收傳遞至函式的相同 hKey 句柄。否則， phkResult 會收到已開啟密鑰的新句柄。

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

[in] ulOptions

指定開啟機碼時要套用的選項。將此參數設定為零或下列專案：

值	意義
REG_OPTION_OPEN_LINK	索引鍵是符號連結。只有在絕對必要時，才應該使用登錄符號連結。

[in] samDesired

遮罩，指定要開啟金鑰的所需訪問許可權。如果密鑰的安全性描述元不允許呼叫進程的要求存取權，函式就會失敗。如需詳細資訊，請參閱登錄機碼安全性和訪問許可權。

[out] phkResult

接收已開啟索引鍵句柄之變數的指標。如果機碼不是其中一個預先定義的登錄機碼，請在您使用句柄完成之後呼叫 RegCloseKey 函式。

傳回值

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

如果函式失敗，傳回值是 Winerror.h 中定義的非零錯誤碼。您可以使用 FormatMessage 函式搭配 FORMAT_MESSAGE_FROM_SYSTEM 旗標來取得錯誤的泛型描述。

注意

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

備註

不同於 RegCreateKeyEx 函式，如果機碼不存在於登錄中， RegOpenKeyEx 函式就不會建立指定的機碼。

某些登錄作業會針對金鑰的安全性描述元執行存取檢查，而不是取得密鑰句柄時所指定的存取掩碼。例如，即使使用 samDesired 開啟金鑰，KEY_READ，如果密鑰的安全性描述元允許，它仍可用來建立登錄機碼。相反地， RegSetValueEx 函式特別需要以KEY_SET_VALUE存取權開啟密鑰。

如果您的服務或應用程式模擬不同的使用者，請勿將此函式與 HKEY_CURRENT_USER搭配使用。請改為呼叫 RegOpenCurrentUser 函式。

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

範例

lResult = RegOpenKeyEx (hKeyRoot, lpSubKey, 0, KEY_READ, &hKey);

if (lResult != ERROR_SUCCESS) 
{
    if (lResult == ERROR_FILE_NOT_FOUND) {
        printf("Key not found.\n");
        return TRUE;
    } 
    else {
        printf("Error opening key.\n");
        return FALSE;
    }
}

若要查看內容中的這個範例，請參閱使用子機碼刪除索引鍵。

注意

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

規格需求

需求	值
最低支援的用戶端	Windows 2000 專業版 [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平台	Windows
標頭	winreg.h (包括 Windows.h)
程式庫	Advapi32.lib
Dll	Advapi32.dll