共用方式為

RegCreateKeyTransactedA 函式 （winreg.h）

  • 發行項

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

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

語法

LSTATUS RegCreateKeyTransactedA(
  [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]            HANDLE                      hTransaction,
                  PVOID                       pExtendedParemeter
);

參數

[in] hKey

開啟登錄機碼的句柄。 呼叫進程必須具有金鑰KEY_CREATE_SUB_KEY存取權。 如需詳細資訊，請參閱 登入機碼安全性和存取權限。

針對登錄機碼的安全性描述元檢查密鑰建立的存取權，而不是取得句柄時指定的存取掩碼。 因此，即使 hKey 是以KEY_READ samDesired 開啟，它也可以用於建立密鑰的作業中，如果安全性描述元允許的話。

此句柄是由 RegCreateKeyTransacted 或 RegOpenKeyTransacted 函式傳回，或者它可以是下列其中一個 預先定義的索引鍵：

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許可權，則會使用ACCESS_SYSTEM_SECURITY和KEY_WRITE訪問許可權開啟密鑰。 如果啟用這兩個許可權，金鑰會同時擁有這兩個許可權的合併訪問許可權。 如需詳細資訊，請參閱 以特殊許可權執行。
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，則不會傳回處置資訊。

[in] hTransaction

使用中交易的句柄。 此句柄是由 createTransaction 函式 傳回。

pExtendedParemeter

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

傳回值

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

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

言論

使用此函式建立金鑰時，會交易金鑰上的後續作業。 如果在認可交易之前，在密鑰上執行非交易作業，則會回復交易。 認可或回復交易之後，您必須使用 RegCreateKeyTransacted 重新開啟密鑰，或使用使用中交易句柄 RegOpenKeyTransacted，才能進行其他作業交易。 如需交易的詳細資訊，請參閱 核心交易管理員。

請注意，此金鑰子機碼的後續作業不會自動交易。 因此，RegDeleteKeyEx 不會執行交易刪除作業。 請改用 RegDeleteKeyTransacted 函式來執行交易刪除作業。

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

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

子機碼1\subkey2\subkey3\subkey4

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

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

注意

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

要求

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

另請參閱

RegCloseKey

RegDeleteKeyTransacted

RegOpenKeyTransacted

RegSaveKey

登錄函式

登錄概觀

SECURITY_ATTRIBUTES