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.

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:

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

Confira também

ACCESS_MASK

ObDereferenceObject

ObReferenceObject

ObReferenceObjectByPointer