Función IoGetDeviceDirectory (wdm.h)

Artículo
08/08/2023

Devuelve un identificador a un directorio en el disco, en el que los controladores pueden almacenar archivos. Los archivos de ese directorio se aplican a una instancia de dispositivo específica.

Sintaxis

NTSTATUS IoGetDeviceDirectory(
  [_In_]  PDEVICE_OBJECT        PhysicalDeviceObject,
  [_In_]  DEVICE_DIRECTORY_TYPE DirectoryType,
  [_In_]  ULONG                 Flags,
  [_In_]  PVOID                 Reserved,
  [_Out_] PHANDLE               DeviceDirectoryHandle
);

Parámetros

[_In_] PhysicalDeviceObject

Puntero al objeto de dispositivo físico que se consulta en la pila de dispositivos de una instancia de dispositivo determinada. No debe ser NULL.

[_In_] DirectoryType

Valor de tipo _DEVICE_DIRECTORY_TYPE que indica el tipo de directorio solicitado.

[_In_] Flags

Debe ser 0.

[_In_] Reserved

Reservado. Debe ser NULL.

[_Out_] DeviceDirectoryHandle

Puntero a una variable que recibe un identificador en el directorio de dispositivos solicitado. El llamador no debe pasar NULL.

Valor devuelto

Devuelve un valor NTSTATUS adecuado. Los valores posibles son:

Código de error	Descripción
STATUS_SUCCESS	La llamada abrió correctamente un identificador en el directorio de dispositivos solicitado.
STATUS_INVALID_PARAMETER	Un valor de entrada para esta función no es válido. Por ejemplo, PhysicalDeviceObject o DeviceDirectoryHandle es NULL; Las marcas no son 0; Reservado no es NULL.

Comentarios

Si se llama a IoGetDeviceDirectory antes de iniciar los discos y volúmenes necesarios, la función no abre un identificador y devuelve un error.

Los controladores suelen usar ZwOpenFile y ZwCreateFile para acceder o crear archivos. Uno de los parámetros de esas funciones es una estructura OBJECT_ATTRIBUTES , que contiene el nombre del objeto y un directorio raíz. Si el directorio raíz es NULL, el nombre del objeto debe ser una ruta de acceso completa. Sin embargo, si proporciona un identificador para el directorio raíz, el nombre del objeto debe ser relativo al objeto (en el caso de los archivos, el directorio), que representa el identificador.

Una vez que la llamada a IoGetDeviceDirectory se realiza correctamente, use el IDENTIFICADOR recibido como directorio raíz en el OBJECT_ATTRIBUTES que se pasa a un ZwOpenFile y ZwCreateFile.

El controlador debe llamar a ZwClose para cerrar el identificador recibido cuando el acceso ya no sea necesario.

Los autores de llamadas de IoGetDeviceDirectory deben ejecutarse en IRQL = PASSIVE_LEVEL en el contexto de un subproceso del sistema.