EVT_SERCX2_CUSTOM_RECEIVE_TRANSACTION_START función de devolución de llamada (sercx.h)

Artículo
10/30/2024

La función de devolución de llamada de eventos EvtSerCx2CustomReceiveTransactionStart llama a la versión 2 de la extensión del marco de serie (SerCx2) para iniciar una transacción de recepción personalizada.

Sintaxis

EVT_SERCX2_CUSTOM_RECEIVE_TRANSACTION_START EvtSercx2CustomReceiveTransactionStart;

void EvtSercx2CustomReceiveTransactionStart(
  [in] SERCX2CUSTOMRECEIVETRANSACTION CustomReceiveTransaction,
  [in] WDFREQUEST Request,
  [in] PMDL Mdl,
  [in] ULONG Offset,
  [in] ULONG Length
)
{...}

Parámetros

[in] CustomReceiveTransaction

Identificador de SERCX2CUSTOMRECEIVETRANSACTION a un objeto custom-receive-transaction. El controlador de controlador serie llamó anteriormente al método SerCx2CustomReceiveTransactionCreate para crear este objeto.

[in] Request

Identificador del objeto de solicitud de marco asociado a la transacción de recepción personalizada. El controlador es responsable de completar esta solicitud. Es posible que esta solicitud no sea la solicitud IRP_MJ_READ enviada por el cliente y, por tanto, el controlador del controlador serie no debe intentar usar esta solicitud para acceder al búfer de lectura. Esta solicitud se usa principalmente para la cancelación, finalización y reenvío de cola (si es necesario). Para tener acceso al búfer de lectura de la solicitud de lectura del cliente, use los parámetros dede Mdl, Offsety Length.

[in] Mdl

Puntero a un MDL que describe las páginas de memoria que abarca el búfer de lectura para la transacción de recepción personalizada. La lista de dispersión y recopilación de la transferencia de datos usará la región de esta memoria especificada por los parámetros de Offset y Length.

[in] Offset

Desplazamiento inicial de la transferencia de datos. Este parámetro es un desplazamiento de bytes desde el principio de la región del búfer descrita por MDL. Si MDL especifica un total de N bytes de espacio en búfer, los valores posibles de desplazamiento están en el intervalo de 0 a N-1.

[in] Length

Tamaño, en bytes, de la transferencia de datos. Si MDL especifica un total de N bytes de espacio en búfer, los valores posibles de Longitud están en el intervalo de 1 a N-Desplazamiento.

Valor devuelto

Ninguno

Observaciones

El controlador de controlador serie debe implementar esta función si crea un objeto custom-receive-transaction. El controlador registra la función en la llamada SerCx2CustomReceiveTransactionCreate que crea este objeto.

Después de que SerCx2 llama a la función EvtSerCx2CustomReceiveTransactionStart, el controlador de controlador serie inicia la transacción mediante la programación del mecanismo de transferencia de datos personalizado para mover datos del FIFO de recepción en el hardware del controlador serie al búfer de la solicitud de lectura. A menos que la solicitud se pueda completar inmediatamente, antes de que se devuelva la función EvtSerCx2CustomReceiveTransactionStart, el controlador debe llamar a un método como WdfRequestMarkCancelableEx para marcar la solicitud como cancelable.

Una vez que la función EvtSerCx2CustomReceiveTransactionStart inicia la transacción, SerCx2 llama periódicamente al EvtSerCx2CustomReceiveTransactionQueryProgress función de devolución de llamada de eventos para supervisar el progreso realizado por el controlador de serie en la realización de esta transacción. Una vez finalizada la transacción y el controlador completa la solicitud de lectura pendiente, SerCx2 llama a la EvtSerCx2CustomReceiveTransactionCleanup función de devolución de llamada de eventos, si el controlador implementa esta función.

Si el controlador del controlador serie implementa un EvtSerCx2CustomReceiveTransactionInitialize función de devolución de llamada de eventos, SerCx2 llama a esta función antes de llamar a la función EvtSerCx2CustomReceiveTransactionStart. Justo antes de la llamada EvtSerCx2CustomReceiveTransactionStart y después de la llamada EvtSerCx2CustomReceiveTransactionInitialize devuelve, SerCx2 inicia el temporizador que detecta si se agota el tiempo de espera de la solicitud de lectura. Para obtener más información, consulte la explicación de los tiempos de espera totales en SERIAL_TIMEOUTS.

Si el mecanismo de transferencia de datos personalizado es un dispositivo DMA maestro de bus, La función evtSerCx2CustomReceiveTransactionStart puede llamar a un método como WdfDmaTransactionInitializeUsingOffset para iniciar una transacción DMA que use el búfer de lectura descrito por el Mdl, Offsety parámetros length.

Si el objeto de solicitud identificado por el parámetro request contiene almacenamiento para un contexto privado, este almacenamiento podría no inicializarse la primera vez que el controlador del controlador serie accede al contexto. En el primer acceso, el controlador normalmente debe rellenar el contexto con ceros y, después, si es necesario, establecer explícitamente los campos en el contexto que requieran valores iniciales distintos de cero.

Para obtener más información, vea SerCx2 Custom-Receive Transactions.

Ejemplos

Para definir un EvtSerCx2CustomReceiveTransactionStart función de devolución de llamada, primero debe proporcionar una declaración de función que identifique el tipo de función de devolución de llamada que está definiendo. Windows proporciona un conjunto de tipos de función de devolución de llamada para controladores. Declarar una función mediante los tipos de función de devolución de llamada ayuda a Análisis de código para controladores, comprobador de controladores estáticos (SDV) y otras herramientas de comprobación encuentran errores y es un requisito para escribir controladores para el sistema operativo Windows.

Por ejemplo, para definir un EvtSerCx2CustomReceiveTransactionStart función de devolución de llamada denominada MyCustomReceiveTransactionStart, use el tipo de función EVT_SERCX2_CUSTOM_RECEIVE_TRANSACTION_START, como se muestra en este ejemplo de código:

EVT_SERCX2_CUSTOM_RECEIVE_TRANSACTION_START  MyCustomReceiveTransactionStart;

A continuación, implemente la función de devolución de llamada de la siguiente manera:

_Use_decl_annotations_
VOID
  MyCustomReceiveTransactionStart(
    SERCX2CUSTOMRECEIVETRANSACTION  CustomReceiveTransaction,
    WDFREQUEST  Request,
    PMDL  Mdl,
    ULONG  Offset,
    ULONG  Length
    )
  {...}

El tipo de función EVT_SERCX2_CUSTOM_RECEIVE_TRANSACTION_START se define en el archivo de encabezado Sercx.h. Para identificar con más precisión los errores al ejecutar las herramientas de análisis de código, asegúrese de agregar la anotación Use_decl_annotations a la definición de función. La anotación Use_decl_annotations garantiza que se usen las anotaciones que se aplican al tipo de función EVT_SERCX2_CUSTOM_RECEIVE_TRANSACTION_START en el archivo de encabezado. Para obtener más información sobre los requisitos de las declaraciones de función, consulte Declaración de funciones mediante tipos de rol de función para controladores kmDF. Para obtener más información sobre Use_decl_annotations, vea Anotación del comportamiento de la función.

Requisitos

Requisito	Valor
cliente mínimo admitido	Disponible a partir de Windows 8.1.
de la plataforma de destino de	Escritorio
encabezado de	sercx.h
irQL	Se llama a irQL <= DISPATCH_LEVEL.