Événements matériels

Certains périphériques audio fournissent des boutons de contrôle de volume matériels, des commutateurs de désactivation 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. À son tour, le pilote de port avertit l’application de l’événement afin qu’elle puisse lire le nouveau paramètre de contrôle à partir de 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 d’adaptateur 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 Automation pour les membres Pins et Nodes de PCFILTER_DESCRIPTOR, ainsi que dans le membre AutomationTable , qui pointe vers la table Automation 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 PCEVENT_ITEM_FLAG_BASICSUPPORT bit dans le membre Flags pour indiquer la prise en charge de base des événements de modification de contrôle, et il doit définir les PCEVENT_ITEM_FLAG_ONESHOT et/ou PCEVENT_ITEM_FLAG_ENABLE bits pour indiquer qu’il prend en charge les notifications ponctuelles et/ou périodiques.

Lorsqu’une application appelle ultérieurement la fonction mixerOpen (décrite dans la documentation Microsoft Windows SDK) pour demander la notification d’un événement particulier, le pilote de port appelle 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 un mute ou un changement de 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 ligne :

    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 attribue au nœud de volume lineout. Les paramètres non spécifiés (tels que le GUID du jeu d’événements et l’ID de broche dans l’exemple précédent) sont traités comme des caractères génériques et correspondent toujours aux paramètres correspondants dans la liste.