Jack Description, proprietà

Articolo
06/14/2023

In Windows Vista e versioni successive, la proprietà KSPROPERTY_JACK_DESCRIPTION descrive un jack audio o un altro connettore fisico in una scheda audio. Il valore della proprietà descrive il colore del jack, la posizione fisica del jack, il tipo di connettore e altre funzionalità jack. Lo scopo di queste informazioni è aiutare l'utente a trovare il jack corretto per la connessione in un dispositivo endpoint audio, ad esempio un microfono, cuffie o altoparlanti. Per altre informazioni, vedere Dispositivi endpoint audio.

Se un filtro KS su una scheda audio supporta la proprietà KSPROPERTY_JACK_DESCRIPTION, il pannello di controllo multimediale di Windows, Mmsys.cpl, visualizza le informazioni sul jack per i pin del ponte sul filtro. Un pin bridge rappresenta una connessione (in genere, un jack) a un dispositivo endpoint audio. Anche se il valore della proprietà contiene informazioni su un pin (o piuttosto, il jack o i jack associati al pin), la proprietà è una proprietà del filtro, non del pin. Per altre informazioni sui pin bridge, vedere Grafici filtro audio. Per altre informazioni sulle proprietà del filtro e sulle proprietà pin, vedere Filtro, Pin e Proprietà nodo.

Un'applicazione audio può ottenere il valore della proprietà KSPROPERTY_JACK_DESCRIPTION per un dispositivo endpoint audio chiamando il metodo IKsJackDescription::GetJackDescription nell'API DeviceTopology. Ad esempio, un'applicazione può usare le informazioni sul jack per aiutare l'utente a distinguere un microfono collegato a un jack XLR verde da un microfono collegato a un jack XLR arancione. Per altre informazioni sull'API DeviceTopology, vedere Topologie di dispositivo.

Il driver di classe Audio Microsoft HD costruisce automaticamente i valori delle proprietà KSPROPERTY_JACK_DESCRIPTION dai dati letti dai registri di configurazione del pin in un codec audio HD. Tuttavia, qualsiasi driver audio basato su KS può implementare il supporto per questa proprietà nelle tabelle di automazione dei filtri. Per altre informazioni sul driver di classe HD Audio, vedere Audio HD e UAA. Per altre informazioni sui registri di configurazione dei pin, vedere il white paper Pin Configuration Guidelines for High Definition Audio Devices (Linee guida per la configurazione dei dispositivi audio ad alta definizione ).

Un dispositivo endpoint audio può connettersi a un pin bridge tramite uno o più jack. Ad esempio, un set di altoparlanti stereo (due canali) richiede un jack, ma un set di altoparlanti surround-5.1 richiede tre jack (presupponendo che ogni jack gestisce due dei sei canali).

La descrizione per ogni jack è contenuta in una struttura KSJACK_DESCRIPTION . Ad esempio, il valore della proprietà KSPROPERTY_JACK_DESCRIPTION per un dispositivo endpoint audio con un jack contiene una struttura KSJACK_DESCRIPTION, ma il valore della proprietà per un dispositivo endpoint con tre jack contiene tre strutture KSJACK_DESCRIPTION. In entrambi i casi, la struttura KSJACK_DESCRIPTION o le strutture nel valore della proprietà sono precedute da una struttura KSMULTIPLE_ITEM che specifica le dimensioni del valore della proprietà. Per altre informazioni, vedere KSPROPERTY_JACK_DESCRIPTION.

Le informazioni jack sono particolarmente utili per aiutare gli utenti a distinguere tra i jack che si connettono a una configurazione altoparlante multicanale. Nell'esempio di codice seguente viene illustrata una matrice di strutture KSJACK_DESCRIPTION usate da un driver audio per descrivere i tre jack per un set di altoparlanti 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
    }
};

Se l'hardware audio può rilevare se il dispositivo è collegato, il driver aggiorna dinamicamente il valore di questo membro per indicare se il dispositivo è attualmente collegato (TRUE) o scollegato (FALSE)

Nell'esempio di codice precedente, il membro IsConnected in ogni elemento della matrice è impostato su TRUE per indicare che il dispositivo endpoint è collegato al jack. Tuttavia, se l'hardware non dispone del rilevamento della presenza jack, IsConnected deve sempre essere impostato su TRUE, se è presente un dispositivo collegato al jack. Per rimuovere l'ambiguità risultante da questo doppio significato del valore restituito TRUE , un'applicazione client può chiamare IKsJackDescription2::GetJackDescription2 per leggere il flag JackCapabilities della struttura KSJACK_DESCRIPTION2 . Se questo flag ha il set di bit JACKDESC2_PRESENCE_DETECT_CAPABILITY, indica che l'endpoint supporta effettivamente il rilevamento della presenza jack. In tal caso, il valore del membro IsConnected può essere interpretato come una riflessione accurata dello stato di inserimento del jack.

La macro RGB visualizzata nelle strutture precedenti è definita nel file di intestazione Wingdi.h in Windows SDK.

Inoltre, una matrice di descrizioni jack può essere usata per mostrare che due o più jack sono funzionalmente equivalenti tra loro. Nell'esempio di codice seguente, il driver audio combina le descrizioni del jack per un jack RCA giallo e per un jack ottico digitale nero in una matrice per indicare all'utente che i due jack portano lo stesso segnale:

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
    }
};

Nell'esempio di codice precedente, i valori dei membri ChannelMapping nelle due strutture KSJACK_DESCRIPTION sono identici.

Il driver di esempio MSVAD "Simple" in WDK (nella directory di esempio Src\Audio\Msvad\Simple) può essere adattato per supportare la proprietà KSPROPERTY_JACK_DESCRIPTION. Questo driver di esempio è pratico per dimostrare l'uso della proprietà perché non richiede hardware effettivo. Può quindi essere installato in qualsiasi computer che esegue Windows. Tuttavia, solo Windows Vista e sistemi operativi successivi forniscono supporto completo per la proprietà KSPROPERTY_JACK_DESCRIPTION. Per altre informazioni su questo esempio, vedere Esempi di Windows Driver Kit.

Il filtro della topologia per l'esempio MSVAD semplice definisce tre pin bridge. Questi pin sono elencati nella tabella seguente.

Pin ID	Descrizione
KSPIN_TOPO_SYNTHIN_SOURCE	Jack di input MIDI
KSPIN_TOPO_MIC_SOURCE	Jack di input del microfono
KSPIN_TOPO_LINEOUT_DEST	Jack di output dell'altoparlante stereo

La parte restante di questo argomento illustra come modificare il driver di esempio MSVAD semplice per fornire le informazioni sul jack per i tre pin bridge.

Prima di tutto, è possibile specificare le informazioni sul jack per questi pin come indicato di seguito:

// 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'esempio di codice precedente imposta i membri ChannelMapping per i due pin di acquisizione su 0. Solo i pin di rendering analogico devono avere valori nonzero ChannelMapping .

La modifica primaria all'esempio MSVAD semplice consiste nell'aggiungere il gestore di proprietà seguente all'implementazione del miniport della topologia nel file di esempio 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'esempio di codice precedente fa riferimento alle tre variabili KSJACK_DESCRIPTION, SynthIn_Jack, MicIn_Jack e LineOut_Jack definite in precedenza. Se il client esegue una query sul filtro per la descrizione del jack di un pin valido, ma una che non è un pin bridge (e pertanto non ha alcuna descrizione jack), la query riesce (con codice di stato STATUS_SUCCESS), ma il gestore delle proprietà restituisce una descrizione jack vuota costituita da una struttura KSMULTIPLE_ITEM e niente altro. Se il client specifica un ID pin non valido (che identifica un pin inesistente), il gestore restituisce il codice di stato STATUS_INVALID_PARAMETER.

Sono necessarie due modifiche aggiuntive all'esempio MSVAD semplice per supportare la proprietà KSPROPERTY_JACK_DESCRIPTION. Si tratta di:

Aggiungere la dichiarazione del metodo PropertyHandlerJackDescription nell'esempio di codice precedente alla definizione della classe CMiniportTopology nel file di intestazione Mintopo.h.
Implementare una tabella di automazione per il filtro della topologia e caricare l'indirizzo di questa tabella nel membro AutomationTable della struttura PCFILTER_DESCRIPTOR nel file di intestazione Toptable.h. Questa struttura è denominata MiniportFilterDescriptor.

Per implementare la tabella di automazione per il filtro, inserire il codice seguente nel file di intestazione Toptable.h (prima della definizione di MiniportFilterDescriptor):

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

DEFINE_PCAUTOMATION_TABLE_PROP(AutomationTopoFilter, PropertiesTopoFilter);

Nell'esempio di codice precedente, il membro gestore della struttura PCPROPERTY_ITEM contiene un puntatore di funzione al gestore delle proprietà aggiunto a Mintopo.cpp in un passaggio precedente. Per rendere accessibile il gestore delle proprietà dal file di intestazione, inserire una dichiarazione di funzione extern per PropertyHandler_TopoFilter all'inizio del file di intestazione.

Per altre informazioni sulla proprietà jack description, vedere Descrizioni jack per sottodevice audio dinamici.

Condividi tramite

Jack Description, proprietà

Commenti e suggerimenti

Risorse aggiuntive