Função ObReferenceObjectByHandleWithTag (wdm.h)
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) |