Função ObReferenceObjectByPointerWithTag (wdm.h)

Artigo
03/18/2023

A rotina ObReferenceObjectByPointerWithTag 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

NTSTATUS ObReferenceObjectByPointerWithTag(
  [in]           PVOID           Object,
  [in]           ACCESS_MASK     DesiredAccess,
  [in, optional] POBJECT_TYPE    ObjectType,
  [in]           KPROCESSOR_MODE AccessMode,
  [in]           ULONG           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 que ele abre o objeto.

[in] DesiredAccess

Especifica os tipos de acesso ao objeto que o chamador solicita. Esse parâmetro é uma máscara de bits do tipo ACCESS_MASK. A interpretação desse campo depende do tipo de objeto. Não use nenhum direito de acesso genérico.

[in, optional] ObjectType

Um ponteiro para uma estrutura opaca que especifica o tipo de objeto. Esse parâmetro aponta para uma estrutura OBJECT_TYPE . Defina ObjectType como NULL ou como um dos seguintes valores de ponteiro, que são declarados no arquivo de cabeçalho Wdm.h: *ExEventObjectType, *ExSemaphoreObjectType, *IoFileObjectType, *PsProcessType, *PsThreadType, *SeTokenObjectType, *TmEnlistmentObjectType, *TmResourceManagerObjectType, *TmTransactionManagerObjectType ou *TmTransactionObjectType. Esse parâmetro poderá ser NULL se AccessMode for KernelMode. Se ObjectType não for NULL, a rotina verificará se o tipo de objeto fornecido corresponde ao tipo de objeto do objeto especificado pelo parâmetro Handle .

[in] AccessMode

Indica o modo de acesso a ser usado para o marcar de acesso. Defina esse parâmetro como um dos seguintes valores de enumeração MODE :

Usermode
KernelMode

Drivers de nível inferior devem especificar KernelMode.

[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

ObReferenceObjectByPointerWithTag retornará STATUS_SUCCESS se a chamada for bem-sucedida. Os possíveis valores retornados por erro incluem o seguinte:

Código de retorno	Descrição
STATUS_OBJECT_TYPE_MISMATCH	O parâmetro ObjectType especifica o tipo de objeto errado para o objeto para o qual o parâmetro Object aponta ou ObjectType é NULL , mas AccessMode é UserMode.

Comentários

Essa rotina acessa a validação do objeto especificado. Se o acesso puder ser concedido, a rotina incrementará a contagem de referência de objeto. Esse incremento impede que o objeto seja excluído enquanto o chamador usa o objeto . Quando o objeto não for mais necessário, o chamador deverá diminuir a contagem de referência chamando a rotina ObDereferenceObjectWithTag ou ObDereferenceObjectDeferDeleteWithTag .

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

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

Para exibir um rastreamento de referência de objeto nas ferramentas de depuração do Windows, use a extensão de 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	Universal
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 de DDI	HwStorPortProhibitedDDIs(storport)