Compartilhar via

Manipuladores de propriedade de áudio

  • Artigo

Um driver de miniporto armazena informações sobre cada propriedade que ele dá suporte em uma estrutura PCPROPERTY_ITEM . Essa estrutura contém as seguintes informações sobre a propriedade :

  • O GUID do conjunto de propriedades e a ID da propriedade (ou índice)

  • Um ponteiro de função para a rotina do manipulador para a propriedade

  • Sinalizadores que especificam as operações de propriedade compatíveis com o manipulador

O driver de miniporto fornece uma tabela de automação (especificada por uma estrutura PCAUTOMATION_TABLE ) para o filtro. O driver fornece tabelas de automação adicionais para os tipos de pino e tipos de nó do filtro – cada tipo de pin ou nó tem sua própria tabela. Cada tabela de automação contém uma matriz (possivelmente vazia) de estruturas de PCPROPERTY_ITEM e cada uma dessas estruturas descreve uma propriedade do filtro, pino ou nó. Quando um cliente envia uma solicitação de propriedade para um filtro, pino ou nó, o driver de porta roteia a solicitação por meio da tabela de automação para o manipulador de propriedades apropriado.

Um driver de miniporte pode especificar uma rotina de manipulador de propriedades exclusiva para cada propriedade. No entanto, se um driver lida com várias propriedades semelhantes, elas às vezes podem ser consolidadas em uma única rotina de manipulador para conveniência. Se fornecer um manipulador exclusivo para cada propriedade ou consolidar várias propriedades em um único manipulador é uma decisão de implementação a ser tomada pelo gravador de driver e deve ser transparente para os clientes que enviam solicitações de propriedade.

Um cliente do modo de usuário pode enviar uma solicitação de propriedade get, set ou basic-support chamando a função Microsoft Win32 DeviceIoControl com o parâmetro de chamada dwIoControlCode definido como IOCTL_KS_PROPERTY. O sistema operacional converte essa chamada em um IRP, que ele envia para o driver de classe. Para obter mais informações, consulte Propriedades do KS.

Quando um cliente envia uma solicitação de propriedade KS (ou seja, um IRP de controle de E/S IOCTL_KS_PROPERTY) para um identificador de filtro ou identificador de pino, o driver do sistema KS (Ks.sys) entrega a solicitação ao driver de porta para o objeto de filtro ou objeto pin. Se o driver de miniporto fornecer um manipulador para a propriedade , o driver de porta encaminhará a solicitação para o manipulador. Antes de encaminhar a solicitação, o driver de porta converte as informações da solicitação de propriedade no formato especificado pela estrutura PCPROPERTY_REQUEST . O driver de porta passa essa estrutura para o manipulador do driver de miniport.

O membro MajorTarget do PCPROPERTY_REQUEST aponta para a interface do driver de miniporto primário para o dispositivo de áudio. Por exemplo, para um dispositivo WavePci, esse é um ponteiro para a interface IMiniportWavePci do objeto de driver de miniport.

No caso de uma solicitação de propriedade KS enviada para um identificador de filtro, o membro MinorTarget de PCPROPERTY_REQUEST é NULL. No caso de uma solicitação enviada para um identificador de pino, MinorTarget aponta para a interface de fluxo do pino. Por exemplo, para um dispositivo WavePci, esse é um ponteiro para a interface IMiniportWavePciStream do objeto de fluxo.

Os membros Instance e Value de PCPROPERTY_REQUEST apontam para os buffers de entrada e saída, respectivamente, da solicitação de propriedade KS. (Os buffers são especificados pelos parâmetros lpInBuffer e lpOutBuffer da função DeviceIoControl .) Esses buffers contêm o descritor de propriedade (dados da instância) e o valor da propriedade (dados da operação), respectivamente, conforme descrito em Conjuntos de Propriedades de Drivers de Áudio. O membro Value aponta para o início do buffer de saída, mas o ponteiro Instância é deslocado do início do buffer de entrada.

O buffer de entrada começa com uma estrutura KSPROPERTY ou KSNODEPROPERTY . O driver de porta copia as informações dessa estrutura para os membros Node, PropertyItem e Verb da estrutura PCPROPERTY_REQUEST. Se algum dado seguir a estrutura KSPROPERTY ou KSNODEPROPERTY no buffer, o driver de porta carregará o membro Da instância com um ponteiro para esses dados. Caso contrário, ele define Instância como NULL.

Se o buffer de entrada começar com uma estrutura KSPROPERTY, que não contém informações de nó, o driver de porta definirá o membro do Nó da estrutura PCPROPERTY_REQUEST como ULONG(-1). Nesse caso, o driver de porta chama o manipulador apropriado da tabela de automação do driver de miniporto para o filtro ou pino, dependendo se o destino da solicitação de propriedade é especificado por um identificador de filtro ou identificador de pino. (Se a tabela não especificar um manipulador para a propriedade , o driver de porta manipulará a solicitação em vez disso.)

Se o buffer de entrada começar com uma estrutura KSNODEPROPERTY, o driver de porta copiará a ID do nó dessa estrutura para o membro do Nó da estrutura PCPROPERTY_REQUEST e chamará o manipulador apropriado da tabela de automação do driver de miniport para o nó. (Novamente, se a tabela não especificar um manipulador para a propriedade , o driver de porta manipulará a solicitação em vez disso.)

O driver de porta verifica o bit KSPROPERTY_TYPE_TOPOLOGY nos sinalizadores de operação da solicitação de propriedade para determinar qual das duas estruturas, KSPROPERTY ou KSNODEPROPERTY, reside no início do buffer de entrada:

  • Se esse bit estiver definido, a solicitação será para uma propriedade de nó e o buffer de entrada começará com uma estrutura KSNODEPROPERTY.

  • Caso contrário, o buffer de entrada começa com uma estrutura KSPROPERTY.

Para obter mais informações sobre KSPROPERTY_TYPE_TOPOLOGY, consulte KSPROPERTY.

Os membros InstanceSize e ValueSize da estrutura PCPROPERTY_REQUEST especificam os tamanhos dos buffers apontados pelos membros Instance e Value . ValueSize é igual ao tamanho do buffer de saída da solicitação de propriedade, mas InstanceSize é o tamanho dos dados que seguem a estrutura KSPROPERTY ou KSNODEPROPERTY no buffer de entrada. Ou seja, InstanceSize é o tamanho do buffer de entrada menos o tamanho da estrutura KSPROPERTY ou KSNODEPROPERTY. Se nenhum dado adicional seguir essa estrutura, o driver de porta definirá InstanceSize como zero (e Instância como NULL).

Por exemplo, se o cliente especificar uma estrutura KSNODEPROPERTY_AUDIO_CHANNEL como os dados de instância no buffer de entrada, o driver de porta passará ao manipulador uma estrutura PCPROPERTY_REQUEST cujo membro Instance aponta para o membro Channel da estrutura KSNODEPROPERTY_AUDIO_CHANNEL e cujo membro InstanceSize contém o valor

sizeof(KSNODEPROPERTY_AUDIO_CHANNEL) – sizeof(KSNODEPROPERTY)

Antes de enviar uma solicitação get-property para recuperar um valor de propriedade, o cliente deve alocar um buffer de saída no qual o manipulador de propriedades do driver de miniport pode gravar o valor da propriedade. Para algumas propriedades, o tamanho do buffer de saída depende do dispositivo e o cliente deve consultar o manipulador de propriedades para o tamanho do buffer necessário. Nesses casos, o cliente envia uma solicitação de propriedade inicial com um ponteiro de buffer de saída de nullptr e um comprimento de buffer de saída igual a zero. O manipulador responde retornando o tamanho do buffer necessário junto com o STATUS_BUFFER_OVERFLOW de código status. Em seguida, o cliente recupera o valor da propriedade alocando um buffer de saída do tamanho especificado e enviando esse buffer em uma segunda solicitação get-property.

Se o tamanho do buffer especificado for muito pequeno para receber qualquer uma das informações solicitadas, o método retornará STATUS_BUFFER_TOO_SMALL.

Em alguns casos, os drivers de porta PortCls retornam STATUS_BUFFER_TOO_SMALL em vez de STATUS_BUFFER_OVERFLOW em resposta a uma solicitação de propriedade com um endereço e tamanho de buffer de saída não zero. O tamanho do buffer necessário não é retornado nesses casos.

Para obter mais informações, consulte Usando valores NTSTATUS e estas postagens no blog: