IKsJackDescription Interface

IKsJackDescription Interface

The IKsJackDescription interface provides information about the jacks or internal connectors that provide a physical connection between a device on an audio adapter and an external or internal endpoint device (for example, a microphone or CD player). The client obtains a reference to the IKsJackDescription interface of a part by calling the IPart::Activate method with parameter refiid set to REFIID IID_IKsJackDescription. The call to IPart::Activate succeeds only if the part supports the IKsJackDescription interface. Only a part object that represents a connector with a Physical_External or Physical_Internal connection type will support this interface.

Most Windows audio adapter drivers support the Windows Driver Model (WDM) and use kernel-streaming (KS) properties to represent the hardware description parameters in connectors (referred to as KS pins). The IKsJackDescription interface provides convenient access to the KSPROPERTY_JACK_DESCRIPTION property of a connector to an endpoint device. For more information about KS properties and KS pins, see the Windows DDK documentation.

IKsJackDescription inherits from the IUnknown interface. In addition to the methods inherited from IUnknown, IKsJackDescription supports the following methods.

Remarks

If an audio endpoint device supports the IKsJackDescription interface, the Windows multimedia control panel, Mmsys.cpl, displays the jack information. To view the jack information, follow these steps:

1. To run Mmsys.cpl, open a Command Prompt window and enter the following command:

   control mmsys.cpl
   

   Alternatively, you can run Mmsys.cpl by right-clicking the speaker icon in the notification area, which is located on the right side of the taskbar, and selecting either Playback Devices or Recording Devices.

2. After the Mmsys.cpl window opens, select a device from either the list of playback devices or the list of recording devices, and click Properties.

3. When the properties window opens, click General. If the selected property page displays the jack information for the device, the device supports the IKsJackDescription interface. If the property page displays the text "No jack information is available", the device does not support the interface.

The following code example shows how to obtain the IKsJackDescription interface for an audio endpoint device:

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

In the preceding code example, the GetJackInfo function takes two parameters. Input parameter pDevice points to the IMMDevice interface of an endpoint device. Output parameter ppJackDesc points to a pointer value into which the function writes the address of the corresponding IKsJackDescription interface, if the interface exists. If the interface does not exist, the function writes NULL to *ppJackDesc and returns error code E_NOINTERFACE.

In the preceding code example, the call to IMMDevice::Activate retrieves the IDeviceTopology interface of the endpoint device. The device topology of an endpoint device contains a single connector (connector number 0) that connects to the adapter device. At the other side of this connection, the connector on the adapter device represents the audio jack or jacks that the endpoint device plugs into. The call to the IDeviceTopology::GetConnector method retrieves the IConnector interface of the connector on the endpoint device, and the IConnector::GetConnectedTo method call retrieves the corresponding connector on the adapter device. Finally, the IConnector::QueryInterface method call retrieves the IPart interface of the adapter device's connector, and the IPart::Activate method call retrieves the connector's IKsJackDescription interface, if it exists.

Requirements

Client: Windows Vista

Header: Include Devicetopology.h.

See Also

• DeviceTopology API
• IPart::Activate