Função ObOpenObjectByPointer (ntifs.h)

Artigo
08/07/2023

A função ObOpenObjectByPointer abre um objeto referenciado por um ponteiro e retorna um identificador para o objeto .

Sintaxe

NTSTATUS ObOpenObjectByPointer(
  [in]           PVOID           Object,
  [in]           ULONG           HandleAttributes,
  [in, optional] PACCESS_STATE   PassedAccessState,
  [in]           ACCESS_MASK     DesiredAccess,
  [in, optional] POBJECT_TYPE    ObjectType,
  [in]           KPROCESSOR_MODE AccessMode,
  [out]          PHANDLE         Handle
);

Parâmetros

[in] Object

Ponteiro para o objeto a ser aberto.

[in] HandleAttributes

Bitmask de sinalizadores que especificam os atributos desejados para o identificador de objeto. Se o chamador não estiver em execução no contexto do processo do sistema, esses sinalizadores deverão incluir OBJ_KERNEL_HANDLE. Esse parâmetro é opcional e pode ser zero. Caso contrário, será uma combinação or'ed de um ou mais dos valores a seguir.

Sinalizador	Significado
OBJ_EXCLUSIVE	O objeto deve ser aberto para acesso exclusivo. Se esse sinalizador for definido e a chamada para ObOpenObjectByPointer for bem-sucedida, o objeto não poderá ser compartilhado e não poderá ser aberto novamente até que o identificador seja fechado. Esse sinalizador é incompatível com o sinalizador OBJ_INHERIT. Esse sinalizador é inválido para objetos de arquivo.
OBJ_FORCE_ACCESS_CHECK	Todas as verificações de acesso devem ser impostas para o objeto, mesmo que o objeto esteja sendo aberto no modo kernel. Se esse sinalizador for especificado, o valor do parâmetro AccessMode será ignorado.
OBJ_INHERIT	O identificador pode ser herdado por processos filho do processo atual. Esse sinalizador é incompatível com o sinalizador OBJ_EXCLUSIVE.
OBJ_KERNEL_HANDLE	O identificador só pode ser acessado no modo kernel. Esse sinalizador deverá ser especificado se o chamador não estiver em execução no contexto do processo do sistema.

[in, optional] PassedAccessState

Ponteiro para uma estrutura ACCESS_STATE que contém o contexto de assunto do objeto, os tipos de acesso concedidos e os tipos de acesso desejados restantes. Esse parâmetro é opcional e pode ser NULL. Em uma rotina de criação de expedição, esse ponteiro pode ser encontrado em IrpSp-Parameters.Create.SecurityContext-AccessState>>, em que IrpSp é um ponteiro para o próprio local de pilha do chamador no IRP. (Para obter mais informações, consulte IRP_MJ_CREATE.)

[in] DesiredAccess

ACCESS_MASK valor que especifica o acesso desejado ao objeto. Esse parâmetro é opcional e pode ser zero.

[in, optional] ObjectType

Ponteiro para o tipo de objeto. Se o valor de AccessMode for KernelMode, esse parâmetro será opcional e poderá ser NULL. Caso contrário, ele deverá ser *ExEventObjectType, *ExSemaphoreObjectType, *IoFileObjectType, *PsThreadType, *SeTokenObjectType ou *CmKeyObjectType.

Observação

Há suporte para o tipo de objeto SeTokenObjectType olhando para o Windows XP e há suporte para o tipo de objeto CmKeyObjectType com o Windows 7.

[in] AccessMode

Modo de acesso a ser usado para a marcar de acesso. Esse parâmetro é necessário e deve ser UserMode ou KernelMode:

Se AccessMode for KernelMode, o sistema sempre permitirá o acesso solicitado, independentemente de qualquer acesso restrito definido anteriormente por um driver (por exemplo, acesso restrito em uma chamada anterior para POB_PRE_OPERATION_CALLBACK retorno de chamada).
Se AccessMode for UserMode, o acesso solicitado será comparado ao acesso concedido para o objeto.

[out] Handle

Ponteiro para uma variável alocada pelo chamador que recebe um identificador para o objeto .

Retornar valor

ObOpenObjectByPointer retorna STATUS_SUCCESS ou um valor NTSTATUS apropriado, como um dos seguintes:

Código de retorno	Descrição
STATUS_ACCESS_DENIED	O chamador não tinha o acesso necessário para abrir um identificador para o objeto. Este é um código de erro.
STATUS_INSUFFICIENT_RESOURCES	ObOpenObjectByPointer encontrou uma falha de alocação de pool. Este é um código de erro.
STATUS_INVALID_PARAMETER	Um valor de sinalizador inválido foi especificado no parâmetro HandleAttributes . Este é um código de erro.
STATUS_OBJECT_TYPE_MISMATCH	O objeto apontado pelo parâmetro Object não era do tipo especificado no parâmetro ObjectType . Este é um código de erro.
STATUS_PRIVILEGE_NOT_HELD	O chamador não tinha o privilégio necessário para criar um identificador com o acesso especificado no parâmetro DesiredAccess . Este é um código de erro.
STATUS_QUOTA_EXCEEDED	O chamador está em execução no contexto de um processo cuja cota de memória não é suficiente para alocar o identificador de objeto. Este é um código de erro.
STATUS_UNSUCCESSFUL	Não foi possível criar o identificador de objeto. Este é um código de erro.

Comentários

Se o parâmetro Object apontar para um objeto de arquivo (ou seja, uma estrutura FILE_OBJECT), ObOpenObjectByPointer só poderá ser chamado depois que pelo menos um identificador tiver sido criado para o objeto de arquivo. Os chamadores podem marcar o membro Flags da estrutura FILE_OBJECT para a qual o parâmetro Object aponta. Se o sinalizador FO_HANDLE_CREATED estiver definido, isso significa que um ou mais identificadores foram criados para o objeto de arquivo, portanto, é seguro chamar ObOpenObjectByPointer.

Qualquer identificador obtido chamando ObOpenObjectByPointer deverá eventualmente ser liberado chamando ZwClose.

As rotinas de driver executadas em um contexto de processo diferente do processo do sistema devem definir o sinalizador OBJ_KERNEL_HANDLE no parâmetro HandleAttributes . Isso restringe o uso do identificador retornado por ObOpenObjectByPointer a processos em execução no modo kernel. Caso contrário, o identificador pode ser acessado pelo processo em cujo contexto o driver está em execução.