Creación y uso de objetos de archivo Driver-Created
Advertencia
UMDF 2 es la versión más reciente de UMDF y sustituye a UMDF 1. Todos los controladores UMDF nuevos deben escribirse con UMDF 2. No se agregan nuevas características a UMDF 1 y hay compatibilidad limitada con UMDF 1 en versiones más recientes de Windows 10. Los controladores universales de Windows deben usar UMDF 2.
Los ejemplos de UMDF 1 archivados se pueden encontrar en la Windows 11, versión 22H2 : actualización de ejemplos de controladores de mayo de 2022.
Para obtener más información, consulta Introducción con UMDF.
Si el controlador necesita crear y enviar una solicitud de E/S independiente de la aplicación al siguiente controlador de la pila (el destino de E/S predeterminado), el controlador debe crear y cerrar sus propios objetos de archivo.
Crear un objeto de archivo
El controlador debe llamar al método IWDFDevice::CreateWdfFile para crear un objeto de archivo para el uso del controlador. Cuando el controlador llama a IWDFDevice::CreateWdfFile, el marco envía una solicitud de creación al siguiente controlador de la pila. El siguiente controlador de la pila podría estar en modo kernel o en modo de usuario.
Este procesamiento de solicitudes de creación de archivos es diferente en el modelo de controlador de Windows (WDM). En WDM, una llamada a la función ZwCreateFile hace que un IRP de creación vaya a la parte superior de la pila del modo kernel. En la ilustración siguiente se muestra el procesamiento de solicitudes create-file en UMDF frente a WDM:
Al llamar a IWDFDevice::CreateWdfFile, el controlador puede crear un objeto de archivo y, a continuación, enviar solicitudes de E/S durante el inicio del dispositivo, antes de que se haya iniciado toda la pila.
El siguiente controlador de la pila debe determinar si puede controlar la solicitud create-file o si debe reenviar la solicitud más abajo de la pila.
Después de llamar a IWDFDevice::CreateWdfFile, un controlador no puede cancelar la operación de creación.
Uso del objeto File
Para enviar una solicitud de lectura asincrónica al siguiente controlador apilado debajo, el controlador puede usar el siguiente patrón.
- Llame a IWDFDevice::CreateWdfFile para crear el objeto de archivo.
- Llame a IWDFDevice::GetDefaultIoTarget para recuperar la interfaz que representa el controlador de nivel inferior.
- Llame a IWDFDevice::CreateRequest para crear un objeto IWDFIoRequest sin formato.
- Llame a IWDFIoRequest::SetCompletionCallback para registrar una interfaz IRequestCallbackRequestCompletion para el método OnCompletion al que el marco llama cuando se completa una solicitud de E/S.
- Llame a IWDFIoTarget::FormatRequestForRead y proporcione un puntero a la interfaz IWDFDriverCreatedFile en el parámetro pFile .
- Llame a IWDFIoRequest::Send para enviar la solicitud.
Cerrar el objeto File
El controlador que llamó a IWDFDevice::CreateWdfFile debe llamar posteriormente a IWDFDriverCreatedFile::Close.
Normalmente, el controlador llama a IWDFDriverCreatedFile::Close desde su método de devolución de llamada IPnpCallbackHardware::OnReleaseHardware o IPnpCallbackSelfManagedIo::OnSelfManagedIoCleanup .
Cuando el controlador llama a IWDFDriverCreatedFile::Close, el marco llama al método IFileCallbackCleanup::OnCleanupFile del controlador siguiente. En este método, el controlador siguiente debe cancelar o completar todas las solicitudes de E/S pendientes asociadas al objeto de archivo. A continuación, el marco cancela las solicitudes de E/S creadas por el controlador que llamó a IWDFDevice::CreateWdfFile. El marco de trabajo no cancela ninguna solicitud de E/S que reduzca los controladores de la pila puede haber asociado con el objeto de archivo. Es responsabilidad del conductor cancelar dichas solicitudes. El objeto de archivo solo se cierra después de que se hayan completado todas las solicitudes de E/S asociadas.
A continuación, el marco llama al método IFileCallbackClose::OnCloseFile del controlador siguiente. En este momento, el marco garantiza que el controlador siguiente no recibirá solicitudes de E/S adicionales para este objeto de archivo.
Una vez que el marco llama a OnCloseFile, destruye la interfaz IWDFFile que representa el objeto de archivo.
Si los objetos de archivo creados por el controlador permanecen después de la devolución de los métodos de eliminación de dispositivos del controlador (por ejemplo , IPnpCallbackHardware::OnReleaseHardware e IPnpCallbackSelfManagedIo::OnSelfManagedIoCleanup), el marco genera una detención del controlador. Para obtener información sobre cómo solucionar este problema, vea Determinar por qué UMDF indica archivos pendientes en tiempo de eliminación de dispositivos.