IoGetDeviceDirectory function (wdm.h)
Returns a handle to a directory on disk, in which drivers can store files. The files in that directory apply to a specific device instance.
Syntax
NTSTATUS IoGetDeviceDirectory(
[_In_] PDEVICE_OBJECT PhysicalDeviceObject,
[_In_] DEVICE_DIRECTORY_TYPE DirectoryType,
[_In_] ULONG Flags,
[_In_] PVOID Reserved,
[_Out_] PHANDLE DeviceDirectoryHandle
);
Parameters
[_In_] PhysicalDeviceObject
A pointer to the physical device object being queried in the device stack of a particular device instance. Must not be NULL.
[_In_] DirectoryType
A _DEVICE_DIRECTORY_TYPE-type value that indicates the type of requested directory.
[_In_] Flags
Must be 0.
[_In_] Reserved
Reserved. Must be NULL.
[_Out_] DeviceDirectoryHandle
A pointer to a variable that receives a HANDLE to the requested device 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 device directory. |
| STATUS_INVALID_PARAMETER | An input value to this function is invalid. For example, PhysicalDeviceObject or DeviceDirectoryHandle is NULL; Flags is not 0; Reserved is not NULL. |
Remarks
If IoGetDeviceDirectory 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 IoGetDeviceDirectory 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 IoGetDeviceDirectory 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 |