Macro ObDereferenceObjectWithTag (wdm.h)

Artigo
03/18/2023

A rotina ObDereferenceObjectWithTag diminui a contagem de referência do objeto especificado e grava um valor de marca de quatro bytes no objeto para dar suporte ao rastreamento de referência de objeto.

Sintaxe

void ObDereferenceObjectWithTag(
  [in]  a,
  [in]  t
);

Parâmetros

[in] a

Um ponteiro para o objeto . O chamador obtém esse ponteiro quando cria o objeto ou de uma chamada anterior para a rotina ObReferenceObjectByHandleWithTag depois de abrir o objeto.

[in] t

Especifica um valor de marca personalizada de quatro bytes. Para obter mais informações, consulte a seção Comentários a seguir.

Retornar valor

Nenhum

Comentários

ObDereferenceObjectWithTag retorna um valor reservado para uso do sistema. Os drivers devem tratar esse valor como VOID.

Um driver de modo kernel chama essa rotina para diminuir a contagem de referência de um objeto por um. Se o objeto foi criado como temporário (ou seja, o sinalizador OBJ_PERMANENT não foi especificado quando o objeto foi criado) e a contagem de referência atinge zero, o gerenciador de objetos exclui o objeto.

Quando a contagem de referência de um objeto atinge zero, um componente do modo kernel pode excluir o objeto. No entanto, um driver pode excluir apenas os objetos que ele criou, e um driver nunca deve tentar excluir nenhum objeto que ele não criou.

Um objeto será permanente se tiver sido criado com o sinalizador de atributo de objeto OBJ_PERMANENT especificado. (Para obter mais informações sobre atributos de objeto, consulte InitializeObjectAttributes.) Um objeto permanente é criado com uma contagem de referência inicial de um, portanto, o objeto não é excluído quando o driver remove sua última referência ao objeto.

Para preparar um objeto permanente a ser excluído, um driver pode chamar a rotina ZwMakeTemporaryObject para tornar o objeto temporário. Um driver só deve excluir um objeto permanente que ele criou. Use as seguintes etapas para excluir um objeto permanente:

Chame ObDereferenceObjectWithTag.
Obtenha o identificador para o objeto . Se necessário, chame a rotina ZwOpenXxx ou ZwCreateXxx apropriada para obter o identificador do objeto.
Chame ZwMakeTemporaryObject com o identificador obtido na etapa 2.
Chame ZwClose com o identificador obtido na etapa 2.

Se a exclusão imediata de um objeto pelo thread atual puder causar um deadlock, não chame ObDereferenceObjectWithTag para desreferenciar o objeto. Em vez disso, chame a rotina ObDereferenceObjectDeferDeleteWithTag para desreferenciar o objeto.

Por exemplo, esse deadlock poderá ocorrer se ObDereferenceObjectWithTag for usado para desreferenciar um objeto KTM (Kernel Transaction Manager ) quando um driver de nível superior na pilha de driver estiver mantendo um bloqueio.

Para obter mais informações sobre referências de objeto, consulte Ciclo de vida de um objeto.

A rotina ObDereferenceObject é semelhante a ObDereferenceObjectWithTag, exceto que não permite que o chamador escreva uma marca personalizada em um objeto . No Windows 7 e versões posteriores do Windows, ObDereferenceObject sempre grava um valor de marca padrão ('tlfD') no objeto. Uma chamada para ObDereferenceObject tem o mesmo efeito que uma chamada para ObDereferenceObjectWithTag que especifica Tag = 'tlfD'.

Para exibir um rastreamento de referência de objeto nas ferramentas de depuração do Windows, use a extensão do depurador !obtrace kernel-mode. No Windows 7, a extensão !obtrace é aprimorada para exibir marcas de referência de objeto, se o rastreamento de referência de objeto estiver habilitado. Por padrão, o rastreamento de referência de objeto está desativado. Use o Editor de Sinalizadores Globais (Gflags) para habilitar o rastreamento de referência de objeto. Para obter mais informações, consulte Rastreamento de referência de objeto com marcas.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Disponível no Windows 7 e versões posteriores do sistema operacional Windows.
Plataforma de Destino	Área de Trabalho
Cabeçalho	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h, Fltkernel.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL
Regras de conformidade da DDI	HwStorPortProhibitedDDIs(storport)