Función TmReferenceEnlistmentKey (wdm.h)

Artículo
02/29/2024

La rutina TmReferenceEnlistmentKey incrementa el recuento de referencias de la clave de un objeto de inscripción especificado y recupera la clave.

Sintaxis

NTSTATUS TmReferenceEnlistmentKey(
  [in]  PKENLISTMENT Enlistment,
  [out] PVOID        *Key
);

Parámetros

[in] Enlistment

Puntero a un objeto de inscripción. El componente puede recibir este puntero como entrada en una rutina de devolución de llamada ResourceManagerNotification . Como alternativa, el componente puede llamar a ObReferenceObjectByHandle y proporcionar el identificador del objeto que proporcionó una llamada anterior a ZwCreateEnlistment, TmCreateEnlistment o ZwOpenEnlistment proporcionada.

[out] Key

Puntero a una variable que recibe la clave de inscripción del objeto de inscripción. El autor de la llamada asigna una clave de inscripción cuando llama a ZwCreateEnlistment o TmCreateEnlistment.

Valor devuelto

TmReferenceEnlistmentKey devuelve STATUS_SUCCESS si la operación se realiza correctamente. De lo contrario, esta rutina podría devolver uno de los siguientes valores:

Código devuelto	Descripción
STATUS_INVALID_PARAMETER	El valor del parámetro Key es NULL.
STATUS_UNSUCCESSFUL	El recuento de referencias del objeto de inscripción especificado se ha reducido a cero, por lo que no se puede incrementar el recuento de referencias.
STATUS_INSUFFICIENT_RESOURCES	El recuento de referencias está en su valor máximo (0xFFFFFFFF) y no se puede incrementar.

La rutina podría devolver otros valores NTSTATUS.

Comentarios

La rutina TmReferenceEnlistmentKey incrementa el recuento de referencias para el valor de clave de un objeto de inscripción y la rutina TmDereferenceEnlistmentKey disminuye el recuento.

Si un administrador de recursos ha definido un valor de clave para una inscripción, el administrador de recursos recibe el valor de clave cuando llama a ZwGetNotificationResourceManager o cuando KTM llama a la rutina de devolución de llamada ResourceManagerNotification .

Mientras un administrador de recursos procesa una notificación, podría usar la clave como puntero a una asignación de memoria temporal y podría usar el recuento de referencias para determinar cuándo debe desasignar la memoria.

Para obtener información sobre cuándo usar las rutinas TmXxx de KTM en lugar de las rutinas ZwXxx , consulte Uso de rutinas TmXxx.

Requisitos

Requisito	Value
Cliente mínimo compatible	Disponible en Windows Vista y versiones posteriores del sistema operativo.
Plataforma de destino	Universal
Encabezado	wdm.h (incluya Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
Archivo DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL