Eventos de hardware

Alguns dispositivos de áudio fornecem botões de controle de volume de hardware, interruptores de mudo 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 miniporta usa a interface IPortEvents para informar o driver de porta que ocorreu um evento de hardware. O driver da porta, por sua vez, notifica o aplicativo do evento para que ele possa ler a nova configuração de controle do dispositivo.

Seu driver de miniporta pode consultar o driver de porta para a interface IPortEvents no momento em que ele atende a chamada Init (consulte IMiniportWavePci::Init, por exemplo) a partir 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 Kit de Driver do Windows (WDK).

Quando o driver de porta chama o método IMiniport::GetDescription do driver, o método gera uma estrutura PCFILTER_DESCRIPTOR que especifica, entre outras coisas, os eventos suportados pelo dispositivo. Os eventos podem ser especificados nas tabelas de automação para os membros Pins e Nodes do PCFILTER_DESCRIPTOR e no membro 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 como KSEVENTSETID_AudioControlChange e KSEVENT_CONTROL_CHANGE, e deve carregar um ponteiro para a rotina EventHandler do driver no membro Handler. O seu driver também deve definir o bit de PCEVENT_ITEM_FLAG_BASICSUPPORT no membro Flags para indicar suporte básico a eventos de alteração de controlo, e deve definir os bits PCEVENT_ITEM_FLAG_ONESHOT e/ou PCEVENT_ITEM_FLAG_ENABLE para indicar que suporta notificação única e/ou recorrente.

Quando um aplicativo posteriormente chama 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 chama a rotina EventHandler do driver com um ponteiro para uma estrutura PCEVENT_REQUEST . O membro Verb 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, seu 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 interrupção de serviço do driver deteta 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 controlo num 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 é o ID do nó que o controlador de miniport atribui ao nó de volume de saída de linha. Parâmetros não especificados (como o GUID do conjunto de eventos e o ID do pino no exemplo anterior) são tratados como curingas e sempre correspondem aos parâmetros correspondentes na lista.