Trabajar con canalizaciones USB en controladores UMDF 1.x
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.
El marco representa cada canalización de una interfaz USB como un objeto de canalización USB de marco. Cuando un controlador configura un dispositivo USB, el marco crea un objeto de canalización USB de marco para cada canalización de cada interfaz seleccionada. Los métodos de objeto de canalización permiten que un controlador:
Obtención de información de canalización UMDF-USB
Después de que un controlador UMDF llame al método IWDFUsbInterface::RetrieveUsbPipeObject para obtener un puntero a la interfaz IWDFUsbTargetPipe para un objeto de canalización USB, el controlador puede llamar a los métodos siguientes que el objeto de canalización USB define para obtener información sobre la canalización USB:
IWDFUsbTargetPipe::GetInformation
Recupera información sobre una canalización USB y su punto de conexión.
IWDFUsbTargetPipe::GetType
Devuelve el tipo de una canalización USB.
IWDFUsbTargetPipe::IsInEndPoint
Determina si una canalización USB está conectada a un punto de conexión de entrada.
IWDFUsbTargetPipe::IsOutEndPoint
Determina si una canalización USB está conectada a un punto de conexión de salida.
IWDFUsbTargetPipe::RetrievePipePolicy
Recupera una directiva de canalización de WinUsb.
Lectura desde una canalización UMDF-USB
Para leer datos de una canalización de entrada USB, el controlador puede usar (o ambos) de las técnicas siguientes:
Leer datos de forma sincrónica.
Para leer datos de forma sincrónica desde una canalización de entrada USB, un controlador UMDF llama primero al método IWDFIoTarget::FormatRequestForRead para crear una solicitud de lectura. A continuación, el controlador llama al método IWDFIoRequest::Send , especificando la marca de WDF_REQUEST_SEND_OPTION_SYNCHRONOUS, para enviar la solicitud de forma sincrónica.
Leer datos de forma asincrónica.
Para leer datos de forma asincrónica desde una canalización de entrada USB, un controlador UMDF llama primero al método IWDFIoTarget::FormatRequestForRead para compilar una solicitud de lectura. A continuación, el controlador llama al método IWDFIoRequest::Send sin especificar la marca WDF_REQUEST_SEND_OPTION_SYNCHRONOUS.
Leer datos de forma sincrónica y continua.
Un lector continuo es un mecanismo proporcionado por el marco que garantiza que una solicitud de lectura esté siempre disponible para una canalización USB. Este mecanismo garantiza que el controlador siempre está listo para recibir datos de un dispositivo que proporciona un flujo de entrada asincrónico y no solicitado. Por ejemplo, un controlador para una tarjeta de interfaz de red (NIC) podría usar un lector continuo para recibir datos de entrada.
Para configurar un lector continuo para una canalización de entrada, la función de devolución de llamada IPnpCallbackHardware::OnPrepareHardware debe llamar al método IWDFUsbTargetPipe2::ConfigureContinuousReader . Este método pone en cola un conjunto de solicitudes de lectura al destino de E/S del dispositivo.
Además, la función de devolución de llamada IPnpCallback::OnD0Entry del controlador debe llamar a IWDFIoTargetStateManagement::Start para iniciar el lector continuo y la función de devolución de llamada IPnpCallback::OnD0Exit debe llamar a IWDFIoTargetStateManagement::Stop para detener el lector continuo.
Cada vez que los datos estén disponibles en el dispositivo, el destino de E/S completará una solicitud de lectura y el marco llamará a una de las dos funciones de devolución de llamada: IUsbTargetPipeContinuousReaderCallbackReadComplete::OnReaderCompletion si el destino de E/S lee correctamente los datos o IUsbTargetPipeContinuousReaderCallbackReadersFailed::OnReaderFailure si el destino de E/S notifica un error.
Después de llamar a un controlador IWDFUsbTargetPipe2::ConfigureContinuousReader, el controlador no puede usar IWDFIoRequest::Send para enviar solicitudes de E/S a la canalización a menos que se llame a la función de devolución de llamada IUsbTargetPipeContinuousReaderCallbackReadersFailed::OnReaderFailure y devuelva FALSE.
Los lectores continuos se admiten en las versiones 1.9 y posteriores de UMDF.
Escritura en una canalización UMDF-USB
Para escribir datos en una canalización de salida USB, un controlador UMDF puede llamar primero al método IWDFIoTarget::FormatRequestForWrite para compilar una solicitud de escritura. A continuación, el controlador puede llamar al método IWDFIoRequest::Send para enviar la solicitud de forma asincrónica.
Detener, vaciar y restablecer una canalización UMDF-USB
Un controlador UMDF puede llamar a los métodos siguientes para detener, vaciar o restablecer una canalización USB:
IWDFUsbTargetPipe::Abort
Envía de forma sincrónica una solicitud para detener todas las transferencias pendientes en una canalización USB.
IWDFUsbTargetPipe::Flush
Envía de forma sincrónica una solicitud para descartar los datos que WinUsb guardó cuando el dispositivo devolvió más datos de los solicitados por el cliente.
IWDFUsbTargetPipe::Reset
Envía una solicitud de forma sincrónica para restablecer una canalización USB.
Establecer directiva para una canalización UMDF-USB
Un controlador UMDF puede llamar al método IWDFUsbTargetPipe::SetPipePolicy para controlar el comportamiento usado por WinUsb para una canalización USB (por ejemplo, tiempos de espera, control de paquetes cortos y otros comportamientos).
Control de errores de canalización
Si el destino USB del controlador completa una solicitud de E/S con un valor de estado de error, el controlador debe hacer lo siguiente:
Llame a IWDFIoTargetStateManagement::Stop con la marca WdfIoTargetCancelSentIo establecida. Esta llamada detiene la canalización y cancela las solicitudes de E/S adicionales que el controlador ha enviado al destino USB, si el destino no ha completado las solicitudes.
Llame a IWDFUsbTargetPipe::Abort para enviar una solicitud de anulación a la canalización.
Llame a IWDFUsbTargetPipe::Reset para enviar una solicitud de restablecimiento a la canalización.
Llame a IWDFIoTargetStateManagement::Start para reiniciar la canalización.
Vuelva a enviar la solicitud de E/S que produjo un error y todas las solicitudes de E/S que siguieron a la solicitud con errores.