SerCx2CustomTransmitCreate, fonction (sercx.h)

Article
08/07/2023

La méthode SerCx2CustomTransmitCreate crée un objet de transmission personnalisée, que la version 2 de l’extension d’infrastructure série (SerCx2) utilise pour écrire des données de transmission dans le contrôleur série au moyen d’un mécanisme de transfert de données personnalisé.

Syntaxe

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

Paramètres

[in] Device

Un handle WDFDEVICE pour l’objet d’appareil framework qui représente le contrôleur série. Le pilote du contrôleur série a créé cet objet dans sa fonction de rappel EvtDriverDeviceAdd . Pour plus d’informations, consultez SerCx2InitializeDevice.

[in] CustomTransmitConfig

Pointeur vers une structure SERCX2_CUSTOM_TRANSMIT_CONFIG . Avant d’appeler cette méthode, l’appelant doit appeler la fonction SERCX2_CUSTOM_TRANSMIT_CONFIG_INIT pour initialiser la structure. Cette structure contient des pointeurs vers un ensemble de routines de rappel d’événements implémentées par le pilote de contrôleur série. SerCx2 appelle ces fonctions pour effectuer des transactions de transmission personnalisées.

[in] Attributes

Pointeur vers une structure WDF_OBJECT_ATTRIBUTES qui décrit les attributs à affecter au nouvel objet de transmission personnalisée. Avant d’appeler cette méthode, l’appelant doit appeler la fonction WDF_OBJECT_ATTRIBUTES_INIT pour initialiser la structure. Ce paramètre est facultatif et peut être spécifié en tant que WDF_NO_OBJECT_ATTRIBUTES si le pilote de contrôleur série n’a pas besoin d’affecter des attributs à l’objet. Pour plus d'informations, consultez la section Notes.

[out] CustomTransmit

Pointeur vers un emplacement dans lequel cette méthode écrit un handle de SERCX2CUSTOMTRANSMIT dans l’objet de transmission personnalisée nouvellement créé. SerCx2 et le pilote de contrôleur série utilisent ce handle dans les appels suivants pour faire référence à cet objet.

Valeur retournée

Cette méthode retourne STATUS_SUCCESS si l’appel réussit. Les valeurs de retour d’erreur possibles incluent les codes status suivants.

Code de retour	Description
STATUS_INVALID_DEVICE_REQUEST	Un objet de transmission personnalisée existe déjà à partir d’un appel SerCx2CustomTransmitCreate précédent ; ou un objet system-DMA-transmit existe à partir d’un appel SerCx2SystemDmaTransmitCreate précédent ; ou un objet system-DMA-transmit existe à partir d’un appel SerCx2SystemDmaTransmitCreate précédent ; ou SerCx2PioTransmitCreate n’a pas encore été appelé pour créer un objet de transmission PIO.
STATUS_INVALID_PARAMETER	Une valeur de paramètre n’est pas valide.
STATUS_INFO_LENGTH_MISMATCH	->La valeurTaille de configuration n’est pas égale à sizeof(SERCX2_CUSTOM_TRANSMIT_CONFIG).
STATUS_INSUFFICIENT_RESOURCES	Les ressources disponibles sont insuffisantes pour créer l’objet de transmission personnalisée.

Remarques

Cette méthode est appelée par le pilote du contrôleur série pour créer un objet de transmission personnalisé. SerCx2 utilise cet objet pour effectuer des transactions de transmission personnalisées, qui sont des transactions qui utilisent un mécanisme de transfert de données personnalisé pour écrire des données transmises au contrôleur série.

Un pilote de contrôleur série doit appeler correctement les méthodes SerCx2InitializeDevice et SerCx2PioTransmitCreate avant d’appeler SerCx2CustomTransmitCreate.

Avant d’appeler SerCx2CustomTransmitCreate, le pilote de contrôleur série doit appeler la fonction SERCX2_CUSTOM_TRANSMIT_CONFIG_INIT pour initialiser la structure SERCX2_CUSTOM_TRANSMIT_CONFIG pointée par CustomTransmitConfig. Cette fonction définit les membres suivants de la structure sur zéro :

Alignment
MinimumTransactionLength
MaximumTransactionLength
MinimumTransferUnit
Exclusif

Si nécessaire, le pilote du contrôleur série peut définir l’un de ces membres sur des valeurs différentes de zéro après le retour de la fonction d’initialisation. Toutefois, pour des raisons pratiques, SerCx2CustomTransmitCreate utilise les valeurs par défaut suivantes si ces membres sont zéro :

Si l’alignement est égal à zéro, SerCx2 définit la valeur d’alignement des données sur une valeur, ce qui signifie que la mémoire tampon d’écriture peut démarrer sur une limite d’octets arbitraire dans la mémoire.
Si MinimumTransactionLength est égal à zéro, SerCx2 définit la longueur minimale de transaction sur un octet.
Si MaximumTransactionLength est égal à zéro, SerCx2 définit la longueur maximale de transaction sur ((ULONG)-1).
Si MinimumTransferUnit est égal à zéro, SerCx2 définit l’unité de transfert minimale sur un octet.
Si Exclusive a la valeur zéro (FALSE), le mode exclusif est désactivé.

Si le pilote appelant définit Exclusive sur TRUE, les membres MinimumTransferUnit, Alignment et MinimumTransactionLength doivent être zéro. Pour plus d’informations, consultez SERCX2_CUSTOM_TRANSMIT_CONFIG.

En option, un pilote de contrôleur série peut utiliser le paramètre Attributes pour créer un contexte pour l’objet de transmission personnalisée et pour fournir des pointeurs vers les fonctions EvtCleanupCallback et EvtDestroyCallback appelées pour préparer l’objet à la suppression. Pour plus d’informations, consultez WDF_OBJECT_ATTRIBUTES.

Si le paramètre Attributes pointe vers une structure WDF_OBJECT_ATTRIBUTES , l’appelant ne doit pas remplacer les valeurs que la fonction d’initialisation WDF_OBJECT_ATTRIBUTES_INIT écrit sur les membres ParentObject, ExecutionLevel et SynchronizationScope de cette structure.

Pour plus d’informations sur la création d’objets de transmission personnalisée, consultez SERCX2CUSTOMTRANSMIT. Pour plus d’informations sur les transactions de transmission personnalisée, consultez Transactions Custom-Transmit SerCx2.