Função ObReferenceObjectByHandleWithTag (wdm.h)

Artigo
08/08/2023

A rotina ObReferenceObjectByHandleWithTag incrementa a contagem de referência do objeto identificado pelo identificador especificado e grava um valor de marca de quatro bytes no objeto para dar suporte ao rastreamento de referência de objeto.

Sintaxe

NTSTATUS ObReferenceObjectByHandleWithTag(
  [in]            HANDLE                     Handle,
  [in]            ACCESS_MASK                DesiredAccess,
  [in, optional]  POBJECT_TYPE               ObjectType,
  [in]            KPROCESSOR_MODE            AccessMode,
  [in]            ULONG                      Tag,
  [out]           PVOID                      *Object,
  [out, optional] POBJECT_HANDLE_INFORMATION HandleInformation
);

Parâmetros

[in] Handle

Especifica um identificador aberto para um 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. 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

Especifica o modo de acesso a ser usado para o marcar de acesso. Ele deve ser UserMode ou KernelMode. Os drivers sempre devem especificar UserMode para identificadores recebidos do espaço de endereço do usuário.

[in] Tag

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

[out] Object

Um ponteiro para uma variável na qual a rotina grava um ponteiro no objeto . A tabela a seguir lista os tipos de ponteiro object designados pelos possíveis valores de parâmetro ObjectType .

Parâmetro ObjectType	Tipo de ponteiro de objeto
*ExEventObjectType	PKEVENT
*ExSemaphoreObjectType	PKSEMAPHORE
*IoFileObjectType	PFILE_OBJECT
*PsProcessType	PEPROCESS ou PKPROCESS
*PsThreadType	PETHREAD ou PKTHREAD
*SeTokenObjectType	PACCESS_TOKEN
*TmEnlistmentObjectType	PKENLISTMENT
*TmResourceManagerObjectType	PKRESOURCEMANAGER
*TmTransactionManagerObjectType	PKTM
*TmTransactionObjectType	PKTRANSACTION

As estruturas que os tipos de ponteiro referenciam são opacas e os drivers não podem acessar os membros da estrutura. Como as estruturas são opacas, PEPROCESS é equivalente a PKPROCESS e PETHREAD é equivalente a PKTHREAD.

[out, optional] HandleInformation

Os drivers definem esse parâmetro como NULL.

Retornar valor

ObReferenceObjectByHandleWithTag 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 incorreto para o objeto identificado pelo parâmetro Handle .
STATUS_ACCESS_DENIED	O chamador não tem os direitos de acesso necessários ao objeto.
STATUS_INVALID_HANDLE	O identificador especificado não é válido.

Comentários

Essa rotina faz a validação de acesso do identificador de objeto especificado. Se o acesso puder ser concedido, a rotina incrementará a contagem de referência de objeto e fornecerá um ponteiro de objeto para o chamador. 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.

ObReferenceObjectByHandleWithTag não fecha ou invalida o identificador de objeto especificado pelo parâmetro Handle . Quando o identificador não é mais necessário, o chamador pode fechar o identificador chamando a rotina ZwClose .

Se o valor do parâmetro AccessMode for KernelMode, o acesso solicitado será sempre permitido. Se AccessMode for UserMode, o acesso solicitado será comparado aos direitos de acesso que o chamador tem ao objeto . Somente drivers de nível mais alto podem especificar com segurança o valor UserMode para o parâmetro AccessMode .

A partir do Windows 7, se AccessMode for KernelMode e o identificador for recebido do espaço de endereço do usuário, o Verificador de Driver emitirá a verificação de bugs C4, subcodifique F6.

A rotina ObReferenceObjectByHandle é semelhante a ObReferenceObjectByHandleWithTag, exceto que não permite que o chamador escreva uma marca personalizada em um objeto . No Windows 7 e versões posteriores do Windows, ObReferenceObjectByHandle sempre grava um valor de marca padrão ('tlfD') no objeto. Uma chamada para ObReferenceObjectByHandle tem o mesmo efeito que uma chamada para ObReferenceObjectByHandleWithTag 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. A extensão !obtrace será 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	PASSIVE_LEVEL
Regras de conformidade da DDI	HwStorPortProhibitedDDIs(storport)