EVT_SPB_CONTROLLER_OTHER fonction de rappel (spbcx.h)

Article
08/07/2023

La fonction de rappel d’événement EvtSpbControllerIoOther d’un pilote de contrôleur SPB gère les demandes de contrôle d’E/S d’appareil qui ne sont pas gérées par d’autres fonctions de rappel d’événements ou par l’extension de l’infrastructure SPB (SpbCx).

Syntaxe

EVT_SPB_CONTROLLER_OTHER EvtSpbControllerOther;

void EvtSpbControllerOther(
  [in] WDFDEVICE Controller,
  [in] SPBTARGET Target,
  [in] SPBREQUEST Request,
  [in] size_t OutputBufferLength,
  [in] size_t InputBufferLength,
  [in] ULONG IoControlCode
)
{...}

Paramètres

[in] Controller

Un handle WDFDEVICE pour l’objet d’appareil framework qui représente le contrôleur SPB.

[in] Target

Un handle SPBTARGET à la cible pour cette demande d’E/S. La cible est un périphérique ou un port attaché au bus. L’extension d’infrastructure SPB (SpbCx) a précédemment affecté ce handle à la cible dans le rappel EvtSpbTargetConnect qui a ouvert la connexion à la cible.

[in] Request

Handle SPBREQUEST pour la demande d’E/S. Votre pilote de contrôleur SPB doit effectuer cette demande. Pour plus d'informations, consultez la section Notes.

[in] OutputBufferLength

Longueur, en octets, de la mémoire tampon de sortie, si une mémoire tampon de sortie est fournie avec la requête.

[in] InputBufferLength

Longueur, en octets, de la mémoire tampon d’entrée, si une mémoire tampon d’entrée est fournie avec la requête.

[in] IoControlCode

Code de contrôle d’E/S (IOCTL) pour la demande. Cette valeur est un IOCTL que l’extension de framework SPB (SpbCx) ne reconnaît pas. Pour plus d'informations, consultez la section Notes.

Valeur de retour

None

Remarques

SpbCx gère la file d’attente d’E/S pour le contrôleur SPB. Si le pilote du contrôleur SPB inscrit une fonction de rappel EvtSpbControllerIoOther , SpbCx appelle cette fonction lorsqu’une demande de contrôle d’E/S d’appareil que SpbCx ne prend pas en charge arrive dans la file d’attente d’E/S du contrôleur. La valeur du paramètre Request est un handle qui encapsule cette demande. Le pilote du contrôleur SPB doit effectuer cette requête en effectuant l’opération demandée ou en retournant une erreur status. Si le pilote ne prend pas en charge le IOCTL spécifié, il doit retourner le STATUS_NOT_SUPPORTED status d’erreur. Pour obtenir la liste des IOCTL que SpbCx prend en charge, consultez Codes de contrôle d’E/S S SpbCx.

Le rappel EvtSpbControllerIoOther permet de distribuer des commandes spécifiques au bus ou au pilote au pilote en tant que IOCTL. Par exemple, les clients (pilotes périphériques) peuvent utiliser ces IOCTL pour coordonner des opérations spécifiques au bus, telles que les échanges de données en duplex intégral avec un appareil cible sur un bus SPI. Ces IOCTL sont soumises au même contrôle de flux que les IOCTL prises en charge par SpbCx.

La fonction de rappel EvtSpbControllerIoOther est similaire à l’EvtIoDeviceControl et traite les IOCTL de la même manière. Pour obtenir des informations générales sur la façon dont les pilotes WDF gèrent les demandes d’E/S, consultez Framework Request Objects.

Un rappel EvtSpbControllerIoOther ne retourne pas de valeur status. Au lieu de cela, le pilote du contrôleur SPB indique la status de l’opération demandée dans la status d’achèvement de la demande d’E/S.

Si une demande d’E/S ne peut pas être effectuée immédiatement, la fonction de rappel doit retourner sans attendre que le pilote du contrôleur SPB termine le traitement de la demande. Le pilote du contrôleur SPB peut effectuer ultérieurement la requête de manière asynchrone.

Une fonction EvtSpbControllerIoOther doit valider les valeurs de paramètre dans les demandes de contrôle d’E/S qu’elle reçoit des clients en mode utilisateur. Pour toutes les fonctions de rappel EvtSpbXxx autres qu’EvtSpbControllerIoOther, SpbCx valide les paramètres en mode utilisateur avant d’appeler la fonction.

Pour inscrire une fonction de rappel EvtSpbControllerIoOther , appelez la méthode SpbControllerSetIoOther .

Exemples

Pour définir une fonction de rappel EvtSpbControllerIoOther , 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 EvtSpbControllerIoOther nommée MyEvtSpbControllerIoOther, utilisez le type de fonction EVT_SPB_CONTROLLER_OTHER, comme indiqué dans cet exemple de code :

EVT_SPB_CONTROLLER_OTHER  MyEvtSpbControllerIoOther;

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

_Use_decl_annotations_
VOID
  MyEvtSpbControllerIoOther(
    WDFDEVICE Controller,
    SPBTARGET Target,
    SPBREQUEST Request,
    size_t OutputBufferLength,
    size_t InputBufferLength,
    ULONG IoControlCode
    )
{ ... }

Le type de fonction EVT_SPB_CONTROLLER_OTHER est défini dans le fichier d’en-tête Spbcx.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_SPB_CONTROLLER_OTHER 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	Pris en charge à partir de Windows 8.
Plateforme cible	Desktop (Expérience utilisateur)
En-tête	spbcx.h
IRQL	Appelé à IRQL <= DISPATCH_LEVEL.