Função TmReferenceEnlistmentKey (wdm.h)

Artigo
02/29/2024

A rotina TmReferenceEnlistmentKey incrementa a contagem de referência para a chave de um objeto de inscrição especificado e recupera a chave.

Sintaxe

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

Parâmetros

[in] Enlistment

Um ponteiro para um objeto de inscrição. Seu componente pode receber esse ponteiro como entrada para uma rotina de retorno de chamada ResourceManagerNotification . Como alternativa, seu componente pode chamar ObReferenceObjectByHandle e fornecer o identificador de objeto fornecido por uma chamada anterior para ZwCreateEnlistment, TmCreateEnlistment ou ZwOpenEnlistment .

[out] Key

Um ponteiro para uma variável que recebe a chave de inscrição do objeto de inscrição. O chamador atribui uma chave de inscrição quando chama ZwCreateEnlistment ou TmCreateEnlistment.

Retornar valor

TmReferenceEnlistmentKey retornará STATUS_SUCCESS se a operação for bem-sucedida. Caso contrário, essa rotina pode retornar um dos seguintes valores:

Código de retorno	Descrição
STATUS_INVALID_PARAMETER	O valor do parâmetro Key é NULL.
STATUS_UNSUCCESSFUL	A contagem de referência do objeto de inscrição especificado foi decrementada para zero, portanto, a contagem de referência não pode ser incrementada.
STATUS_INSUFFICIENT_RESOURCES	A contagem de referência está no valor máximo (0xFFFFFFFF) e não pode ser incrementada.

A rotina pode retornar outros valores NTSTATUS.

Comentários

A rotina TmReferenceEnlistmentKey incrementa a contagem de referência para o valor de chave de um objeto de inscrição e a rotina TmDereferenceEnlistmentKey diminui a contagem.

Se um gerenciador de recursos tiver definido um valor de chave para uma inscrição, o gerenciador de recursos receberá o valor da chave quando chamar ZwGetNotificationResourceManager ou quando KTM chamar a rotina de retorno de chamada ResourceManagerNotification .

Enquanto um gerenciador de recursos está processando uma notificação, ele pode usar a chave como um ponteiro para uma alocação de memória temporária e pode usar a contagem de referência para determinar quando ela deve desalocar a memória.

Para obter informações sobre quando usar as rotinas TmXxx da KTM em vez de rotinas ZwXxx , consulte Usando rotinas TmXxx.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Disponível no Windows Vista e versões posteriores do sistema operacional.
Plataforma de Destino	Universal
Cabeçalho	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL