ZwCreateResourceManager function (wdm.h)

The ZwCreateResourceManager routine creates a resource manager object.

Syntax

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
);

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, optional] ResourceManagerGuid

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(storport), PowerIrpDDis(wdm)

See also

ACCESS_MASK

InitializeObjectAttributes

OBJECT_ATTRIBUTES

UNICODE_STRING

ZwClose

ZwCreateEnlistment

ZwCreateTransactionManager

ZwGetNotificationResourceManager

ZwOpenResourceManager

ZwOpenTransactionManager

ZwQueryInformationResourceManager

ZwRecoverResourceManager