Consultas de suporte básico para propriedades de áudio
Ao especificar os dados de uma solicitação set-property para um filtro, pino ou nó, o cliente frequentemente precisa saber os intervalos de dados válidos para o valor ou os valores especificados para a propriedade. Os intervalos podem variar de dispositivo para dispositivo e, possivelmente, até mesmo de nó para nó no mesmo dispositivo.
Algumas propriedades são definidas para permitir que solicitações set-property especifiquem valores fora do intervalo, mas os drivers de miniportar fixam silenciosamente esses valores ao intervalo com suporte (por exemplo, consulte KSPROPERTY_AUDIO_VOLUMELEVEL). Uma solicitação get subsequente para a mesma propriedade recupera as configurações reais do driver para o valor ou os valores, que podem ser versões fixadas dos valores especificados pelo cliente na solicitação set.
No entanto, um cliente pode precisar saber o intervalo de um valor de propriedade em vez de simplesmente depender do driver de miniport para fixar automaticamente um valor fora do intervalo. Por exemplo, um aplicativo em janelas que apresenta um controle deslizante de controle de volume para um dispositivo de áudio pode precisar saber o intervalo de volumes do dispositivo para mapear esse intervalo para o comprimento total do controle deslizante.
A rotina do manipulador do driver para uma propriedade específica deve ser capaz de fornecer informações de intervalo em resposta a uma solicitação de propriedade de suporte básico (KSPROPERTY_TYPE_BASICSUPPORT). Ao enviar uma solicitação de propriedade de suporte básico para um driver, um cliente fornece um buffer de valor no qual o manipulador de propriedades grava as informações de suporte básico, que consistem em uma estrutura KSPROPERTY_DESCRIPTION que pode ser seguida por dados específicos da propriedade. Esses dados normalmente consistem em especificações para um ou mais intervalos de parâmetros, dependendo da propriedade .
Em geral, o cliente não sabe com antecedência o tamanho desse buffer de valor e deve enviar uma ou duas solicitações preliminares ao manipulador de propriedades para determinar o tamanho do valor. O formato dessas solicitações preliminares é bem definido. Os clientes esperam que os drivers sigam estas convenções ao lidar com uma solicitação de suporte básico:
Se a solicitação especificar o tamanho do valor como sizeof(ULONG), o manipulador de propriedades deverá gravar o valor do membro AccessFlags da estrutura KSPROPERTY_DESCRIPTION no buffer de valor do tamanho ULONG. O manipulador define o KSPROPERTY_TYPE_BASICSUPPORT bit de sinalizador se fornecer suporte adicional para solicitações de propriedade de suporte básico.
Se a solicitação especificar o tamanho do valor como sizeof(KSPROPERTY_DESCRIPTION), o manipulador deverá gravar uma estrutura KSPROPERTY_DESCRIPTION no buffer de dados. O manipulador define o campo DescriptionSize da estrutura igual ao tamanho dessa estrutura mais o tamanho de todas as informações adicionais específicas da propriedade que o manipulador tem disponível para carregar no buffer de dados após a estrutura. Esse é o tamanho do buffer de valor que o cliente precisa alocar para conter as informações de suporte básico da propriedade.
Se a solicitação especificar um tamanho de valor grande o suficiente para conter a estrutura KSPROPERTY_DESCRIPTION e as informações específicas da propriedade, o manipulador deverá gravar a estrutura KSPROPERTY_DESCRIPTION no início do buffer e deve gravar as informações específicas da propriedade na parte do buffer de dados que segue o final da estrutura KSPROPERTY_DESCRIPTION. Ao gravar a estrutura KSPROPERTY_DESCRIPTION, o manipulador deve definir o campo DescriptionSize para o tamanho dessa estrutura mais o tamanho das informações específicas da propriedade que seguem a estrutura.
Se a solicitação especificar um tamanho de valor que não corresponda a um desses três casos, o manipulador de propriedades rejeitará a solicitação e retornará status código STATUS_BUFFER_TOO_SMALL.
As informações específicas da propriedade que o manipulador grava no buffer de valor podem incluir intervalos de dados para valores de propriedade. O membro MembersSize do KSPROPERTY_MEMBERSHEADER indica se os intervalos de dados estão incluídos:
MembersSize será zero se nenhum intervalo for necessário. Esse é o caso, por exemplo, se os valores de propriedade forem do tipo BOOL.
MembersSize será diferente de zero se a estrutura KSPROPERTY_MEMBERSHEADER for seguida por descritores de intervalo para um ou mais valores de propriedade.
Para um valor de propriedade do tipo BOOL, nenhum descritor de intervalo é necessário porque o intervalo é implicitamente limitado aos valores TRUE e FALSE. No entanto, os descritores de intervalo são necessários para especificar os intervalos de valores de propriedade com tipos inteiros.
Por exemplo, a solicitação de suporte básico para uma propriedade KSPROPERTY_AUDIO_VOLUMELEVEL em um nó de volume (KSNODETYPE_VOLUME) recupera as configurações de volume mínimo e máximo para esse nó. Nesse caso, o cliente precisa alocar um buffer de valor grande o suficiente para conter as seguintes estruturas:
As três estruturas são empacotadas em locais adjacentes no buffer na ordem mostrada na lista anterior. Ao lidar com a solicitação, o driver de miniporto grava os níveis de volume mínimo e máximo no membro Bounds da estrutura KSPROPERTY_STEPPING_LONG.
Para obter um exemplo de uma solicitação de suporte básico com uma matriz de descritores de intervalo, consulte a figura em Expondo nós multicanal. Para obter mais informações sobre solicitações de propriedade de suporte básico, consulte Propriedades do KS. Para obter exemplos de código, consulte as implementações do manipulador de propriedades nos drivers de áudio de exemplo no WDK (Microsoft Windows Driver Kit).