EVT_SERCX2_CONTROL fonction de rappel (sercx.h)
La fonction de rappel d’événement 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
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] 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 Request .
[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 Request .
[in] IoControlCode
Spécifie le code de contrôle d’E/S (IOCTL) de la demande de contrôle d’E/S série spécifiée par le paramètre Request . Les 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 la section Notes.
Valeur retournée
La fonction EvtSerCx2Control retourne STATUS_SUCCESS si l’appel réussit. Sinon, elle retourne une erreur appropriée status code.
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 de périphérique d’infrastructure 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éfinies 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 afin d’effectuer des opérations dépendantes du matériel.
Lorsque SerCx2 reçoit une demande de contrôle d’E/S série qui ne peut être gérée que par le pilote de 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 réalisation 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 l’erreur STATUS_NOT_SUPPORTED code status.
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 Request et une valeur de status pour indiquer si la demande a réussi. Cette valeur status est écrite dans le bloc status de la requête.
La valeur de retour de la fonction EvtSerCx2Control doit toujours correspondre à la valeur status que cette fonction écrit dans le bloc status 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 IOCTL indiqués dans le tableau suivant. La colonne située à droite de la table indique si la fonction EvtSerCx2Control est requise 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 | Facultatif |
| 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 | Facultatif |
| IOCTL_SERIAL_SET_FIFO_CONTROL | Facultatif |
| 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 IOCTL série que SerCx2 présente à la fonction EvtSerCx2Control . Pour tout IOCTL qui ne fait pas partie de cette liste, SerCx2 gère l’IOCTL ou échoue immédiatement à l’IOCTL et définit la requête status sur STATUS_NOT_SUPPORTED. SerCx2 gère IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION demandes, mais appelle la fonction de rappel d’événement EvtSerCx2ApplyConfig pendant le traitement d’une telle demande. SerCx2 gère IOCTL_SERIAL_PURGE demandes, mais peut appeler la fonction de rappel d’événement EvtSerCx2PurgeFifos pendant le traitement d’une telle demande. SerCx effectue un traitement préliminaire des requêtes IOCTL_SERIAL_SET_WAIT_MASK , mais appelle la fonction de rappel d’événement EvtSerCx2SetWaitMask , si elle est implémentée, pour terminer la gestion d’une telle demande. Pour plus d’informations sur la prise en charge de SerCx2 pour les IOCTL série, consultez Interface de demande 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 demande 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 demande de 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 demande IOCTL_SERIAL_GET_DTRRTS , mais le gestionnaire du pilote pour cette requête est requis pour prendre en charge uniquement le bit d’indicateur SERIAL_RTS_STATE dans la valeur de sortie de cette requête. En 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 demande de IOCTL_SERIAL_GET_COMMSTATUS , mais le gestionnaire du pilote pour cette requête est requis pour prendre en charge uniquement les membres suivants de la structure SERIAL_STATUS utilisée par cette demande :
- Erreurs
- HoldReasons
IOCTL_SERIAL_GET_PROPERTIES
La fonction EvtSerCx2Control dans votre pilote de contrôleur série doit prendre en charge la demande 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 une vitesse maximale 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 demande IOCTL_SERIAL_GET_MODEMSTATUS . Le gestionnaire du pilote pour cette requête doit définir la valeur de sortie de la demande sur le modem brut status valeur d’enregistrement 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 doit 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 membres ControlHandShake et FlowReplace 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
Votre pilote doit prendre en charge les bits d’indicateur suivants dans le membre FlowReplace :
- SERIAL_RTS_CONTROL
- SERIAL_RTS_HANDSHAKE
Un pilote qui ne prend pas en charge un bit d’indicateur particulier dans le membre ControlHandShake ou FlowReplace doit définir ce bit d’indicateur sur zéro dans la valeur de sortie pour la demande IOCTL_SERIAL_GET_HANDFLOW . Si une requête de IOCTL_SERIAL_SET_HANDFLOW spécifie un bit d’indicateur ControlHandshake ou FlowReplace que le pilote ne prend pas en charge, la fonction EvtSerCx2Control doit échouer et renvoyer STATUS_INVALID_PARAMETER.
En option, un pilote peut prendre en charge les membres XonLimit et XoffLimit de la structure SERIAL_HANDFLOW . Toutefois, ces membres sont rarement, voire jamais, nécessaires, et Microsoft recommande de ne pas les prendre en charge. Un pilote qui ne prend pas en charge les membres XonLimit et XoffLimit doit définir ces membres sur zéro dans la valeur de sortie pour la requête IOCTL_SERIAL_GET_HANDFLOW . Si une demande de IOCTL_SERIAL_SET_HANDFLOW spécifie un membre XonLimit ou XoffLimit différent de zéro et que le pilote ne prend pas en charge ces membres, la fonction EvtSerCx2Control doit échouer à la demande 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 fonction de rappel aide l’analyse du code pour les pilotes, le vérificateur de pilotes statique (SDV) et d’autres outils de vérification à la recherche d’erreurs. Il s’agit d’une exigence pour l’écriture de 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 indiqué 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 lors de l’exécution des 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 Annotating Function Behavior.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Disponible à partir de Windows 8.1. |
| Plateforme cible | Desktop (Expérience utilisateur) |
| En-tête | sercx.h |
| IRQL | Appelé à IRQL <= DISPATCH_LEVEL. |
Voir aussi
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour