RegCreateKeyA 函式 (winreg.h)
建立指定的登錄機碼。 如果機碼已存在於登錄中,函式就會開啟它。
語法
LSTATUS RegCreateKeyA(
[in] HKEY hKey,
[in, optional] LPCSTR lpSubKey,
[out] PHKEY phkResult
);
參數
[in] hKey
開啟登錄機碼的句柄。 呼叫進程必須KEY_CREATE_SUB_KEY密鑰的存取權。 如需詳細資訊,請參閱 登錄機碼安全性和訪問許可權。
系統會根據登錄機碼的安全性描述元檢查密鑰建立的存取權,而不是取得句柄時所指定的存取掩碼。 因此,即使 hKey 是以 KEY_READ samDesired 開啟,它仍可在建立密鑰的作業中使用,如果安全性描述元允許的話。
RegCreateKeyEx 或 RegOpenKeyEx 函式會傳回此句柄,或者它可以是下列其中一個預先定義的索引鍵:
- HKEY_CLASSES_ROOT
- HKEY_CURRENT_CONFIG
- HKEY_CURRENT_USER
- HKEY_LOCAL_MACHINE
- HKEY_USERS
[in, optional] lpSubKey
此函式開啟或建立的索引鍵名稱。 此機碼必須是 hKey 參數所識別之索引鍵的子機碼。
如需機碼名稱的詳細資訊,請參閱 登錄的結構。
如果 hKey 是其中一個預先定義的金鑰, lpSubKey 可能是 NULL。 在此情況下, phkResult 會收到傳入函式的相同 hKey 句柄。
[out] phkResult
接收已開啟或已建立索引鍵句柄之變數的指標。 如果機碼不是其中一個預先定義的登錄機碼,請在您使用句柄完成之後呼叫 RegCloseKey 函式。
傳回值
如果函式成功,傳回值會ERROR_SUCCESS。
如果函式失敗,傳回值是 Winerror.h 中定義的非零錯誤碼。 您可以使用 FormatMessage 函式搭配 FORMAT_MESSAGE_FROM_SYSTEM 旗標來取得錯誤的泛型描述。
備註
應用程式無法建立直接 子 系HKEY_USERS或 HKEY_LOCAL_MACHINE的密鑰。 應用程式可以在較低層級的 HKEY_USERS 或 HKEY_LOCAL_MACHINE 樹狀結構中建立子機碼。
如果您的服務或應用程式模擬不同的使用者,請勿將此函式與 HKEY_CURRENT_USER搭配使用。 請改為呼叫 RegOpenCurrentUser 函式。
RegCreateKey 函式會在指定的路徑中建立所有遺漏的索引鍵。 應用程式可以利用此行為一次建立數個金鑰。 例如,應用程式可以針對 lpSubKey 參數指定下列格式的字串,同時建立與上述三個子機碼相同的子機碼四個層級:
subkey1\subkey2\subkey3\subkey4
請注意,如果路徑中的現有索引鍵拼字不正確,此行為將會導致建立不必要的索引鍵。
注意
winreg.h 標頭會根據 UNICODE 預處理器常數的定義,將 RegCreateKey 定義為別名,自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼,可能會導致編譯或運行時間錯誤不符。 如需詳細資訊,請參閱 函式原型的慣例。
規格需求
需求 | 值 |
---|---|
最低支援的用戶端 | Windows 2000 專業版 [僅限傳統型應用程式] |
最低支援的伺服器 | Windows 2000 Server [僅限傳統型應用程式] |
目標平台 | Windows |
標頭 | winreg.h (包括 Windows.h) |
程式庫 | Advapi32.lib |
Dll | Advapi32.dll |