ZwCreateResourceManager 函式 (wdm.h)

發行項
02/29/2024

ZwCreateResourceManager 例程會建立資源管理員物件。

語法

NTSYSCALLAPI NTSTATUS ZwCreateResourceManager(
  [out]          PHANDLE            ResourceManagerHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in]           HANDLE             TmHandle,
  [in, optional] LPGUID             ResourceManagerGuid,
  [in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
  [in, optional] ULONG              CreateOptions,
  [in, optional] PUNICODE_STRING    Description
);

參數

[out] ResourceManagerHandle

呼叫端配置變數的指標，如果 呼叫 ZwCreateResourceManager 成功，就會接收新 Resource Manager 物件的句柄。

[in] DesiredAccess

ACCESS_MASK值，指定呼叫端對 Resource Manager 物件的要求存取權。除了針對各種物件定義的訪問許可權之外， (請參閱 ACCESS_MASK) ，呼叫者還可以指定下列任何資源管理員物件的存取權旗標：

ACCESS_MASK旗標	允許呼叫端
RESOURCEMANAGER_ENLIST	在交易中編列 (請參閱 ZwCreateEnlistment) 。
RESOURCEMANAGER_GET_NOTIFICATION	收到與此資源管理員相關聯交易的相關通知， (請參閱 ZwGetNotificationResourceManager) 。
RESOURCEMANAGER_REGISTER_PROTOCOL	未使用。
RESOURCEMANAGER_QUERY_INFORMATION	(資源管理員的查詢資訊，請參閱 ZwQueryInformationResourceManager) 。
RESOURCEMANAGER_SET_INFORMATION	未使用。
RESOURCEMANAGER_RECOVER	復原資源管理員 (請參閱 ZwRecoverResourceManager) 。
RESOURCEMANAGER_COMPLETE_PROPAGATION	未使用。

或者，您可以指定下列一或多個泛型 ACCESS_MASK 旗標。 (STANDARD_RIGHTS_ Xxx 旗標是預先定義的系統值，可用來強制執行系統對象的安全性。) 您也可以將這些泛型旗標與上表中的其他旗標結合。下表顯示泛型訪問許可權如何對應至特定訪問許可權。

一般訪問許可權	特定訪問許可權集
RESOURCEMANAGER_GENERIC_READ	STANDARD_RIGHTS_READ、RESOURCEMANAGER_QUERY_INFORMATION和 SYNCHRONIZE
RESOURCEMANAGER_GENERIC_WRITE	STANDARD_RIGHTS_WRITE、RESOURCEMANAGER_SET_INFORMATION、RESOURCEMANAGER_RECOVER、RESOURCEMANAGER_ENLIST、RESOURCEMANAGER_GET_NOTIFICATION、RESOURCEMANAGER_REGISTER_PROTOCOL、RESOURCEMANAGER_COMPLETE_PROPAGATION和 SYNCHRONIZE
RESOURCEMANAGER_GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE、RESOURCEMANAGER_RECOVER、RESOURCEMANAGER_ENLIST、RESOURCEMANAGER_GET_NOTIFICATION、RESOURCEMANAGER_COMPLETE_PROPAGATION和 SYNCHRONIZE
RESOURCEMANAGER_ALL_ACCESS	STANDARD_RIGHTS_REQUIRED、RESOURCEMANAGER_GENERIC_READ、RESOURCEMANAGER_GENERIC_WRITE和RESOURCEMANAGER_GENERIC_EXECUTE

[in] TmHandle

先前所有 ZwCreateTransactionManager 或 ZwOpenTransactionManager 取得的交易管理員物件的句柄。

[in, optional] ResourceManagerGuid

KTM 將用來識別資源管理員之 GUID 的指標。如果此指標為 NULL，KTM 會產生 GUID。

[in, optional] ObjectAttributes

指定物件名稱和其他屬性之OBJECT_ATTRIBUTES 結構的指標。使用 InitializeObjectAttributes 例程來初始化這個結構。如果呼叫端未在系統線程內容中執行，它必須在呼叫 InitializeObjectAttributes 時設定OBJ_KERNEL_HANDLE屬性。這個參數是選擇性的，而且可以是 NULL。

[in, optional] CreateOptions

選擇性物件建立旗標。下表包含 Ktmtypes.h 中定義的可用旗標。

CreateOptions 旗標	意義
RESOURCE_MANAGER_COMMUNICATION	僅供內部使用。
RESOURCE_MANAGER_VOLATILE	呼叫端會管理變動性資源。它將是非持續性的，而且不會執行復原。

這個參數是選擇性的，而且可以是零。

[in, optional] Description

呼叫端提供的 UNICODE_STRING 結構的指標，其中包含NULL終止的字串。字串提供資源管理員的描述。 KTM 會儲存字串的複本，並將字串包含在寫入記錄數據流的訊息中。字串長度上限為 MAX_RESOURCEMANAGER_DESCRIPTION_LENGTH。這個參數是選擇性的，而且可以是 NULL。

傳回值

如果作業成功，ZwCreateResourceManager 會傳回STATUS_SUCCESS。否則，此例程可能會傳回下列其中一個值：

傳回碼	Description
STATUS_OBJECT_TYPE_MISMATCH	TmHandle 指定的句柄不是交易物件的句柄。
STATUS_INVALID_HANDLE	TmHandle 指定的句柄無效。
STATUS_ACCESS_DENIED	呼叫端沒有指定之交易管理員對象的適當存取權。
STATUS_TRANSACTION_OBJECT_EXPIRED	TmHandle 指定的句柄已關閉。
STATUS_INVALID_PARAMETER	CreateOptions 參數的值無效，或 Description 參數的字串太長。
STATUS_TM_VOLATILE	CreateOptions 參數不會指定RESOURCE_MANAGER_VOLATILE但TmHandle 指定的交易管理員是變動性的。
STATUS_OBJECT_NAME_COLLISION	ResourceManagerGuid 指定的 GUID 已經存在。
STATUS_ACCESS_DENIED	DesiredAccess 參數的值無效。

例程可能會傳回其他 NTSTATUS值。

備註

呼叫 ZwCreateResourceManager 的資源管理員最終必須呼叫 ZwClose 以關閉物件句柄。

如需 ZwCreateResourceManager 的詳細資訊，請參閱建立 Resource Manager。

針對來自內核模式驅動程式的呼叫，Windows 原生系統服務例程的 NtXxx 和 ZwXxx 版本會以處理和解譯輸入參數的方式，以不同的方式運作。如需 例程 NtXxx 和 ZwXxx 版本之間關聯性的詳細資訊，請參閱使用原生系統服務例程的 Nt 和 Zw 版本。

規格需求

需求	值
最低支援的用戶端	適用於 Windows Vista 和更新版本的作業系統版本。
目標平台	Universal
標頭	wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h)
程式庫	NtosKrnl.lib
Dll	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI 合規性規則	HwStorPortProhibitedDDIs (storport) 、 PowerIrpDDis (wdm)