InitializeObjectAttributes, macro (ntdef.h)

Article
08/25/2023

La macro InitializeObjectAttributes initialise la structure opaque OBJECT_ATTRIBUTES , qui spécifie les propriétés d’un handle d’objet aux routines qui ouvrent des handles.

Syntaxe

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

Paramètres

p

Pointeur vers la structure OBJECT_ATTRIBUTES à initialiser.

n

Pointeur vers une chaîne Unicode qui contient le nom de l’objet pour lequel un handle doit être ouvert. Il doit s’agir d’un nom d’objet complet ou d’un nom de chemin d’accès relatif au répertoire d’objets spécifié par le paramètre RootDirectory.

a

Spécifie un ou plusieurs des indicateurs suivants :

Indicateur	Description
OBJ_INHERIT	Ce handle peut être hérité par les processus enfants du processus actuel.
OBJ_PERMANENT	Cet indicateur s’applique uniquement aux objets nommés dans le gestionnaire d’objets. Par défaut, ces objets sont supprimés lorsque tous les handles ouverts sont fermés. Si cet indicateur est spécifié, l’objet n’est pas supprimé lorsque tous les handles ouverts sont fermés. Les pilotes peuvent utiliser ZwMakeTemporaryObject pour supprimer des objets permanents.
OBJ_EXCLUSIVE	Un seul handle peut être ouvert pour cet objet.
OBJ_CASE_INSENSITIVE	Si cet indicateur est spécifié, une comparaison qui ne respecte pas la casse est utilisée lors de la mise en correspondance du paramètre ObjectName avec les noms d’objets existants. Sinon, les noms d’objets sont comparés à l’aide des paramètres système par défaut.
OBJ_OPENIF	Si cet indicateur est spécifié dans une routine qui crée des objets et que cet objet existe déjà, la routine doit ouvrir cet objet. Sinon, la routine qui crée l’objet retourne un code NTSTATUS de STATUS_OBJECT_NAME_COLLISION.
OBJ_KERNEL_HANDLE	Spécifie que le handle est accessible uniquement en mode noyau.
OBJ_FORCE_ACCESS_CHECK	La routine ouvrant le handle doit appliquer toutes les vérifications d’accès pour l’objet, même si le handle est ouvert en mode noyau.

r

Handle vers le répertoire d’objets racine pour le nom de chemin spécifié dans le paramètre ObjectName. Si ObjectName est un nom d’objet complet, RootDirectory a la valeur NULL. Utilisez ZwCreateDirectoryObject ZwCreateDirectoryObject pour obtenir un handle dans un répertoire d’objets.

s

Spécifie un descripteur de sécurité à appliquer à un objet lors de sa création. Ce paramètre est facultatif. Les pilotes peuvent spécifier NULL pour accepter la sécurité par défaut de l’objet. Pour plus d'informations, consultez la section Notes qui suit.

Valeur de retour

None

Notes

InitializeObjectAttributes initialise une structure OBJECT_ATTRIBUTES qui spécifie les propriétés d’un handle d’objet à ouvrir. L’appelant peut ensuite passer un pointeur vers cette structure vers une routine qui ouvre réellement le handle.

Les routines de pilote qui s’exécutent dans un contexte de processus autre que celui du processus système doivent définir l’indicateur OBJ_KERNEL_HANDLE pour le paramètre Attributes . Cet indicateur limite l’utilisation d’un handle ouvert pour cet objet aux processus s’exécutant uniquement en mode noyau. Sinon, le handle est accessible par le processus dans lequel le pilote est en cours d’exécution.

Notez que InitializeObjectAttributes définit toujours le membre SecurityQualityOfService de OBJECT_ATTRIBUTES sur NULL. Les pilotes qui nécessitent une valeur non NULL peuvent définir SecurityQualityOfService directement.