Macro ObReferenceObjectWithTag (wdm.h)

A rotina ObReferenceObjectWithTag incrementa 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 ObReferenceObjectWithTag(
  [in]  Object,
  [in]  Tag
);

Parâmetros

[in] Object

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] Tag

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

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

ObReferenceObjectWithTag simplesmente incrementa a contagem de referência de ponteiro para um objeto, sem fazer nenhuma verificação de acesso no objeto especificado. Por outro lado, as rotinas ObReferenceObjectByHandleWithTag e ObReferenceObjectByPointerWithTag verificam se o chamador tem os direitos de acesso necessários ao objeto e falha se o chamador não tem esses direitos.

Uma chamada ObReferenceObjectWithTag impede a exclusão do objeto especificado pelo menos até que o driver chame a rotina ObDereferenceObjectWithTag ou feche o objeto. Depois que o objeto não for mais necessário, o driver deverá chamar ObDereferenceObjectWithTag para remover sua referência ao 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.

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

A rotina ObReferenceObject é semelhante a ObReferenceObjectWithTag, exceto que não permite que o chamador escreva uma marca personalizada em um objeto . No Windows 7 e versões posteriores do Windows, ObReferenceObject sempre grava um valor de marca padrão ('tlfD') no objeto. Uma chamada para ObReferenceObject tem o mesmo efeito que uma chamada para ObReferenceObjectWithTag 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)

Confira também

ObDereferenceObjectWithTag

ObReferenceObject

ObReferenceObjectByHandleWithTag

ObReferenceObjectByPointerWithTag