Objetos de archivo de marco

Cuando una aplicación o un controlador intentan acceder a un dispositivo, normalmente creando o abriendo un archivo, el sistema operativo envía una solicitud de creación de archivos a la pila de controladores. Cuando la aplicación o el controlador han terminado de usar el dispositivo, el sistema envía solicitudes de limpieza de archivos y cierre a la pila de controladores. Los tipos de solicitud de estas tres solicitudes son WdfRequestTypeCreate, WdfRequestTypeCleanup y WdfRequestTypeClose, respectivamente.

Normalmente, a menos que el controlador haya llamado a WdfDeviceInitSetExclusive, el controlador debe realizar operaciones específicas del archivo u otras operaciones específicas de acceso cuando recibe solicitudes de creación, limpieza y cierre de archivos, ya que varios archivos pueden abrirse simultáneamente o varias aplicaciones pueden acceder al dispositivo simultáneamente. Por lo tanto, el controlador debe realizar un seguimiento de las solicitudes de E/S asociadas a cada archivo o aplicación.

El marco define objetos de archivo de marco, que representan los medios de una aplicación o controlador para acceder a un dispositivo, como un archivo, directorio, volumen, ranura de correo, canalización con nombre o todo el dispositivo. Un nombre de archivo se puede asociar a un objeto de archivo, pero el significado de un nombre de archivo es específico del controlador. Para obtener más información sobre los nombres de archivo, vea Controlar el acceso al espacio de nombres del dispositivo.

Si el controlador debe controlar las operaciones de archivo, debe llamar a WdfDeviceInitSetFileObjectConfig desde su función de devolución de llamada EvtDriverDeviceAdd . El método WdfDeviceInitSetFileObjectConfig recibe una estructura WDF_FILEOBJECT_CONFIG como entrada. El controlador usa esta estructura para registrar sus funciones de devolución de llamada EvtDeviceFileCreate, EvtFileCleanup y EvtFileClose y, opcionalmente, para indicar si el marco debe crear un objeto de archivo de marco cada vez que el controlador recibe una solicitud de creación de archivos.

La mayoría de los controladores que controlan las operaciones de archivo almacenan información específica del archivo en el espacio de contexto del objeto de archivo de marco. Si el controlador controla las operaciones de archivo, pero no necesita almacenar información en el espacio de contexto de un objeto de archivo, el marco de trabajo no tiene que crear objetos de archivo de marco para el controlador.

Crear o abrir un archivo

Cuando el marco recibe una solicitud de creación de archivos para el controlador de función, es:

1. Crea un objeto de archivo de marco que representa el archivo, a menos que el controlador haya indicado anteriormente que no necesita usar objetos de archivo de marco.

2. Llama a la función de devolución de llamada EvtDeviceFileCreate del controlador, si el controlador ha registrado la función de devolución de llamada.

La función de devolución de llamada EvtDeviceFileCreate normalmente obtiene información sobre el archivo, como su nombre y marcas de objeto de archivo. Normalmente, el controlador almacena esta información en el espacio de contexto del objeto de archivo de marco.

En lugar de proporcionar una función de devolución de llamada EvtDeviceFileCreate , el controlador puede llamar a WdfDeviceConfigureRequestDispatching para establecer una cola de E/S para recibir todas las solicitudes de creación de archivos (WdfRequestTypeCreate tipo de solicitud). Posteriormente, el controlador recibirá solicitudes de creación de archivos en el controlador de solicitudes EvtIoDefault de la cola. (Una cola de E/S no puede recibir solicitudes de creación de archivos si el miembro DefaultQueue de la estructura WDF_IO_QUEUE_CONFIG de la cola está establecido en TRUE).

Si el controlador no proporciona una función de devolución de llamada EvtDeviceFileCreate y no configura una cola de E/S para controlar las solicitudes de E/S con tipo WdfRequestTypeCreate, el marco:

• Completa todas las solicitudes de creación de archivos para el controlador con un valor de estado de STATUS_SUCCESS, si el controlador es un controlador de función.

• Reenvía todas las solicitudes de creación de archivos al controlador inferior siguiente, si el controlador es un controlador de filtro.

(Para ver cómo puede cambiar este comportamiento, consulte el miembro AutoForwardCleanupClose de la estructura WDF_FILEOBJECT_CONFIG ).

Nota Si el controlador de función no proporciona ninguna interfaz de dispositivo que las aplicaciones puedan usar para acceder a los dispositivos del controlador, el controlador debe proporcionar una función de devolución de llamada EvtDeviceFileCreate que complete todas las solicitudes de creación de archivos con un valor de estado para el que NT_SUCCESS(status) es igual a FALSE. De lo contrario, una aplicación malintencionada podría intentar acceder a un dispositivo mediante el nombre del objeto de dispositivo físico (PDO) del dispositivo. (Todos los DPO tienen nombres).

Si un controlador reenvía una solicitud de creación a un destino de E/S, el controlador no debe completar posteriormente la solicitud con un valor de estado de error a menos que el controlador reciba un valor de estado de error del destino de E/S. De lo contrario, no se notificará a los controladores inferiores que la solicitud de creación produjo un error y podría intentar funcionar como si el archivo estuviera abierto.

Si un controlador reenvía una solicitud de creación a un destino de E/S, el controlador no puede establecer la marca de WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET si el marco ha creado un objeto de archivo de marco para la solicitud de creación. Por lo tanto, el controlador no puede establecer la marca de WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET para una solicitud de creación a menos que también establezca la marca WdfFileObjectNotRequired , ya que el controlador no podrá limpiar el WDFFILEOBJECT en caso de que un controlador inferior en la pila produzca un error en la solicitud de creación. En su lugar, el controlador puede usar cualquier otra opción de envío, por ejemplo, enviar de forma asincrónica con una rutina de finalización o enviar de forma sincrónica. En ambos casos, el controlador debe llamar a WdfRequestComplete cuando recupera el control.

Tenga en cuenta que si un controlador completa una solicitud de creación con un estado de error, el marco elimina el objeto de archivo de marco, pero no llama a las funciones de devolución de llamada EvtFileCleanup o EvtFileClose del controlador. Por lo tanto, si el controlador asigna memoria adicional específica del objeto fuera del espacio de contexto del objeto de archivo, debe proporcionar una función de devolución de llamada EvtCleanupCallback o EvtDestroyCallback que elimine la memoria asignada.

Para Windows Vista y versiones posteriores, se pueden cancelar las solicitudes de creación de archivos. Las versiones anteriores del sistema operativo Windows no admiten la cancelación de solicitudes de creación de archivos.

El sistema siempre crea un objeto de archivo windows Driver Model (WDM) para cada solicitud de creación que procede de una aplicación de usuario. Si un controlador envía una solicitud de creación, es posible que no cree un objeto de archivo WDM para la solicitud. Normalmente, el marco no crea un objeto de archivo de marco si un objeto de archivo WDM no está presente. Sin embargo, si el controlador ha llamado a WdfDeviceInitSetExclusive y si el controlador ha establecido WdfFileObjectWdfCannotUseFsContexts en el miembro FileObjectClass de la estructura WDF_FILEOBJECT_CONFIG , el marco creará un objeto de archivo de marco incluso si no existe un objeto de archivo WDM.

Obtener información de archivo

La función de devolución de llamada EvtDeviceFileCreate del controlador puede llamar a uno o varios de los métodos de objeto siguientes para obtener información sobre el acceso de una aplicación o controlador a un dispositivo:

WdfFileObjectGetFileName
Devuelve el nombre de archivo contenido en un objeto de archivo de marco.

WdfFileObjectGetFlags
Devuelve las marcas contenidas en un objeto de archivo de marco.

WdfFileObjectWdmGetFileObject
Devuelve el objeto de archivo WDM asociado a un objeto de archivo de marco.

WdfRequestGetParameters
Recupera los parámetros asociados a un objeto de solicitud de marco. Si el tipo de solicitud es WdfRequestTypeCreate, el miembro Parameters.Create de la estructura WDF_REQUEST_PARAMETERS contiene información sobre la solicitud de creación de archivos.

Normalmente, el controlador almacena información de archivo en el espacio de contexto del objeto de archivo de marco. Cuando el controlador obtiene una solicitud de E/S de una si sus colas de E/S, el controlador puede llamar a WdfRequestGetFileObject para obtener un identificador para el objeto de archivo de marco asociado a la solicitud. A continuación, el controlador puede recuperar la información del archivo almacenada en el espacio de contexto del objeto de archivo de marco.

El controlador puede buscar en una cola de E/S las solicitudes asociadas a un archivo determinado llamando a WdfIoQueueRetrieveRequestByFileObject.

Si el controlador tiene un puntero a una estructura de DEVICE_OBJECT WDM, el controlador puede llamar a WdfDeviceGetFileObject para obtener un identificador para el objeto de archivo de marco asociado al objeto de dispositivo WDM.

Cerrar un archivo

Cuando una aplicación u otro controlador cierra un archivo, el marco recibe una solicitud de limpieza y una solicitud de cierre para el controlador. Marco:

1. Llama a las funciones de devolución de llamada EvtFileCleanup y EvtFileClose del controlador, si el controlador ha registrado estas funciones de devolución de llamada.

2. Elimina el objeto de archivo de marco que representa el archivo.

Las funciones de devolución de llamada EvtFileCleanup y EvtFileClose del controlador reciben un identificador para el objeto de archivo de marco. El controlador puede llamar a WdfFileObjectGetDevice para determinar qué objeto de dispositivo de marco está asociado al objeto de archivo de marco.