Interface IKsJackDescription (devicetopology.h)

Article
08/23/2023

L’interface IKsJackDescription fournit des informations sur les prises ou les connecteurs internes qui fournissent une connexion physique entre un appareil sur une carte audio et un périphérique de point de terminaison externe ou interne (par exemple, un microphone ou un lecteur CD). Le client obtient une référence à l’interface IKsJackDescription d’un composant en appelant la méthode IPart::Activate avec refiid de paramètre défini sur REFIID IID_IKsJackDescription. L’appel à IPart::Activate réussit uniquement si le composant prend en charge l’interface IKsJackDescription . Seul un objet de partie qui représente un connecteur avec un type de connexion Physical_External ou Physical_Internal prend en charge cette interface.

La plupart des pilotes d’adaptateur audio Windows prennent en charge le modèle de pilote Windows (WDM) et utilisent les propriétés KS (kernel-streaming) pour représenter les paramètres de description du matériel dans les connecteurs (appelés broches KS). L’interface IKsJackDescription fournit un accès pratique à la propriété KSPROPERTY_JACK_DESCRIPTION d’un connecteur à un appareil de point de terminaison. Pour plus d’informations sur les propriétés KS et les broches KS, consultez la documentation windows DDK.

Héritage

L’interface IKsJackDescription hérite de l’interface IUnknown. IKsJackDescription a également les types de membres suivants :

Méthodes

L’interface IKsJackDescription a ces méthodes.


IKsJackDescription::GetJackCount La méthode GetJackCount obtient le nombre de prises nécessaires pour se connecter à un périphérique de point de terminaison audio.
IKsJackDescription::GetJackDescription La méthode GetJackDescription obtient une description d’une prise audio.

Notes

Si un appareil de point de terminaison audio prend en charge l’interface IKsJackDescription , le panneau de configuration multimédia Windows, Mmsys.cpl, affiche les informations de prise. Pour afficher les informations de prise jack, procédez comme suit :

Pour exécuter Mmsys.cpl, ouvrez une fenêtre d’invite de commandes et entrez la commande suivante :
mmsys.cplde contrôle

Vous pouvez également exécuter Mmsys.cpl en cliquant avec le bouton droit sur l’icône du haut-parleur dans la zone de notification, qui se trouve sur le côté droit de la barre des tâches, puis en sélectionnant Périphériques de lecture ou Périphériques d’enregistrement.
Une fois la fenêtre Mmsys.cpl ouverte, sélectionnez un appareil dans la liste des périphériques de lecture ou dans la liste des périphériques d’enregistrement, puis cliquez sur Propriétés.
Lorsque la fenêtre propriétés s’ouvre, cliquez sur Général. Si la page de propriétés sélectionnée affiche les informations de prise jack pour l’appareil, l’appareil prend en charge l’interface IKsJackDescription . Si la page de propriétés affiche le texte « Aucune information de prise jack n’est disponible », l’appareil ne prend pas en charge l’interface.

L’exemple de code suivant montre comment obtenir l’interface IKsJackDescription pour un appareil de point de terminaison audio :

//-----------------------------------------------------------
// Get the IKsJackDescription interface that describes the
// audio jack or jacks that the endpoint device plugs into.
//-----------------------------------------------------------
#define EXIT_ON_ERROR(hres)  \
              if (FAILED(hres)) { goto Exit; }
#define SAFE_RELEASE(punk)  \
              if ((punk) != NULL)  \
                { (punk)->Release(); (punk) = NULL; }

HRESULT GetJackInfo(IMMDevice *pDevice,
                    IKsJackDescription **ppJackDesc)
{
    HRESULT hr = S_OK;
    IDeviceTopology *pDeviceTopology = NULL;
    IConnector *pConnFrom = NULL;
    IConnector *pConnTo = NULL;
    IPart *pPart = NULL;
    IKsJackDescription *pJackDesc = NULL;

    if (NULL != ppJackDesc)
    {
        *ppJackDesc = NULL;
    }
    if (NULL == pDevice || NULL == ppJackDesc)
    {
        return E_POINTER;
    }

    // Get the endpoint device's IDeviceTopology interface.
    hr = pDevice->Activate(__uuidof(IDeviceTopology), CLSCTX_ALL,
                           NULL, (void**)&pDeviceTopology);
    EXIT_ON_ERROR(hr)

    // The device topology for an endpoint device always
    // contains just one connector (connector number 0).
    hr = pDeviceTopology->GetConnector(0, &pConnFrom);
    EXIT_ON_ERROR(hr)

    // Step across the connection to the jack on the adapter.
    hr = pConnFrom->GetConnectedTo(&pConnTo);
    if (HRESULT_FROM_WIN32(ERROR_PATH_NOT_FOUND) == hr)
    {
        // The adapter device is not currently active.
        hr = E_NOINTERFACE;
    }
    EXIT_ON_ERROR(hr)

    // Get the connector's IPart interface.
    hr = pConnTo->QueryInterface(__uuidof(IPart), (void**)&pPart);
    EXIT_ON_ERROR(hr)

    // Activate the connector's IKsJackDescription interface.
    hr = pPart->Activate(CLSCTX_INPROC_SERVER,
                         __uuidof(IKsJackDescription), (void**)&pJackDesc);
    EXIT_ON_ERROR(hr)

    *ppJackDesc = pJackDesc;

Exit:
    SAFE_RELEASE(pDeviceTopology)
    SAFE_RELEASE(pConnFrom)
    SAFE_RELEASE(pConnTo)
    SAFE_RELEASE(pPart)
    return hr;
}

Dans l’exemple de code précédent, la fonction GetJackInfo prend deux paramètres. Le paramètre d’entrée pDevice pointe vers l’interface IMMDevice d’un appareil de point de terminaison. Le paramètre de sortie ppJackDesc pointe vers une valeur de pointeur dans laquelle la fonction écrit l’adresse de l’interface IKsJackDescription correspondante, si l’interface existe. Si l’interface n’existe pas, la fonction écrit NULL dans *ppJackDesc et retourne le code d’erreur E_NOINTERFACE.

Dans l’exemple de code précédent, l’appel à IMMDevice::Activate récupère l’interface IDeviceTopology de l’appareil de point de terminaison. La topologie d’appareil d’un appareil de point de terminaison contient un seul connecteur (numéro de connecteur 0) qui se connecte à l’appareil adaptateur. De l’autre côté de cette connexion, le connecteur sur le périphérique adaptateur représente la ou les prises audio auxquelles le périphérique de point de terminaison se branche. L’appel à la méthode IDeviceTopology::GetConnector récupère l’interface IConnector du connecteur sur l’appareil de point de terminaison, et l’appel de méthode IConnector::GetConnectedTo récupère le connecteur correspondant sur l’appareil adaptateur. Enfin, l’appel de méthode IConnector::QueryInterface récupère l’interface IPart du connecteur du périphérique de l’adaptateur, et l’appel de méthode IPart::Activate récupère l’interface IKsJackDescription du connecteur, le cas échéant.

Spécifications


Client minimal pris en charge	Windows Vista [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2008 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	devicetopology.h

Voir aussi

Interfaces audio principales

DeviceTopology API

IPart::Activate

Partager via