Événements matériels

Certains périphériques audio fournissent des boutons de contrôle de volume matériel, des commutateurs muets ou d’autres types de contrôles manuels. Les applications peuvent répondre aux modifications apportées à ces contrôles en ajustant le volume ou en modifiant la façon dont le flux audio est lu. Lorsque l’utilisateur ajuste un contrôle matériel, le pilote miniport utilise l’interface IPortEvents pour informer le pilote de port qu’un événement matériel s’est produit. Le pilote de port notifie ensuite l’application de l’événement afin qu’elle puisse lire le nouveau réglage de contrôle depuis l’appareil.

Votre pilote miniport peut interroger le pilote de port pour l’interface IPortEvents au moment où il prend en charge l’appel Init (voir IMiniportWavePci ::Init, par exemple) à partir du pilote de port. Sur Microsoft Windows 98 SE, Windows Me et Windows 2000 et versions ultérieures, cette requête réussit. Pour obtenir un exemple de code, consultez l’exemple de carte audio Sb16 dans les versions antérieures du Kit de pilotes Windows (WDK).

Lorsque le pilote de port appelle la méthode IMiniport ::GetDescription de votre pilote, la méthode génère une structure PCFILTER_DESCRIPTOR qui spécifie, entre autres, les événements pris en charge par votre appareil. Les événements peuvent être spécifiés dans les tables d'automatisation pour les membres broches et nœuds de PCFILTER_DESCRIPTOR, et dans le membre table d'automatisation, qui pointe vers la table d'automatisation pour le filtre lui-même. Chaque événement est spécifié par une structure PCEVENT_ITEM . Votre pilote doit définir les membres Set et Id de la structure PCEVENT_ITEM sur KSEVENTSETID_AudioControlChange et KSEVENT_CONTROL_CHANGE, et doit charger un pointeur vers la routine EventHandler de votre pilote dans le membre Handler. Votre pilote doit également définir le bit PCEVENT_ITEM_FLAG_BASICSUPPORT dans le membre Flags pour indiquer la prise en charge de base des événements de modification de contrôle, et définir les PCEVENT_ITEM_FLAG_ONESHOT et/ou PCEVENT_ITEM_FLAG_ENABLE bits pour indiquer qu’il prend en charge une notification ponctuelle et/ou périodique.

Lorsqu’une application appelle ultérieurement la fonction mixerOpen (décrite dans la documentation du Kit de développement logiciel (SDK) Microsoft Windows) pour demander la notification d’un événement particulier, le pilote de port appelle ensuite la routine EventHandler de votre pilote avec un pointeur vers une structure PCEVENT_REQUEST . Le membre Verb de cette structure est défini sur PCEVENT_VERB_ADD et son membre EventItem spécifie l’événement à activer. La structure PCEVENT_REQUEST contient également un pointeur vers une structure KSEVENT_ENTRY que votre pilote doit traiter comme des données système opaques. Après avoir activé l’événement, votre gestionnaire doit appeler IPortEvents ::AddEventToEventList avec le même pointeur KSEVENT_ENTRY. Avec cet appel, le gestionnaire reconnaît que l’événement est activé.

Lorsque l'événement matériel se produit et que la routine de service d'interruption de votre pilote détecte une mise en sourdine ou une modification du volume, votre pilote signale l'événement au pilote de port en appelant IPortEvents::GenerateEventList avec un ensemble de paramètres qui décrivent l'événement. Par exemple, l'appel suivant décrit une modification de contrôle dans un nœud de volume de sortie :

    pPE->GenerateEventList(NULL, KSEVENT_CONTROL_CHANGE,
                           FALSE, ULONG(-1), TRUE, LINEOUT_VOL);

Pendant cet appel, le pilote de port recherche dans sa liste d’événements tous les événements qui correspondent aux paramètres d’appel et envoie une notification aux clients qui surveillent ces événements. Dans cet exemple, pPE est un pointeur vers l’objet IPortEvents et LINEOUT_VOL est l’ID de nœud que le pilote miniport affecte au nœud de volume lineout. Les paramètres non spécifiés (comme le GUID de l'ensemble d'événements et l'ID de broche dans l'exemple précédent) sont considérés comme des caractères génériques et correspondent toujours aux paramètres analogues dans la liste.