IoGetDriverDirectory function (wdm.h)

Article
02/25/2022

Returns a handle to a directory on disk from which the driver can read and write files. The files in that directory apply to a specific driver object.

Syntax

NTSTATUS IoGetDriverDirectory(
  [_In_]  PDRIVER_OBJECT        DriverObject,
  [_In_]  DRIVER_DIRECTORY_TYPE DirectoryType,
  [_In_]  ULONG                 Flags,
  [_Out_] PHANDLE               DriverDirectoryHandle
);

Parameters

[_In_] DriverObject

A pointer to the driver object (DRIVER_OBJECT structure) of the calling driver.

[_In_] DirectoryType

A _DRIVER_DIRECTORY_TYPE-type value that indicates the type of requested directory.

[_In_] Flags

Must be 0.

[_Out_] DriverDirectoryHandle

A pointer to a variable that receives a HANDLE to the requested driver directory. The caller must not pass NULL.

Return value

Returns an appropriate NTSTATUS value. Possible values include:

Error code	Description
STATUS_SUCCESS	The call successfully opened a handle to the requested driver directory.
STATUS_INVALID_PARAMETER	An input value to this function is invalid. For example, DriverObject or DriverDirectoryHandle is NULL; Flags is not 0.

Remarks

If IoGetDriverDirectory is called before the required disks and volumes have been started, the function does not open a handle and returns an error.

Drivers typically use ZwOpenFile and ZwCreateFile to access/create files. One of the parameters for those functions is an OBJECT_ATTRIBUTES structure, which contains the object name and a root directory. If the root directory is NULL, then the object name must be a fully qualified path. However, if you provide a handle for the root directory, then the object name must be relative to the object (in the case of files, the directory), that the handle represents.

After the IoGetDriverDirectory call succeeds, use the received HANDLE as a root directory in the OBJECT_ATTRIBUTES that you are passing to a ZwOpenFile and ZwCreateFile.

The driver must call ZwClose to close the received handle when access is no longer required.

Callers of IoGetDriverDirectory must be running at IRQL = PASSIVE_LEVEL in the context of a system thread.

Requirements

Requirement	Value
Minimum supported client	Windows 10, version 1803
Header	wdm.h
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL