Nota
O acesso a esta página requer autorização. Podes tentar iniciar sessão ou mudar de diretório.
O acesso a esta página requer autorização. Podes tentar mudar de diretório.
Ao especificar os dados de uma solicitação de propriedade definida para um filtro, pino ou nó, o cliente freqüentemente precisa saber os intervalos de dados válidos para o valor ou valores que especifica para a propriedade. Os intervalos podem variar de dispositivo para dispositivo e, possivelmente, até de nó para nó dentro do mesmo dispositivo.
Algumas propriedades são definidas para permitir que solicitações de definição de propriedade especifiquem valores fora do intervalo, mas os drivers de miniporta ajustam silenciosamente esses valores para o intervalo suportado (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 valores, que podem ser versões fixas dos valores que o cliente especificou na solicitação definida.
No entanto, um cliente pode precisar saber o intervalo para um valor de propriedade em vez de simplesmente confiar no driver de miniporta para fixar automaticamente um valor fora do intervalo. Por exemplo, um aplicativo em janela que apresenta um controle deslizante de controle de volume para um dispositivo de áudio pode precisar conhecer o intervalo de volume do dispositivo para mapear esse intervalo para o comprimento total do controle deslizante.
A rotina de gestão do controlador para uma propriedade específica deve ser capaz de fornecer informação sobre limites 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 consiste em uma estrutura de KSPROPERTY_DESCRIPTION que pode ser seguida por dados específicos da propriedade. Esses dados geralmente 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 quão grande esse buffer de valor deve ser e deve enviar uma ou duas solicitações preliminares para o manipulador de propriedade para determinar o tamanho do valor. O formato destes pedidos preliminares está 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 propriedade deverá gravar o valor do membro AccessFlags da estrutura KSPROPERTY_DESCRIPTION no buffer de valor de tamanho ULONG. O manipulador define o bit de sinalização KSPROPERTY_TYPE_BASICSUPPORT caso ofereça suporte adicional para pedidos de propriedades 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 gravará as informações específicas da propriedade na parte do buffer de dados que segue o final da estrutura KSPROPERTY_DESCRIPTION. Ao escrever 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á o código de status STATUS_BUFFER_TOO_SMALL.
As informações específicas da propriedade que o manipulador grava no buffer de valores 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 é zero se não forem necessários intervalos. Este é 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 que seja grande o suficiente para conter as seguintes estruturas:
As três estruturas são compactadas em locais adjacentes no buffer na ordem mostrada na lista anterior. Ao lidar com a solicitação, o driver de miniporta 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 Exposing Multichannel Nodes. 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 Microsoft Windows Driver Kit (WDK).