Circuits ACX

Article
06/27/2024

Cette rubrique traite des circuits ACX. Pour une vue d'ensemble de l'ACX et une liste de termes ACX, voir Vue d'ensemble des extensions de la classe audio ACX.

Comme décrit dans Résumé des objets ACX, un objet AcxCircuit représente un chemin audio partiel ou complet vers un appareil audio perçu par l'utilisateur (haut-parleurs, micro, etc.). Un AcxCircuit possède au moins une broche d'entrée et une broche de sortie (ACXPIN), et peut agréger un ou plusieurs objets de type AcxElements. Le circuit représente un point de terminaison existant et ses capacités.

Le flux ACX est un composant pilote créé pour représenter un flux audio, créé par un circuit. Le flux est composé d'une liste d'éléments créés sur la base des éléments du circuit parent. Un circuit de flux est un circuit dans une architecture multi-pile (chemin audio partiel) qui est directement interfacé avec un service de diffusion en continu en mode utilisateur supérieur. Un circuit de base est un circuit dans une architecture multi-pile (chemin audio partiel) qui donne l'identité de l'appareil de terminaison audio.

Identification des circuits ACX

Chaque circuit ACX possède un identifiant de circuit. Le modèle ACX définit les éléments suivants :

Name (str), identifie de manière unique ce type d'appareil audio du circuit. Il est utilisé pour localiser le réglage de l'INF, et il fait partie du lien symbolique utilisé pour accéder à ce circuit à partir d'un appareil distant. Exemple : "Render0", "Render1" ou "Capture0".
Lien symbolique. Un lien symbolique est associé à tous les circuits exposés. Les clients utilisent ce lien symbolique pour ouvrir un chemin de communication avec l'appareil/le circuit.
ID du composant du circuit (guid). Identifie de manière unique l'instance du circuit (spécifique au fournisseur). Il ne peut pas être utilisé dans les liaisons AcxCircuitTemplate si l'URI du circuit a été spécifié.
URI du composant du circuit (str). Identifie de manière unique l'instance du circuit (spécifique au fournisseur). Il ne peut pas être utilisé dans les liaisons AcxCircuitTemplate si l'ID du circuit a été spécifié.
ID du composant de l'usine de circuits (guid). Identifie de manière unique l'instance de l'usine de circuits (spécifique au fournisseur). Il ne peut pas être utilisé dans les liaisons AcxCircuitTemplate si l'URI de l'usine de circuits a été spécifié.
URI du composant de l'usine de circuits (str). Identifie de manière unique l'instance de l'usine de circuits (spécifique au fournisseur). Il ne peut pas être utilisé dans les liaisons AcxCircuitTemplate si l'ID de l'usine de circuits a été spécifié.

AcxCircuitCreate

La fonction AcxCircuitCreate est utilisée pour créer un ACXCIRCUIT. Une structure opaque ACXCIRCUIT_INIT utilisée par la fonction AcxCircuitCreate. AcxCircuitInitAllocate est utilisée pour initialiser la structure ACXCIRCUIT_INIT.

AcxFactoryCircuit

Un pilote ACX peut également créer des objets AcxFactoryCircuit (fournisseurs de circuits) pendant la séquence de mise sous tension à l'aide de la fonction AcxFactoryCircuitCreate et de la fonction AcxDeviceAddFactoryCircuit.

Composition des circuits ACX

ACX relie les circuits entre eux jusqu'à ce qu'ils forment un chemin audio complet. ACX utilise des liaisons audio pour connecter les circuits audio entre eux. Pour plus d'informations, consultez la section Composition multicircuit ACX.

Création dynamique de circuits ACX (à tout moment)

ACX peut créer un circuit dynamique à la demande. Pour ce faire, le pilote alloue une structure WDFDEVICE_INIT en appelant WdfPdoInitAllocate. Le pilote spécifie ensuite tous les rappels PnP/power qu’il souhaite recevoir et crée le périphérique. Le pilote instancie le nouvel appareil/circuit en appelant AcxDeviceAddCircuitDevice. Pour plus d'informations, voir Enumération des appareils ACX.

Suppression dynamique du circuit ACX

Le pilote invoque AcxDeviceRemoveCircuitDevice pour retirer le périphérique audio de la liste des périphériques. Cette opération déclenche la séquence de mise hors tension de l'appareil/du circuit ACX. L'appareil/le circuit est supprimé de manière asynchrone. Pour plus d'informations, voir Enumération des appareils ACX.

AcxDeviceRemoveCircuit et AcxDeviceDetachCircuit

Il existe deux méthodes courantes pour gérer la fin d'un circuit. AcxDeviceDetachCircuit ou AcxDeviceRemoveCircuit.

Si l'appelant invoque AcxDeviceDetachCircuit, il ne doit pas appeler AcxDeviceRemoveCircuit. Si le pilote appelant souhaite supprimer le circuit après AcxDeviceDetachCircuit, il doit utiliser WdfObjectDelete.

En appelant AcxDeviceRemoveCircuit, le pilote appelant demande à ACX de supprimer ce circuit et de le retirer/supprimer de l'appareil. Dans ce cas, il n'est pas nécessaire d'appeler WdfObjectDelete sur le circuit.

En résumé, AcxDeviceDetachCircuit signifie que le pilote possède la gestion de la durée de vie des objets circuit, AcxDeviceRemoveCircuit signifie que le circuit sera retiré et supprimé.

Pour des informations générales sur la gestion de la durée de vie des objets WDF, voir Cycle de vie des objets du cadre.

AcxDeviceRemoveCircuitDevice

Contrairement à la terminaison de circuit discutée ci-dessus, AcxDeviceRemoveCircuitDevice est utilisé par le pilote audio pour supprimer un point de terminaison audio existant et peut être appelé à tout moment au cours du cycle de vie du pilote.

Les pilotes peuvent également choisir de toujours détruire et recréer les appareils audio lors du rééquilibrage. Il s'agit du même scénario que ci-dessus lorsque l'appareil détecte que les nouveaux paramètres ne sont pas compatibles avec les anciens.

La suppression du circuit doit être effectuée dans les rappels EvtDevicePrepareHardware/EvtDeviceReleaseHardware, et le nouveau circuit est recréé dans EvtDevicePrepareHardware. Le pilote supprime un circuit en le désenregistrant (à l'aide de AcxDeviceRemoveCircuit).

Fonction de rappel EvtAcxCircuitReleaseHardware (EVT_ACX_CIRCUIT_RELEASE_HARDWARE)

Si un pilote a enregistré une fonction de rappel EvtAcxCircuitReleaseHardware, le framework l'appelle lors des transitions suivantes :

Rééquilibrage des ressources
Suppression ordonnée
Suppression surprise

La structure ACX appelle la fonction de rappel EvtAcxCircuitReleaseHardware après que la structure WDF a cessé d'envoyer des requêtes d'E/S à l'appareil, que toutes les interruptions affectées à l'appareil ont été désactivées et déconnectées, et que l'appareil a été mis hors tension.

La structure ACX appelle la fonction de rappel EvtAcxCircuitReleaseHardware avant que la structure WDF n'appelle la fonction de rappel EvtDeviceReleaseHardware du pilote.

Lorsque le cadre appelle la fonction EvtAcxCircuitReleaseHardware, le PDO de l'appareil existe toujours et peut être interrogé pour obtenir des informations sur l'appareil qui sont disponibles à l'état hors tension, par exemple l'état de la configuration PCI.

En outre, les ressources matérielles traduites que le cadre fournit à EvtDeviceReleaseHardware sont toujours affectées à l'appareil. L'objectif principal de cette fonction de rappel est de libérer ces ressources, et en particulier de démapper toutes les ressources mémoire que la fonction de rappel EvtAcxCircuitPrepareHardware du pilote a mappées. Le pilote peut également utiliser cette fonction de rappel pour effectuer toute autre activité de gestion de l'ACXCIRCUIT qui pourrait être nécessaire dans l'état hors tension. En général, toutes les autres opérations d'arrêt du matériel doivent être effectuées dans la fonction de rappel EvtDeviceD0Exit du pilote.

Le framework ACX appelle toujours la fonction de rappel EvtAcxCircuitReleaseHardware du pilote si la fonction de rappel EvtAcxCircuitPrepareHardware du pilote a été appelée, à moins que la fonction EvtAcxCircuitPrepareHardware n'ait renvoyé un code d'échec.

Pour plus d'informations sur les ressources matérielles, voir Introduction aux ressources matérielles.

Fonction de rappel EvtAcxFactoryCircuitReleaseHardware (EVT_ACX_FACTORY_CIRCUIT_RELEASE_HARDWARE)

Lorsque le cadre appelle la fonction EvtAcxFactoryCircuitReleaseHardware, le PDO de l'appareil existe toujours et peut être interrogé pour obtenir des informations sur l'appareil qui sont disponibles dans l'état hors tension, par exemple l'état de la configuration PCI.

Le cadre ACX appelle toujours la fonction de rappel EvtAcxFactoryCircuitReleaseHardware du pilote si la fonction de rappel EvtAcxFactoryCircuitPrepareHardware du pilote a été appelée, à moins que la fonction EvtAcxFactoryCircuitPrepareHardware n'ait renvoyé un code d'échec.

Pour plus d’informations sur la gestion des objets WDF et de circuit, veuillez consulter la section ACX WDF Driver Lifetime Management.