EVT_SERCX2_CONTROL fonction de rappel (sercx.h)

Article
10/30/2024

La fonction de rappel d’événements EvtSerCx2Control est appelée par la version 2 de l’extension d’infrastructure série (SerCx2) pour gérer une demande de contrôle d’E/S série.

Syntaxe

EVT_SERCX2_CONTROL EvtSercx2Control;

NTSTATUS EvtSercx2Control(
  [in] WDFDEVICE Device,
  [in] WDFREQUEST Request,
  [in] size_t OutputBufferLength,
  [in] size_t InputBufferLength,
  [in] ULONG IoControlCode
)
{...}

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] Request

Handle WDFREQUEST pour l’objet de demande d’infrastructure qui représente la demande de contrôle d’E/S série.

[in] OutputBufferLength

Longueur, en octets, de la mémoire tampon de sortie pour la demande de contrôle d’E/S série spécifiée par le paramètre Demande.

[in] InputBufferLength

Longueur, en octets, de la mémoire tampon d’entrée pour la demande de contrôle d’E/S série spécifiée par le paramètre Demande.

[in] IoControlCode

Spécifie le code de contrôle d’E/S (IOCTL) à partir de la demande de contrôle d’E/S série spécifiée par le paramètre Requête. Les listes IOCTL pour les demandes de contrôle d’E/S série sont définies dans le fichier d’en-tête Ntddser.h. Pour plus d’informations, consultez Remarques.

Valeur de retour

La fonction EvtSerCx2Control retourne STATUS_SUCCESS si l’appel réussit. Sinon, elle retourne un code d’état d’erreur approprié.

Remarques

Votre pilote de contrôleur série doit implémenter cette fonction. Le pilote inscrit la fonction dans l’appel à la méthode SerCx2InitializeDevice qui termine l’initialisation de l’objet d’appareil framework pour le contrôleur série.

La fonction EvtSerCx2Control permet à votre pilote de gérer certaines demandes de contrôle d’E/S série que SerCx2 ne peut pas gérer. SerCx2 gère tout le traitement d’un sous-ensemble des IOCTL série définis dans le fichier d’en-tête Ntddser.h. Toutefois, SerCx2 s’appuie sur le pilote pour gérer les demandes de contrôle d’E/S série pour effectuer des opérations dépendantes du matériel.

Lorsque SerCx2 reçoit une demande de contrôle d’E/S série qui peut être gérée uniquement par le pilote du contrôleur série, SerCx2 appelle la fonction EvtSerCx2Control pour transmettre la demande de contrôle d’E/S au pilote. Le pilote est responsable de la fin de cette demande. Un pilote qui n’implémente pas la prise en charge d’une demande de contrôle d’E/S particulière doit effectuer cette demande de contrôle d’E/S avec le code d’état d’erreur STATUS_NOT_SUPPORTED.

Pour terminer la demande de contrôle d’E/S, le pilote appelle généralement la méthode WdfRequestComplete et fournit, en tant que paramètres d’entrée, la valeur du paramètre demande et une valeur d’état pour indiquer si la demande a réussi. Cette valeur d’état est écrite dans le bloc d’état de la demande.

La valeur de retour de la fonction EvtSerCx2Control doit toujours correspondre à la valeur d’état que cette fonction écrit dans le bloc d’état de la demande de contrôle d’E/S. L’implémentation actuelle de SerCx2 ignore cette valeur de retour.

SerCx2 appelle la fonction EvtSerCx2Control pour gérer les IOCTLs indiquées dans le tableau suivant. La colonne située à droite de la table indique si la fonction EvtSerCx2Control est nécessaire pour implémenter la prise en charge d’un IOCTL particulier.

Nom de la demande de contrôle d’E/S	Obligatoire ou facultatif
IOCTL_SERIAL_CLR_DTR	Optionnel
IOCTL_SERIAL_CLR_RTS	Obligatoire
IOCTL_SERIAL_GET_BAUD_RATE	Obligatoire
IOCTL_SERIAL_GET_COMMSTATUS	Obligatoire
IOCTL_SERIAL_GET_DTRRTS	Obligatoire
IOCTL_SERIAL_GET_HANDFLOW	Obligatoire
IOCTL_SERIAL_GET_LINE_CONTROL	Obligatoire
IOCTL_SERIAL_GET_MODEM_CONTROL	Obligatoire
IOCTL_SERIAL_GET_MODEMSTATUS	Obligatoire
IOCTL_SERIAL_GET_PROPERTIES	Obligatoire
IOCTL_SERIAL_SET_BAUD_RATE	Obligatoire
IOCTL_SERIAL_SET_BREAK_OFF	Obligatoire
IOCTL_SERIAL_SET_BREAK_ON	Obligatoire
IOCTL_SERIAL_SET_DTR	Optionnel
IOCTL_SERIAL_SET_FIFO_CONTROL	Optionnel
IOCTL_SERIAL_SET_HANDFLOW	Obligatoire
IOCTL_SERIAL_SET_LINE_CONTROL	Obligatoire
IOCTL_SERIAL_SET_MODEM_CONTROL	Obligatoire
IOCTL_SERIAL_SET_RTS	Obligatoire

Le tableau précédent répertorie tous les IOCTLs série présentés par SerCx2 à la fonction EvtSerCx2Control . SerCx2 gère le IOCTL ou échoue immédiatement à IOCTL et définit l’état de la demande sur STATUS_NOT_SUPPORTED. SerCx2 gère les requêtes IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION, mais appelle la fonction de rappel d’événements EvtSerCx2ApplyConfig pendant le traitement de cette demande. SerCx2 gère les requêtes IOCTL_SERIAL_PURGE, mais peut appeler la fonction de rappel d’événements EvtSerCx2PurgeFifos pendant le traitement de cette requête. SerCx effectue un traitement préliminaire des requêtes IOCTL_SERIAL_SET_WAIT_MASK, mais appelle la fonction de rappel d’événements EvtSerCx2SetWaitMask, si elle est implémentée, pour terminer la gestion d’une telle requête. Pour plus d’informations sur la prise en charge de SerCx2 pour les IOCTLs série, consultez interface de requête d’E/S série.

IOCTL_SERIAL_CLR_DTR et IOCTL_SERIAL_SET_DTR

Si la fonction EvtSerCx2Control dans votre pilote de contrôleur série prend en charge la requête IOCTL_SERIAL_SET_DTR, cette fonction doit également prendre en charge la requête IOCTL_SERIAL_CLR_DTR, et vice versa. Si votre pilote ne prend pas en charge ces deux requêtes, le gestionnaire du pilote pour la requête IOCTL_SERIAL_GET_DTRRTS doit définir le bit d’indicateur SERIAL_DTR_STATE dans la valeur de sortie de cette requête sur zéro.

IOCTL_SERIAL_GET_DTRRTS

La fonction EvtSerCx2Control dans votre pilote de contrôleur série doit prendre en charge la requête IOCTL_SERIAL_GET_DTRRTS, mais le gestionnaire du pilote pour cette demande est nécessaire pour prendre en charge uniquement le bit d’indicateur SERIAL_RTS_STATE dans la valeur de sortie de cette requête. En guise d’option, le pilote peut également prendre en charge le bit d’indicateur SERIAL_DTR_STATE. Si le bit d’indicateur SERIAL_DTR_STATE n’est pas pris en charge, définissez ce bit sur zéro.

IOCTL_SERIAL_GET_COMMSTATUS

La fonction EvtSerCx2Control dans votre pilote de contrôleur série doit prendre en charge la requête IOCTL_SERIAL_GET_COMMSTATUS, mais le gestionnaire du pilote pour cette demande est nécessaire pour prendre en charge uniquement les membres suivants de la structure SERIAL_STATUS utilisée par cette demande :

erreurs
HoldReasons

En guise d’option, le pilote peut également prendre en charge l’un des autres membres de cette structure. Définissez tous les membres non pris en charge sur zéro.

IOCTL_SERIAL_GET_PROPERTIES

La fonction EvtSerCx2Control dans votre pilote de contrôleur série doit prendre en charge la demande de IOCTL_SERIAL_GET_PROPERTIES. Le gestionnaire du pilote pour cette requête doit définir le membre MaxBaud de la structure SERIAL_COMMPROP utilisée par cette requête sur le taux maximal de bauds pris en charge, exprimé en bits par seconde (bps). Par exemple, si le contrôleur série prend en charge un taux maximal de bauds de 115 200 bps, le pilote définit MaxBaud = 115200.

IOCTL_SERIAL_GET_MODEMSTATUS

La fonction EvtSerCx2Control dans votre pilote de contrôleur série doit prendre en charge la requête IOCTL_SERIAL_GET_MODEMSTATUS. Le gestionnaire du pilote pour cette requête doit définir la valeur de sortie de la requête sur la valeur d’inscription d’état du modem brut lue à partir du matériel du contrôleur série.

IOCTL_SERIAL_GET_HANDFLOW et IOCTL_SERIAL_SET_HANDFLOW

La fonction EvtSerCx2Control dans votre pilote de contrôleur série doit prendre en charge les requêtes IOCTL_SERIAL_GET_HANDFLOW et IOCTL_SERIAL_SET_HANDFLOW, mais elle est nécessaire pour prendre en charge uniquement un sous-ensemble des bits d’indicateur définis pour ces requêtes. Les bits d’indicateur sont définis pour les ControlHandShake et FlowReplace membres de la structure SERIAL_HANDFLOW utilisée par ces requêtes.

Votre pilote doit prendre en charge le bit d’indicateur suivant dans le membre ControlHandshake :

SERIAL_CTS_HANDSHAKE

En guise d’option, un pilote peut prendre en charge l’un des autres bits d’indicateur définis pour le membre ControlHandshake.

Votre pilote doit prendre en charge les bits d’indicateur suivants dans le membre FlowReplace :

SERIAL_RTS_CONTROL
SERIAL_RTS_HANDSHAKE

En guise d’option, un pilote peut prendre en charge l’un des autres bits d’indicateur définis pour le membre FlowReplace. Toutefois, ces autres bits d’indicateur sont rarement, si nécessaire, et Microsoft recommande de les prendre en charge.

Un pilote qui ne prend pas en charge un bit d’indicateur particulier dans le ControlHandShake ou membre FlowReplace doit définir ce bit d’indicateur sur zéro dans la valeur de sortie de la requête IOCTL_SERIAL_GET_HANDFLOW. Si une requête IOCTL_SERIAL_SET_HANDFLOW spécifie un ControlHandshake ou FlowReplace bit d’indicateur que le pilote ne prend pas en charge, la fonction EvtSerCx2Control doit échouer à la requête et retourner STATUS_INVALID_PARAMETER.

En guise d’option, un pilote peut prendre en charge les membres XonLimit et XoffLimit de la structure SERIAL_HANDFLOW. Toutefois, ces membres sont rarement, si jamais, nécessaires, et Microsoft recommande de les prendre en charge. Un pilote qui ne prend pas en charge le XonLimit et les membres XoffLimit doivent définir ces membres sur zéro dans la valeur de sortie de la requête IOCTL_SERIAL_GET_HANDFLOW. Si une requête IOCTL_SERIAL_SET_HANDFLOW spécifie un membre XonLimit ou membre XoffLimit et que le pilote ne prend pas en charge ces membres, la fonction EvtSerCx2Control doit échouer et retourner STATUS_NOT_IMPLEMENTED.

Exemples

Pour définir une fonction de rappel EvtSerCx2Control, vous devez d’abord fournir une déclaration de fonction qui identifie le type de fonction de rappel que vous définissez. Windows fournit un ensemble de types de fonctions de rappel pour les pilotes. La déclaration d’une fonction à l’aide des types de fonctions de rappel permet d'Analyse du code pour les pilotes, static Driver Verifier (SDV) et d’autres outils de vérification recherchent des erreurs, et il est nécessaire d’écrire des pilotes pour le système d’exploitation Windows.

Par exemple, pour définir une fonction de rappel EvtSerCx2Control nommée MyControl, utilisez le type de fonction EVT_SERCX2_CONTROL, comme illustré dans cet exemple de code :

EVT_SERCX2_CONTROL  MyControl;

Ensuite, implémentez votre fonction de rappel comme suit :

_Use_decl_annotations_
NTSTATUS
  MyControl(
    WDFDEVICE  Device,
    WDFREQUEST  Request,
    size_t  OutputBufferLength,
    size_t  InputBufferLength,
    ULONG  IoControlCode
    )
  {...}

Le type de fonction EVT_SERCX2_CONTROL est défini dans le fichier d’en-tête Sercx.h. Pour identifier plus précisément les erreurs lorsque vous exécutez les outils d’analyse du code, veillez à ajouter l’annotation Use_decl_annotations à votre définition de fonction. L’annotation Use_decl_annotations garantit que les annotations appliquées au type de fonction EVT_SERCX2_CONTROL dans le fichier d’en-tête sont utilisées. Pour plus d’informations sur la configuration requise pour les déclarations de fonction, consultez déclaration de fonctions à l’aide de types de rôles de fonction pour les pilotes KMDF. Pour plus d’informations sur Use_decl_annotations, consultez annoter le comportement de la fonction.