Função ObReferenceObjectByHandle (wdm.h)
A rotina ObReferenceObjectByHandle fornece validação de acesso no identificador do objeto e, se o acesso puder ser concedido, retornará o ponteiro correspondente para o corpo do objeto.
Sintaxe
NTSTATUS ObReferenceObjectByHandle(
[in] HANDLE Handle,
[in] ACCESS_MASK DesiredAccess,
[in, optional] POBJECT_TYPE ObjectType,
[in] KPROCESSOR_MODE AccessMode,
[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 solicitados ao objeto . A interpretação desse campo depende do tipo de objeto. Não use nenhum direito de acesso genérico. Para obter mais informações, consulte ACCESS_MASK.
[in, optional] ObjectType
Ponteiro para o tipo de objeto. ObjectType pode ser *ExEventObjectType, *ExSemaphoreObjectType, *IoFileObjectType, *PsProcessType, *PsThreadType, *SeTokenObjectType, *TmEnlistmentObjectType, *TmResourceManagerObjectType, *TmTransactionManagerObjectType ou *TmTransactionObjectType.
Se ObjectType não for NULL, o sistema operacional verificará se o tipo de objeto fornecido corresponde ao tipo de objeto do objeto especificado por 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.
[out] Object
Ponteiro para uma variável que recebe um ponteiro para o corpo do objeto. A tabela a seguir contém os tipos de ponteiro.
| 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 isso como NULL.
Retornar valor
ObReferenceObjectByHandle retornará STATUS_SUCCESS se a chamada for bem-sucedida. Os possíveis valores retornados incluem os seguintes códigos de erro:
| 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 pode receber os direitos de acesso solicitados ao objeto . |
| STATUS_INVALID_HANDLE | O parâmetro Handle não é um identificador de objeto válido. |
Comentários
Um ponteiro para o corpo do objeto é recuperado da entrada da tabela de objetos e retornado ao chamador por meio do parâmetro Object .
Se AccessMode for UserMode, o acesso solicitado será comparado ao acesso concedido para o objeto. Se AccessMode for KernelMode, o identificador deverá ter origem no espaço de endereço do kernel.
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.
Se a chamada for bem-sucedida, um ponteiro para o corpo do objeto será retornado ao chamador e a contagem de referência do ponteiro será incrementada. Incrementar essa contagem impede que o objeto seja excluído enquanto o ponteiro está sendo referenciado. O chamador deve diminuir a contagem de referência com ObDereferenceObject assim que for feito com o objeto .
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Disponível a partir do Windows 2000. |
| Plataforma de Destino | Universal |
| Cabeçalho | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| Biblioteca | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| Regras de conformidade da DDI | HwStorPortProhibitedDIs(storport), IrqlObPassive(wdm), TargetRelationNeedsRef(wdm) |