EVT_WDF_USB_READER_COMPLETION_ROUTINE función de devolución de llamada (wdfusb.h)

  • Artículo

[Se aplica a KMDF y UMDF]

La función de devolución de llamada de eventos EvtUsbTargetPipeReadComplete de un controlador informa al controlador de que un lector continuo ha completado correctamente una solicitud de lectura.

Sintaxis

EVT_WDF_USB_READER_COMPLETION_ROUTINE EvtWdfUsbReaderCompletionRoutine;

void EvtWdfUsbReaderCompletionRoutine(
  [in] WDFUSBPIPE Pipe,
  [in] WDFMEMORY Buffer,
  [in] size_t NumBytesTransferred,
  [in] WDFCONTEXT Context
)
{...}

Parámetros

[in] Pipe

Identificador de un objeto de canalización de marco.

[in] Buffer

Identificador de un objeto de memoria de marco que representa un búfer que contiene datos del dispositivo.

[in] NumBytesTransferred

Número de bytes de datos que se encuentran en el búfer de lectura.

[in] Context

Información de contexto definida por el controlador que el controlador especificó en el miembro EvtUsbTargetPipeReadCompleteContext de la estructura WDF_USB_CONTINUOUS_READER_CONFIG de la canalización.

Valor devuelto

None

Observaciones

Para registrar una función de devolución de llamada EvtUsbTargetPipeReadComplete , el controlador debe colocar la dirección de la función en una estructura de WDF_USB_CONTINUOUS_READER_CONFIG .

Si un controlador ha creado un lector continuo para una canalización USB, el marco llama a la función de devolución de llamada EvtUsbTargetPipeReadComplete del controlador cada vez que el destino de E/S del controlador completa correctamente una solicitud de lectura. Se llama a la función de devolución de llamada en irQL en la que el destino de E/S completó la solicitud de lectura, que normalmente es IRQL = DISPATCH_LEVEL, pero no superior a DISPATCH_LEVEL. (Si el destino de E/S no completa correctamente una solicitud, el marco llama a la función de devolución de llamada EvtUsbTargetPipeReadersFailed del controlador).

Para acceder al búfer que contiene datos leídos desde el dispositivo, el controlador puede llamar a WdfMemoryGetBuffer. El marco escribe los datos en el búfer, después del encabezado definido por el miembro HeaderLength de la estructura WDF_USB_CONTINUOUS_READER_CONFIG . Tenga en cuenta que el puntero que WdfMemoryGetBuffer devuelve apunta al principio del encabezado, pero el parámetro NumBytesTransferred de la función de devolución de llamada EvtUsbTargetPipeReadCompleteno incluye la longitud del encabezado.

De forma predeterminada, el marco elimina el objeto de memoria del búfer después de que se devuelva la función de devolución de llamada EvtUsbTargetPipeReadComplete . Sin embargo, es posible que desee que el objeto de memoria permanezca válido después de que se devuelva la función de devolución de llamada. Por ejemplo, es posible que desee que el controlador almacene el identificador de objeto en el espacio de contexto del objeto de canalización de marco para que el controlador pueda procesar el contenido del objeto de memoria después de que se devuelva la función de devolución de llamada. Para extender la duración del objeto de memoria, la función de devolución de llamada debe pasar el identificador del objeto de memoria a WdfObjectReference. Posteriormente, el controlador debe llamar a WdfObjectDereference para que el marco pueda eliminar el objeto.

El marco sincroniza las llamadas a las funciones de devolución de llamada EvtUsbTargetPipeReadComplete y EvtUsbTargetPipeReadersFailed según las reglas siguientes:

  • Estas funciones de devolución de llamada no se ejecutan simultáneamente para una canalización USB individual.
  • Si el controlador crea varios lectores continuos para varias canalizaciones USB, con varias funciones de devolución de llamada EvtUsbTargetPipeReadComplete y EvtUsbTargetPipeReadersFailed , las múltiples funciones de devolución de llamada se pueden ejecutar simultáneamente.
  • Si el controlador ha especificado el valor predeterminado NumPendingReads o un valor mayor que 1, y si se completa una solicitud de lectura mientras se ejecuta la función de devolución de llamada EvtUsbTargetPipeReadComplete , el marco puede llamar a la función de devolución de llamada EvtUsbTargetPipeReadComplete antes de que se devuelva la función de devolución de llamada.
  • El marco de trabajo no sincroniza estas funciones de devolución de llamada con ninguna otra función de devolución de llamada.
En el miembro BufferAttributes de la estructura WDF_USB_CONTINUOUS_READER_CONFIG , el controlador puede especificar las funciones de devolución de llamada EvtCleanupCallback y EvtDestroyCallback para el objeto de memoria. Si especifica una función de devolución de llamada EvtCleanupCallback , el marco llamará a esa función de devolución de llamada cuando intente eliminar el objeto de memoria, después de que se devuelva la función de devolución de llamada EvtUsbTargetPipeReadComplete . Si la función de devolución de llamada EvtUsbTargetPipeReadComplete ha llamado a WdfObjectReference, la función de devolución de llamada EvtCleanupCallback (si se proporciona) no debe llamar a WdfObjectDereference.

El controlador debe llamar a WdfObjectDereference cuando haya terminado de usar el objeto de memoria. A continuación, el marco puede llamar a la función de devolución de llamada EvtDestroyCallback del controlador (si se proporciona) y eliminar el objeto de memoria.

Para obtener más información sobre la función de devolución de llamada EvtUsbTargetPipeReadComplete y los destinos de E/S USB, consulte Destinos de E/S USB.

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 Wdf.h)
IRQL <=DISPATCH_LEVEL (vea la sección Comentarios).

Consulte también

EvtUsbTargetPipeReadersFailed

WDF_USB_CONTINUOUS_READER_CONFIG

WdfMemoryGetBuffer