ZwOpenTransactionManager routine

The ZwOpenTransactionManager routine obtains a handle to an existing transaction manager object.

Syntax


NTSTATUS ZwOpenTransactionManager(
  _Out_     PHANDLE TmHandle,
  _In_      ACCESS_MASK DesiredAccess,
  _In_opt_  POBJECT_ATTRIBUTES ObjectAttributes,
  _In_opt_  PUNICODE_STRING LogFileName,
  _In_opt_  LPGUID TmIdentity,
  _In_opt_  ULONG OpenOptions
);

Parameters

TmHandle [out]

A pointer to a caller-allocated variable that receives a handle to the transaction manager object if ZwOpenTransactionManager returns STATUS_SUCCESS.

DesiredAccess [in]

An ACCESS_MASK value that specifies the caller's requested access to the transaction manager object. For information about how to specify this parameter, see the DesiredAccess parameter of ZwCreateTransactionManager.

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.

LogFileName [in, optional]

A pointer to a UNICODE_STRING structure that contains the path and file name of the log file stream that was created when the transaction manager object was created. For more information, see the LogFileName parameter of ZwCreateTransactionManager. This parameter is optional and can be NULL.

TmIdentity [in, optional]

A pointer to a GUID that identifies the transaction manager object. This parameter is optional and can be NULL.

OpenOptions [in, optional]

This parameter is not used and must be zero.

Return value

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

Return codeDescription
STATUS_INVALID_PARAMETER

The value of an input parameter is invalid.

STATUS_INSUFFICIENT_RESOURCES

KTM could not allocate system resources (typically memory).

STATUS_OBJECT_NAME_INVALID

The object name that the ObjectAttributes parameter specifies is invalid.

STATUS_LOG_CORRUPTION_DETECTED

KTM encountered an error while creating or opening the log file.

STATUS_ACCESS_DENIED

The value of the DesiredAccess parameter is invalid.

 

The routine might return other NTSTATUS values.

Remarks

The caller can identify which transaction manager object to open by using one of the following three techniques:

  • Use the LogFileName parameter to specify the path and file name of a log file stream that was created when the transaction manager object was created.

  • Use the TmIdentity parameter to specify the GUID that identifies the transaction manager object.

  • Use the ObjectAttributes parameter to supply an OBJECT_ATTRIBUTES structure that contains the object name that the caller previously specified to the ZwCreateTransactionManager routine.

You must specify only one of the above-listed parameters (an object name, a log file name, or a GUID) and set the other two parameters to NULL.

Your TPS component must call ZwRecoverTransactionManager after it has called ZwOpenTransactionManager.

A TPS component that calls ZwOpenTransactionManager must eventually call ZwClose to close the object handle.

For more information about how to use ZwOpenTransactionManager, see Transaction Manager Objects and Creating a Resource Manager.

Requirements

Version

Available in Windows Vista and later operating system versions.

Header

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

Library

Ntoskrnl.lib

IRQL

PASSIVE_LEVEL

DDI compliance rules

PowerIrpDDis, HwStorPortProhibitedDDIs

See also

InitializeObjectAttributes
OBJECT_ATTRIBUTES
UNICODE_STRING
ZwClose
ZwCreateTransactionManager
ZwQueryInformationTransactionManager

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft