Requêtes de prise en charge de base pour les propriétés audio
Lors de la spécification des données d’une demande set-property sur un filtre, une broche ou un nœud, le client a souvent besoin de connaître les plages de données valides pour la ou les valeurs qu’il spécifie pour la propriété . Les plages peuvent varier d’un appareil à l’autre, voire même d’un nœud à un autre au sein du même appareil.
Certaines propriétés sont définies pour permettre aux demandes set-property de spécifier des valeurs hors limites, mais les pilotes miniports limitent silencieusement ces valeurs à la plage prise en charge (par exemple, voir KSPROPERTY_AUDIO_VOLUMELEVEL). Une requête get suivante pour la même propriété récupère les paramètres réels du pilote pour la ou les valeurs, qui peuvent être des versions limitées des valeurs spécifiées par le client dans la demande d’ensemble.
Toutefois, un client peut avoir besoin de connaître la plage d’une valeur de propriété au lieu de simplement s’appuyer sur le pilote miniport pour bloquer automatiquement une valeur hors plage. Par exemple, une application fenêtré qui présente un curseur de contrôle de volume pour un périphérique audio peut avoir besoin de connaître la plage de volumes de l’appareil afin de mapper cette plage à toute la longueur du curseur.
La routine de gestionnaire du pilote pour une propriété particulière doit être en mesure de fournir des informations de plage en réponse à une demande de propriété de support de base (KSPROPERTY_TYPE_BASICSUPPORT). Lors de l’envoi d’une demande de propriété de support de base à un pilote, un client fournit une mémoire tampon de valeur dans laquelle le gestionnaire de propriétés écrit les informations de support de base, qui se compose d’une structure de KSPROPERTY_DESCRIPTION qui peut être suivie de données spécifiques à la propriété. Ces données se composent généralement de spécifications pour une ou plusieurs plages de paramètres, en fonction de la propriété .
En général, le client ne sait pas à l’avance la taille de cette mémoire tampon de valeur et doit envoyer une ou deux demandes préliminaires au gestionnaire de propriétés pour déterminer la taille de la valeur. Le format de ces demandes préliminaires est bien défini. Les clients s’attendent à ce que les pilotes respectent ces conventions lors de la gestion d’une demande de support de base :
Si la demande spécifie la taille de la valeur sizeof(ULONG), le gestionnaire de propriétés doit écrire la valeur du membre AccessFlags de la structure KSPROPERTY_DESCRIPTION dans la mémoire tampon de valeur de taille ULONG. Le gestionnaire définit le bit d’indicateur KSPROPERTY_TYPE_BASICSUPPORT s’il fournit une prise en charge supplémentaire pour les demandes de propriétés de support de base.
Si la demande spécifie la taille de la valeur sizeof(KSPROPERTY_DESCRIPTION), le gestionnaire doit écrire une structure de KSPROPERTY_DESCRIPTION dans la mémoire tampon de données. Le gestionnaire définit le champ DescriptionSize de la structure égal à la taille de cette structure, plus la taille de toutes les informations supplémentaires spécifiques aux propriétés que le gestionnaire peut charger dans la mémoire tampon de données suivant la structure. Il s’agit de la taille de la mémoire tampon de valeur que le client doit allouer pour contenir les informations de support de base de la propriété.
Si la demande spécifie une taille de valeur suffisamment grande pour contenir à la fois la structure KSPROPERTY_DESCRIPTION et les informations spécifiques à la propriété, le gestionnaire doit écrire la structure KSPROPERTY_DESCRIPTION au début de la mémoire tampon, et il doit écrire les informations spécifiques à la propriété dans la partie de la mémoire tampon de données qui suit la fin de la structure KSPROPERTY_DESCRIPTION. Lors de l’écriture de la structure KSPROPERTY_DESCRIPTION, le gestionnaire doit définir le champ DescriptionSize sur la taille de cette structure, plus la taille des informations spécifiques à la propriété qui suivent la structure.
Si la demande spécifie une taille de valeur qui ne correspond pas à l’un de ces trois cas, le gestionnaire de propriétés rejette la requête et retourne status code STATUS_BUFFER_TOO_SMALL.
Les informations spécifiques à la propriété que le gestionnaire écrit dans la mémoire tampon de valeurs peuvent inclure des plages de données pour les valeurs de propriété. Le membre MembersSize de KSPROPERTY_MEMBERSHEADER indique si des plages de données sont incluses :
MembersSize est égal à zéro si aucune plage n’est nécessaire. C’est le cas, par exemple, si les valeurs de propriété sont de type BOOL.
MembersSize est différent de zéro si la structure KSPROPERTY_MEMBERSHEADER est suivie de descripteurs de plage pour une ou plusieurs valeurs de propriété.
Pour une valeur de propriété de type BOOL, aucun descripteur de plage n’est nécessaire, car la plage est implicitement limitée aux valeurs TRUE et FALSE. Toutefois, des descripteurs de plage sont nécessaires pour spécifier les plages de valeurs de propriété avec des types entiers.
Par exemple, la demande de support de base pour une propriété KSPROPERTY_AUDIO_VOLUMELEVEL sur un nœud de volume (KSNODETYPE_VOLUME) récupère les paramètres de volume minimal et maximal pour ce nœud. Dans ce cas, le client doit allouer une mémoire tampon de valeur suffisamment grande pour contenir les structures suivantes :
Les trois structures sont empaquetées dans des emplacements adjacents dans la mémoire tampon dans l’ordre indiqué dans la liste précédente. Lors de la gestion de la demande, le pilote miniport écrit les niveaux de volume minimum et maximal dans le membre Bounds de la structure KSPROPERTY_STEPPING_LONG.
Pour obtenir un exemple de demande de support de base avec un tableau de descripteurs de plage, consultez la figure dans Exposition de nœuds multicanaux. Pour plus d’informations sur les demandes de propriétés de support de base, consultez Propriétés KS. Pour obtenir des exemples de code, reportez-vous aux implémentations de gestionnaires de propriétés dans les exemples de pilotes audio du Kit de pilotes Microsoft Windows (WDK).