Método IWDFUsbTargetPipe2::ConfigureContinuousReader (wudfusb.h)

Artículo
03/08/2023

[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. Para obtener más información, consulta Introducción con UMDF.

El método ConfigureContinuousReader configura el marco para leer continuamente desde una canalización USB.

Sintaxis

HRESULT ConfigureContinuousReader(
  [in]           SIZE_T                                              TransferLength,
  [in]           SIZE_T                                              HeaderLength,
  [in]           SIZE_T                                              TrailerLength,
  [in]           UCHAR                                               NumPendingReads,
  [in, optional] IUnknown                                            *pMemoryCleanupCallbackInterface,
  [in]           IUsbTargetPipeContinuousReaderCallbackReadComplete  *pOnCompletion,
  [in, optional] PVOID                                               pCompletionContext,
  [in, optional] IUsbTargetPipeContinuousReaderCallbackReadersFailed *pOnFailure
);

Parámetros

[in] TransferLength

Longitud máxima, en bytes, de datos que se pueden recibir del dispositivo.

[in] HeaderLength

Desplazamiento, en bytes, en el búfer que recibe datos del dispositivo. El marco almacenará datos del dispositivo en un búfer de lectura, empezando por el valor de desplazamiento. En otras palabras, este espacio precede al espacio de tamaño TransferLength en el que el marco almacena los datos del dispositivo.

[in] TrailerLength

Longitud, en bytes, de un espacio de búfer final. Este espacio sigue el espacio de tamaño TransferLength en el que el marco almacena los datos del dispositivo.

[in] NumPendingReads

Número de solicitudes de lectura que el marco pondrá en cola para recibir datos del destino de E/S. Si este valor es cero, el marco usa un número predeterminado de solicitudes de lectura. Si el valor especificado es mayor que el valor máximo permitido, el marco usa el valor máximo permitido. Para obtener más información sobre el parámetro NumPendingReads , vea la siguiente sección Comentarios.

[in, optional] pMemoryCleanupCallbackInterface

Puntero a una interfaz IUnkown proporcionada por el controlador que el marco usa para acceder a una función de devolución de llamada IObjectCleanup::OnCleanup opcional. El marco llama a la función de devolución de llamada cuando desasigna el búfer de lectura que crea para controlar la operación de lectura continua. Este parámetro es opcional y puede ser NULL.

[in] pOnCompletion

Puntero a una interfaz IUsbTargetPipeContinuousReaderCallbackReadComplete proporcionada por el controlador que proporciona una función de devolución de llamada OnReaderCompletion .

[in, optional] pCompletionContext

Puntero sin tipo a la información de contexto definida por el controlador que el marco pasa a la función de devolución de llamada IUsbTargetPipeContinuousReaderCallbackReadComplete::OnReaderCompletion .

[in, optional] pOnFailure

Puntero a una interfaz IUsbTargetPipeContinuousReaderCallbackReadersFailed proporcionada por el controlador que proporciona una función de devolución de llamada OnReaderFailure .

Valor devuelto

ConfigureContinuousReader devuelve S_OK si la operación se realiza correctamente. De lo contrario, este método puede devolver uno de los valores siguientes:

Código devuelto	Descripción
HRESULT_FROM_NT (STATUS_INVALID_DEVICE_STATE)	El controlador ya ha configurado un lector continuo para la canalización USB. La canalización USB no está configurada para transferencias de entrada masivas o de interrupción.
E_OUTOFMEMORY	Error en el intento del marco de trabajo de asignar un búfer.
ERROR_ARITHMETIC_OVERFLOW	El parámetro TransferLength, HeaderLength o TrailerLength especificó un tamaño demasiado grande o no válido.

Este método podría devolver uno de los otros valores que contiene Winerror.h.

Comentarios

Puede configurar un lector continuo para una canalización masiva o una canalización de interrupción. La canalización debe tener un punto de conexión de entrada.

Después de llamar a ConfigureContinuousReader para configurar un lector continuo, el controlador debe llamar a IWDFIoTargetStateManagement::Start para iniciar el lector. Para detener el lector, el controlador debe llamar a IWDFIoTargetStateManagement::Stop.

Normalmente, un controlador llama a ConfigureContinuousReader desde su función de devolución de llamada IPnpCallbackHardware::OnPrepareHardware . El controlador debe llamar a IWDFIoTargetStateManagement::Start desde su función de devolución de llamada IPnpCallback::OnD0Entry y debe llamar a IWDFIoTargetStateManagement::Stop desde su función de devolución de llamada IPnpCallback::OnD0Exit .

Cada vez que el destino de E/S de la canalización completa correctamente una solicitud de lectura, el marco llama a la función de devolución de llamada IUsbTargetPipeContinuousReaderCallbackReadComplete::OnReaderCompletion . Si el destino de E/S notifica un error al procesar una solicitud, el marco llama a la función de devolución de llamada IUsbTargetPipeContinuousReaderCallbackReadersFailed::OnReaderFailure una vez completadas todas las solicitudes de lectura. (Por lo tanto, no se llamará a la función de devolución de llamada OnReaderCompletion mientras se ejecuta la función de devolución de llamada OnReaderFailure ).

Use las instrucciones siguientes para elegir un valor para el parámetro NumPendingReads :

Establezca NumPendingReads en cero si desea que el controlador use el valor predeterminado del marco.
El valor predeterminado es mayor que uno y proporciona un rendimiento razonablemente bueno para muchos dispositivos en muchas configuraciones de procesador.
Establezca NumPendingReads en uno si es importante que el controlador reciba búferes de datos en el orden exacto en el que el dispositivo entrega los datos.
Si el marco pone en cola más de una solicitud de lectura, es posible que el controlador no reciba los búferes de datos en el mismo orden en que el dispositivo entrega los datos.
Establezca NumPendingReads en un número que cumpla los requisitos de rendimiento del dispositivo, en función de las medidas de rendimiento exhaustivas.
En primer lugar, pruebe el dispositivo con el valor predeterminado (0) para NumPendingReads. Las pruebas deben incluir varias configuraciones de hardware, incluidos distintos tipos y números de procesadores, y diferentes controladores de host USB y configuraciones USB. A continuación, puede experimentar con valores más altos mediante las mismas pruebas. Un controlador que podría requerir un valor mayor es uno para un dispositivo que tiene una alta velocidad de interrupción, donde los datos se pueden perder si las interrupciones no se aparecen rápidamente.

Un valor NumPendingReads demasiado grande puede ralentizar el rendimiento de un sistema. Debe usar el valor más bajo que cumpla los requisitos de rendimiento. Normalmente, los valores superiores a tres o cuatro no mejoran el rendimiento de los datos. Pero los valores más altos pueden reducir la latencia o la posibilidad de que falten datos en una canalización de alta frecuencia.

Una vez que un controlador ha llamado a 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.

Para obtener más información sobre el método ConfigureContinuousReader y los destinos de E/S USB, consulte Lectura de una canalización UMDF-USB.

Ejemplos

En el ejemplo de código siguiente se configura un lector continuo. En este ejemplo, el tamaño máximo del búfer es el tamaño de un búfer definido por el controlador. Los desplazamientos del búfer de encabezado y finalizador se establecen en cero y el número de operaciones de lectura pendientes se establece en dos. En el ejemplo se usa el puntero de interfaz de la canalización de destino para el parámetro pCompletionContext , por lo que la función de devolución de llamada OnReaderCompletion puede determinar la canalización en la que se completó la operación de lectura.

HRESULT hr, hrQI;
IUsbTargetPipeContinuousReaderCallbackReadComplete *pOnCompletionCallback = NULL;
IUsbTargetPipeContinuousReaderCallbackReadersFailed *pOnFailureCallback= NULL;
IWDFUsbTargetPipe2 * pIUsbInterruptPipe2;

//
// Obtain interfaces.
//
hrQI = this->QueryInterface(IID_PPV_ARGS(&pOnCompletionCallback));
if (!SUCCEEDED(hrQI)) goto Error;
hrQI = this->QueryInterface(IID_PPV_ARGS(&pOnFailureCallback));
if (!SUCCEEDED(hrQI)) goto Error;
hrQI = m_pIUsbInterruptPipe->QueryInterface(IID_PPV_ARGS(&pIUsbInterruptPipe2));
if (!SUCCEEDED(hrQI)) goto Error;

//
// Configure the reader.
//
hr = pIUsbInterruptPipe2->ConfigureContinuousReader(
                                                    sizeof(m_MyBuffer), 
                                                    0,
                                                    0,
                                                    2, 
                                                    NULL,
                                                    pOnCompletionCallback,
                                                    m_pIUsbTargetPipe,
                                                    pOnFailureCallback
                                                    );
...

Requisitos

Requisito	Value
Finalización del soporte técnico	No disponible en UMDF 2.0 y versiones posteriores.
Plataforma de destino	Escritorio
Versión mínima de UMDF	1,9
Encabezado	wudfusb.h (incluya Wudfusb.h)
Archivo DLL	WUDFx.dll