Właściwość opisu Jacka

W systemie Windows Vista i nowszych właściwość KSPROPERTY_JACK_DESCRIPTION opisuje gniazdo audio lub inny fizyczny łącznik na karcie audio. Wartość właściwości opisuje kolor gniazda, fizyczną lokalizację gniazda, typ łącznika i inne funkcje gniazda. Celem tych informacji jest pomoc użytkownikowi w znalezieniu poprawnego gniazda do podłączania urządzenia punktu końcowego audio, takiego jak mikrofon, słuchawki lub głośniki. Aby uzyskać więcej informacji, zobacz Urządzenia punktu końcowego audio.

Jeśli filtr KS na karcie audio obsługuje właściwość KSPROPERTY_JACK_DESCRIPTION, panel sterowania multimediami Windows, Mmsys.cpl, wyświetla informacje o gnieździe dla pinach mostkowych na filtrze. Kołek mostka reprezentuje połączenie (zazwyczaj gniazdo) z urządzeniem audio jako punktem końcowym. Mimo że wartość właściwości zawiera informacje o pinie (a raczej o gnieździe lub gniazdach, które są skojarzone z pinem), właściwość jest właściwością filtra, a nie pina. Aby uzyskać więcej informacji na temat pinezek mostka, zobacz Audio Filter Graphs (Wykresy filtru audio). Aby uzyskać więcej informacji na temat właściwości filtru i właściwości pinezki, zobacz Właściwości filtru, pinezki i węzła.

Aplikacja audio może uzyskać wartość właściwości KSPROPERTY_JACK_DESCRIPTION dla urządzenia punktu końcowego audio, wywołując metodę IKsJackDescription::GetJackDescription w interfejsie API DeviceTopology. Na przykład aplikacja może użyć informacji o jacku, aby ułatwić użytkownikowi odróżnienie mikrofonu podłączonego do zielonego gniazda XLR z mikrofonu podłączonego do pomarańczowego gniazda XLR. Aby uzyskać więcej informacji na temat interfejsu API DeviceTopology, zobacz Topologie urządzeń.

Sterownik klasy HD Audio Microsoft automatycznie konstruuje wartości właściwości KSPROPERTY_JACK_DESCRIPTION z danych odczytywanych z rejestrów konfiguracji pinów w kodeku audio HD. Jednak każdy sterownik audio oparty na KS może zaimplementować obsługę tej właściwości w tabelach automatyzacji filtrów. Aby uzyskać więcej informacji na temat sterownika klasy HD Audio, zobacz HD Audio i UAA. Aby uzyskać więcej informacji na temat rejestrów konfiguracji przypinania, zobacz oficjalny dokument Wytyczne dotyczące konfiguracji przypinania dla urządzeń audio o wysokiej rozdzielczości .

Urządzenie punktu końcowego audio może połączyć się z pinem mostka za pomocą jednego lub więcej gniazd. Na przykład zestaw głośników stereo (dwukanałowych) wymaga jednego gniazda, ale zestaw głośników dźwiękowych 5.1 wymaga trzech gniazd (przy założeniu, że każdy gniazdo obsługuje dwa z sześciu kanałów).

Opis każdego gniazda znajduje się w strukturze KSJACK_DESCRIPTION . Na przykład wartość właściwości KSPROPERTY_JACK_DESCRIPTION dla urządzenia punktu końcowego audio z jednym jackiem zawiera jedną strukturę KSJACK_DESCRIPTION, ale wartość właściwości urządzenia punktu końcowego z trzema jackami zawiera trzy struktury KSJACK_DESCRIPTION. W obu przypadkach struktura lub struktury KSJACK_DESCRIPTION w wartości właściwości są poprzedzone strukturą KSMULTIPLE_ITEM określającą rozmiar wartości właściwości. Aby uzyskać więcej informacji, zobacz KSPROPERTY_JACK_DESCRIPTION.

Informacje o jacku są szczególnie przydatne, aby ułatwić użytkownikom rozróżnienie między gniazdami, które łączą się z konfiguracją głośnika wielokanałowego. Poniższy przykład kodu przedstawia tablicę struktur KSJACK_DESCRIPTION używanych przez sterownik audio w celu opisania trzech gniazd dla zestawu głośników 5.1 przestrzennych.

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

Jeśli sprzęt audio może wykryć, czy urządzenie jest podłączone, sterownik dynamicznie aktualizuje wartość tego elementu członkowskiego, aby wskazać, czy urządzenie jest aktualnie podłączone (PRAWDA) lub odłączone (FAŁSZ)

W poprzednim przykładzie kodu element członkowski IsConnected w każdym elemencie tablicy ma wartość TRUE , aby wskazać, że urządzenie punktu końcowego jest podłączone do gniazda. Jeśli jednak sprzęt nie ma wykrywania obecności jacka, IsConnected musi być zawsze ustawiony na TRUE, niezależnie od tego, czy urządzenie jest podłączone do gniazda. Aby usunąć niejednoznaczność wynikającą z tego podwójnego znaczenia wartości zwracanej TRUE , aplikacja kliencka może wywołać element IKsJackDescription2::GetJackDescription2 , aby odczytać flagę JackCapabilities struktury KSJACK_DESCRIPTION2 . Jeśli ta flaga ma ustawiony bit JACKDESC2_PRESENCE_DETECT_CAPABILITY, wskazuje, że punkt końcowy w rzeczywistości obsługuje wykrywanie obecności wtyku. W takim przypadku wartość elementu członkowskiego IsConnected może być interpretowana jako dokładne odbicie stanu podłączenia gniazda.

Makro RGB, które pojawia się w poprzednich strukturach, jest zdefiniowane w pliku nagłówkowym Wingdi.h w pakiecie SDK dla Windows.

Ponadto można użyć tablicy opisów jacków, aby pokazać, że co najmniej dwa gniazda są funkcjonalnie równoważne sobie. W poniższym przykładzie kodu sterownik audio łączy opisy gniazda dla żółtego gniazda RCA i czarnego gniazda cyfrowego optycznego w jedną tablicę, aby wskazać użytkownikowi, że dwa gniazda niosą ten sam sygnał:

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

W poprzednim przykładzie kodu wartości elementów członkowskich ChannelMapping w dwóch strukturach KSJACK_DESCRIPTION są identyczne.

Przykładowy sterownik MSVAD "Simple" w zestawie WDK (w przykładowym katalogu Src\Audio\Msvad\Simple) można przystosować do obsługi właściwości KSPROPERTY_JACK_DESCRIPTION. Ten przykładowy sterownik jest wygodny do zademonstrowania użycia właściwości, ponieważ nie wymaga rzeczywistego sprzętu. W związku z tym można go zainstalować na dowolnym komputerze z systemem Windows. (Jednak tylko systemy operacyjne Windows Vista i nowsze zapewniają pełną obsługę właściwości KSPROPERTY_JACK_DESCRIPTION). Aby uzyskać więcej informacji na temat tego przykładu, zobacz Windows Driver Kit Samples (Przykłady zestawu sterowników systemu Windows).

Filtr topologii audio dla przykładu Simple MSVAD definiuje trzy mostki. Te pinezki są wymienione w poniższej tabeli.

W pozostałej części tego tematu wyjaśniono, jak zmodyfikować przykładowy sterownik Simple MSVAD, aby udostępnić informacje o gniazdach dla trzech mostkowych pinów.

Najpierw można określić informacje o gniazdach dla tych pinów w następujący sposób:

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

Powyższy przykład kodu ustawia członków ChannelMapping dla dwóch pinów przechwytywania na wartość 0. Tylko wyprowadzenia renderowania analogowego powinny mieć niezerowe wartości ChannelMapping.

Podstawową modyfikacją przykładu Simple MSVAD jest dodanie następującego modułu obsługi właściwości do implementacji miniportu topologii w przykładowym pliku 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;
}

Powyższy przykład kodu odnosi się do trzech zmiennych KSJACK_DESCRIPTION — SynthIn_Jack, MicIn_Jack i LineOut_Jack — które zostały zdefiniowane wcześniej. Jeśli klient wykonuje zapytanie do filtru o opis gniazdka prawidłowego pinu, ale takiego, który nie jest pinem mostka (i dlatego nie ma opisu gniazdka), zapytanie powiedzie się (z kodem STATUS_SUCCESS), ale procedura obsługi właściwości zwraca pusty opis gniazdka składający się z jednej struktury KSMULTIPLE_ITEM i niczego więcej. Jeśli klient określa nieprawidłowy identyfikator pin (który identyfikuje nieistniejący numer PIN), program obsługi zwraca kod stanu STATUS_INVALID_PARAMETER.

Do obsługi właściwości KSPROPERTY_JACK_DESCRIPTION wymagane są dwie dodatkowe modyfikacje przykładu Simple MSVAD. Są to:

• Dodaj deklarację metody PropertyHandlerJackDescription w poprzednim przykładzie kodu do definicji klasy CMiniportTopology w pliku nagłówka Mintopo.h.

• Zaimplementuj tabelę automatyzacji dla filtru topologii i załaduj adres tej tabeli do elementu członkowskiego AutomationTable struktury PCFILTER_DESCRIPTOR w pliku nagłówkowym Toptable.h. Ta struktura nosi nazwę MiniportFilterDescriptor.

Aby zaimplementować tabelę automatyzacji dla filtru, wstaw następujący kod do pliku nagłówka Toptable.h (przed definicją MiniportFilterDescriptor):

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

DEFINE_PCAUTOMATION_TABLE_PROP(AutomationTopoFilter, PropertiesTopoFilter);

W poprzednim przykładzie kodu członek Handler struktury PCPROPERTY_ITEM zawiera wskaźnik funkcji do procedury obsługi właściwości, która została dodana do Mintopo.cpp we wcześniejszym kroku. Aby program obsługi właściwości był dostępny z pliku nagłówka, wstaw deklarację funkcji extern dla PropertyHandler_TopoFilter na początku pliku nagłówka.

Aby uzyskać więcej informacji na temat właściwości opisu gniazda, sprawdź Opisy gniazda dla dynamicznych urządzeń audio.