funzione TSPI_lineGenerateTone (tspi.h)

Articolo
03/03/2024

La funzione TSPI_lineGenerateTone genera il tono specificato tramite la chiamata specificata. Richiamando questa funzione con zero per dwToneMode interrompe qualsiasi generazione di toni attualmente in corso nella chiamata specificata. Richiamando TSPI_lineGenerateTone o TSPI_lineGenerateDigits mentre la generazione del tono è in corso interrompe la generazione del tono corrente o la generazione di cifre in corso e avvia la generazione dei nuovi toni o cifre specificati.

Sintassi

LONG TSPIAPI TSPI_lineGenerateTone(
  HDRVCALL                 hdCall,
  DWORD                    dwEndToEndID,
  DWORD                    dwToneMode,
  DWORD                    dwDuration,
  DWORD                    dwNumTones,
  LPLINEGENERATETONE const lpTones
);

Parametri

hdCall

L'handle del provider di servizi per la chiamata alla generazione del tono deve essere eseguita. Lo stato della chiamata di hdCall può essere qualsiasi stato, ad eccezione dell'inattività.

dwEndToEndID

Identificatore univoco non interpretato della richiesta per l'intera durata, ovvero fino all'invio del messaggio di LINE_GENERATE corrispondente. Il provider di servizi include questo identificatore come uno dei parametri del messaggio.

dwToneMode

Definisce il tono da generare. I toni possono essere standard o personalizzati. Un tono personalizzato è costituito da un set di frequenze arbitrarie. Un numero ridotto di toni standard è predefinito. La durata del tono viene specificata da dwDuration per toni standard e personalizzati. Se dwToneMode è impostato su zero, viene annullata qualsiasi generazione di cifre o toni in corso. Questo parametro usa una e solo una delle costanti LINETONEMODE_.

dwDuration

Durata in millisecondi durante la quale il tono viene sostenuto. Un valore pari a 0 per dwDuration usa una durata predefinita per il tono specificato. I valori predefiniti sono:

CUSTOM: infinito

RINGBACK: infinito

OCCUPATO: infinito

BEEP: infinito

FATTURAZIONE: fissa (ciclo singolo)

Questo parametro non viene convalidato da TAPI quando questa funzione viene chiamata.

dwNumTones

Numero di voci nella matrice lpTones . Questo parametro viene ignorato se dwToneMode non è uguale a LINETONEMODE_CUSTOM.

lpTones

Puntatore a una matrice LINEGENERATETONE che specifica i componenti del tono. Questo parametro viene ignorato per i toni noncustom. Se lpTones è un tono multifrequenza, i vari toni vengono riprodotti simultaneamente.

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_NOMEM, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALTONEMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALTONE, LINEERR_RESOURCEUNAVAIL, LINEERR_RESOURCEUNAVAIL.

Commenti

TSPI_lineGenerateTone restituisce zero (esito positivo) quando la generazione del tono viene avviata correttamente; non quando la generazione del tono viene completata. La funzione consente la generazione inband di diversi toni predefiniti, ad esempio ringback, toni occupati e beep. Consente inoltre l'infrastruttura di toni personalizzati specificando le frequenze dei componenti, la cadenza e il volume, se supportata dal provider di servizi. Poiché questi toni vengono generati come toni in banda, la chiamata dovrebbe in genere trovarsi nello stato connesso per la generazione del tono essere efficace. Al termine della generazione del tono o quando la generazione del tono viene annullata, viene inviato un messaggio LINE_GENERATE a TAPI.

Nota Per ogni chiamata è consentita una sola richiesta di generazione inband (generazione di tono o generazione di cifre). Ciò implica che se la generazione del tono è attualmente in corso su una chiamata, richiamando TSPI_lineGenerateDigits o TSPI_lineGenerateTone annulla la generazione del tono. Il provider di servizi deve terminare qualsiasi generazione del tono in corso quando viene richiamata una successiva TSPI_lineGenerateDigits o TSPI_lineGenerateTone funzione.

La funzione corrispondente a livello TAPI non include il parametro formale dwEndToEndID. A questo livello non esiste alcun contrassegno end-to-end. TAPI usa il contrassegno end-to-end a livello TSPI per distinguere una richiesta TSPI_lineGenerateTone da un'altra.