NtCreateResourceManager function (wdm.h)

Article
03/11/2022

The ZwCreateResourceManager routine creates a resource manager object.

Syntax

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

Parameters

[out] ResourceManagerHandle

A pointer to a caller-allocated variable that receives a handle to the new resource manager object if the call to ZwCreateResourceManager is successful.

[in] DesiredAccess

An ACCESS_MASK value that specifies the caller's requested access to the resource manager object. In addition to the access rights that are defined for all kinds of objects (see ACCESS_MASK), the caller can specify any of the following access right flags for resource manager objects:

ACCESS_MASK flag	Allows the caller to
RESOURCEMANAGER_ENLIST	Enlist in transactions (see ZwCreateEnlistment).
RESOURCEMANAGER_GET_NOTIFICATION	Receive notifications about the transactions that are associated with this resource manager (see ZwGetNotificationResourceManager).
RESOURCEMANAGER_REGISTER_PROTOCOL	Not used.
RESOURCEMANAGER_QUERY_INFORMATION	Query information about the resource manager (see ZwQueryInformationResourceManager).
RESOURCEMANAGER_SET_INFORMATION	Not used.
RESOURCEMANAGER_RECOVER	Recover the resource manager (see ZwRecoverResourceManager).
RESOURCEMANAGER_COMPLETE_PROPAGATION	Not used.

Alternatively, you can specify one or more of the following generic ACCESS_MASK flags. (The STANDARD_RIGHTS_Xxx flags are predefined system values that are used to enforce security on system objects.) You can also combine these generic flags with additional flags from the preceding table. The following table shows how generic access rights correspond to specific access rights.

Generic access right	Set of specific access rights
RESOURCEMANAGER_GENERIC_READ	STANDARD_RIGHTS_READ, RESOURCEMANAGER_QUERY_INFORMATION, and SYNCHRONIZE
RESOURCEMANAGER_GENERIC_WRITE	STANDARD_RIGHTS_WRITE, RESOURCEMANAGER_SET_INFORMATION, RESOURCEMANAGER_RECOVER, RESOURCEMANAGER_ENLIST, RESOURCEMANAGER_GET_NOTIFICATION, RESOURCEMANAGER_REGISTER_PROTOCOL, RESOURCEMANAGER_COMPLETE_PROPAGATION, and SYNCHRONIZE
RESOURCEMANAGER_GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE, RESOURCEMANAGER_RECOVER, RESOURCEMANAGER_ENLIST, RESOURCEMANAGER_GET_NOTIFICATION, RESOURCEMANAGER_COMPLETE_PROPAGATION, and SYNCHRONIZE
RESOURCEMANAGER_ALL_ACCESS	STANDARD_RIGHTS_REQUIRED, RESOURCEMANAGER_GENERIC_READ, RESOURCEMANAGER_GENERIC_WRITE, and RESOURCEMANAGER_GENERIC_EXECUTE

[in] TmHandle

A handle to a transaction manager object that was obtained by a previous all to ZwCreateTransactionManager or ZwOpenTransactionManager.

[in] RmGuid

A pointer to a GUID that KTM will use to identify the resource manager. If this pointer is NULL, KTM generates a GUID.

[in, optional] ObjectAttributes

A pointer to an OBJECT_ATTRIBUTES structure that specifies the object name and other attributes. Use the InitializeObjectAttributes routine to initialize this structure. If the caller is not running in a system thread context, it must set the OBJ_KERNEL_HANDLE attribute when it calls InitializeObjectAttributes. This parameter is optional and can be NULL.

[in, optional] CreateOptions

Optional object creation flags. The following table contains the available flags, which are defined in Ktmtypes.h.

CreateOptions flag	Meaning
RESOURCE_MANAGER_COMMUNICATION	For internal use only.
RESOURCE_MANAGER_VOLATILE	The caller will manage volatile resources. It will be non-persistent and will not perform recovery.

This parameter is optional and can be zero.

[in, optional] Description

A pointer to a caller-supplied UNICODE_STRING structure that contains a NULL-terminated string. The string provides a description of the resource manager. KTM stores a copy of the string and includes the string in messages that it writes to the log stream. The maximum string length is MAX_RESOURCEMANAGER_DESCRIPTION_LENGTH. This parameter is optional and can be NULL.

Return value

ZwCreateResourceManager returns STATUS_SUCCESS if the operation succeeds. Otherwise, this routine might return one of the following values:

Return code	Description
STATUS_OBJECT_TYPE_MISMATCH	The handle that TmHandle specifies is not a handle to a transaction object.
STATUS_INVALID_HANDLE	The handle that TmHandle specifies is invalid.
STATUS_ACCESS_DENIED	The caller does not have appropriate access to the specified transaction manager object.
STATUS_TRANSACTION_OBJECT_EXPIRED	The handle that TmHandle specifies is closed.
STATUS_INVALID_PARAMETER	The CreateOptions parameter's value is invalid or the Description parameter's string is too long.
STATUS_TM_VOLATILE	The CreateOptions parameter does not specify RESOURCE_MANAGER_VOLATILE but the transaction manager that TmHandle specifies is volatile.
STATUS_OBJECT_NAME_COLLISION	The GUID that ResourceManagerGuid specifies already exists.
STATUS_ACCESS_DENIED	The value of the DesiredAccess parameter is invalid.

The routine might return other NTSTATUS values.

Remarks

A resource manager that calls ZwCreateResourceManager must eventually call ZwClose to close the object handle.

For more information about ZwCreateResourceManager, see Creating a Resource Manager.

For calls from kernel-mode drivers, the NtXxx and ZwXxx versions of a Windows Native System Services routine can behave differently in the way that they handle and interpret input parameters. For more information about the relationship between the NtXxx and ZwXxx versions of a routine, see Using Nt and Zw Versions of the Native System Services Routines.

Requirements

Requirement	Value
Minimum supported client	Available in Windows Vista and later operating system versions.
Target Platform	Universal
Header	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI compliance rules	HwStorPortProhibitedDDIs, PowerIrpDDis