Função lineSetMediaControl (tapi.h)

Artigo
03/02/2024

A função lineSetMediaControl habilita e desabilita as ações de controle no fluxo de mídia associado à linha, ao endereço ou à chamada especificados. As ações de controle de mídia podem ser disparadas pela detecção de dígitos, tipos de mídia, tons personalizados e estados de chamada especificados.

Sintaxe

LONG lineSetMediaControl(
  HLINE                             hLine,
  DWORD                             dwAddressID,
  HCALL                             hCall,
  DWORD                             dwSelect,
  LPLINEMEDIACONTROLDIGIT const     lpDigitList,
  DWORD                             dwDigitNumEntries,
  LPLINEMEDIACONTROLMEDIA const     lpMediaList,
  DWORD                             dwMediaNumEntries,
  LPLINEMEDIACONTROLTONE const      lpToneList,
  DWORD                             dwToneNumEntries,
  LPLINEMEDIACONTROLCALLSTATE const lpCallStateList,
  DWORD                             dwCallStateNumEntries
);

Parâmetros

hLine

Identificador para um dispositivo de linha aberta.

dwAddressID

Identificador de endereço no dispositivo de linha aberta especificado. Um identificador de endereço está permanentemente associado a um endereço; o identificador permanece constante entre as atualizações do sistema operacional.

hCall

Manipule para uma chamada. O aplicativo deve ser um proprietário da chamada. O estado de chamada de hCall pode ser qualquer estado.

dwSelect

Se o controle de mídia solicitado está associado a uma única chamada, é o padrão para todas as chamadas em um endereço ou é o padrão para todas as chamadas em uma linha. Esse parâmetro é um e apenas uma das constantes LINECALLSELECT_.

lpDigitList

Ponteiro para a matriz que contém os dígitos que são para disparar ações de controle de mídia, do tipo LINEMEDIACONTROLDIGIT. Sempre que um dígito na lista de dígitos é detectado, a ação de controle de mídia especificada é executada no fluxo de mídia da chamada.

Os dígitos válidos para o modo de pulso são '0' a '9'. Os dígitos válidos para o modo DTMF são '0' a '9', 'A', 'B', 'C', 'D', '*', '#'.

dwDigitNumEntries

Número de entradas no lpDigitList.

lpMediaList

Ponteiro para uma matriz com entradas do tipo LINEMEDIACONTROLMEDIA. A matriz tem entradas dwMediaNumEntries . Cada entrada contém um tipo de mídia a ser monitorado, informações específicas do tipo de mídia (como duração) e um campo de controle de mídia. Se um tipo de mídia na lista for detectado, a ação de controle de mídia correspondente será executada no fluxo de mídia da chamada.

dwMediaNumEntries

Número de entradas em lpMediaList.

lpToneList

Ponteiro para uma matriz com entradas do tipo LINEMEDIACONTROLTONE. A matriz tem entradas dwToneNumEntries . Cada entrada contém uma descrição de um tom a ser monitorado, a duração do tom e um campo de controle de mídia. Se um tom na lista for detectado, a ação de controle de mídia correspondente será executada no fluxo de mídia da chamada.

dwToneNumEntries

Número de entradas em lpToneList.

lpCallStateList

Ponteiro para uma matriz com entradas do tipo LINEMEDIACONTROLCALLSTATE. A matriz tem entradas dwCallStateNumEntries . Cada entrada contém um estado de chamada e uma ação de controle de mídia. Sempre que a chamada fornecida faz a transição para um dos estados de chamada na lista, a ação de controle de mídia correspondente é invocada.

dwCallStateNumEntries

Número de entradas em lpCallStateList.

Retornar valor

Retornará zero se a solicitação for bem-sucedida ou um número de erro negativo se ocorrer um erro. Os valores retornados possíveis são:

LINEERR_INVALADDRESSID, LINEERR_NOMEM, LINEERR_INVALCALLHANDLE, LINEERR_NOTOWNER, LINEERR_INVALCALLSELECT, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATELIST, LINEERR_OPERATIONFAILED, LINEERR_INVALDIGITLIST, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALLINEHANDLE, LINEERR_UNINITIALIZED, LINEERR_INVALMEDIALIST, LINEERR_INVALPOINTER, LINEERR_INVALTONELIST.

Comentários

A função lineSetMediaControl será considerada bem-sucedida se o controle de mídia tiver sido iniciado corretamente, não quando qualquer controle de mídia tiver entrado em vigor. O controle de mídia em andamento é alterado ou cancelado chamando essa função novamente com parâmetros diferentes ou NULLs. Se um ou mais dos parâmetros lpDigitList, lpMediaList, lpToneList e lpCallStateList forem NULL, o dígito, o tipo de mídia, o tom ou o controle de mídia disparado pelo estado correspondente serão desabilitados. Para modificar apenas uma parte dos parâmetros de controle de mídia, deixando as configurações restantes em vigor, o aplicativo deve invocar lineSetMediaControl, fornecendo os parâmetros anteriores para as partes que devem permanecer em vigor e novos parâmetros para as partes que devem ser modificadas.

Se hCall estiver selecionado e a chamada for encerrada ou o aplicativo desalocar seu identificador, o controle de mídia nessa chamada será cancelado.

Todos os aplicativos que são proprietários da chamada têm, em princípio, permissão para fazer solicitações de controle de mídia na chamada. Somente uma única solicitação de controle de mídia pode ser pendente em uma chamada em todos os aplicativos que possuem a chamada. Cada vez que lineSetMediaControl é chamado, a nova solicitação substitui qualquer controle de mídia e, em seguida, em vigor na chamada, seja definido pelo aplicativo de chamada ou por qualquer outro aplicativo proprietário.

Dependendo do provedor de serviços e de outras atividades que competem por esses recursos, o número de detecções simultâneas que podem ser feitas pode variar ao longo do tempo. Se os recursos do provedor de serviços forem supercomprometidos, o erro LINEERR_RESOURCEUNAVAIL será retornado.

Se o controle de mídia tem suporte ou não pelo provedor de serviços é uma funcionalidade de dispositivo.