Propriedades filtrar, fixar e nó
Os drivers de áudio WDM (Modelo de Driver do Microsoft Windows) representam um dispositivo de áudio como um filtro KS e representam um buffer de hardware no dispositivo como um pino no filtro. Quando um cliente envia uma solicitação de propriedade para um desses objetos de filtro ou pino, o driver de porta recebe a solicitação e roteia a solicitação para o manipulador de propriedades apropriado no driver de porta ou no driver de miniporto.
Os dispositivos de áudio dão suporte a três tipos de propriedades:
Propriedades do filtro
Uma propriedade de filtro é uma propriedade do filtro como um todo, em vez de uma propriedade de um determinado pin ou nó dentro do filtro. As solicitações de propriedades de filtro especificam identificadores de filtro, mas não especificam IDs de nó.
Fixar propriedades
Uma propriedade pin é uma propriedade de uma instância de pin específica no filtro. As solicitações para essas propriedades especificam identificadores de pino, mas não especificam IDs de nó.
Propriedades de nó
Uma propriedade de nó é uma propriedade de um nó de topologia dentro do filtro. Uma solicitação para uma propriedade de nó especifica um identificador de filtro ou identificador de pino, além de uma ID de nó.
Se uma solicitação de propriedade de nó especifica um filtro ou identificador de pino depende se o nó é exclusivo do filtro. Para obter mais informações, consulte a seção Propriedades do Nó a seguir.
A figura a seguir mostra esses três tipos de solicitação de propriedade: uma solicitação pin-property enviada a uma instância de pin, uma solicitação de propriedade de nó enviada a um nó (em uma instância de filtro ou pino) e uma solicitação de propriedade de filtro enviada a uma instância de filtro.
Normalmente, o driver de porta lida com a maioria das solicitações de propriedades de filtro e fixação, e o driver de miniporto manipula solicitações de propriedades de nó.
O driver de porta fornece seus próprios manipuladores internos para as propriedades de filtro e fixação usadas pelo driver do sistema SysAudio (consulte KSPROPSETID_Sysaudio e KSPROPSETID_Sysaudio_Pin) e driver do sistema WDMAud. Um driver de miniporte não precisa implementar manipuladores para propriedades que o driver de porta manipula. Um driver de miniporto típico fornece poucos manipuladores, se houver, para filtrar e fixar propriedades. O driver de miniporto fornece os manipuladores para propriedades de nó que representam recursos dependentes de hardware do dispositivo de áudio. Os drivers de porta não fornecem nenhuma manipulação interna de propriedades de nó, com exceção de KSPROPERTY_TOPOLOGY_NAME.
Quando o driver de porta e os manipuladores de fornecimento do driver de miniporto para a mesma propriedade, o driver de porta usa seu próprio manipulador e ignora o manipulador do driver de miniport.
Filtrar Descritores
O driver de porta obtém ponteiros para os manipuladores de propriedade do driver de miniport chamando o método IMiniport::GetDescription . Por meio desse método, o driver de porta recupera um ponteiro para o descritor de filtro do driver de miniport, que é uma estrutura do tipo PCFILTER_DESCRIPTOR. Essa estrutura especifica os manipuladores de propriedade do driver de miniport para propriedades de filtro, fixação e nó:
O membro AutomationTable da estrutura PCFILTER_DESCRIPTOR aponta para a tabela de automação do filtro. Esta tabela especifica os manipuladores de propriedade do driver de miniport para propriedades de filtro.
O membro Pins da estrutura PCFILTER_DESCRIPTOR contém as tabelas de automação para os pinos. Cada tabela especifica os manipuladores de propriedade para as propriedades de pin de um tipo de pino específico.
O membro Nós da estrutura PCFILTER_DESCRIPTOR contém as tabelas de automação para os nós de topologia dentro do filtro. Cada tabela especifica os manipuladores de propriedade para as propriedades do nó de um tipo de nó específico.
Propriedades de Filtro
O driver de porta acessa os manipuladores de propriedade de filtro do driver de miniport por meio do membro AutomationTable de PCFILTER_DESCRIPTOR. Normalmente, essa tabela de automação contém poucos manipuladores porque o driver de porta fornece seus próprios manipuladores internos para todas as propriedades de filtro que SysAudio e WDMAud usam para consultar e configurar dispositivos de áudio.
No entanto, o driver de miniporto pode fornecer manipuladores para propriedades de filtro, como KSPROPERTY_GENERAL_COMPONENTID que fornecem informações dependentes de hardware que não estão disponíveis para o driver de porta. Dois dos drivers de áudio de exemplo no WDK (Microsoft Windows Driver Kit) lidam com a propriedade KSPROPERTY_GENERAL_COMPONENTID. Para obter mais informações, consulte as implementações do driver de miniport no driver de exemplo do Sysvad, que é discutido em Drivers de Áudio de Exemplo.
Todos os drivers de porta em Portcls.sys fornecem tratamento para os conjuntos de propriedades KSPROPSETID_Pin e KSPROPSETID_Topology . Todas as propriedades nesses conjuntos são propriedades de filtro, com exceção de KSPROPERTY_TOPOLOGY_NAME, que é uma propriedade de nó (que usa um identificador de filtro, não um identificador de pino, para especificar o destino da solicitação). Os drivers de porta dão suporte ao seguinte subconjunto das propriedades KSPROPSETID_Pin:
KSPROPERTY_PIN_CONSTRAINEDDATARANGES
KSPROPERTY_PIN_DATAINTERSECTION
KSPROPERTY_PIN_GLOBALCINSTANCES
KSPROPERTY_PIN_NECESSARYINSTANCES
KSPROPERTY_PIN_PHYSICALCONNECTION
KSPROPERTY_PIN_PROPOSEDATAFORMAT
KSPROPERTY_PIN_PROPOSEDATAFORMAT2
Essas propriedades fornecem informações sobre as fábricas de pinos pertencentes a um filtro. Normalmente, os clientes consultam o filtro para essas propriedades antes de criar instâncias de fixação. Os drivers de porta dão suporte a todas as quatro propriedades KSPROPSETID_Topology, que fornecem informações sobre a topologia interna do filtro.
Além disso, o driver de porta DMus fornece um manipulador para a propriedade KSPROPERTY_SYNTH_MASTERCLOCK , que é uma propriedade get-only de um filtro DirectMusic. KSPROPERTY_SYNTH_MASTERCLOCK é membro do conjunto de propriedades KSPROPSETID_SynthClock .
Fixar propriedades
O driver de porta acessa os manipuladores de propriedade pin do driver de miniport por meio do membro Pins de PCFILTER_DESCRIPTOR. Esse membro aponta para uma matriz de descritores de pin e cada descritor aponta para a tabela de automação para um tipo de pino (identificado por uma ID de pin, que é simplesmente o índice de matriz).
Normalmente, essas tabelas de automação contêm poucas entradas porque o driver de porta fornece seus próprios manipuladores para todas as propriedades de pino que SysAudio e WDMAud usam. Um driver de miniporto tem a opção de fornecer manipuladores para uma ou mais propriedades de pino que o driver de porta não manipula, mas apenas os clientes que sabem sobre essas propriedades podem enviar solicitações de propriedade para elas.
Com exceção do driver de porta topologia, todos os drivers de porta em Portcls.sys fornecem manipuladores internos para as seguintes propriedades de pino:
KSPROPERTY_CONNECTION_DATAFORMAT
KSPROPERTY_CONNECTION_ALLOCATORFRAMING
KSPROPERTY_DRMAUDIOSTREAM_CONTENTID
Algumas das propriedades nesta lista exigem informações dependentes de hardware do driver de miniport. Quando o driver de porta recebe um IRP que contém uma solicitação para uma dessas propriedades, ele não passa o IRP para o driver de miniporte. Em vez disso, o driver de porta manipula a solicitação em si, mas seu manipulador obtém as informações necessárias chamando um ponto de entrada no driver de miniporte. Por exemplo, o driver de porta fornece seu próprio manipulador de propriedades para solicitações de KSPROPERTY_AUDIO_POSITION. Esse manipulador simplesmente chama o método GetPosition do fluxo de driver de miniport (por exemplo, IMiniportWavePciStream::GetPosition) para obter a posição atual.
Propriedades do nó
O driver de porta acessa os manipuladores de propriedade de nó do driver de miniport por meio do membro Nodes do PCFILTER_DESCRIPTOR. Esse membro aponta para uma matriz de descritores de nó e cada descritor aponta para a tabela de automação para um tipo de nó (identificado por uma ID de nó, que é simplesmente o índice de matriz). Normalmente, todos ou a maioria dos manipuladores de propriedade pertencentes a um driver de miniporto residem na matriz Nós . Um driver de áudio representa os controles de hardware em um dispositivo de áudio como nós de topologia e usa o mecanismo de propriedade para fornecer aos clientes acesso às configurações de controle dependentes de hardware.
Conforme descrito anteriormente, um cliente envia uma solicitação de propriedade de filtro para um identificador de filtro e uma solicitação de propriedade de pin para um identificador de pino. Ao contrário de uma instância de filtro ou pino, um nó não é um objeto kernel e não tem um identificador. Um cliente envia uma solicitação de propriedade de nó para um identificador de pino ou um identificador de filtro, mas a solicitação também especifica uma ID de nó para indicar que a solicitação é para uma propriedade de nó em vez de uma propriedade de pin ou filtro.
Veja a seguir regras gerais para determinar se uma propriedade de nó deve usar um identificador de filtro ou identificador de pino:
Se um filtro contiver várias instâncias de um tipo de pino específico e cada pino desse tipo contiver um nó com uma ID de nó específica, cada instância de pin conterá uma instância do nó. Nesse caso, uma solicitação de propriedade de nó deve especificar um identificador de pino (em vez de apenas um identificador de filtro) para distinguir entre várias instâncias do mesmo tipo de nó. A combinação de identificador de pino e ID de nó identifica de forma inequívoca uma instância de nó específica como o destino da solicitação.
Se um filtro contiver apenas uma instância de um nó específico, uma solicitação de propriedade de nó especificará um identificador de filtro. A combinação de identificador de filtro e ID do nó é suficiente para identificar de forma inequívoca o nó que é o destino da solicitação.
Antes de implementar um manipulador para uma propriedade de nó específica, no entanto, o gravador de driver deve se referir a Conjuntos de Propriedades de Drivers de Áudio para marcar se o destino da propriedade deve ser especificado como um identificador de filtro ou identificador de pino.
Os drivers de porta no Portcls.sys atualmente não fornecem manipulação interna de propriedades de nó, com exceção de KSPROPERTY_TOPOLOGY_NAME.
Solicitações de propriedade superespecificadas e subespecificadas
Os drivers devem estar preparados para lidar com solicitações de propriedade de clientes que não seguem as regras anteriores. As solicitações podem ser superespecificadas ou subespecificadas:
Solicitações superespecificadas
Se uma solicitação de propriedade exigir apenas um identificador de filtro, mas o cliente enviar a solicitação para um identificador de pino, o destino da solicitação será superespecificado. No entanto, os drivers normalmente tratam a solicitação como válida; ou seja, eles tratam a solicitação como se ela tivesse sido enviada para o filtro que contém o pino.
Solicitações subespecificadas
Se uma solicitação de propriedade exigir um identificador de pino, mas um cliente enviar a solicitação para um identificador de filtro, o destino da solicitação será subespecificado. Por exemplo, se um filtro contiver várias instâncias de pino com o mesmo tipo de nó e um cliente enviar uma solicitação para uma propriedade desse tipo de nó para um identificador de filtro em vez de um identificador de pino, o driver não terá como determinar qual instância de nó deve receber a solicitação. Nesse caso, o comportamento depende do driver. Em vez de falhar automaticamente todas as solicitações subespecificadas, alguns drivers tratam uma solicitação de set-property não especificada como válida. Nesse caso, a interpretação é que a solicitação define o valor padrão para a ID do nó especificada. Quando uma fábrica de pinos cria uma nova instância de nó, a propriedade que pertence ao novo nó é inicializada para o valor padrão. Uma solicitação que altera o valor padrão não tem efeito sobre instâncias de nó criadas antes da solicitação. Além disso, os drivers falham uniformemente em solicitações de propriedade get-property subespecificadas porque o manipulador não tem como determinar qual instância de nó consultar para a propriedade.
Exceções às regras
Por motivos históricos, algumas propriedades de áudio têm peculiaridades comportamentais que violam essas regras gerais. Os exemplos são os seguintes:
Conforme descrito em Aplicando configurações de Speaker-Configuration, um cliente pode alterar a configuração do alto-falante de um dispositivo de áudio definindo a propriedade KSPROPERTY_AUDIO_CHANNEL_CONFIG de um nó 3D (KSNODETYPE_3D_EFFECTS). A configuração do alto-falante é global porque altera a configuração do alto-falante para todos os fluxos que fazem parte da combinação que o dispositivo reproduz por meio dos alto-falantes. De acordo com a regra geral, uma solicitação de propriedade de nó que afeta o filtro como um todo deve especificar um identificador de filtro (mais uma ID de nó). No entanto, essa propriedade específica requer um identificador de pino em vez de um identificador de filtro. O identificador de pino designa a instância de pino que contém o nó 3D que é o destino da solicitação.
KSPROPERTY_SYNTH_VOLUME e KSPROPERTY_SYNTH_MASTERCLOCK são propriedades de um nó de sintetizador (KSNODETYPE_SYNTHESIZER). Embora ambas sejam propriedades de nó, as solicitações para essas propriedades não incluem IDs de nó. (Observe que o descritor de propriedade para a solicitação é uma estrutura do tipo KSPROPERTY, não KSNODEPROPERTY.) Esse comportamento viola a regra geral de que uma propriedade de nó requer uma ID de nó. Apesar dessa discrepância, um driver de miniporto que dá suporte a qualquer propriedade deve fornecer o manipulador de propriedades por meio do membro Nodes do PCFILTER_DESCRIPTOR (em vez do membro Pins ).