ZwOpenDirectoryObject, fonction (ntifs.h)

Article
03/01/2024

La routine ZwOpenDirectoryObject ouvre un objet répertoire existant.

Syntaxe

NTSYSAPI NTSTATUS ZwOpenDirectoryObject(
  [out] PHANDLE            DirectoryHandle,
  [in]  ACCESS_MASK        DesiredAccess,
  [in]  POBJECT_ATTRIBUTES ObjectAttributes
);

Paramètres

[out] DirectoryHandle

Handle pour l’objet d’annuaire nouvellement ouvert.

[in] DesiredAccess

Structure ACCESS_MASK spécifiant les types d’accès demandés pour cet objet d’annuaire. Un appelant peut en spécifier un ou une combinaison des éléments suivants.

DesiredAccess Drapeaux	Signification
DIRECTORY_QUERY	Interroger l’accès à l’objet directory
DIRECTORY_TRAVERSE	Accès nom-recherche à l’objet d’annuaire
DIRECTORY_CREATE_OBJECT	Accès de création de nom à l’objet d’annuaire
DIRECTORY_CREATE_SUBDIRECTORY	Accès de création de sous-répertoire à l’objet directory
DIRECTORY_ALL_ACCESS	Tous les droits précédents plus STANDARD_RIGHTS_REQUIRED.

Ces types d’accès demandés sont comparés à la liste de contrôle d’accès discrétionnaire (DACL) de l’objet pour déterminer quels accès sont accordés ou refusés.

[in] ObjectAttributes

Attributs spécifiés pour l’objet directory fourni par l’appelant. Ce paramètre est initialisé en appelant la macro InitializeObjectAttributes .

Valeur retournée

ZwOpenDirectoryObject retourne STATUS_SUCCESS ou une erreur appropriée status. Les codes de status d’erreur les plus courants sont les suivants :

Code de retour	Description
STATUS_INSUFFICIENT_RESOURCES	Une mémoire tampon temporaire requise par cette routine n’a pas pu être allouée.
STATUS_INVALID_PARAMETER	Le paramètre ObjectAttributes spécifié était un pointeur NULL , pas un pointeur valide vers une structure OBJECT_ATTRIBUTES , ou certains champs spécifiés dans la structure OBJECT_ATTRIBUTES n’étaient pas valides.
STATUS_OBJECT_NAME_INVALID	Le paramètre ObjectAttributes contenait un champ ObjectName dans la structure OBJECT_ATTRIBUTES qui n’était pas valide, car une chaîne vide a été trouvée après le caractère OBJECT_NAME_PATH_SEPARATOR.
STATUS_OBJECT_NAME_NOT_FOUND	Le paramètre ObjectAttributes contenait un champ ObjectName dans la structure OBJECT_ATTRIBUTES introuvable.
STATUS_OBJECT_PATH_NOT_FOUND	Le paramètre ObjectAttributes contenait un champ ObjectName dans la structure OBJECT_ATTRIBUTES avec un chemin d’accès à l’objet introuvable.
STATUS_OBJECT_PATH_SYNTAX_BAD	Le paramètre ObjectAttributes ne contenait pas de champ RootDirectory , mais le champ ObjectName dans la structure OBJECT_ATTRIBUTES était une chaîne vide ou ne contenait pas de caractère OBJECT_NAME_PATH_SEPARATOR. Cela indique une syntaxe incorrecte pour le chemin d’accès de l’objet.

La routine ZwOpenDirectoryObject lève une exception si le paramètre DirectoryHandle est un pointeur non conforme.

Remarques

ZwOpenDirectoryObject ouvre un objet d’annuaire existant et retourne un handle à l’objet.

La routine ZwOpenDirectoryObject est appelée après l’utilisation de la macro InitializeObjectAttributes pour initialiser des attributs spécifiques de la structure OBJECT_ATTRIBUTES pour l’objet à ouvrir.

Un objet directory est créé à l’aide de la routine ZwCreateDirectoryObject. Tout handle obtenu en appelant ZwOpenDirectoryObject doit finalement être libéré en appelant ZwClose.

Pour plus d’informations sur la sécurité et le contrôle d’accès, consultez Modèle de sécurité Windows pour les développeurs de pilotes et la documentation sur ces rubriques dans le Kit de développement logiciel (SDK) Windows.

Note Si l’appel à la fonction ZwCreateDirectoryObject se produit en mode utilisateur, vous devez utiliser le nom « NtCreateDirectoryObject » au lieu de « ZwCreateDirectoryObject ».

Pour les appels provenant de pilotes en mode noyau, les versions NtXxx et ZwXxx d’une routine Windows Native System Services peuvent se comporter différemment dans la façon dont elles gèrent et interprètent les paramètres d’entrée. Pour plus d’informations sur la relation entre les versions NtXxx et ZwXxx d’une routine, consultez Using Nt and Zw Versions of the Native System Services Routines.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP
Plateforme cible	Universal
En-tête	ntifs.h (inclure Ntdef.h, Ntifs.h, Fltkernel.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Règles de conformité DDI	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)