Função TmReferenceEnlistmentKey (wdm.h)
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 |
|---|---|
|
O valor do parâmetro Key é NULL. |
|
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. |
|
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 |