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 |
|---|---|
|
The handle that TmHandle specifies is not a handle to a transaction object. |
|
The handle that TmHandle specifies is invalid. |
|
The caller does not have appropriate access to the specified transaction manager object. |
|
The handle that TmHandle specifies is closed. |
|
The CreateOptions parameter's value is invalid or the Description parameter's string is too long. |
|
The CreateOptions parameter does not specify RESOURCE_MANAGER_VOLATILE but the transaction manager that TmHandle specifies is volatile. |
|
The GUID that ResourceManagerGuid specifies already exists. |
|
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
ZwGetNotificationResourceManager