ZwCreateKeyTransacted 函式 (wdm.h)
ZwCreateKeyTransacted 例程會建立新的登錄機碼或開啟現有的登錄機碼，並將密鑰與交易產生關聯。
語法
NTSYSAPI NTSTATUS ZwCreateKeyTransacted(
[out] PHANDLE KeyHandle,
[in] ACCESS_MASK DesiredAccess,
[in] POBJECT_ATTRIBUTES ObjectAttributes,
ULONG TitleIndex,
[in, optional] PUNICODE_STRING Class,
[in] ULONG CreateOptions,
[in] HANDLE TransactionHandle,
[out, optional] PULONG Disposition
);
參數
[out] KeyHandle
HANDLE 變數的指標，例程會將句柄寫入索引鍵。
[in] DesiredAccess
指定呼叫端要求之金鑰的存取類型。 此參數是 ACCESS_MASK 值。 如需詳細資訊，請參閱 ZwCreateKey 例程的 DesiredAccess 參數描述。
[in] ObjectAttributes
要開啟之索引鍵之物件屬性的指標。 此參數指向先前必須由 InitializeObjectAttributes 例程初始化的OBJECT_ATTRIBUTES結構。 呼叫端必須將登錄機碼的名稱指定為 InitializeObjectAttributes 呼叫中的 ObjectName 參數。 如果呼叫端未在系統線程內容中執行，它必須在呼叫 InitializeObjectAttributes 時設定OBJ_KERNEL_HANDLE屬性。
TitleIndex
裝置和中繼驅動程式將此參數設定為零。
[in, optional] Class
裝置和中繼驅動程式將此參數設定為 NULL。
[in] CreateOptions
指定例程建立或開啟金鑰時要套用的選項。 將此參數設定為零，或設定為下列一或多個 REG_OPTION_XXX 旗標位的位 OR。
| CreateOptions 旗標 | Description |
|---|---|
| REG_OPTION_VOLATILE | 計算機重新啟動之後 ，不會 保留密鑰。 |
| REG_OPTION_NON_VOLATILE | 計算機重新啟動之後，會保留金鑰。 |
| REG_OPTION_CREATE_LINK | 索引鍵是符號連結。 裝置和中繼驅動程式不會使用此旗標。 |
| REG_OPTION_BACKUP_RESTORE | 以啟用備份和還原作業的特殊許可權開啟金鑰。 裝置和中繼驅動程式不會使用此旗標。 |
[in] TransactionHandle
交易物件的句柄。 若要取得此句柄，您可以呼叫 ZwCreateTransaction 例程。 或者，如果您有交易物件的指標，則可以提供 ObOpenObjectByPointer 例程的指標，以取得對應的交易句柄。
[out, optional] Disposition
例程寫入下列其中一個值的位置指標，指出呼叫建立新的索引鍵或開啟現有索引鍵。
| 處置 值 | Description |
|---|---|
| REG_CREATED_NEW_KEY | 已建立新的金鑰。 |
| REG_OPENED_EXISTING_KEY | 已開啟現有的金鑰。 |
如果不需要此資訊，您可以設定 處置 = NULL 。
傳回值
如果呼叫成功建立或開啟密鑰，ZwCreateKeyTransacted 會傳回STATUS_SUCCESS。 可能的錯誤傳回值包括下列各項：
| 傳回碼 | Description |
|---|---|
|
ObjectAttributes 參數為 NULL 或指向無效的資訊，或 CreateOptions 參數值指定無效的選項。 |
|
物件屬性中的登錄路徑無效。 |
|
找不到物件屬性中的登錄路徑。 |
|
呼叫端沒有開啟具名登錄機碼句柄的必要訪問許可權。 |
|
記憶體配置作業失敗。 |
備註
此例程提供呼叫端可以使用的句柄來存取登錄機碼。 此外，此例程會將密鑰與使用中交易產生關聯。
KeyHandle 所指向的句柄不再使用之後，驅動程式必須呼叫 ZwClose 例程來關閉它。
如同 ZwCreateKeyTransacted，ZwOpenKeyTransacted 例程會將密鑰與交易產生關聯。 不同於 ZwCreateKeyTransacted，它可以建立新的密鑰或開啟現有的機碼， ZwOpenKeyTransacted 只能開啟已經存在的登錄機碼。
例如，在內核模式驅動程式取得交易的句柄 (之後，藉由呼叫 ZwCreateTransaction) ，驅動程式就可以執行屬於此交易的一系列登錄作業。 驅動程式可以認可交易中所做的變更，或復原交易來關閉交易。
驅動程式成功完成屬於交易一部分的所有登錄作業之後，就可以呼叫 ZwCommitTransaction 例程來認可變更。 驅動程式可以呼叫 ZwRollbackTransaction 例程來復原交易。
在交易期間，如果執行作業的系統呼叫符合下列任一條件，登錄作業就會是交易的一部分：
- 呼叫會將交易句柄指定為輸入參數。 例如，呼叫 ZwCreateKeyTransacted 和 ZwOpenKeyTransacted 可以將一或多個句柄與交易產生關聯。
- 呼叫會指定做為輸入參數的登錄機碼句柄，由呼叫 ZwCreateKeyTransacted 或提供交易句柄的 ZwOpenKeyTransacted 取得。 例如，對 ZwSetValueKey 例程的呼叫可以使用以這種方式取得的機碼句柄，將登錄機碼的值設定為交易的一部分。
對象屬性中的安全性描述元會決定在稍後呼叫例程時授與 DesiredAccess 參數所指定的訪問許可權，例如存取密鑰的 ZwOpenKeyTransacted ，或是建立密鑰子機碼的例程，例如 ZwCreateKeyTransacted 。
如果內核模式呼叫端未在系統線程內容中執行，則必須確保所建立的任何句柄都是核心句柄。 否則，進程可以在其中執行驅動程序的內容中存取句柄。 如需詳細資訊，請參閱 物件句柄。
如需如何在核心模式中使用登錄機碼的詳細資訊，請參閱 在驅動程式中使用登錄。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | 可在 Windows Vista 和更新版本的 Windows 中使用。 |
| 目標平台 | Universal |
| 標頭 | wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h) |
| 程式庫 | NtosKrnl.lib |
| Dll | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| DDI 合規性規則 | HwStorPortProhibitedDDIs (storport) 、 PowerIrpDDis (wdm) |