Jack Description, propriété

Article
06/15/2023

Dans Windows Vista et versions ultérieures, la propriété KSPROPERTY_JACK_DESCRIPTION décrit une prise audio ou un autre connecteur physique sur une carte audio. La valeur de la propriété décrit la couleur de la prise, l’emplacement physique de la prise, le type de connecteur et d’autres fonctionnalités de prise. L’objectif de ces informations est d’aider l’utilisateur à trouver la prise appropriée pour brancher un appareil de point de terminaison audio tel qu’un microphone, un casque ou des haut-parleurs. Pour plus d’informations, consultez Périphériques de point de terminaison audio.

Si un filtre KS sur une carte audio prend en charge la propriété KSPROPERTY_JACK_DESCRIPTION, le panneau de configuration multimédia Windows, Mmsys.cpl, affiche les informations de prise pour les broches de pont sur le filtre. Une broche de pont représente une connexion (généralement, une prise) à un appareil de point de terminaison audio. Bien que la valeur de la propriété contienne des informations sur une broche (ou plutôt la prise ou les prises qui sont associées à l’épingle), la propriété est une propriété du filtre, et non de la broche. Pour plus d’informations sur les broches de pont, consultez Graphiques de filtre audio. Pour plus d’informations sur les propriétés de filtre et les propriétés de broche, consultez Propriétés de filtre, d’épingle et de nœud.

Une application audio peut obtenir la valeur de propriété KSPROPERTY_JACK_DESCRIPTION pour un appareil de point de terminaison audio en appelant la méthode IKsJackDescription::GetJackDescription dans l’API DeviceTopology. Par exemple, une application peut utiliser les informations de prise pour aider l’utilisateur à distinguer un microphone branché à une prise XLR verte d’un microphone branché sur une prise XLR orange. Pour plus d’informations sur l’API DeviceTopology, consultez Topologies d’appareils.

Le pilote de classe Audio Microsoft HD construit automatiquement les valeurs de propriété KSPROPERTY_JACK_DESCRIPTION à partir des données qu’il lit à partir des registres de configuration de broche dans un codec AUDIO HD. Toutefois, n’importe quel pilote audio basé sur KS peut implémenter la prise en charge de cette propriété dans ses tables d’automatisation des filtres. Pour plus d’informations sur le pilote de classe Audio HD, consultez Audio HD et UAA. Pour plus d’informations sur les registres de configuration des broches, consultez le livre blanc Pin Configuration Guidelines for High Definition Audio Devices .

Un appareil de point de terminaison audio peut se connecter à une broche de pont via une ou plusieurs prises. Par exemple, un ensemble de haut-parleurs stéréo (à deux canaux) nécessite une prise, mais un ensemble de haut-parleurs à son surround 5.1 nécessite trois prises (en supposant que chaque prise gère deux des six canaux).

La description de chaque prise est contenue dans une structure KSJACK_DESCRIPTION . Par exemple, la valeur de propriété KSPROPERTY_JACK_DESCRIPTION d’un appareil de point de terminaison audio avec une prise contient une structure KSJACK_DESCRIPTION, mais la valeur de propriété d’un appareil de point de terminaison avec trois prises contient trois structures KSJACK_DESCRIPTION. Dans les deux cas, la ou les structures KSJACK_DESCRIPTION dans la valeur de propriété sont précédées d’une structure KSMULTIPLE_ITEM qui spécifie la taille de la valeur de propriété. Pour plus d’informations, consultez KSPROPERTY_JACK_DESCRIPTION.

Les informations jack sont particulièrement utiles pour aider les utilisateurs à faire la distinction entre les prises qui se connectent à une configuration de haut-parleur multicanal. L’exemple de code suivant montre un tableau de structures KSJACK_DESCRIPTION qu’un pilote audio utilise pour décrire les trois prises d’un ensemble de haut-parleurs surround 5.1 :

KSJACK_DESCRIPTION ar_5dot1_Jacks[] =
{
    // Jack 1
    {
        (SPEAKER_FRONT_LEFT | SPEAKER_FRONT_RIGHT), // ChannelMapping (L,R)
        RGB(0,255,0),       // Color (green)
        eConnType3Point5mm, // ConnectionType
        eGeoLocRear,        // GeoLocation
        eGenLocPrimaryBox,  // GenLocation
        ePortConnJack,      // PortConnection
        TRUE                // IsConnected
    },
    // Jack 2
    {
        (SPEAKER_FRONT_CENTER | SPEAKER_LOW_FREQUENCY), // (C,Sub)
        RGB(0,0,255),       // (red)
        eConnType3Point5mm,
        eGeoLocRear,
        eGenLocPrimaryBox,
        ePortConnJack,
        TRUE
    },
    // Jack 3
    {
        (SPEAKER_SIDE_LEFT | SPEAKER_SIDE_RIGHT),  // (SL,SR)
        RGB(0,255,255),     // (yellow)
        eConnType3Point5mm,
        eGeoLocRear,
        eGenLocPrimaryBox,
        ePortConnJack,
        TRUE
    }
};

Si le matériel audio peut détecter si l’appareil est branché, le pilote met à jour dynamiquement la valeur de ce membre pour indiquer si l’appareil est actuellement branché (TRUE) ou débranché (FALSE)

Dans l’exemple de code précédent, le membre IsConnected de chaque élément de tableau a la valeur TRUE pour indiquer que l’appareil de point de terminaison est branché à la prise. Toutefois, si le matériel n’a pas de détection de présence de prise, IsConnected doit toujours être défini sur TRUE, qu’il y ait un appareil branché sur la prise. Pour supprimer l’ambiguïté qui résulte de cette double signification de la valeur de retour TRUE , une application cliente peut appeler IKsJackDescription2::GetJackDescription2 pour lire l’indicateur JackCapabilities de la structure KSJACK_DESCRIPTION2 . Si cet indicateur a le JACKDESC2_PRESENCE_DETECT_CAPABILITY bit défini, il indique que le point de terminaison prend en charge la détection de la présence d’un jack. Dans ce cas, la valeur du membre IsConnected peut être interprétée comme une réflexion précise de la status d’insertion de la prise.

La macro RVB qui apparaît dans les structures précédentes est définie dans le fichier d’en-tête Wingdi.h du Kit de développement logiciel (SDK) Windows.

En outre, un tableau de descriptions de prises peut être utilisé pour montrer que deux prises ou plus sont fonctionnellement équivalentes l’une à l’autre. Dans l’exemple de code suivant, le pilote audio combine les descriptions d’une prise RCA jaune et d’une prise optique numérique noire dans un tableau pour indiquer à l’utilisateur que les deux prises portent le même signal :

KSJACK_DESCRIPTION ar_SPDIF_Jacks[] =
{
    // Jack 1
    {
        (SPEAKER_FRONT_LEFT | SPEAKER_FRONT_RIGHT), // ChannelMapping (L,R)
        RGB(0,255,255),         // Color (yellow)
        eConnTypeRCA,           // ConnectionType (RCA)
        eGeoLocRear,            // GeoLocation
 eGenLocPrimaryBox,   // GenLocation
        ePortConnJack,       // PortConnection
        TRUE                    // IsConnected
    },
    // Jack 2
    {
        (SPEAKER_FRONT_LEFT | SPEAKER_FRONT_RIGHT), // (L,R)
        RGB(0,0,0),             // (black)
        eConnTypeOptical,       // (optical)
        eGeoLocRear,
 eGenLocPrimaryBox,
        ePortConnJack,
        TRUE
    }
};

Dans l’exemple de code précédent, les valeurs des membres ChannelMapping dans les deux structures KSJACK_DESCRIPTION sont identiques.

L’exemple de pilote MSVAD « Simple » dans le WDK (dans l’exemple de répertoire Src\Audio\Msvad\Simple) peut être adapté pour prendre en charge la propriété KSPROPERTY_JACK_DESCRIPTION. Cet exemple de pilote est pratique pour démontrer l’utilisation de la propriété, car elle ne nécessite pas de matériel réel. Ainsi, il peut être installé sur n’importe quel ordinateur exécutant Windows. (Toutefois, seuls Windows Vista et les systèmes d’exploitation ultérieurs fournissent une prise en charge complète de la propriété KSPROPERTY_JACK_DESCRIPTION.) Pour plus d’informations sur cet exemple, consultez Exemples du Kit de pilotes Windows.

Le filtre de topologie de l’exemple MSVAD simple définit trois broches de pont. Ces broches sont répertoriées dans le tableau suivant.

ID d’épingle	Description
KSPIN_TOPO_SYNTHIN_SOURCE	Prise d’entrée MIDI
KSPIN_TOPO_MIC_SOURCE	Prise d’entrée du microphone
KSPIN_TOPO_LINEOUT_DEST	Prise de sortie du haut-parleur stéréo

Le reste de cette rubrique explique comment modifier l’exemple de pilote MSVAD simple pour fournir les informations de prise pour les trois broches de pont.

Tout d’abord, les informations de prise jack pour ces broches peuvent être spécifiées comme suit :

// Describe MIDI input jack (pin ID = KSPIN_TOPO_SYNTHIN_SOURCE).
static KSJACK_DESCRIPTION SynthIn_Jack[] =
{
    {
        0,                  // ChannelMapping
        RGB(255,255,0),    // Color (cyan)
 eConnType3Point5mm, // ConnectionType
        eGeoLocRear,        // GeoLocation
        eGenLocPrimaryBox,  // GenLocation
        ePortConnJack,      // PortConnection
        TRUE                // IsConnected
    }
};

// Describe microphone jack (pin ID = KSPIN_TOPO_MIC_SOURCE).
static KSJACK_DESCRIPTION MicIn_Jack[] =
{
    {
        0,
        RGB(0,128,255),   // (orange)
 eConnType3Point5mm,
        eGeoLocFront,
        eGenLocPrimaryBox,
        ePortConnJack,
        TRUE
    }
};

// Describe stereo speaker jack (pin ID = KSPIN_TOPO_LINEOUT_DEST).
static KSJACK_DESCRIPTION LineOut_Jack[] =
{
    {
        (SPEAKER_FRONT_LEFT | SPEAKER_FRONT_RIGHT), // ChannelMapping (L,R)
        RGB(0,255,0),       // (green)
 eConnType3Point5mm,
        eGeoLocRear,
        eGenLocPrimaryBox,
        ePortConnJack,
        TRUE
    }
};

L’exemple de code précédent définit les membres ChannelMapping pour les deux broches de capture sur 0. Seules les broches de rendu analogique doivent avoir des valeurs ChannelMapping différentes de zéro.

La principale modification apportée à l’exemple MSVAD simple consiste à ajouter le gestionnaire de propriétés suivant à l’implémentation du miniport de topologie dans l’exemple de fichier Mintopo.cpp :

#define ARRAY_LEN(a)  sizeof(a)/sizeof(a[0]);
#define MAXIMUM_VALID_PIN_ID  KSPIN_TOPO_WAVEIN_DEST

NTSTATUS
CMiniportTopology::PropertyHandlerJackDescription(
               IN PPCPROPERTY_REQUEST PropertyRequest)
{
    PAGED_CODE();

    ASSERT(PropertyRequest);

    DPF_ENTER(("[PropertyHandlerJackDescription]"));

    NTSTATUS ntStatus = STATUS_INVALID_DEVICE_REQUEST;
    ULONG nPinId = (ULONG)-1;

    if (PropertyRequest->InstanceSize >= sizeof(ULONG))
    {
        nPinId = *((PULONG)(PropertyRequest->Instance));

        if (nPinId > MAXIMUM_VALID_PIN_ID)
        {
            ntStatus = STATUS_INVALID_PARAMETER;
        }
        else if (PropertyRequest->Verb & KSPROPERTY_TYPE_BASICSUPPORT)
        {
            ntStatus = PropertyHandler_BasicSupport(
                            PropertyRequest,
                            KSPROPERTY_TYPE_BASICSUPPORT | KSPROPERTY_TYPE_GET,
                            VT_ILLEGAL);
        }
        else
        {
            PKSJACK_DESCRIPTION pJack = NULL;
            ULONG cJacks = 0;

            switch (nPinId)
            {
            case KSPIN_TOPO_SYNTHIN_SOURCE:
                pJack = SynthIn_Jack;
                cJacks = ARRAY_LEN(SynthIn_Jack);
                break;
            case KSPIN_TOPO_MIC_SOURCE:
                pJack = MicIn_Jack;
                cJacks = ARRAY_LEN(MicIn_Jack);
                break;
            case KSPIN_TOPO_LINEOUT_DEST:
                pJack = LineOut_Jack;
                cJacks = ARRAY_LEN(LineOut_Jack);
                break;
            default:
                break;
            }

            ULONG cbNeeded = sizeof(KSMULTIPLE_ITEM) +
                             sizeof(KSJACK_DESCRIPTION) * cJacks;

            if (PropertyRequest->ValueSize == 0)
            {
                PropertyRequest->ValueSize = cbNeeded;
                ntStatus = STATUS_BUFFER_OVERFLOW;
            }
            else if (PropertyRequest->ValueSize < cbNeeded)
            {
                ntStatus = STATUS_BUFFER_TOO_SMALL;
            }
            else if (PropertyRequest->Verb & KSPROPERTY_TYPE_GET)
            {
                PKSMULTIPLE_ITEM pMI = (PKSMULTIPLE_ITEM)PropertyRequest->Value;

                pMI->Size = cbNeeded;
                pMI->Count = cJacks;

                // Copy jack description structure into Value buffer.
                // RtlCopyMemory correctly handles the case Length=0.
                PKSJACK_DESCRIPTION pDesc = (PKSJACK_DESCRIPTION)(pMI + 1);

                RtlCopyMemory(pDesc, pJack, pMI->Size * pMI->Count);

                ntStatus = STATUS_SUCCESS;
            }
        }
    }

    return ntStatus;
}

NTSTATUS
PropertyHandler_TopoFilter(IN PPCPROPERTY_REQUEST PropertyRequest)
{
    PAGED_CODE();

    ASSERT(PropertyRequest);

    DPF_ENTER(("[PropertyHandler_TopoFilter]"));

    // PropertyRequest structure is filled by PortCls.
    // MajorTarget is a pointer to miniport object for miniports.
    //
    NTSTATUS ntStatus = STATUS_INVALID_DEVICE_REQUEST;
    PCMiniportTopology pMiniport = (PCMiniportTopology)PropertyRequest->MajorTarget;

    if (IsEqualGUIDAligned(*PropertyRequest->PropertyItem->Set, KSPROPSETID_Jack) &&
        (PropertyRequest->PropertyItem->Id == KSPROPERTY_JACK_DESCRIPTION))
    {
        ntStatus = pMiniport->PropertyHandlerJackDescription(PropertyRequest);
    }

    return ntStatus;
}

L’exemple de code précédent fait référence aux trois variables KSJACK_DESCRIPTION ( SynthIn_Jack, MicIn_Jack et LineOut_Jack ) qui ont été définies précédemment. Si le client interroge le filtre pour la description de la prise d’une broche valide, mais qui n’est pas une broche de pont (et n’a donc pas de description de prise), la requête réussit (avec status code STATUS_SUCCESS), mais le gestionnaire de propriétés retourne une description de prise vide composée d’une structure KSMULTIPLE_ITEM et rien d’autre. Si le client spécifie un ID d’épingle non valide (qui identifie un code confidentiel inexistant), le gestionnaire retourne status code STATUS_INVALID_PARAMETER.

Deux modifications supplémentaires à l’exemple MSVAD simple sont nécessaires pour prendre en charge la propriété KSPROPERTY_JACK_DESCRIPTION. Ces règles sont les suivantes :

Ajoutez la déclaration de la méthode PropertyHandlerJackDescription dans l’exemple de code précédent à la définition de classe CMiniportTopology dans le fichier d’en-tête Mintopo.h.
Implémentez une table Automation pour le filtre de topologie et chargez l’adresse de cette table dans le membre AutomationTable de la structure PCFILTER_DESCRIPTOR dans le fichier d’en-tête Toptable.h. Cette structure est nommée MiniportFilterDescriptor.

Pour implémenter la table Automation pour le filtre, insérez le code suivant dans le fichier d’en-tête Toptable.h (avant la définition de MiniportFilterDescriptor) :

static PCPROPERTY_ITEM PropertiesTopoFilter[] =
{
    {
        &KSPROPSETID_Jack,
        KSPROPERTY_JACK_DESCRIPTION,
        KSPROPERTY_TYPE_GET | KSPROPERTY_TYPE_BASICSUPPORT,
        PropertyHandler_TopoFilter
    }
};

DEFINE_PCAUTOMATION_TABLE_PROP(AutomationTopoFilter, PropertiesTopoFilter);

Dans l’exemple de code précédent, le membre Handler de la structure PCPROPERTY_ITEM contient un pointeur de fonction vers le gestionnaire de propriétés qui a été ajouté à Mintopo.cpp à une étape précédente. Pour rendre le gestionnaire de propriétés accessible à partir du fichier d’en-tête, insérez une déclaration de fonction extern pour PropertyHandler_TopoFilter au début du fichier d’en-tête.

Pour plus d’informations sur la propriété description de la prise, consultez Descriptions des jacks pour les sous-appareils audio dynamiques.

Partager via

Jack Description, propriété

Commentaires

Ressources supplémentaires