Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
Lorsque vous spécifiez les données d'une requête set-property à un filtre, une broche ou un nœud, le client doit fréquemment connaître les plages de données valides pour la valeur ou les valeurs qu'il spécifie pour la propriété. Les plages peuvent varier d’un appareil à l’autre, voire d’un nœud à un nœud au sein du même appareil.
Certaines propriétés sont définies pour autoriser les requêtes set-property à spécifier des valeurs hors plage, mais les pilotes miniports limitent silencieusement ces valeurs à la plage prise en charge (par exemple, voir KSPROPERTY_AUDIO_VOLUMELEVEL). Une requête de récupération suivante pour la même propriété récupère les paramètres réels du pilote pour la valeur ou les valeurs, qui peuvent être des versions limitées des valeurs spécifiées par le client dans la demande de définition.
Toutefois, un client peut avoir besoin de connaître la plage d’une valeur de propriété au lieu de simplement compter sur le pilote miniport pour limiter automatiquement une valeur hors plage. Par exemple, une application fenêtrée qui présente un curseur de volume pour un appareil audio peut avoir besoin de connaître la plage de volumes de l’appareil afin d'adapter cette plage à la longueur totale du curseur.
La routine du gestionnaire du pilote pour une caractéristique particulière doit être en mesure de fournir des informations de portée en réponse à une demande de caractéristique 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 prise en charge de base, qui se compose d’une structure 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 suivent ces conventions lors de la gestion d’une demande de support de base :
Si la requête spécifie la taille de la valeur sous la forme sizeof(ULONG), le gestionnaire de propriétés doit écrire la valeur du membre AccessFlags de la structure KSPROPERTY_DESCRIPTION dans une mémoire tampon de taille ULONG. Le gestionnaire définit le bit d’indicateur KSPROPERTY_TYPE_BASICSUPPORT s’il fournit un support supplémentaire pour les requêtes de propriété de support basique.
Si la requête spécifie la taille de la valeur en tant que sizeof(KSPROPERTY_DESCRIPTION), le gestionnaire doit écrire une structure 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, ainsi que la taille de toutes les informations supplémentaires spécifiques aux propriétés que le gestionnaire a disponibles pour charger dans la mémoire tampon de données en 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 prise en charge de base de la propriété.
Si la demande spécifie une taille de valeur suffisante pour contenir à la fois la structure KSPROPERTY_DESCRIPTION et les informations spécifiques à la propriété, le gestionnaire doit écrire la structure KSPROPERTY_DESCRIPTION dans le début de la mémoire tampon et é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, ainsi que la taille des informations spécifiques à la propriété qui suivent la structure.
Si la requête 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 le code d’état 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 les 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, les 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 regroupé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 requête, le pilote miniport écrit les niveaux de volume minimal 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 Exposing Multichannel Nodes. 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 du gestionnaire de propriétés dans les exemples de pilotes audio dans le Kit de pilotes Microsoft Windows (WDK).