funzione TSPI_lineMonitorTones (tspi.h)

Articolo
03/03/2024

La funzione TSPI_lineMonitorTones abilita e disabilita il rilevamento dei toni inbandati 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 la quale deve essere eseguito il rilevamento del tono. Lo stato della chiamata di hdCall può essere qualsiasi stato, ad eccezione dell'inattività.

dwToneListID

Identificatore univoco per questo elenco di toni. Diversi elenchi di toni possono essere in sospeso contemporaneamente. 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 ogni caso, gli altri elenchi di toni con dwToneListIDdiversi vengono mantenuti invariati.

lpToneList

Elenco di toni da monitorare, di tipo LINEMONITORTONE. Ogni tono in questo elenco ha un campo tag definito dall'applicazione usato per identificare i singoli toni nell'elenco allo scopo di segnalare un rilevamento del tono. 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 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 viene chiamata questa funzione.

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 viene terminato il monitoraggio del tono. Come per il monitoraggio multimediale, il monitoraggio del tono rimane attivo 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 non passa all'inattività.

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 tono 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 usata per il monitoraggio di un singolo tono a frequenza triplica rispetto a tre toni a frequenza singola. Se le risorse vengono sottoposte a overcommitted, il provider di servizi restituisce LINEERR_RESOURCEUNAVAIL.

Il provider di servizi monitora tutti i toni in tutti gli elenchi di toni contemporaneamente. Quando viene rilevato un tono, ogni tono corrispondente di 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 del tono da tutte le applicazioni al provider di servizi, mantenendo comunque la possibilità di filtrare e inoltrare gli eventi di rilevamento del tono in base all'applicazione. In questo modo, i progettisti del provider di servizi offrono la massima flessibilità per determinare il grado di discriminare toni molto vicini, perché TAPI non presuppone quali descrizioni dei toni sono considerate identiche.