função TSPI_lineMonitorTones (tspi.h)

Artigo
03/03/2024

A função TSPI_lineMonitorTones habilita e desabilita a detecção de tons de banda na chamada. Sempre que um tom especificado é detectado, uma mensagem é enviada ao aplicativo cliente por meio do TAPI.

Sintaxe

LONG TSPIAPI TSPI_lineMonitorTones(
  HDRVCALL                hdCall,
  DWORD                   dwToneListID,
  LPLINEMONITORTONE const lpToneList,
  DWORD                   dwNumEntries
);

Parâmetros

hdCall

O identificador para a chamada para a qual a detecção de tom deve ser feita. O estado de chamada do hdCall pode ser qualquer estado, exceto ocioso.

dwToneListID

O identificador exclusivo para esta lista de tons. Várias listas de tom podem ser excelentes ao mesmo tempo. O provedor de serviços deve substituir qualquer lista antiga com o mesmo dwToneListID pela nova lista de tons. Se lpToneList for NULL, a lista de tons com dwToneListID será simplesmente descartada. De qualquer forma, outras listas de tom com dwToneListIDdiferentes são mantidas inalteradas.

lpToneList

Uma lista de tons a serem monitorados, do tipo LINEMONITORTONE. Cada tom nesta lista tem um campo de marca definido pelo aplicativo que é usado para identificar tons individuais na lista com a finalidade de relatar uma detecção de tom. O monitoramento de tom em andamento é cancelado ou alterado chamando essa operação com NULL para lpToneList ou com outra lista de tons. O provedor de serviços deve copiar a lista de tons em sua própria memória para referência posterior, em vez de simplesmente manter o ponteiro na memória do aplicativo.

dwNumEntries

O número de entradas em lpToneList. O parâmetro dwNumEntries será ignorado se lpToneList for NULL. 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_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_INVALTONE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_INVALPOINTER.

Comentários

Essa função retorna zero (êxito) quando o monitoramento de tom é iniciado corretamente, não quando o monitoramento de tom é encerrado. Assim como acontece com o monitoramento de mídia, o monitoramento de tom permanece em vigor para uma determinada lista de tons até que essa lista de tons seja explicitamente desabilitada chamando TSPI_lineMonitorTones com o mesmo dwToneListID e outra lista de tom (ou uma lista de tom NULL ) ou até que a chamada faça a transição para ocioso.

Embora essa função possa ser invocada em qualquer estado de chamada, exceto ocioso, os tons normalmente só podem ser detectados enquanto a chamada está no estado conectado . A detecção de tom geralmente requer recursos computacionais. Dependendo do provedor de serviços e de outras atividades que competem por esses recursos, o número de tons que podem ser detectados pode variar ao longo do tempo. Além disso, uma quantidade equivalente de recursos pode ser consumida para monitorar um único tom de frequência tripla versus três tons de frequência única. Se os recursos forem supercomprometidos, o provedor de serviços retornará LINEERR_RESOURCEUNAVAIL.

O provedor de serviços monitora todos os tons em todas as listas de tom simultaneamente. Quando um tom é detectado, cada tom correspondente de cada lista de tons é relatado separadamente usando uma mensagem LINE_MONITORTONE . Cada relatório de tom inclui o identificador de lista de tom e a marca específica do aplicativo. Alguns provedores de serviços podem não ser capazes de discriminar tons muito próximos, de modo que várias correspondências possam ser relatadas até mesmo para tons cujas descrições não são estritamente idênticas.

ObserveTSPI_lineMonitorTones também é usado para detectar o silêncio. O silêncio é especificado como um tom com todas as frequências zero.

A função correspondente no nível TAPI não inclui um parâmetro dwToneListID . A inclusão desse parâmetro na interface TSPI permite que o TAPI encaminhe a união de todas as listas de monitoramento de tom de todos os aplicativos para o provedor de serviços, mantendo a capacidade de filtrar e encaminhar os eventos de detecção de tom de acordo com o aplicativo. Isso dá aos designers do provedor de serviços a flexibilidade máxima para determinar o grau em que eles podem discriminar tons muito próximos, pois a TAPI não faz suposições sobre quais descrições de tom são consideradas idênticas.