PTM_RM_NOTIFICATION callback function (wdm.h)

A resource manager's ResourceManagerNotification callback routine receives and handles transaction notifications.

Syntax

PTM_RM_NOTIFICATION PtmRmNotification;

NTSTATUS PtmRmNotification(
  [in]      PKENLISTMENT EnlistmentObject,
  [in]      PVOID RMContext,
  [in]      PVOID TransactionContext,
  [in]      ULONG TransactionNotification,
  [in, out] PLARGE_INTEGER TmVirtualClock,
  [in]      ULONG ArgumentLength,
  [in]      PVOID Argument
)
{...}

Parameters

[in] EnlistmentObject

A pointer to an enlistment object. The ResourceManagerNotification callback routine is receiving a notification for the enlistment that this object represents.

[in] RMContext

The value that the resource manager previously specified for the RMKey parameter of the TmEnableCallbacks routine.

[in] TransactionContext

The value that the resource manager previously specified for the EnlistmentKey parameter of the ZwCreateEnlistment routine.

[in] TransactionNotification

One of the TRANSACTION_NOTIFY_XXX values that are defined in Ktmtypes.h. This value specifies the type of transaction notification that KTM sent to the caller.

[in, out] TmVirtualClock

A pointer to a location that contains the virtual clock value at the time that KTM prepared the notification for delivery to the resource manager. If the callback routine increases this value before it returns, KTM updates the virtual clock to the new value. (Typically, resource managers do not modify the virtual clock value.)

[in] ArgumentLength

The length, in bytes, of the buffer that the Argument parameter points to. This parameter is zero if a buffer is not available.

[in] Argument

A pointer to a buffer that contains notification-specific arguments. This parameter is NULL if the notification that the TransactionNotification parameter specifies does not require an argument buffer.

For a list of notifications that include an additional argument buffer, see the Remarks section of TRANSACTION_NOTIFICATION.

Return value

ResourceManagerNotification callback routine must return STATUS_SUCCESS or another status value for which NT_SUCCESS(status) equals TRUE if the operation is successful.

Typically, the resource manager returns STATUS_SUCCESS if it services the notification synchronously and STATUS_PENDING if it services the notification asynchronously, but it can return STATUS_PENDING in either case. However, the resource manager can return STATUS_PENDING only for notifications that it responds to by calling one of the TmXxxComplete or ZwXxxComplete routines.

In other words, if the resource manager must respond to a notification by calling one of the TmXxxComplete or ZwXxxComplete routines, it can return STATUS_PENDING for the notification and later call the appropriate TmXxxComplete or ZwXxxComplete routine.

If an error occurs, the callback routine must return a status value for which NT_SUCCESS(status) equals FALSE.

Remarks

To register a ResourceManagerNotification callback routine, your resource manager must call TmEnableCallbacks.

Note that ResourceManagerNotification callback routines receive a pointer, instead of a handle, to an enlistment object. You can pass the enlistment object pointer to the enlistment object's TmXxx routines.

For more information about ResourceManagerNotification callback routines, see Creating a Resource Manager.

The ResourceManagerNotification callback routine is called at IRQL = PASSIVE_LEVEL, and it must return at IRQL = PASSIVE_LEVEL.

Requirements

See also

TRANSACTION_NOTIFICATION

TmEnableCallbacks

ZwCreateEnlistment

ZwGetNotificationResourceManager