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

[in] samDesired

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

[in, optional] lpSecurityAttributes

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

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

[out] phkResult

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

[out, optional] lpdwDisposition

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

值 意義
REG_CREATED_NEW_KEY
0x00000001L
 索引鍵不存在且已建立。
REG_OPENED_EXISTING_KEY
0x00000002L
 索引鍵已存在，而且只是開啟而不需要變更。
 

如果 lpdwDisposition 為 NULL，則不會傳回任何處置資訊。

傳回值

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

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

備註

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

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

subkey1\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 專業版 [僅限傳統型應用程式]
最低支援的伺服器 Windows 2000 Server [僅限傳統型應用程式]
目標平台 Windows
標頭 winreg.h (包括 Windows.h)
程式庫 Advapi32.lib
Dll Advapi32.dll

另請參閱

RegCloseKey

RegDeleteKey

RegOpenKeyEx

RegSaveKey

登錄函式

登錄概觀

SECURITY_ATTRIBUTES