ZwCreateDirectoryObject

NTSTATUS
ZwCreateDirectoryObject(
OUT PHANDLE DirectoryHandle,
IN ACCESS_MASK DesiredAccess,
IN POBJECT_ATTRIBUTES ObjectAttributes
);

ZwCreateDirectoryObject creates or opens a directory object, which is a container for other objects.

Parameters

DirectoryHandle

Points to a variable that receives the directory object handle if the call is successful.

DesiredAccess

Specifies the type of access that the caller requires to the directory object. This value is compared with the granted access on an existing directory object. A caller can specify one or a combination of the following:

ObjectAttributes

Points to a structure that specifies the object's attributes, which has already been initialized with InitializeObjectAttributes.

Return Value

ZwCreateDirectoryObject can return one of the following values:

STATUS_SUCCESS
STATUS_ACCESS_DENIED
STATUS_ACCESS_VIOLATION
STATUS_DATATYPE_MISALIGNMENT

Comments

A directory object is a container for other objects. Note that file system directories are not represented by directory objects, but rather by file objects.

Directory objects are an integral part of the system's object management and are manipulated indirectly as a result of other operations. For example, when a device object is created, its name is inserted in a directory object and the pointer counts of both the directory object and the named device object are incremented. Any named object's header contains a pointer to the directory object containing that object's name.

Drivers that create a set of device objects might set up a directory object when they initialize. For example, a disk driver might use this technique to group the device object representing a physical disk and the device objects representing partitions on that disk in a driver-created directory object.

Before the DriverEntry routine returns control, such a driver calls ZwMakeTemporaryObject if its directory object was initialized with the permanent attribute, and ZwClose to release the directory object created to hold such a group of related device objects.

If a directory object was initialized as temporary and its handle count becomes zero, the directory object's name is deleted. Name deletion occurs for a temporary object when the last handle to the object has been closed. A driver also can delete a directory object it creates when the object is no longer needed by using this technique.

Callers of ZwCreateDirectoryObject must be running at IRQL PASSIVE_LEVEL.

See Also

InitializeObjectAttributes, ObDereferenceObject, ZwClose, ZwMakeTemporaryObject