EVT_SPB_CONTROLLER_LOCK fonction de rappel (spbcx.h)

Article
02/26/2024

La fonction de rappel d’événement EvtSpbControllerLock d’un pilote de contrôleur SPB verrouille le contrôleur SPB pour les accès d’un seul appareil cible sur le bus.

Syntaxe

EVT_SPB_CONTROLLER_LOCK EvtSpbControllerLock;

void EvtSpbControllerLock(
  [in] WDFDEVICE Controller,
  [in] SPBTARGET Target,
  [in] SPBREQUEST LockRequest
)
{...}

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

Un handle SPBREQUEST à une demande de contrôle d’E/S pour verrouiller le contrôleur. Votre pilote de contrôleur SPB doit effectuer cette demande en effectuant l’opération demandée ou en retournant une erreur status. Pour plus d’informations, consultez Remarques.

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 EvtSpbControllerLock , SpbCx appelle cette fonction lorsqu’un client (pilote périphérique) du contrôleur envoie une requête IOCTL_SPB_LOCK_CONTROLLER à une cible sur le bus. La valeur du paramètre LockRequest est un handle qui encapsule cette requête.

Les fonctions EvtSpbControllerLock et EvtSpbControllerUnlock effectuent des opérations complémentaires. Les deux fonctions sont facultatives. Si votre pilote de contrôleur SPB implémente une fonction EvtSpbControllerUnlock , il n’est pas nécessaire d’implémenter une fonction EvtSpbControllerLock , mais peut le faire. Toutefois, si votre pilote de contrôleur SPB implémente une fonction EvtSpbControllerLock , il doit également implémenter une fonction EvtSpbControllerUnlock . Pour plus d’informations, consultez Remarques dans SPB_CONTROLLER_CONFIG.

Tant que le verrou est en vigueur, le contrôleur ne doit pas autoriser les accès aux cibles sur le bus autre que la cible désignée par le paramètre LockRequest .

Si le pilote du contrôleur SPB doit changer le mode de son contrôleur pour remplacer temporairement le mécanisme de sélection cible normal, il peut le faire pendant le rappel EvtSpbControllerLock . Si ce changement de mode implique un long délai ou nécessite que le pilote attende une interruption de l’appareil, le pilote doit lancer le changement de mode, puis revenir à partir du rappel sans délai. Plus tard, le pilote peut effectuer l’opération de verrouillage dans un DPC du minuteur ou un DPC d’interruption.

Si l’opération de verrouillage se termine dans un DPC, le pilote du contrôleur SPB doit avoir précédemment alloué toutes les ressources dont il a besoin pour l’opération de verrouillage.

Un rappel EvtSpbControllerLock doit éviter d’échouer une demande de verrouillage. Si le vérificateur de pilotes est activé, un tel échec déclenche une interruption du vérificateur, qui signale au gestionnaire de Plug-and-Play que le contrôleur a échoué. SpbCx ignore l’échec d’une demande de verrouillage et n’essaie pas de gérer ou d’atténuer l’échec.

La fonction EvtSpbControllerLock ne retourne pas de valeur. Au lieu de cela, le pilote du contrôleur SPB indique la status de l’opération de verrouillage dans la status d’achèvement de la demande d’E/S identifiée par le paramètre LockRequest. Définissez la status d’achèvement sur STATUS_SUCCESS.

SpbCx appelle la fonction de rappel d’événement EvtSpbControllerUnlock pour déverrouiller un contrôleur précédemment verrouillé par un rappel EvtSpbControllerLock .

Pour inscrire une fonction de rappel EvtSpbControllerLock , appelez la méthode SpbDeviceInitialize .

Pour plus d’informations sur la fonction EvtSpbControllerLock , consultez Gestion des séquences Client-Implemented.

Exemples

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

EVT_SPB_CONTROLLER_LOCK  MyEvtSpbControllerLock;

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

_Use_decl_annotations_
VOID
  MyEvtSpbControllerLock(
    WDFDEVICE Controller,
    SPBTARGET Target,
    SPBREQUEST LockRequest
    )
{ ... }

Le type de fonction EVT_SPB_CONTROLLER_LOCK 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_LOCK 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.

Partager via