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
0x00000004L
 如果設定此旗標，函式會忽略 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
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，則不會傳回任何處置資訊。

[in] hTransaction

使用中交易的控制碼。 CreateTransaction函式會傳回這個控制碼。

pExtendedParemeter

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

傳回值

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

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

備註

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

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

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

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

subkey1\subkey2\subkey3\subkey4

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

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

注意

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

規格需求

   
最低支援的用戶端 Windows Vista [僅限傳統型應用程式]
最低支援的伺服器 Windows Server 2008 [僅限傳統型應用程式]
目標平台 Windows
標頭 winreg.h (包含 Windows.h)
程式庫 Advapi32.lib
Dll Advapi32.dll

另請參閱

RegCloseKey

RegDeleteKeyTransacted

RegOpenKeyTransacted

RegSaveKey

登錄函式

登錄概觀

SECURITY_ATTRIBUTES