Propriétés de filtre, d’épingle et de nœud
Les pilotes audio WDM (Microsoft Windows Driver Model) représentent un périphérique audio en tant que filtre KS, et ils représentent une mémoire tampon matérielle sur l’appareil en tant que broche sur le filtre. Lorsqu’un client envoie une demande de propriété à l’un de ces objets de filtre ou d’épingle, le pilote de port reçoit la demande et achemine la demande vers le gestionnaire de propriétés approprié dans le pilote de port ou le pilote miniport.
Les appareils audio prennent en charge trois types de propriétés :
Filtrer les propriétés
Une propriété filter est une propriété du filtre dans son ensemble plutôt qu’une propriété d’une broche ou d’un nœud particulier dans le filtre. Les demandes de propriétés de filtre spécifient des handles de filtre, mais elles ne spécifient pas d’ID de nœud.
Propriétés du code pin
Une propriété pin est une propriété d’une broche particulière instance sur le filtre. Les demandes de ces propriétés spécifient des poignées de broches, mais elles ne spécifient pas d’ID de nœud.
Propriétés du nœud
Une propriété de nœud est une propriété d’un nœud de topologie dans le filtre. Une requête pour une propriété de nœud spécifie un handle de filtre ou un handle de broche, plus un ID de nœud.
Si une requête de propriété de nœud spécifie un filtre ou une poignée de broches, le nœud est unique ou non au filtre. Pour plus d’informations, consultez la section Propriétés du nœud suivante.
L’illustration suivante montre ces trois types de demande de propriété : une requête pin-property envoyée à un instance de broche, une requête de propriété de nœud envoyée à un nœud (sur un filtre ou une épingle instance) et une demande de propriété de filtre envoyée à un instance de filtre.
En règle générale, le pilote de port gère la plupart des requêtes pour les propriétés de filtre et de broche, et le pilote miniport gère les requêtes relatives aux propriétés de nœud.
Le pilote de port fournit ses propres gestionnaires intégrés pour les propriétés de filtre et de broche utilisées par le pilote système SysAudio (voir KSPROPSETID_Sysaudio et KSPROPSETID_Sysaudio_Pin) et le pilote système WDMAud. Un pilote miniport n’a pas besoin d’implémenter des gestionnaires pour les propriétés gérées par le pilote de port. Un pilote miniport classique fournit peu de gestionnaires, voire aucun, pour les propriétés de filtre et de broche. Le pilote miniport fournit les gestionnaires pour les propriétés de nœud qui représentent les fonctionnalités dépendantes du matériel du périphérique audio. Les pilotes de port ne fournissent aucune gestion intégrée des propriétés de nœud, à l’exception de KSPROPERTY_TOPOLOGY_NAME.
Lorsque le pilote de port et le pilote miniport fournissent des gestionnaires pour la même propriété, le pilote de port utilise son propre gestionnaire et ignore le gestionnaire du pilote miniport.
Descripteurs de filtre
Le pilote de port obtient des pointeurs vers les gestionnaires de propriétés du pilote miniport en appelant la méthode IMiniport ::GetDescription . Grâce à cette méthode, le pilote de port récupère un pointeur vers le descripteur de filtre du pilote miniport, qui est une structure de type PCFILTER_DESCRIPTOR. Cette structure spécifie les gestionnaires de propriétés du pilote miniport pour les propriétés de filtre, d’épingle et de nœud :
Le membre AutomationTable de la structure PCFILTER_DESCRIPTOR pointe vers la table Automation pour le filtre. Ce tableau spécifie les gestionnaires de propriétés du pilote miniport pour les propriétés de filtre.
Le membre Pins de la structure PCFILTER_DESCRIPTOR contient les tables Automation pour les broches. Chaque table spécifie les gestionnaires de propriétés pour les propriétés de broche d’un type de broche particulier.
Le membre Nœuds de la structure PCFILTER_DESCRIPTOR contient les tables Automation pour les nœuds de topologie à l’intérieur du filtre. Chaque table spécifie les gestionnaires de propriétés pour les propriétés de nœud d’un type de nœud particulier.
Propriétés de filtre
Le pilote de port accède aux gestionnaires de propriété de filtre du pilote miniport via le membre AutomationTable de PCFILTER_DESCRIPTOR. En règle générale, cette table Automation contient peu de gestionnaires, car le pilote de port fournit ses propres gestionnaires intégrés pour toutes les propriétés de filtre utilisées par SysAudio et WDMAud pour interroger et configurer des périphériques audio.
Toutefois, le pilote miniport peut fournir des gestionnaires pour les propriétés de filtre telles que KSPROPERTY_GENERAL_COMPONENTID qui fournissent des informations dépendantes du matériel qui ne sont pas disponibles pour le pilote de port. Deux des exemples de pilotes audio du Kit de pilotes Microsoft Windows (WDK) gèrent la propriété KSPROPERTY_GENERAL_COMPONENTID. Pour plus d’informations, consultez les implémentations de pilotes miniport dans l’exemple de pilote Sysvad, qui est décrit dans Exemples de pilotes audio.
Tous les pilotes de port dans Portcls.sys fournissent la gestion des jeux de propriétés KSPROPSETID_Pin et KSPROPSETID_Topology . Toutes les propriétés de ces jeux sont des propriétés de filtre, à l’exception de KSPROPERTY_TOPOLOGY_NAME, qui est une propriété de nœud (qui utilise un handle de filtre, et non un handle pin, pour spécifier la cible de la requête). Les pilotes de port prennent en charge le sous-ensemble suivant des propriétés KSPROPSETID_Pin :
KSPROPERTY_PIN_CONSTRAINEDDATARANGES
KSPROPERTY_PIN_DATAINTERSECTION
KSPROPERTY_PIN_GLOBALCINSTANCES
KSPROPERTY_PIN_NECESSARYINSTANCES
KSPROPERTY_PIN_PHYSICALCONNECTION
KSPROPERTY_PIN_PROPOSEDATAFORMAT
KSPROPERTY_PIN_PROPOSEDATAFORMAT2
Ces propriétés fournissent des informations sur les fabriques de broches appartenant à un filtre. En règle générale, les clients interrogent le filtre pour ces propriétés avant de créer des instances d’épingle. Les pilotes de port prennent en charge les quatre propriétés KSPROPSETID_Topology, qui fournissent des informations sur la topologie interne du filtre.
En outre, le pilote de port DMus fournit un gestionnaire pour la propriété KSPROPERTY_SYNTH_MASTERCLOCK , qui est une propriété get-only d’un filtre DirectMusic. KSPROPERTY_SYNTH_MASTERCLOCK est membre de l’ensemble de propriétés KSPROPSETID_SynthClock .
Propriétés du code pin
Le pilote de port accède aux gestionnaires de propriétés pin du pilote miniport via le membre Pins de PCFILTER_DESCRIPTOR. Ce membre pointe vers un tableau de descripteurs de broche, et chaque descripteur pointe vers la table Automation pour un type de broche (identifié par un ID de broche, qui est simplement l’index du tableau).
En règle générale, ces tables Automation contiennent peu d’entrées, car le pilote de port fournit ses propres gestionnaires pour toutes les propriétés de broche utilisées par SysAudio et WDMAud. Un pilote miniport a la possibilité de fournir des gestionnaires pour une ou plusieurs propriétés de broche que le pilote de port ne gère pas, mais seuls les clients qui connaissent ces propriétés peuvent envoyer des demandes de propriété pour celles-ci.
À l’exception du pilote de port de topologie, tous les pilotes de port dans Portcls.sys fournissent des gestionnaires intégrés pour les propriétés de broche suivantes :
KSPROPERTY_CONNECTION_DATAFORMAT
KSPROPERTY_CONNECTION_ALLOCATORFRAMING
KSPROPERTY_DRMAUDIOSTREAM_CONTENTID
Certaines des propriétés de cette liste nécessitent des informations dépendantes du matériel du pilote miniport. Lorsque le pilote de port reçoit un IRP contenant une demande pour l’une de ces propriétés, il ne transmet pas l’IRP au pilote miniport. Au lieu de cela, le pilote de port gère la requête lui-même, mais son gestionnaire obtient les informations dont il a besoin en appelant un point d’entrée dans le pilote miniport. Par exemple, le pilote de port fournit son propre gestionnaire de propriétés pour les requêtes KSPROPERTY_AUDIO_POSITION. Ce gestionnaire appelle simplement la méthode GetPosition du flux de pilotes miniport (par exemple, IMiniportWavePciStream ::GetPosition) pour obtenir la position actuelle.
Propriétés du nœud
Le pilote de port accède aux gestionnaires de propriété de nœud du pilote miniport via le membre Nodes de PCFILTER_DESCRIPTOR. Ce membre pointe vers un tableau de descripteurs de nœud, et chaque descripteur pointe vers la table Automation pour un type de nœud (identifié par un ID de nœud, qui est simplement l’index du tableau). En règle générale, la totalité ou la plupart des gestionnaires de propriétés appartenant à un pilote miniport résident dans le tableau Nœuds . Un pilote audio représente les contrôles matériels d’un périphérique audio en tant que nœuds de topologie, et il utilise le mécanisme de propriété pour fournir aux clients un accès aux paramètres de contrôle dépendant du matériel.
Comme décrit précédemment, un client envoie une demande de propriété de filtre à un handle de filtre et une demande de propriété d’épingle à un descripteur d’épingle. Contrairement à un filtre ou une épingle instance, un nœud n’est pas un objet de noyau et n’a pas de handle. Un client envoie une demande de propriété de nœud à un handle d’épingle ou à un handle de filtre, mais la demande spécifie également un ID de nœud pour indiquer que la demande concerne une propriété de nœud plutôt qu’une propriété d’épingle ou de filtre.
Voici des règles générales permettant de déterminer si une propriété de nœud doit utiliser un handle de filtre ou un handle d’épingle :
Si un filtre contient plusieurs instances d’un type de broche particulier et que chaque broche de ce type contient un nœud avec un ID de nœud particulier, chaque épingle instance contient une instance du nœud. Dans ce cas, une requête node-property doit spécifier un handle d’épingle (plutôt qu’un simple handle de filtre) pour faire la distinction entre plusieurs instances du même type de nœud. La combinaison du handle d’épingle et de l’ID de nœud identifie sans ambiguïté un nœud particulier instance comme cible pour la requête.
Si un filtre ne contient qu’une seule instance d’un nœud particulier, une demande de propriété de nœud spécifie un handle de filtre. La combinaison du handle de filtre et de l’ID de nœud est suffisante pour identifier sans ambiguïté le nœud qui est la cible de la requête.
Toutefois, avant d’implémenter un gestionnaire pour une propriété de nœud particulière, l’enregistreur de pilotes doit faire référence à Audio Drivers Property Sets pour case activée si la cible de la propriété doit être spécifiée en tant que handle de filtre ou de poignée d’épingle.
Actuellement, les pilotes de port dans Portcls.sys ne fournissent pas de gestion intégrée des propriétés de nœud, à l’exception de KSPROPERTY_TOPOLOGY_NAME.
Demandes de propriétés sur-spécifiées et sous-spécifiées
Les pilotes doivent être prêts à traiter les demandes de propriété de clients qui ne suivent pas les règles précédentes. Les demandes peuvent être sur-spécifiées ou sous-spécifiées :
Demandes surdéspecifiées
Si une demande de propriété nécessite uniquement un handle de filtre, mais que le client envoie la demande à un handle d’épingle à la place, la cible de la requête est surdéspecifiée. Toutefois, les pilotes traitent généralement la requête comme valide ; autrement dit, ils traitent la requête comme si elle avait été envoyée au filtre contenant l’épingle.
Demandes sous-spécifiées
Si une demande de propriété nécessite un handle d’épingle, mais qu’un client envoie la demande à un handle de filtre à la place, la cible de la requête est sous-spécifiée. Par exemple, si un filtre contient plusieurs instances d’épingle avec le même type de nœud et qu’un client envoie une demande pour une propriété de ce type de nœud à un handle de filtre plutôt qu’à un handle d’épingle, le pilote n’a aucun moyen de déterminer le nœud instance doit recevoir la demande. Dans ce cas, le comportement dépend du pilote. Au lieu d’échouer automatiquement toutes les demandes sous-spécifiées, certains pilotes traitent une demande set-property sous-spécifiée comme valide. Dans ce cas, l’interprétation est que la requête définit la valeur par défaut pour l’ID de nœud spécifié. Lorsqu’une fabrique d’épingles crée un nœud instance, la propriété appartenant au nouveau nœud est initialisée à la valeur par défaut. Une requête qui modifie la valeur par défaut n’a aucun effet sur les instances de nœud créées avant la demande. En outre, les pilotes échouent uniformément aux demandes get-property sous-spécifiées, car le gestionnaire n’a aucun moyen de déterminer quel nœud instance interroger la propriété.
Exceptions aux règles
Pour des raisons historiques, quelques propriétés audio ont des bizarreries comportementales qui violent ces règles générales. Voici quelques exemples :
Comme décrit dans Application des paramètres de Speaker-Configuration, un client peut modifier la configuration du haut-parleur d’un périphérique audio en définissant la propriété KSPROPERTY_AUDIO_CHANNEL_CONFIG d’un nœud 3D (KSNODETYPE_3D_EFFECTS). Le paramètre de configuration du haut-parleur est global, car il modifie la configuration de l’orateur pour tous les flux qui font partie de la combinaison que l’appareil lit sur les haut-parleurs. Selon la règle générale, une requête node-property qui affecte le filtre dans son ensemble doit spécifier un handle de filtre (plus un ID de nœud). Toutefois, cette propriété particulière nécessite un handle d’épingle au lieu d’un handle de filtre. Le handle de broche désigne le instance de broche contenant le nœud 3D qui est la cible de la requête.
KSPROPERTY_SYNTH_VOLUME et KSPROPERTY_SYNTH_MASTERCLOCK sont des propriétés d’un nœud de synthèse (KSNODETYPE_SYNTHESIZER). Bien que les deux soient des propriétés de nœud, les demandes pour ces propriétés n’incluent pas d’ID de nœud. (Notez que le descripteur de propriété pour la requête est une structure de type KSPROPERTY, et non KSNODEPROPERTY.) Ce comportement enfreint la règle générale selon laquelle une propriété de nœud nécessite un ID de nœud. Malgré cette différence, un pilote miniport qui prend en charge l’une ou l’autre propriété doit fournir le gestionnaire de propriétés via le membre Nodes de PCFILTER_DESCRIPTOR (au lieu du membre Pins ).
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour