Macro InitializeObjectAttributes (ntdef.h)

Artigo
08/25/2023

A macro InitializeObjectAttributes inicializa a estrutura de OBJECT_ATTRIBUTES opaca, que especifica as propriedades de um identificador de objeto para rotinas que abrem identificadores.

Sintaxe

VOID InitializeObjectAttributes(
  [out]          POBJECT_ATTRIBUTES   p,
  [in]           PUNICODE_STRING      n,
  [in]           ULONG                a,
  [in]           HANDLE               r,
  [in, optional] PSECURITY_DESCRIPTOR s
);

Parâmetros

p

Um ponteiro para a estrutura OBJECT_ATTRIBUTES a ser inicializada.

n

Um ponteiro para uma cadeia de caracteres Unicode que contém o nome do objeto para o qual um identificador deve ser aberto. Deve ser um nome de objeto totalmente qualificado ou um nome de caminho relativo para o diretório de objeto especificado pelo parâmetro RootDirectory.

a

Especifica um ou mais dos seguintes sinalizadores:

Sinalizador	Descrição
OBJ_INHERIT	Esse identificador pode ser herdado por processos filho do processo atual.
OBJ_PERMANENT	Esse sinalizador só se aplica a objetos nomeados dentro do gerenciador de objetos. Por padrão, esses objetos são excluídos quando todos os identificadores abertos para eles são fechados. Se esse sinalizador for especificado, o objeto não será excluído quando todos os identificadores abertos forem fechados. Os drivers podem usar ZwMakeTemporaryObject para excluir objetos permanentes.
OBJ_EXCLUSIVE	Somente um único identificador pode ser aberto para esse objeto.
OBJ_CASE_INSENSITIVE	Se esse sinalizador for especificado, uma comparação que não diferencia maiúsculas de minúsculas será usada ao corresponder o parâmetro ObjectName com os nomes dos objetos existentes. Caso contrário, os nomes de objeto são comparados usando as configurações padrão do sistema.
OBJ_OPENIF	Se esse sinalizador for especificado para uma rotina que cria objetos e esse objeto já existir, a rotina deverá abrir esse objeto. Caso contrário, a rotina de criação do objeto retorna um código NTSTATUS de STATUS_OBJECT_NAME_COLLISION.
OBJ_KERNEL_HANDLE	Especifica que o identificador só pode ser acessado no modo kernel.
OBJ_FORCE_ACCESS_CHECK	A rotina de abertura do identificador deve impor todas as verificações de acesso para o objeto, mesmo que o identificador esteja sendo aberto no modo kernel.

r

Um identificador para o diretório do objeto raiz para o nome do caminho especificado no parâmetro ObjectName. Se ObjectName for um nome de objeto totalmente qualificado, RootDirectory será NULL. Use ZwCreateDirectoryObject ZwCreateDirectoryObject para obter um identificador para um diretório de objeto.

s

Especifica um descritor de segurança a ser aplicado a um objeto quando ele é criado. Esse parâmetro é opcional. Os drivers podem especificar NULL para aceitar a segurança padrão do objeto. Para obter mais informações, consulte a seção Comentários a seguir.

Valor retornado

Nenhum

Comentários

InitializeObjectAttributes inicializa uma estrutura OBJECT_ATTRIBUTES que especifica as propriedades de um identificador de objeto a ser aberto. Em seguida, o chamador pode passar um ponteiro para essa estrutura para uma rotina que realmente abre o identificador.

As rotinas de driver executadas em um contexto de processo diferente do processo do sistema devem definir o sinalizador OBJ_KERNEL_HANDLE para o parâmetro Attributes . Esse sinalizador restringe o uso de um identificador aberto para esse objeto a processos em execução somente no modo kernel. Caso contrário, o identificador pode ser acessado pelo processo em cujo contexto o driver está em execução.

Observe que InitializeObjectAttributes sempre define o membro SecurityQualityOfService de OBJECT_ATTRIBUTES como NULL. Os drivers que exigem um valor não NULL podem definir SecurityQualityOfService diretamente.