Share via

Interface IKsJackDescription (devicetopology.h)

  • Artigo

A interface IKsJackDescription fornece informações sobre as tomadas ou conectores internos que fornecem uma conexão física entre um dispositivo em um adaptador de áudio e um dispositivo de ponto de extremidade externo ou interno (por exemplo, um microfone ou player de CD). O cliente obtém uma referência à interface IKsJackDescription de uma parte chamando o método IPart::Activate com refiid de parâmetro definido como REFIID IID_IKsJackDescription. A chamada para IPart::Activate só terá êxito se a parte der suporte à interface IKsJackDescription . Somente um objeto de parte que representa um conector com um tipo de conexão Physical_External ou Physical_Internal dará suporte a essa interface.

A maioria dos drivers de adaptador de áudio do Windows dá suporte ao WDM (Modelo de Driver do Windows) e usa propriedades de KS (streaming de kernel) para representar os parâmetros de descrição de hardware em conectores (conhecidos como pinos KS). A interface IKsJackDescription fornece acesso conveniente à propriedade KSPROPERTY_JACK_DESCRIPTION de um conector para um dispositivo de ponto de extremidade. Para obter mais informações sobre propriedades KS e pinos KS, consulte a documentação do DDK do Windows.

Herança

A interface IKsJackDescription herda da interface IUnknown . IKsJackDescription também tem estes tipos de membros:

Métodos

A interface IKsJackDescription tem esses métodos.

 
IKsJackDescription::GetJackCount

O método GetJackCount obtém o número de tomadas necessárias para se conectar a um dispositivo de ponto de extremidade de áudio.
IKsJackDescription::GetJackDescription

O método GetJackDescription obtém uma descrição de uma tomada de áudio.

Comentários

Se um dispositivo de ponto de extremidade de áudio der suporte à interface IKsJackDescription , o painel de controle multimídia do Windows, Mmsys.cpl, exibirá as informações de tomada. Para exibir as informações de tomada, siga estas etapas:

  1. Para executar Mmsys.cpl, abra uma janela do Prompt de Comando e insira o seguinte comando:

    mmsys.cplde controle

    Como alternativa, você pode executar Mmsys.cpl clicando com o botão direito do mouse no ícone do alto-falante na área de notificação, que está localizada no lado direito da barra de tarefas e selecionando Dispositivos de Reprodução ou Dispositivos de Gravação.

  2. Depois que a janela Mmsys.cpl for aberta, selecione um dispositivo na lista de dispositivos de reprodução ou na lista de dispositivos de gravação e clique em Propriedades.
  3. Quando a janela de propriedades for aberta, clique em Geral. Se a página de propriedades selecionada exibir as informações de tomada do dispositivo, o dispositivo oferecerá suporte à interface IKsJackDescription . Se a página de propriedades exibir o texto "Nenhuma informação de tomada está disponível", o dispositivo não oferecerá suporte à interface .
O exemplo de código a seguir mostra como obter a interface IKsJackDescription para um dispositivo de ponto de extremidade de áudio:
//-----------------------------------------------------------
// 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;
}

No exemplo de código anterior, a função GetJackInfo usa dois parâmetros. O parâmetro de entrada pDevice aponta para a interface IMMDevice de um dispositivo de ponto de extremidade. O parâmetro de saída ppJackDesc aponta para um valor de ponteiro no qual a função grava o endereço da interface IKsJackDescription correspondente, se a interface existir. Se a interface não existir, a função gravará NULL em *ppJackDesc e retornará o código de erro E_NOINTERFACE.

No exemplo de código anterior, a chamada para IMMDevice::Activate recupera a interface IDeviceTopology do dispositivo de ponto de extremidade. A topologia de dispositivo de um dispositivo de ponto de extremidade contém um único conector (número do conector 0) que se conecta ao dispositivo adaptador. No outro lado dessa conexão, o conector no dispositivo adaptador representa a tomada de áudio ou as tomadas às quais o dispositivo de ponto de extremidade se conecta. A chamada para o método IDeviceTopology::GetConnector recupera a interface IConnector do conector no dispositivo de ponto de extremidade e a chamada de método IConnector::GetConnectedTo recupera o conector correspondente no dispositivo adaptador. Por fim, a chamada do método IConnector::QueryInterface recupera a interface IPart do conector do dispositivo adaptador e a chamada do método IPart::Activate recupera a interface IKsJackDescription do conector, se existir.

Requisitos

   
Cliente mínimo com suporte Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows Server 2008 [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho devicetopology.h

Confira também

Principais interfaces de áudio

DeviceTopology API

IPart::Activate