ZwOpenDirectoryObject function (ntifs.h)

  • Article

The ZwOpenDirectoryObject routine opens an existing directory object.

Syntax

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

Parameters

[out] DirectoryHandle

Handle for the newly opened directory object.

[in] DesiredAccess

An ACCESS_MASK structure specifying the requested types of access being requested for this directory object. A caller can specify one or a combination of the following.

DesiredAccess Flags Meaning
DIRECTORY_QUERY Query access to the directory object
DIRECTORY_TRAVERSE Name-lookup access to the directory object
DIRECTORY_CREATE_OBJECT Name-creation access to the directory object
DIRECTORY_CREATE_SUBDIRECTORY Subdirectory-creation access to the directory object
DIRECTORY_ALL_ACCESS All of the preceding rights plus STANDARD_RIGHTS_REQUIRED.
 

These requested access types are compared with the object's discretionary access-control list (DACL) to determine which accesses are granted or denied.

[in] ObjectAttributes

Specified attributes for the directory object supplied by the caller. This parameter is initialized by calling the InitializeObjectAttributes macro.

Return value

ZwOpenDirectoryObject returns STATUS_SUCCESS or an appropriate error status. The most common error status codes include the following:

Return code Description
STATUS_INSUFFICIENT_RESOURCES
 A temporary buffer required by this routine could not be allocated.
STATUS_INVALID_PARAMETER
 The specified ObjectAttributes parameter was a NULL pointer, not a valid pointer to an OBJECT_ATTRIBUTES structure, or some of the fields specified in the OBJECT_ATTRIBUTES structure were invalid.
STATUS_OBJECT_NAME_INVALID
 The ObjectAttributes parameter contained an ObjectName field in the OBJECT_ATTRIBUTES structure that was invalid because an empty string was found after the OBJECT_NAME_PATH_SEPARATOR character.
STATUS_OBJECT_NAME_NOT_FOUND
 The ObjectAttributes parameter contained an ObjectName field in the OBJECT_ATTRIBUTES structure that could not be found.
STATUS_OBJECT_PATH_NOT_FOUND
 The ObjectAttributes parameter contained an ObjectName field in the OBJECT_ATTRIBUTES structure with an object path that could not be found.
STATUS_OBJECT_PATH_SYNTAX_BAD
 The ObjectAttributes parameter did not contain a RootDirectory field, but the ObjectName field in the OBJECT_ATTRIBUTES structure was an empty string or did not contain an OBJECT_NAME_PATH_SEPARATOR character. This indicates incorrect syntax for the object path.
 

The ZwOpenDirectoryObject routine throws an exception if the DirectoryHandle parameter is an illegal pointer.

Remarks

ZwOpenDirectoryObject opens an existing directory object and returns a handle to the object.

The ZwOpenDirectoryObject routine is called after the InitializeObjectAttributes macro is used to initialize specific attributes of the OBJECT_ATTRIBUTES structure for the object to be opened.

A directory object is created using the ZwCreateDirectoryObject routine. Any handle obtained by calling ZwOpenDirectoryObject must eventually be released by calling ZwClose.

For more information about security and access control, see Windows security model for driver developers and the documentation on these topics in the Windows SDK.

Note  If the call to the ZwCreateDirectoryObject function occurs in user mode, you should use the name "NtCreateDirectoryObject" instead of "ZwCreateDirectoryObject".
 
For calls from kernel-mode drivers, the NtXxx and ZwXxx versions of a Windows Native System Services routine can behave differently in the way that they handle and interpret input parameters. For more information about the relationship between the NtXxx and ZwXxx versions of a routine, see Using Nt and Zw Versions of the Native System Services Routines.

Requirements

Requirement Value
Minimum supported client Windows XP
Target Platform Universal
Header ntifs.h (include Ntdef.h, Ntifs.h, Fltkernel.h)
Library NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL
DDI compliance rules HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)

See also

ACCESS_MASK

ACL

InitializeObjectAttributes

Using Nt and Zw Versions of the Native System Services Routines

ZwClose

ZwCreateDirectoryObject