Función WdfUsbTargetPipeConfigContinuousReader (wdfusb.h)

Artículo
08/08/2023

[Se aplica a KMDF y UMDF]

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

Sintaxis

NTSTATUS WdfUsbTargetPipeConfigContinuousReader(
  [in] WDFUSBPIPE                        Pipe,
  [in] PWDF_USB_CONTINUOUS_READER_CONFIG Config
);

Parámetros

[in] Pipe

Identificador de un objeto de canalización de marco que se obtuvo mediante una llamada a WdfUsbInterfaceGetConfiguredPipe.

[in] Config

Puntero a una estructura de WDF_USB_CONTINUOUS_READER_CONFIG asignada por el autor de la llamada.

Valor devuelto

WdfUsbTargetPipeConfigContinuousReader devuelve STATUS_SUCCESS 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
STATUS_INFO_LENGTH_MISMATCH	Tamaño de la estructura WDF_USB_CONTINUOUS_READER_CONFIG que el parámetro Config especificado era incorrecto.
STATUS_INVALID_PARAMETER	Se ha detectado un parámetro no válido.
STATUS_INSUFFICIENT_RESOURCES	Memoria insuficiente disponible.
STATUS_INVALID_DEVICE_REQUEST	El tipo de la canalización no era válido.
STATUS_INTEGER_OVERFLOW	El miembro HeaderLength, TransferLength o TrailerLength de la estructura WDF_USB_CONTINUOUS_READER_CONFIG que el parámetro Config especificó un tamaño que era demasiado grande o no válido.
STATUS_INVALID_BUFFER_SIZE	El tamaño del búfer de lectura no era un múltiplo del tamaño máximo del paquete de la canalización.

Para obtener una lista de otros valores devueltos que podría devolver el método WdfUsbTargetPipeConfigContinuousReader, vea Errores de creación de objetos de marco.

Este método también podría devolver otros valores NTSTATUS.

Se produce una comprobación de errores si el controlador proporciona un identificador de objeto no válido.

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 WdfUsbTargetPipeConfigContinuousReader para configurar un lector continuo, el controlador debe llamar a WdfIoTargetStart para iniciar el lector. Para detener el lector, el controlador debe llamar a WdfIoTargetStop.

Normalmente, un controlador llama a WdfUsbTargetPipeConfigContinuousReader desde su función de devolución de llamada EvtDevicePrepareHardware . El controlador debe llamar a WdfIoTargetStart desde su función de devolución de llamada EvtDeviceD0Entry y debe llamar a WdfIoTargetStop desde su función de devolución de llamada EvtDeviceD0Exit .

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 EvtUsbTargetPipeReadComplete del controlador. 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 EvtUsbTargetPipeReadersFailed del controlador una vez completadas todas las solicitudes de lectura. (Por lo tanto, no se llamará a la función de devolución de llamada EvtUsbTargetPipeReadComplete mientras se está ejecutando la función de devolución de llamada EvtUsbTargetPipeReadersFailed ).

Si no proporciona la devolución de llamada opcional EvtUsbTargetPipeReadersFailed , el marco responde a un intento de lectura erróneo enviando otra solicitud de lectura. Por lo tanto, si el bus está en un estado en el que no acepta lecturas, el marco envía continuamente nuevas solicitudes para recuperarse de una lectura errónea.

Una vez que un controlador haya llamado a WdfUsbTargetPipeConfigContinuousReader, el controlador no puede usar WdfUsbTargetPipeReadSynchronously o WdfRequestSend para enviar solicitudes de E/S a la canalización a menos que se haya detenido el lector continuo. Para detener el lector, el controlador puede llamar a WdfIoTargetStop o devolver FALSE desde su función de devolución de llamada EvtUsbTargetPipeReadersFailed . Si el controlador llama a WdfUsbTargetPipeReadSynchronousmente mientras se detiene el lector, debe establecer la marca WDF_REQUEST_SEND_OPTION_IGNORE_TARGET_STATE en el miembro Flags del parámetro RequestOptions . De lo contrario, la solicitud se escribirá en lápiz hasta que se reinicie el destino.

El marco establece la marca USBD_SHORT_TRANSFER_OK en su URB interno. Establecer esta marca permite que el último paquete de una transferencia de datos sea menor que el tamaño máximo del paquete.

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

Ejemplos

En el ejemplo de código siguiente se inicializa una estructura de WDF_USB_CONTINUOUS_READER_CONFIG y se llama a WdfUsbTargetPipeConfigContinuousReader.

WDF_USB_CONTINUOUS_READER_CONFIG  contReaderConfig;
NTSTATUS  status;

WDF_USB_CONTINUOUS_READER_CONFIG_INIT(
                                      &contReaderConfig,
                                      OsrFxEvtUsbInterruptPipeReadComplete,
                                      DeviceContext,
                                      sizeof(UCHAR)
                                      );
status = WdfUsbTargetPipeConfigContinuousReader(
                                      Pipe,
                                      &contReaderConfig
                                      );

Requisitos

Requisito	Value
Plataforma de destino	Universal
Versión mínima de KMDF	1.0
Versión mínima de UMDF	2.0
Encabezado	wdfusb.h (incluya Wdfusb.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
Reglas de cumplimiento de DDI	DriverCreate(kmdf), FailD0EntryIoTargetState(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), UsbContReader(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)