Gestionnaires de propriétés audio
Un pilote miniport stocke des informations sur chaque propriété qu’il prend en charge dans une structure PCPROPERTY_ITEM . Cette structure contient les informations suivantes sur la propriété :
GUID du jeu de propriétés et ID de propriété (ou index)
Pointeur de fonction vers la routine de gestionnaire pour la propriété
Indicateurs spécifiant les opérations de propriété que le gestionnaire prend en charge
Le pilote miniport fournit une table Automation (spécifiée par une structure PCAUTOMATION_TABLE ) pour le filtre. Le pilote fournit des tables d’automatisation supplémentaires pour les types de broches et de nœuds du filtre : chaque type de broche ou de nœud a sa propre table. Chaque table Automation contient un tableau (éventuellement vide) de structures PCPROPERTY_ITEM, et chacune de ces structures décrit une propriété du filtre, de l’épingle ou du nœud. Lorsqu’un client envoie une demande de propriété à un filtre, une broche ou un nœud, le pilote de port achemine la demande via la table Automation vers le gestionnaire de propriétés approprié.
Un pilote miniport peut spécifier une routine de gestionnaire de propriétés unique pour chaque propriété. Toutefois, si un pilote gère plusieurs propriétés similaires, celles-ci peuvent parfois être regroupées en une seule routine de gestionnaire pour plus de commodité. Le fait de fournir un gestionnaire unique pour chaque propriété ou de consolider plusieurs propriétés en un seul gestionnaire est une décision d’implémentation qui doit être prise par l’enregistreur de pilotes et doit être transparente pour les clients qui envoient des demandes de propriété.
Un client en mode utilisateur peut envoyer une demande de propriété get, set ou de support de base en appelant la fonction Microsoft Win32 DeviceIoControl avec le paramètre dwIoControlCode défini sur IOCTL_KS_PROPERTY. Le système d’exploitation convertit cet appel en IRP, qu’il distribue au pilote de classe. Pour plus d’informations, consultez Propriétés KS.
Lorsqu’un client envoie une demande de propriété KS (c’est-à-dire un IRP de contrôle d’E/S IOCTL_KS_PROPERTY) à un handle de filtre ou à une poignée de broche, le pilote système KS (Ks.sys) remet la demande au pilote de port pour l’objet de filtre ou l’objet pin. Si le pilote miniport fournit un gestionnaire pour la propriété, le pilote de port transfère la demande au gestionnaire. Avant de transférer la demande, le pilote de port convertit les informations de la demande de propriété au format spécifié par la structure PCPROPERTY_REQUEST . Le pilote de port transmet cette structure au gestionnaire du pilote miniport.
Le membre MajorTarget de PCPROPERTY_REQUEST pointe vers l’interface du pilote miniport principal pour le périphérique audio. Par exemple, pour un appareil WavePci, il s’agit d’un pointeur vers l’interface IMiniportWavePci de l’objet de pilote miniport.
Dans le cas d’une demande de propriété KS envoyée à un handle de filtre, le membre MinorTarget de PCPROPERTY_REQUEST a la valeur NULL. Dans le cas d’une requête envoyée à une poignée de broche, MinorTarget pointe vers l’interface de flux pour la broche. Par exemple, pour un appareil WavePci, il s’agit d’un pointeur vers l’interface IMiniportWavePciStream de l’objet de flux.
Les membres Instance et Valeur de PCPROPERTY_REQUEST pointent respectivement vers les mémoires tampons d’entrée et de sortie de la demande de propriété KS. (Les mémoires tampons sont spécifiées par les paramètres lpInBuffer et lpOutBuffer de la fonction DeviceIoControl.) Ces mémoires tampons contiennent respectivement le descripteur de propriété (instance données) et la valeur de propriété (données d’opération), comme décrit dans Jeux de propriétés de pilotes audio. Le membre Value pointe vers le début de la mémoire tampon de sortie, mais le pointeur d’instance est décalé à partir du début de la mémoire tampon d’entrée.
La mémoire tampon d’entrée commence par une structure KSPROPERTY ou KSNODEPROPERTY . Le pilote de port copie les informations de cette structure dans les membres Node, PropertyItem et Verb de la structure PCPROPERTY_REQUEST. Si des données suivent la structure KSPROPERTY ou KSNODEPROPERTY dans la mémoire tampon, le pilote de port charge le membre de l’instance avec un pointeur vers ces données. Sinon, il définit Instance sur NULL.
Si la mémoire tampon d’entrée commence par une structure KSPROPERTY, qui ne contient aucune information sur le nœud, le pilote de port définit le membre nœud de la structure PCPROPERTY_REQUEST sur ULONG(-1). Dans ce cas, le pilote de port appelle le gestionnaire approprié à partir de la table Automation du pilote miniport pour le filtre ou la broche, selon que la cible pour la demande de propriété est spécifiée par une poignée de filtre ou une poignée de broche. (Si la table ne spécifie pas de gestionnaire pour la propriété, le pilote de port gère plutôt la requête.)
Si la mémoire tampon d’entrée commence par une structure KSNODEPROPERTY, le pilote de port copie l’ID de nœud de cette structure dans le membre node de la structure PCPROPERTY_REQUEST et appelle le gestionnaire approprié à partir de la table Automation du pilote miniport pour le nœud. (Là encore, si la table ne spécifie pas de gestionnaire pour la propriété, le pilote de port gère plutôt la requête.)
Le pilote de port vérifie le bit KSPROPERTY_TYPE_TOPOLOGY dans les indicateurs d’opération de la demande de propriété pour déterminer laquelle des deux structures, KSPROPERTY ou KSNODEPROPERTY, réside au début de la mémoire tampon d’entrée :
Si ce bit est défini, la demande concerne une propriété de nœud et la mémoire tampon d’entrée commence par une structure KSNODEPROPERTY.
Sinon, la mémoire tampon d’entrée commence par une structure KSPROPERTY.
Pour plus d’informations sur KSPROPERTY_TYPE_TOPOLOGY, consultez KSPROPERTY.
Les membres InstanceSize et ValueSize de la structure PCPROPERTY_REQUEST spécifient les tailles des mémoires tampons pointées par les membres Instance et Value . ValueSize est égal à la taille de la mémoire tampon de sortie de la demande de propriété, mais InstanceSize correspond à la taille des données qui suivent la structure KSPROPERTY ou KSNODEPROPERTY dans la mémoire tampon d’entrée. Autrement dit, InstanceSize est la taille de la mémoire tampon d’entrée moins la taille de la structure KSPROPERTY ou KSNODEPROPERTY. Si aucune donnée supplémentaire ne suit cette structure, le pilote de port définit InstanceSize sur zéro (et Instance sur NULL).
Par exemple, si le client spécifie une structure KSNODEPROPERTY_AUDIO_CHANNEL comme instance données dans la mémoire tampon d’entrée, le pilote de port transmet au gestionnaire une structure PCPROPERTY_REQUEST dont le membre d’instance pointe vers le membre Channel de la structure KSNODEPROPERTY_AUDIO_CHANNEL et dont le membre InstanceSize contient la valeur
sizeof(KSNODEPROPERTY_AUDIO_CHANNEL) - sizeof(KSNODEPROPERTY)
Avant d’envoyer une demande get-property pour récupérer une valeur de propriété, le client doit allouer une mémoire tampon de sortie dans laquelle le gestionnaire de propriétés du pilote miniport peut écrire la valeur de la propriété. Pour certaines propriétés, la taille de la mémoire tampon de sortie dépend de l’appareil et le client doit interroger le gestionnaire de propriétés pour connaître la taille de mémoire tampon requise. Dans ce cas, le client envoie une demande de propriété initiale avec un pointeur de mémoire tampon de sortie nullptr et une longueur de mémoire tampon de sortie égale à zéro. Le gestionnaire répond en retournant la taille de mémoire tampon requise avec le code status STATUS_BUFFER_OVERFLOW. Le client récupère ensuite la valeur de la propriété en allouant une mémoire tampon de sortie de la taille spécifiée et en envoyant cette mémoire tampon dans une deuxième requête get-property.
Si la taille de mémoire tampon spécifiée est trop petite pour recevoir l’une des informations demandées, la méthode retourne STATUS_BUFFER_TOO_SMALL.
Dans certains cas, les pilotes de port PortCls retournent STATUS_BUFFER_TOO_SMALL au lieu de STATUS_BUFFER_OVERFLOW en réponse à une demande de propriété avec une adresse et une taille de mémoire tampon de sortie non nulle. Dans ce cas, la taille de mémoire tampon requise n’est pas retournée.
Pour plus d’informations, consultez Utilisation des valeurs NTSTATUS et les billets de blog suivants :