Eventi hardware

Alcuni dispositivi audio forniscono manopole di controllo del volume hardware, commutatori disattivati o altri tipi di controlli manuali. Le applicazioni possono rispondere alle modifiche apportate a questi controlli modificando il volume o modificando in altro modo il modo in cui viene riprodotto il flusso audio. Quando l'utente regola un controllo hardware, il driver miniport usa l'interfaccia IPortEvents per informare il driver della porta che si è verificato un evento hardware. Il driver della porta, a sua volta, invia una notifica all'applicazione dell'evento in modo che possa leggere la nuova impostazione del controllo dal dispositivo.

Il driver miniport può eseguire una query sul driver di porta per l'interfaccia IPortEvents al momento in cui esegue la chiamata Init (vedere IMiniportWavePci::Init, ad esempio) dal driver della porta. In Microsoft Windows 98 SE, Windows Me e Windows 2000 e versioni successive la query ha esito positivo. Per un esempio di codice, vedere l'adattatore audio di esempio Sb16 nelle versioni precedenti di Windows Driver Kit (WDK).

Quando il driver di porta chiama il metodo IMiniport::GetDescription del driver, il metodo restituisce una struttura PCFILTER_DESCRIPTOR che specifica, tra le altre cose, gli eventi supportati dal dispositivo. Gli eventi possono essere specificati nelle tabelle di automazione per i membri Pin e Nodi di PCFILTER_DESCRIPTOR e nel membro AutomationTable , che punta alla tabella di automazione per il filtro stesso. Ogni evento viene specificato da una struttura PCEVENT_ITEM . Il driver deve impostare i membri Set e ID della struttura PCEVENT_ITEM su KSEVENTSETID_AudioControlChange e KSEVENT_CONTROL_CHANGE e deve caricare un puntatore alla routine EventHandler del driver nel membro Handler . Il driver deve anche impostare il bit di PCEVENT_ITEM_FLAG_BASICSUPPORT nel membro Flags per indicare il supporto di base per gli eventi di modifica del controllo e deve impostare i bit PCEVENT_ITEM_FLAG_ONESHOT e/o PCEVENT_ITEM_FLAG_ENABLE per indicare che supporta una notifica singola e/o ricorrente.

Quando un'applicazione chiama successivamente la funzione mixerOpen (descritta nella documentazione di Microsoft Windows SDK) per richiedere la notifica di un determinato evento, il driver della porta chiama quindi la routine EventHandler del driver con un puntatore a una struttura PCEVENT_REQUEST. Il membro Verb di questa struttura è impostato su PCEVENT_VERB_ADD e il relativo membro EventItem specifica l'evento che deve essere abilitato. La struttura PCEVENT_REQUEST contiene anche un puntatore a una struttura KSEVENT_ENTRY che il driver deve trattare come dati di sistema opachi. Dopo aver abilitato l'evento, il gestore deve chiamare IPortEvents::AddEventToEventList con lo stesso puntatore KSEVENT_ENTRY. Con questa chiamata, il gestore riconosce che l'evento è abilitato.

Quando si verifica l'evento hardware e la routine interrupt-service del driver rileva una modifica del volume o disattiva l'audio, il driver segnala l'evento al driver di porta chiamando IPortEvents::GenerateEventList con un set di parametri che descrivono l'evento. Ad esempio, la chiamata seguente descrive una modifica del controllo in un nodo lineout-volume:

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

Durante questa chiamata, il driver di porta cerca nell'elenco eventi tutti gli eventi che corrispondono ai parametri di chiamata e invia notifiche ai client che monitorano questi eventi. In questo esempio pPE è un puntatore all'oggetto IPortEvents e LINEOUT_VOL è l'ID nodo assegnato dal driver miniport al nodo lineout-volume. I parametri non specificati, ad esempio il GUID del set di eventi e l'ID pin nell'esempio precedente, vengono considerati come caratteri jolly e corrispondono sempre ai parametri corrispondenti nell'elenco.