ZwCreateResourceManager routine

The ZwCreateResourceManager routine creates a resource manager object.

Syntax


NTSTATUS ZwCreateResourceManager(
  _Out_     PHANDLE ResourceManagerHandle,
  _In_      ACCESS_MASK DesiredAccess,
  _In_      HANDLE TmHandle,
  _In_opt_  LPGUID ResourceManagerGuid,
  _In_opt_  POBJECT_ATTRIBUTES ObjectAttributes,
  _In_opt_  ULONG CreateOptions,
  _In_opt_  PUNICODE_STRING Description
);

Parameters

ResourceManagerHandle [out]

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

DesiredAccess [in]

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 flagAllows 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 rightSet 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

 

TmHandle [in]

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

ResourceManagerGuid [in, optional]

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

ObjectAttributes [in, optional]

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.

CreateOptions [in, optional]

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

CreateOptions flagMeaning

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.

Description [in, optional]

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 codeDescription
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.

Requirements

Version

Available in Windows Vista and later operating system versions.

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)

Library

Ntoskrnl.lib

IRQL

PASSIVE_LEVEL

DDI compliance rules

PowerIrpDDis, HwStorPortProhibitedDDIs

See also

ACCESS_MASK
InitializeObjectAttributes
OBJECT_ATTRIBUTES
UNICODE_STRING
ZwClose
ZwCreateEnlistment
ZwCreateTransactionManager
ZwGetNotificationResourceManager
ZwOpenResourceManager
ZwOpenTransactionManager
ZwQueryInformationResourceManager
ZwRecoverResourceManager

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft