funzione TSPI_lineMonitorTones (tspi.h)

Articolo
03/08/2023

La funzione TSPI_lineMonitorTones abilita e disabilita il rilevamento dei toni in banda nella chiamata. Ogni volta che viene rilevato un tono specificato, viene inviato un messaggio all'applicazione client tramite TAPI.

Sintassi

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

Parametri

hdCall

Handle alla chiamata per cui eseguire il rilevamento del tono. Lo stato della chiamata di hdCall può essere qualsiasi stato tranne l'inattività.

dwToneListID

Identificatore univoco per questo elenco di toni. Diversi elenchi di toni possono essere in sospeso alla volta. Il provider di servizi deve sostituire qualsiasi elenco precedente con lo stesso dwToneListID con il nuovo elenco di toni. Se lpToneList è NULL, l'elenco di toni con dwToneListID viene semplicemente eliminato. In qualsiasi caso, altri elenchi di toni con dwToneListIDs diversi vengono mantenuti invariati.

lpToneList

Elenco di toni da monitorare, di tipo LINEMONITORTONE. Ogni tono in questo elenco include un campo tag definito dall'applicazione che viene usato per identificare i singoli toni nell'elenco allo scopo di segnalare un rilevamento dei toni. Il monitoraggio del tono in corso viene annullato o modificato chiamando questa operazione con NULL per lpToneList o con un altro elenco di toni. Il provider di servizi deve copiare l'elenco di toni nella propria memoria per un riferimento successivo, anziché conservare semplicemente il puntatore nella memoria dell'applicazione.

dwNumEntries

Numero di voci in lpToneList. Il parametro dwNumEntries viene ignorato se lpToneList è NULL. TAPI non convalida questo parametro quando questa funzione viene chiamata.

Valore restituito

Restituisce zero se la funzione ha esito positivo o un numero di errore se si verifica un errore. I valori restituiti possibili sono i seguenti:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_INVALTONE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_INVALPOINTER.

Commenti

Questa funzione restituisce zero (esito positivo) quando il monitoraggio del tono viene avviato correttamente, non quando il monitoraggio del tono viene terminato. Come per il monitoraggio multimediale, il monitoraggio del tono rimane effettivo per un determinato elenco di toni fino a quando tale elenco di toni non viene disabilitato in modo esplicito chiamando TSPI_lineMonitorTones con lo stesso dwToneListID e un altro elenco di toni (o un elenco di toni NULL ) o fino a quando la chiamata passa a inattiva.

Anche se questa funzione può essere richiamata in qualsiasi stato di chiamata, ad eccezione dell'inattività, i toni possono in genere essere rilevati solo mentre la chiamata si trova nello stato connesso . Il rilevamento dei toni richiede in genere risorse di calcolo. A seconda del provider di servizi e di altre attività che competono per tali risorse, il numero di toni che possono essere rilevati può variare nel tempo. Inoltre, una quantità equivalente di risorse può essere utilizzata per il monitoraggio di un singolo tono di frequenza triplo rispetto a tre toni di frequenza singola. Se le risorse vengono sovracommesse, il provider di servizi restituisce LINEERR_RESOURCEUNAVAIL.

Il provider di servizi monitora tutti i toni in tutti gli elenchi di toni simultaneamente. Quando viene rilevato un tono, ogni tono corrispondente da ogni elenco di toni viene segnalato separatamente usando un messaggio di LINE_MONITORTONE . Ogni report di tono include sia l'identificatore dell'elenco dei toni che il tag specifico dell'applicazione. Alcuni provider di servizi potrebbero non essere in grado di discriminare toni molto vicini, in modo che più corrispondenze possano essere segnalate anche per i toni le cui descrizioni non sono strettamente identiche.

NotaTSPI_lineMonitorTones viene usato anche per rilevare il silenzio. Il silenzio viene specificato come tono con tutte le frequenze zero.

La funzione corrispondente a livello TAPI non include un parametro dwToneListID . L'inclusione di questo parametro nell'interfaccia TSPI consente a TAPI di inoltrare l'unione di tutti gli elenchi di monitoraggio dei toni da tutte le applicazioni al provider di servizi, mantenendo comunque la possibilità di filtrare e inoltrare gli eventi di rilevamento dei toni in base all'applicazione. In questo modo, i progettisti del provider di servizi offrono la massima flessibilità per determinare il grado in cui possono discriminare toni molto vicini, perché TAPI non presuppone quali descrizioni del tono sono considerate identiche.