função TSPI_lineSetMediaControl (tspi.h)

Artigo
08/26/2023

A função TSPI_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 especificados, tipos de mídia, tons personalizados e estados de chamada. Os novos controles de mídia especificados substituem todos os que estavam em vigor para essa linha, endereço ou chamada antes dessa solicitação.

Sintaxe

LONG TSPIAPI TSPI_lineSetMediaControl(
  HDRVLINE                          hdLine,
  DWORD                             dwAddressID,
  HDRVCALL                          hdCall,
  DWORD                             dwSelect,
  LPLINEMEDIACONTROLDIGIT const     lpDigitList,
  DWORD                             dwDigitNumEntries,
  LPLINEMEDIACONTROLMEDIA const     lpMediaList,
  DWORD                             dwMediaNumEntries,
  LPLINEMEDIACONTROLTONE const      lpToneList,
  DWORD                             dwToneNumEntries,
  LPLINEMEDIACONTROLCALLSTATE const lpCallStateList,
  DWORD                             dwCallStateNumEntries
);

Parâmetros

hdLine

O identificador para uma linha.

dwAddressID

Um 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. O TAPI não valida esse parâmetro quando essa função é chamada.

hdCall

O identificador de uma chamada. O estado de chamada de hdCall pode ser qualquer estado.

dwSelect

Especifica 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 usa as seguintes constantes LINECALLSELECT_.

lpDigitList

Um ponteiro para a matriz que contém os dígitos que devem disparar ações de controle de mídia, do tipo LINEMEDIACONTROLDIGIT. Sempre que um dígito listado 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

O número de entradas no lpDigitList. O TAPI não valida esse parâmetro quando essa função é chamada.

lpMediaList

Um 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

O número de entradas em lpMediaList. O TAPI não valida esse parâmetro quando essa função é chamada.

lpToneList

Um 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

O número de entradas em lpToneList. O TAPI não valida esse parâmetro quando essa função é chamada.

lpCallStateList

Um 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.

dwCallStateNumEntries

O número de entradas em lpCallStateList. O TAPI não valida esse parâmetro quando essa função é chamada.

Retornar valor

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

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

Comentários

Essa função retorna zero (êxito) quando o controle de mídia é iniciado corretamente, não quando qualquer controle de mídia entra em vigor. O controle de mídia em andamento é alterado ou cancelado quando essa função é chamada novamente com parâmetros diferentes ou NULLs.

Somente uma única solicitação de controle de mídia pode ser pendente em uma chamada ao mesmo tempo. Uma solicitação substitui qualquer que possa estar pendente.

Dependendo do provedor de serviços e de outras atividades que competem por esses recursos, a quantidade 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, ele retornará LINEERR_RESOURCEUNAVAIL.

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

Sempre que TSPI_lineSetMediaControl é chamado, a nova solicitação substitui qualquer controle de mídia atualmente em vigor. Se um ou mais dos parâmetros lpDigitList, lpMediaList, lpToneList e lpCallStateList forem NULL, o dígito correspondente, o tipo de mídia, o tom ou o controle de mídia disparado pelo estado da chamada 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 TSPI_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.