Eventos de hardware

Alguns dispositivos de áudio fornecem botões de controle de volume de hardware, comutadores mudos ou outros tipos de controles manuais. Os aplicativos podem responder a alterações nesses controles ajustando o volume ou alterando a maneira como o fluxo de áudio é reproduzido. Quando o usuário ajusta um controle de hardware, o driver de miniporto usa a interface IPortEvents para informar ao driver de porta que ocorreu um evento de hardware. O driver de porta, por sua vez, notifica o aplicativo sobre o evento para que ele leia a nova configuração de controle do dispositivo.

O driver de miniporto pode consultar o driver de porta para a interface IPortEvents no momento em que ele atende à chamada init (consulte IMiniportWavePci::Init, por exemplo) do driver de porta. No Microsoft Windows 98 SE, Windows Me e Windows 2000 e posterior, essa consulta é bem-sucedida. Para obter um exemplo de código, consulte o adaptador de áudio de exemplo Sb16 em versões anteriores do WDK (Windows Driver Kit).

Quando o driver de porta chama o método IMiniport::GetDescription do seu driver, o método gera uma estrutura PCFILTER_DESCRIPTOR que especifica, entre outras coisas, os eventos que o seu dispositivo suporta. Os eventos podem ser especificados nas tabelas de automação para os Pins e Nodes do PCFILTER_DESCRIPTOR, e no AutomationTable, que aponta para a tabela de automação do próprio filtro. Cada evento é especificado por uma estrutura PCEVENT_ITEM . O driver deve definir os membros Set e Id da estrutura PCEVENT_ITEM para KSEVENTSETID_AudioControlChange e KSEVENT_CONTROL_CHANGE e deve carregar um ponteiro para a rotina EventHandler do driver no membro Handler. O driver também deve definir o bit PCEVENT_ITEM_FLAG_BASICSUPPORT no membro Flags para indicar suporte básico a eventos de mudança de controle, e deve definir os bits PCEVENT_ITEM_FLAG_ONESHOT e/ou PCEVENT_ITEM_FLAG_ENABLE para indicar que ele dá suporte a notificações de captura única e/ou recorrentes.

Quando um aplicativo chama mais tarde a função mixerOpen (descrita na documentação do SDK do Microsoft Windows) para solicitar a notificação de um evento específico, o driver de porta, em seguida, chama a rotina EventHandler do seu driver com um ponteiro para uma estrutura PCEVENT_REQUEST. O membro verbo dessa estrutura é definido como PCEVENT_VERB_ADD e seu membro EventItem especifica o evento que deve ser habilitado. A estrutura PCEVENT_REQUEST também contém um ponteiro para uma estrutura KSEVENT_ENTRY que o driver deve tratar como dados opacos do sistema. Depois de habilitar o evento, o manipulador deve chamar IPortEvents::AddEventToEventList com o mesmo ponteiro KSEVENT_ENTRY. Com essa chamada, o manipulador reconhece que o evento está habilitado.

Quando o evento de hardware ocorre e a rotina de serviço de interrupção do driver detecta um mudo ou uma alteração de volume, o driver sinaliza o evento para o driver de porta chamando IPortEvents::GenerateEventList com um conjunto de parâmetros que descrevem o evento. Por exemplo, a chamada a seguir descreve uma alteração de controle em um nó de volume de saída de linha:

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

Durante essa chamada, o driver de porta pesquisa sua lista de eventos para todos os eventos que correspondem aos parâmetros de chamada e envia notificação para os clientes que estão monitorando esses eventos. Neste exemplo, pPE é um ponteiro para o objeto IPortEvents e LINEOUT_VOL é a identificação do nó que o driver de miniporto atribui ao nó de volume de saída de linha. Parâmetros não especificados (como o GUID do conjunto de eventos e a ID do pino no exemplo anterior) são tratados como curingas e sempre correspondem aos parâmetros correspondentes na lista.