Uso de objetos de dispositivo de control

Un objeto de dispositivo de control es un objeto de dispositivo de marco que no admite Plug and Play (PnP) ni operaciones de administración de energía. Los controladores pueden usar objetos de dispositivo de control para representar dispositivos virtuales solo de software o dispositivos de hardware heredados (es decir, dispositivos que no proporcionan funcionalidades de administración de energía o PnP).

Un controlador que crea un objeto de dispositivo de control también suele crear un vínculo simbólico para el objeto de dispositivo. Las aplicaciones pueden enviar solicitudes de E/S al objeto de dispositivo de control pasando el nombre del vínculo simbólico a un elemento de API, como la función CreateFile de Microsoft Win32.

El marco de trabajo no asocia objetos de dispositivo de control a una pila de dispositivos. Por lo tanto, cuando una aplicación envía una solicitud de E/S a un objeto de dispositivo de control, el administrador de E/S entrega la solicitud directamente al controlador que creó el objeto de dispositivo de control, en lugar de al controlador en la parte superior de la pila. (Sin embargo, un controlador adicional puede llamar a IoAttachDevice para adjuntar un objeto de dispositivo encima del objeto de dispositivo de control. En este caso, el controlador adicional recibe primero la solicitud de E/S).

Usos de objetos de dispositivo de control

Dos usos típicos para los dispositivos de control son:

1. Un controlador de filtro para un dispositivo PnP, si el controlador admite un conjunto de códigos de control de E/S personalizados para que las aplicaciones las usen.

   Si una aplicación intentó enviar los códigos de control de E/S personalizados a la parte superior de la pila del controlador (por ejemplo, el nombre del vínculo simbólico de una interfaz de dispositivo), un controlador por encima del controlador de filtro podría producir un error en la solicitud de E/S si el controlador no reconoce los códigos de control de E/S personalizados. Para evitar este problema, el controlador de filtro puede crear un objeto de dispositivo de control. Las aplicaciones pueden usar el nombre del vínculo simbólico del objeto de dispositivo de control para enviar códigos de control de E/S directamente al controlador de filtro.

   (Tenga en cuenta que una mejor manera de que el controlador de filtro evite el problema es actuar como controlador de bus y enumerar los dispositivos secundarios que funcionan en modo sin procesar. En otras palabras, para cada dispositivo que admita el controlador de filtro, el controlador puede crear un objeto de dispositivo físico (PDO) que no requiera un controlador de función. El controlador llama a WdfPdoInitAssignRawDevice y WdfDeviceInitAssignName para cada uno de estos dispositivos, y la aplicación puede identificar un dispositivo por nombre cuando envía un código de control de E/S personalizado).

2. Controlador para un dispositivo que no admite PnP.

   Este controlador debe usar objetos de dispositivo de control, ya que los objetos de dispositivo para estos dispositivos no residen en una pila de dispositivos y no proporcionan funcionalidades PnP. Para obtener más información sobre cómo admitir dispositivos que no son PnP, consulte Uso de Kernel-Mode Driver Framework con controladores que no son PnP.

Crear un objeto de dispositivo de control

Para crear un objeto de dispositivo de control, un controlador debe:

1. Llame a WdfControlDeviceInitAllocate para obtener una estructura WDFDEVICE_INIT .

2. Llame a los métodos de inicialización de objetos, según sea necesario, para inicializar la estructura WDFDEVICE_INIT. El controlador solo puede llamar a los métodos de inicialización siguientes:

   • WdfControlDeviceInitSetShutdownNotification
   • WdfDeviceInitAssignName
   • WdfDeviceInitAssignSDDLString
   • WdfDeviceInitAssignWdmIrpPreprocessCallback
   • WdfDeviceInitSetCharacteristics
   • WdfDeviceInitSetDeviceClass
   • WdfDeviceInitSetExclusive
   • WdfDeviceInitSetFileObjectConfig
   • WdfDeviceInitSetIoInCallerContextCallback
   • WdfDeviceInitSetIoType
   • WdfDeviceInitSetRequestAttributes

3. Llame a WdfDeviceCreate, que usa el contenido de la estructura WDFDEVICE_INIT para crear un objeto de dispositivo de marco.

4. Complete las siguientes operaciones de inicialización:

   • Cree una cola de E/S predeterminada para el dispositivo, si es necesario.
   • Llame a WdfDeviceConfigureRequestDispatching, si es necesario.
   • Llame a WdfDeviceCreateSymbolicLink para crear un nombre de vínculo simbólico que las aplicaciones puedan usar para acceder al dispositivo de control.

5. Llame a WdfControlFinishInitializing.

Reglas para usar objetos de dispositivo de control

Los controladores que crean objetos de dispositivo de control deben cumplir las reglas siguientes:

• Los controladores no pueden pasar el identificador del objeto de dispositivo de control a los métodos de marco que enumeran los dispositivos secundarios.

• Los controladores no pueden pasar el identificador del objeto de dispositivo de control a los métodos de marco que admiten interfaces de dispositivo.

• Los controladores pueden crear colas de E/S y registrar controladores de solicitudes para las colas, pero el marco no permite administrar las colas.

• Los controladores pueden crear objetos de archivo para controlar objetos de dispositivo.

Asignar un nombre a un objeto de dispositivo de control

Se debe asignar un nombre a todos los objetos de dispositivo de control. Normalmente, el controlador llamará a WdfDeviceInitAssignName para asignar un nombre de dispositivo y, a continuación, llamará a WdfDeviceCreateSymbolicLink para crear un nombre de vínculo simbólico que las aplicaciones pueden usar para tener acceso al objeto.

Si el controlador no llama a WdfDeviceInitAssignName para asignar un nombre de dispositivo, el marco genera automáticamente un nombre para los dispositivos de control, pero el controlador no puede llamar a WdfDeviceCreateSymbolicLink.

El controlador puede llamar a WdfDeviceInitSetDeviceClass para especificar una clase de configuración de dispositivo para un dispositivo de control. La clase de instalación de dispositivos identifica una sección del Registro que contiene información proporcionada por el administrador sobre los dispositivos que pertenecen a la clase de instalación. Para obtener más información sobre cómo llamar a WdfDeviceInitSetDeviceClass, vea Controlar el acceso a dispositivos en controladores de Framework-Based.

Recepción de la notificación del apagado del sistema

Dado que los objetos de dispositivo de control no admiten PnP, el controlador no puede registrar funciones de devolución de llamada que informen al controlador cuando cambia el estado de energía de un dispositivo. Sin embargo, el controlador puede llamar a WdfControlDeviceInitSetShutdownNotification para registrar una función de devolución de llamada EvtDeviceShutdownNotification . Esta función de devolución de llamada informa al controlador cuando el sistema está a punto de perder su potencia.

Eliminar un objeto de dispositivo de control

Algunos controladores tienen que eliminar sus objetos de dispositivo de control antes de que se descargue el controlador, como se indica a continuación:

• Si el controlador crea objetos de dispositivo de control (que no admiten PnP o administración de energía) y si el controlador también crea objetos de dispositivo de marco que admiten PnP y administración de energía, el controlador debe llamar finalmente a WdfObjectDelete en IRQL = PASSIVE_LEVEL para eliminar los objetos de dispositivo de control.

  Si el controlador crea ambos tipos de objetos de dispositivo, el sistema operativo no puede descargar el controlador hasta que el controlador haya eliminado los objetos de dispositivo de control.

  Sin embargo, el controlador no debe eliminar los objetos de dispositivo de control hasta que el marco haya eliminado los demás objetos de dispositivo. Para determinar cuándo el marco ha eliminado los demás objetos de dispositivo, el controlador debe proporcionar funciones EvtCleanupCallback para esos objetos.

• Si el controlador crea objetos de dispositivo de control pero no crea objetos de dispositivo de marco que admiten PnP y administración de energía, el controlador no tiene que eliminar los objetos de dispositivo de control.

  En este caso, el marco elimina los objetos de dispositivo de control después de que se devuelva la función de devolución de llamada EvtDriverUnload del controlador.