Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Ao especificar os dados de uma solicitação para definir propriedade ("set-property") em um filtro, pino ou nó, o cliente frequentemente precisa conhecer 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é mesmo de nó para nó dentro do mesmo dispositivo.
Algumas propriedades são definidas para permitir que solicitações de definição de propriedades especifiquem valores fora da faixa permitida, mas os drivers de miniporte ajustam silenciosamente esses valores para a faixa suportada (por exemplo, consulte KSPROPERTY_AUDIO_VOLUMELEVEL). Uma solicitação de obtenção subsequente para a mesma propriedade recupera as configurações reais do driver para o valor ou valores, que podem ser versões fixadas dos valores especificados pelo cliente na solicitação definida.
No entanto, um cliente pode precisar saber o intervalo de um valor de propriedade em vez de simplesmente depender do driver de miniporto para fixar automaticamente um valor que está fora do intervalo. Por exemplo, um aplicativo com 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 até o comprimento total do controle deslizante.
A rotina de 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 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 propriedades deverá gravar o valor do membro AccessFlags da estrutura KSPROPERTY_DESCRIPTION no buffer de valor do tamanho ULONG. O manipulador define o bit de sinalizador KSPROPERTY_TYPE_BASICSUPPORT caso ele forneça mais suporte 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 de propriedade que o manipulador tem disponível para carregar no buffer de dados seguindo 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 escrever a estrutura de 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 corresponde 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 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 não houver necessidade de intervalos. Esse é o caso, por exemplo, se os valores de propriedade forem do tipo BOOL.
MembersSize não será zero se a estrutura de 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 está 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ínima e máxima 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 Multicanais. 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).