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.
Les pilotes audio WDM (Microsoft Windows Driver Model) représentent un périphérique audio en tant que filtre KS et représentent une mémoire tampon matérielle sur le périphérique sous forme de 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 requête et la redirige 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 :
Propriétés de filtre
Une propriété de filtre 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 d’épingle
Une propriété de broche est une propriété d’une instance spécifique de broche sur le filtre. Les demandes de ces propriétés spécifient des poignées d'épingle, mais elles ne spécifient pas d'identifiants de nœud.
Propriétés de 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 descripteur de filtre ou un descripteur de broche, ainsi qu’un ID de nœud.
Si une demande de propriété de nœud spécifie une poignée de filtre ou d’épingle dépend de si le nœud est unique au filtre. Pour plus d’informations, consultez la section Propriétés de nœud suivante.
La figure suivante montre ces trois types de requêtes de propriété : une requête de propriété de broche envoyée à une instance de broche, une requête de propriété de nœud envoyée à un nœud (que ce soit sur une instance de filtre ou de broche), et une requête de propriété de filtre envoyée à une 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 demandes de 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 typique fournit peu, voire aucun, de gestionnaires 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 d'automatisation du filtre. Ce tableau spécifie les gestionnaires de propriétés du pilote miniport pour les propriétés de filtre.
Le membre broches de la structure PCFILTER_DESCRIPTOR contient les tables d’automatisation des broches. Chaque table spécifie les gestionnaires de propriétés pour les propriétés de broche d'un type de broche.
Le membre nœuds de la structure PCFILTER_DESCRIPTOR contient les tables d’automatisation des 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 du filtre
Le pilote de port accède aux gestionnaires de propriétés 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 dans le 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écrite dans Sample Audio Drivers.
Tous les pilotes de port dans Portcls.sys fournissent la gestion des ensembles de propriétés KSPROPSETID_Pin et KSPROPSETID_Topology . Toutes les propriétés de ces ensembles sont des propriétés de filtre, à l’exception de KSPROPERTY_TOPOLOGY_NAME, qui est une propriété de nœud (utilisant une poignée de filtre, et non une poignée de broche, 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 usines de broches d'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é en lecture seule d’un filtre DirectMusic. KSPROPERTY_SYNTH_MASTERCLOCK est membre du jeu de propriétés KSPROPSETID_SynthClock .
Propriétés d’épingler
Le pilote de port accède aux gestionnaires de propriétés de broche 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 le tableau d'automatisation 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 tableaux d'automatisation contiennent peu d'entrées, car le pilote de port fournit ses propres gestionnaires pour toutes les propriétés de la broche qu'utilisent 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 requêtes de propriété les concernant.
À l'exception du pilote de port de topologie, tous les pilotes de port à l'état Portcls.sys fournissent des gestionnaires intégrés pour les propriétés de pin suivantes :
KSPROPERTY_CONNECTION_DATAFORMAT
KSPROPERTY_CONNECTION_ALLOCATORFRAMING
KSPROPERTY_DRMAUDIOSTREAM_CONTENTID
Certaines des propriétés de cette liste nécessitent des informations dépendant du matériel fournies par le pilote miniport. Lorsque le pilote de port reçoit un IRP contenant une demande d’une de ces propriétés, il ne transmet pas le protocole IRP au pilote miniport. Au lieu de cela, le pilote de port gère la requête elle-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és de nœud du pilote miniport via le membre Nœuds de PCFILTER_DESCRIPTOR. Ce membre pointe vers un tableau de descripteurs de nœuds, 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 de tableau). En règle générale, tous 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 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 requête de propriété de filtre à un handle de filtre et une requête de propriété de broche à un handle de broche. Contrairement à une instance de filtre ou d’épingle, un nœud n’est pas un objet noyau et n’a pas de handle. Un client envoie une demande de propriété de nœud à une poignée de broche ou à une poignée de filtre, mais la demande spécifie également un ID de nœud pour indiquer que la requête concerne une propriété de nœud plutôt qu'une propriété de broche ou de filtre.
Voici quelques règles générales pour déterminer si une propriété de nœud doit utiliser un gestionnaire de filtre ou un gestionnaire de broche :
Si un filtre contient plusieurs instances d’un certain type de connecteur et que chaque connecteur de ce type contient un nœud avec un ID de nœud particulier, alors chaque instance de connecteur contient une instance du nœud. Dans ce cas, une requête de propriété de nœud doit spécifier une poignée d'épingle (plutôt qu'une poignée de filtre) pour distinguer plusieurs instances du même type de nœud. La combinaison du handle de broche et de l’ID de nœud identifie sans ambiguïté une instance de nœud particulière comme cible pour la requête.
Si un filtre contient une seule instance d’un nœud particulier, une requête de propriété de nœud spécifie un handle de filtre. La combinaison de handle de filtre et d’ID de nœud suffit pour identifier sans ambiguïté le nœud qui est la cible de la requête.
Avant d'implémenter un gestionnaire pour une propriété de nœud particulière, toutefois, le développeur de pilotes doit faire référence aux Audio Drivers Property Sets pour vérifier si la cible de la propriété doit être spécifiée en tant que handle de filtre ou poignée de broche.
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é surspecifiées et sous-spécifiées
Les pilotes doivent être prêts à traiter les demandes de propriété des clients qui ne suivent pas les règles précédentes. Les demandes peuvent être surspecifiées ou sous-spécifiées :
Demandes surspecifiées
Si une demande de propriété nécessite uniquement un handle de filtre, mais que le client envoie la requête à un handle d’épingle à la place, la cible de la requête est surspecifiée. Toutefois, les pilotes traitent généralement la requête comme valide ; autrement dit, ils traitent la demande comme si elle avait été envoyée au filtre contenant la broche.
Demandes sous-spécifiées
Si une demande de propriété nécessite un handle de broche, mais qu’un client envoie la requête à un handle de filtre à la place, la cible de la requête est insuffisamment spécifiée. Par exemple, si un filtre contient plusieurs instances de broche ayant le même type de nœud et qu’un client envoie une requête pour une propriété de ce type de nœud à un handle de filtre plutôt qu’à un handle de broche, le pilote n’a aucun moyen de déterminer quelle instance de nœud doit recevoir la requête. 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 de définition de propriété sous-spécifiée comme valide. Dans ce cas, l’interprétation est que la requête définit la valeur par défaut de l’ID de nœud spécifié. Lorsqu’une fabrique d’épingles crée une instance de nœud, 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 face aux requêtes get-property non spécifiées, car le gestionnaire n’a aucun moyen de déterminer l’instance de nœud à interroger pour 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 Speaker-Configuration, un client peut modifier la configuration de l’orateur d’un appareil audio en définissant la propriété KSPROPERTY_AUDIO_CHANNEL_CONFIG d’un nœud 3D (KSNODETYPE_3D_EFFECTS). Le paramètre de configuration de l’orateur est global, car il modifie la configuration de l’orateur pour tous les flux qui font partie de la combinaison que l’appareil lit par le biais des haut-parleurs. Selon la règle générale, une demande de propriété de nœud 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 une poignée de goupille au lieu d'une poignée de filtre. La poignée d'épingle désigne l’instance d’épingle 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 de 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 supporte l’une ou l’autre propriété doit fournir le gestionnaire de propriété via le membre Nœuds de PCFILTER_DESCRIPTOR (au lieu du membre Pins).