Macro InitializeObjectAttributes (ntdef.h)

Articolo
08/25/2023

La macro InitializeObjectAttributes inizializza la struttura OBJECT_ATTRIBUTES opaca, che specifica le proprietà di un handle di oggetto per le routine che aprono handle.

Sintassi

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

Parametri

p

Puntatore alla struttura OBJECT_ATTRIBUTES da inizializzare.

n

Puntatore a una stringa Unicode contenente il nome dell'oggetto per il quale deve essere aperto un handle. Deve essere un nome di oggetto completo o un nome di percorso relativo alla directory dell'oggetto specificata dal parametro RootDirectory.

a

Specifica uno o più flag seguenti:

Flag	Descrizione
OBJ_INHERIT	Questo handle può essere ereditato dai processi figlio del processo corrente.
OBJ_PERMANENT	Questo flag si applica solo agli oggetti denominati all'interno del gestore oggetti. Per impostazione predefinita, tali oggetti vengono eliminati quando vengono chiusi tutti gli handle aperti. Se questo flag viene specificato, l'oggetto non viene eliminato quando tutti gli handle aperti vengono chiusi. I driver possono usare ZwMakeTemporaryObject per eliminare oggetti permanenti.
OBJ_EXCLUSIVE	Per questo oggetto è possibile aprire un solo handle.
OBJ_CASE_INSENSITIVE	Se questo flag viene specificato, viene utilizzato un confronto senza distinzione tra maiuscole e minuscole quando si associa il parametro ObjectName ai nomi degli oggetti esistenti. In caso contrario, i nomi degli oggetti vengono confrontati usando le impostazioni di sistema predefinite.
OBJ_OPENIF	Se questo flag viene specificato in una routine che crea oggetti e tale oggetto esiste già, la routine deve aprire tale oggetto. In caso contrario, la routine che crea l'oggetto restituisce un codice NTSTATUS di STATUS_OBJECT_NAME_COLLISION.
OBJ_KERNEL_HANDLE	Specifica che è possibile accedere all'handle solo in modalità kernel.
OBJ_FORCE_ACCESS_CHECK	La routine che apre l'handle deve applicare tutti i controlli di accesso per l'oggetto, anche se l'handle viene aperto in modalità kernel.

r

Handle per la directory dell'oggetto radice per il nome del percorso specificato nel parametro ObjectName. Se ObjectName è un nome di oggetto completo, RootDirectory è NULL. Utilizzare ZwCreateDirectoryObject ZwCreateDirectoryObject per ottenere un handle in una directory di oggetti.

s

Specifica un descrittore di sicurezza da applicare a un oggetto al momento della creazione. Questo parametro è facoltativo e, I driver possono specificare NULL per accettare la sicurezza predefinita per l'oggetto. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.

Valore restituito

nessuno

Osservazioni

InitializeObjectAttributes inizializza una struttura OBJECT_ATTRIBUTES che specifica le proprietà di un handle di oggetto da aprire. Il chiamante può quindi passare un puntatore a questa struttura a una routine che apre effettivamente l'handle.

Le routine del driver eseguite in un contesto di processo diverso da quello del processo di sistema devono impostare il flag di OBJ_KERNEL_HANDLE per il parametro Attributes . Questo flag limita l'uso di un handle aperto per tale oggetto ai processi in esecuzione solo in modalità kernel. In caso contrario, l'handle può essere accessibile dal processo nel cui contesto è in esecuzione il driver.

Si noti che InitializeObjectAttributes imposta sempre il membro SecurityQualityOfService di OBJECT_ATTRIBUTES su NULL. I driver che richiedono un valore non NULL possono impostare direttamente SecurityQualityOfService .