funzione lineGenerateTone (tapi.h)

Articolo
08/26/2023

La funzione lineGenerateTone genera il tono di banda specificato sulla chiamata specificata. Richiamando questa funzione con zero per dwToneMode interrompe la generazione del tono attualmente in corso nella chiamata specificata. Richiamando lineGenerateTone o lineGenerateDigits mentre la generazione del tono è in corso interrompe la generazione o la generazione di cifre del tono corrente e avvia la generazione del tono o delle cifre appena specificate.

Sintassi

LONG lineGenerateTone(
  HCALL                    hCall,
  DWORD                    dwToneMode,
  DWORD                    dwDuration,
  DWORD                    dwNumTones,
  LPLINEGENERATETONE const lpTones
);

Parametri

hCall

Gestire la chiamata in cui deve essere generato un tono. L'applicazione deve essere un proprietario della chiamata. Lo stato della chiamata di hCall può essere qualsiasi stato.

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 con dwDuration per toni standard e personalizzati. Il parametro dwToneMode può avere un solo set di bit. Se non vengono impostati bit (il valore 0 viene passato), la generazione del tono viene annullata. Questo parametro usa una delle costanti LINETONEMODE_.

dwDuration

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

CUSTOM: il tono viene sostenuto fino a quando non viene chiuso, in genere dall'interazione dell'utente o da un timeout dell'attrezzatura.

RINGBACK: il tono viene sostenuto fino a quando non viene chiuso, in genere dall'interazione dell'utente o da un timeout dell'attrezzatura.

OCCUPATO: il tono viene sostenuto fino a quando non viene chiuso, in genere dall'interazione dell'utente o da un timeout dell'attrezzatura.

BEEP: il tono viene sostenuto fino a quando non viene chiuso, in genere dall'interazione dell'utente o da un timeout dell'attrezzatura.

FATTURAZIONE: fissa (ciclo singolo).

dwNumTones

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

lpTones

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

Valore restituito

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

LINEERR_INVALCALLHANDLE, LINEERR_NOTOWNER, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALPOINTER, LINEERR_OPERATIONFAILED, LINEERR_INVALTONEMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALTONE, LINEERR_UNINITIALIZED, LINEERR_NOMEM.

Commenti

La funzione lineGenerateTone viene considerata completata correttamente quando la generazione del tono è stata avviata correttamente, non al termine della generazione del tono. La funzione consente la generazione inband di diversi toni predefiniti, ad esempio ringback, toni occupati e beep. Consente inoltre di fabbricare toni personalizzati specificando le frequenze dei componenti, la cadenza e il volume. 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 di LINE_GENERATE all'applicazione.

Una sola richiesta di generazione inband (generazione di tono o generazione di cifre) può essere in corso per ogni chiamata in tutte le applicazioni che sono proprietari della chiamata. Ciò implica che se la generazione del tono è attualmente in corso su una chiamata, richiamando lineGenerateDigits annulla la generazione del tono.

Se viene restituito il valore di errore LINEERR_INVALPOINTER, il parametro lpTones specificato non è valido o il valore specificato dal parametro dwNumTones è troppo grande.