共用方式為

RegCreateKeyExA 函式 （winreg.h）

  • 發行項

建立指定的登錄機碼。 如果索引鍵已經存在，函式就會開啟它。 請注意，索引鍵名稱不區分大小寫。

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

備份或還原系統狀態的應用程式，包括系統檔案和登錄區，應該使用 磁碟區陰影複製服務，而不是登錄功能。

語法

LSTATUS RegCreateKeyExA(
  [in]            HKEY                        hKey,
  [in]            LPCSTR                      lpSubKey,
                  DWORD                       Reserved,
  [in, optional]  LPSTR                       lpClass,
  [in]            DWORD                       dwOptions,
  [in]            REGSAM                      samDesired,
  [in, optional]  const LPSECURITY_ATTRIBUTES lpSecurityAttributes,
  [out]           PHKEY                       phkResult,
  [out, optional] LPDWORD                     lpdwDisposition
);

參數

[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] lpSubKey

此函式開啟或建立的子機碼名稱。 指定的子機碼必須是 hKey 參數所識別之索引鍵的子機碼;在登錄樹狀結構中，最多可以有32個層級。 如需金鑰名稱的詳細資訊，請參閱登錄結構 。

如果 lpSubKey 是空字串的指標，phkResult 會接收由 hKey所指定之索引鍵的新句柄。

這個參數不能 NULL。

Reserved

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

[in, optional] lpClass

這個索引鍵的使用者定義類別類型。 這個參數可能會忽略。 此參數可以是 NULL。

[in] dwOptions

此參數可以是下列其中一個值。

價值 意義
REG_OPTION_BACKUP_RESTORE
0x000000004L
 如果已設定此旗標，函式會忽略 samDesired 參數，並嘗試開啟具有備份或還原密鑰所需存取權的密鑰。 如果呼叫線程已啟用SE_BACKUP_NAME許可權，則會使用ACCESS_SYSTEM_SECURITY開啟密鑰，並KEY_READ訪問許可權。 如果呼叫線程已啟用SE_RESTORE_NAME許可權，從 Windows Vista 開始，金鑰會以ACCESS_SYSTEM_SECURITY、DELETE 和KEY_WRITE訪問許可權開啟。 如果啟用這兩個許可權，金鑰會同時擁有這兩個許可權的合併訪問許可權。 如需詳細資訊，請參閱 以特殊許可權執行。
REG_OPTION_CREATE_LINK
0x000000002L
注意： 登錄符號連結只有在絕對 必要 時，才應該用於應用程式相容性。
 
此索引鍵是符號連結。 目標路徑會指派給機碼的 L“SymbolicLinkValue” 值。 目標路徑必須是絕對登錄路徑。
REG_OPTION_NON_VOLATILE
0x00000000L
 此索引鍵不是揮發性;這是預設值。 信息會儲存在檔案中，並在系統重新啟動時保留。 RegSaveKey 函式會儲存非揮發性的索引鍵。
REG_OPTION_VOLATILE
0x000000001L
 函式所建立的所有索引鍵都是揮發性的。 此資訊會儲存在記憶體中，而且不會在卸除對應的登錄區時保留。 針對 HKEY_LOCAL_MACHINE，只有在系統起始完整關機時，才會發生此情況。 針對由 RegLoadKey 函式載入的登錄機碼，當執行對應的 RegUnLoadKey 時，就會發生這種情況。 RegSaveKey 函式不會儲存揮發性索引鍵。 已存在的索引鍵會忽略此旗標。
注意 在用戶選取的關機時，快速啟動關機是系統的默認行為。
 

[in] samDesired

遮罩，指定要建立之密鑰的訪問許可權。 如需詳細資訊，請參閱 登入機碼安全性和存取權限。

[in, optional] lpSecurityAttributes

SECURITY_ATTRIBUTES 結構的指標，決定傳回的句柄是否可以由子進程繼承。 如果 lpSecurityAttributesNULL，則無法繼承句柄。

lpSecurityDescriptor 結構的成員會指定新密鑰的安全性描述元。 如果 lpSecurityAttributesNULL，則密鑰會取得預設的安全性描述元。 密鑰的預設安全性描述元中的 ACL 會繼承自其直接父金鑰。

[out] phkResult

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

[out, optional] lpdwDisposition

接收下列其中一個處置值的變數指標。

價值 意義
REG_CREATED_NEW_KEY
0x000000001L
 金鑰不存在且已建立。
REG_OPENED_EXISTING_KEY
0x000000002L
 機碼已存在，而且只是開啟而不變更。
 

如果 lpdwDispositionNULL，則不會傳回處置資訊。

傳回值

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

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

言論

RegCreateKeyEx 函式所建立的索引鍵沒有值。 應用程式可以使用 RegSetValueEx 函式來設定索引鍵值。

RegCreateKeyEx 函式會在指定的路徑中建立所有遺漏的索引鍵。 應用程式可以利用此行為一次建立數個金鑰。 例如，應用程式可以藉由為 lpSubKey 參數指定下列格式的字串，同時建立四層深的子機碼：

子機碼1\subkey2\subkey3\subkey4

請注意，如果路徑中的現有索引鍵拼錯，此行為將會導致建立不必要的密鑰。

應用程式無法建立 HKEY_USERS 或 HKEY_LOCAL_MACHINE直接子系的索引鍵。 應用程式可以在較低層級的 HKEY_USERS 或 HKEY_LOCAL_MACHINE 樹狀結構中建立子機碼。

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

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

注意

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

要求

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

另請參閱

RegCloseKey

RegDeleteKey

RegOpenKeyEx

RegSaveKey

登錄函式

登錄概觀

SECURITY_ATTRIBUTES