SerCx2CustomReceiveCreate, fonction (sercx.h)

Article
10/30/2024

La méthode SerCx2CustomReceiveCreate crée un objet de réception personnalisé, que la version 2 de l’extension d’infrastructure série (SerCx2) utilise pour lire les données de réception du contrôleur série au moyen d’un mécanisme de transfert de données personnalisé.

Syntaxe

NTSTATUS SerCx2CustomReceiveCreate(
  [in]  WDFDEVICE                     Device,
  [in]  PSERCX2_CUSTOM_RECEIVE_CONFIG CustomReceiveConfig,
  [in]  PWDF_OBJECT_ATTRIBUTES        Attributes,
  [out] SERCX2CUSTOMRECEIVE           *CustomReceive
);

Paramètres

[in] Device

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

[in] CustomReceiveConfig

Pointeur vers une structure SERCX2_CUSTOM_RECEIVE_CONFIG. Avant d’appeler cette méthode, l’appelant doit appeler la fonction SERCX2_CUSTOM_RECEIVE_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 du contrôleur série. SerCx2 appelle ces fonctions pour effectuer des transactions de réception personnalisées.

[in] Attributes

Pointeur vers une structure WDF_OBJECT_ATTRIBUTES qui décrit les attributs à affecter au nouvel objet de réception personnalisé. 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 du contrôleur série n’a pas besoin d’affecter des attributs à l’objet. Pour plus d’informations, consultez Remarques.

[out] CustomReceive

Pointeur vers un emplacement vers lequel cette méthode écrit un handle SERCX2CUSTOMRECEIVE dans l’objet de réception personnalisé 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 de retour

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

Retourner le code	Description
STATUS_INVALID_DEVICE_REQUEST	Un objet de réception personnalisé existe déjà à partir d’un appel précédent SerCx2CustomReceiveCreate ; ou un objet system-DMA-receive existe à partir d’un appel précédent SerCx2CustomReceiveCreate ; ou un objet de transmission DMA système existe à partir d’un appel précédent SerCx2CustomTransmitCreate ; ou SerCx2PioReceiveCreate n’a pas encore été appelé pour créer un objet piO-receive.
STATUS_INVALID_PARAMETER	Une valeur de paramètre n’est pas valide.
STATUS_INFO_LENGTH_MISMATCH	La valeur Config->Size ne correspond pas taille de(SERCX2_CUSTOM_RECEIVE_CONFIG).
STATUS_INSUFFICIENT_RESOURCES	Les ressources insuffisantes sont disponibles pour créer l’objet de réception personnalisé.

Remarques

Cette méthode est appelée par le pilote du contrôleur série pour créer un objet de réception personnalisé. SerCx2 utilise cet objet pour effectuer des transactions de réception personnalisées, qui sont des transactions qui utilisent un mécanisme de transfert de données personnalisé pour lire les données reçues par le contrôleur série.

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

Avant d’appeler SerCx2CustomReceiveCreate, le pilote du contrôleur série doit appeler la fonction SERCX2_CUSTOM_RECEIVE_CONFIG_INIT pour initialiser la structure SERCX2_CUSTOM_RECEIVE_CONFIG pointée par CustomReceiveConfig. Cette fonction définit les membres suivants de la structure sur zéro :

d’alignement
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érente de zéro après la retour de la fonction d’initialisation. Toutefois, pour des raisons pratiques, SerCx2CustomReceiveCreate utilise les valeurs par défaut suivantes si ces membres sont zéro :

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

Si le pilote appelant définit exclusif sur TRUE, les membres MinimumTransferUnit, Alignmentet MinimumTransactionLength membres doivent être zéro. Pour plus d’informations, consultez SERCX2_CUSTOM_RECEIVE_CONFIG.

En guise d’option, un pilote de contrôleur série peut utiliser le paramètre Attributes pour créer un contexte pour l’objet de réception personnalisée et fournir des pointeurs vers EvtCleanupCallback et EvtDestroyCallback fonctions 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 dans le ParentObject, ExecutionLevelet SynchronizationScope membres de cette structure.

Pour plus d’informations sur la création d’objets de réception personnalisés, consultez SERCX2CUSTOMRECEIVE. Pour plus d’informations sur les transactions de réception personnalisées, consultez SerCx2 Custom-Receive Transactions.