Función SerCx2CustomTransmitCreate (sercx.h)

Artículo
10/30/2024

El método SerCx2CustomTransmitCreate crea un objeto de transmisión personalizado, que la versión 2 de la extensión del marco de serie (SerCx2) usa para escribir datos de transmisión al controlador serie mediante un mecanismo personalizado de transferencia de datos.

Sintaxis

NTSTATUS SerCx2CustomTransmitCreate(
  [in]  WDFDEVICE                      Device,
  [in]  PSERCX2_CUSTOM_TRANSMIT_CONFIG CustomTransmitConfig,
  [in]  PWDF_OBJECT_ATTRIBUTES         Attributes,
  [out] SERCX2CUSTOMTRANSMIT           *CustomTransmit
);

Parámetros

[in] Device

Un identificador WDFDEVICE para el objeto de dispositivo de marco que representa el controlador serie. El controlador de controlador serie creó este objeto en su función de devolución de llamada EvtDriverDeviceAdd. Para obtener más información, vea SerCx2InitializeDevice.

[in] CustomTransmitConfig

Puntero a una estructura de SERCX2_CUSTOM_TRANSMIT_CONFIG. Antes de llamar a este método, el llamador debe llamar a la función SERCX2_CUSTOM_TRANSMIT_CONFIG_INIT para inicializar la estructura. Esta estructura contiene punteros a un conjunto de rutinas de devolución de llamada de eventos implementadas por el controlador del controlador serie. SerCx2 llama a estas funciones para realizar transacciones de transmisión personalizadas.

[in] Attributes

Puntero a una estructura WDF_OBJECT_ATTRIBUTES que describe los atributos que se van a asignar al nuevo objeto de transmisión personalizada. Antes de llamar a este método, el autor de la llamada debe llamar a la función WDF_OBJECT_ATTRIBUTES_INIT para inicializar la estructura. Este parámetro es opcional y se puede especificar como WDF_NO_OBJECT_ATTRIBUTES si el controlador del controlador serie no necesita asignar atributos al objeto . Para obtener más información, vea Comentarios.

[out] CustomTransmit

Puntero a una ubicación a la que este método escribe un identificador de SERCX2CUSTOMTRANSMIT en el objeto de transmisión personalizado recién creado. SerCx2 y el controlador del controlador serie usan este identificador en llamadas posteriores para hacer referencia a este objeto.

Valor devuelto

Este método devuelve STATUS_SUCCESS si la llamada se realiza correctamente. Entre los posibles valores devueltos de error se incluyen los siguientes códigos de estado.

Código devuelto	Descripción
STATUS_INVALID_DEVICE_REQUEST	Ya existe un objeto de transmisión personalizada de un anterior llamada SerCx2CustomTransmitCreate; o existe un objeto system-DMA-transmit a partir de una llamada a serCx2SystemDmaTransmitCreate anterior; o existe un objeto system-DMA-transmit a partir de una llamada de anterior SerCx2SystemDmaTransmitCreate; o no se ha llamado a serCx2PioTransmitCreate para crear un objeto PIO-transmit.
STATUS_INVALID_PARAMETER	Un valor de parámetro no es válido.
STATUS_INFO_LENGTH_MISMATCH	El valorConfig Config no es igual a tamaño de(SERCX2_CUSTOM_TRANSMIT_CONFIG).
STATUS_INSUFFICIENT_RESOURCES	Hay recursos insuficientes disponibles para crear el objeto de transmisión personalizada.

Observaciones

El controlador del controlador de serie llama a este método para crear un objeto de transmisión personalizado. SerCx2 usa este objeto para realizar transacciones de transmisión personalizadas, que son transacciones que usan un mecanismo de transferencia de datos personalizado para escribir datos de transmisión al controlador serie.

Un controlador de controlador serie debe llamar correctamente a los métodos SerCx2InitializeDevice y SerCx2PioTransmitCreate métodos antes de llamar a SerCx2CustomTransmitCreate.

Antes de llamar a SerCx2CustomTransmitCreate, el controlador de controlador serie debe llamar a la función SERCX2_CUSTOM_TRANSMIT_CONFIG_INIT para inicializar la estructura de SERCX2_CUSTOM_TRANSMIT_CONFIG apuntada por CustomTransmitConfig. Esta función establece los siguientes miembros de la estructura en cero:

de alineación de
minimumTransactionLength
MaximumTransactionLength
minimumTransferUnit
exclusivo

Si es necesario, el controlador de controlador serie puede establecer cualquiera de estos miembros en valores distintos de cero después de que se devuelva la función de inicialización. Sin embargo, para mayor comodidad, SerCx2CustomTransmitCreate usa los siguientes valores predeterminados si estos miembros son cero:

Si alineación es cero, SerCx2 establece el valor de alineación de datos en uno, lo que significa que el búfer de escritura puede iniciarse en un límite arbitrario de bytes en la memoria.
Si minimumTransactionLength es cero, SerCx2 establece la longitud mínima de la transacción en un byte.
Si MaximumTransactionLength es cero, SerCx2 establece la longitud máxima de transacción en ((ULONG)-1).
Si minimumTransferUnit es cero, SerCx2 establece la unidad de transferencia mínima en un byte.
Si exclusivo es cero (FALSE), el modo exclusivo está deshabilitado.

Si el controlador de llamada establece Exclusive en TRUE, los miembros MinimumTransferUnit, Alignmenty MinimumTransactionLength miembros deben ser cero. Para obtener más información, vea SERCX2_CUSTOM_TRANSMIT_CONFIG.

Como opción, un controlador de controlador serie puede usar el parámetro Attributes para crear un contexto para el objeto de transmisión personalizada y proporcionar punteros a EvtCleanupCallback y EvtDestroyCallback funciones a las que se llama para preparar el objeto para su eliminación. Para obtener más información, vea WDF_OBJECT_ATTRIBUTES.

Si el parámetro Attributes apunta a una estructura WDF_OBJECT_ATTRIBUTES, el autor de la llamada no debe sobrescribir los valores que escribe la función de inicialización WDF_OBJECT_ATTRIBUTES_INIT en el ParentObject, ExecutionLevely SynchronizationScope miembros de esta estructura.

Para obtener más información sobre cómo crear objetos de transmisión personalizados, vea SERCX2CUSTOMTRANSMIT. Para obtener más información sobre las transacciones de transmisión personalizadas, vea SerCx2 Custom-Transmit Transactions.