TmReferenceEnlistmentKey - NtDoc
Native API online documentation, based on the System Informer
(formerly Process Hacker) phnt
headers
// wdm.h
NTSTATUS TmReferenceEnlistmentKey(
[in] PKENLISTMENT Enlistment,
[out] PVOID *Key
);
View the official Windows Driver Kit DDI referenceNo description available.
The TmReferenceEnlistmentKey routine increments the reference count for the key of a specified enlistment object and retrieves the key.
Enlistment [in]A pointer to an enlistment object. Your component can receive this pointer as input to a ResourceManagerNotification callback routine. Alternatively, your component can call ObReferenceObjectByHandle and supply the object handle that a previous call to ZwCreateEnlistment, TmCreateEnlistment, or ZwOpenEnlistment provided.
Key [out]A pointer to a variable that receives the enlistment object's enlistment key. The caller assigns an enlistment key when it calls ZwCreateEnlistment or TmCreateEnlistment.
TmReferenceEnlistmentKey returns STATUS_SUCCESS if the operation succeeds. Otherwise, this routine might return one of the following values:
| Return code | Description |
|---|---|
| STATUS_INVALID_PARAMETER | The Key parameter's value is NULL. |
| STATUS_UNSUCCESSFUL | The reference count of the specified enlistment object has been decremented to zero, so the reference count cannot be incremented. |
| STATUS_INSUFFICIENT_RESOURCES | The reference count is at its maximum value (0xFFFFFFFF) and cannot be incremented. |
The routine might return other NTSTATUS values.
The TmReferenceEnlistmentKey routine increments the reference count for an enlistment object's key value, and the TmDereferenceEnlistmentKey routine decrements the count.
If a resource manager has defined a key value for an enlistment, the resource manager receives the key value when it calls ZwGetNotificationResourceManager or when KTM calls the ResourceManagerNotification callback routine.
While a resource manager is processing a notification, it might use the key as a pointer to a temporary memory allocation, and it might use the reference count to determine when it should deallocate the memory.
For information about when to use KTM's Tm*Xxx* routines instead of Zw*Xxx* routines, see Using TmXxx Routines.