funzione lineGenerateDigits (tapi.h)

Articolo
03/08/2023

La funzione lineGenerateDigits avvia la generazione delle cifre specificate nella chiamata specificata come toni in banda usando la modalità di segnalazione specificata. La chiamata a questa funzione con un valore NULL per lpszDigits interrompe qualsiasi generazione di cifre attualmente in corso. Richiamando lineGenerateDigits o lineGenerateTone mentre la generazione di cifre è in corso interrompe la generazione di cifre o la generazione del tono corrente e avvia la generazione delle cifre o del tono specificati più di recente.

Sintassi

LONG lineGenerateDigits(
  HCALL  hCall,
  DWORD  dwDigitMode,
  LPCSTR lpszDigits,
  DWORD  dwDuration
);

Parametri

hCall

Gestire la chiamata. L'applicazione deve essere un proprietario della chiamata. Lo stato di chiamata di hCall può essere qualsiasi stato. TAPI non impone requisiti di callstate, tuttavia alcuni provider di servizi Tapi potrebbero richiedere che l'hCall sia nello stato LINECALLSTATE_CONNECTED.

dwDigitMode

Formato da usare per segnalare queste cifre. Tenere presente che dwDigitMode può avere solo un singolo set di flag. Questo parametro usa una delle costanti LINEDIGITMODE_.

lpszDigits

Puntatore a un buffer di caratteri con terminazione null contenente le cifre da generare. I caratteri validi sono quelli specificati per le costanti LINEDIGITMODE_ fornite in dwDigitModes.

Inoltre, la virgola (,) è anche un carattere valido. Una virgola inserisce un ritardo aggiuntivo tra il segnale del precedente e le cifre successive separate. La durata di questa pausa è definita dalla configurazione e le funzionalità del dispositivo linea indicano questa durata. È possibile usare più virgole per inserire pause più lunghe. Le cifre non valide vengono ignorate durante la generazione, anziché essere segnalate come errori.

L'esclamazione (!) è un carattere valido. Questo carattere causa un'operazione "hookflash", come descritto per gli indirizzi dialable.

dwDuration

Entrambe la durata in millisecondi di cifre DTMF e di spaziatura tra cifre DTMF e DTMF. Un valore pari a 0 usa un valore predefinito. Il parametro dwDuration deve essere compreso nell'intervallo specificato da MinDialParams e MaxDialParams in LINEDEVCAPS. Se non è compreso nell'intervallo, il valore effettivo è impostato sul valore più vicino nell'intervallo.

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_INVALDIGITMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALPOINTER, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.

Commenti

La funzione lineGenerateDigits viene considerata completata correttamente quando la generazione di cifre è stata avviata correttamente, non quando vengono generate tutte le cifre. Al contrario di lineDial, che chiama cifre in modo dipendente dalla rete, lineGenerateDigits garantisce di produrre le cifre come toni in banda sul canale vocale usando impulsi DTMF o hookswitch quando si usa l'impulso. La funzione lineGenerateDigits in genere non è adatta per effettuare chiamate o comporre. È destinato alla segnalazione end-to-end su una chiamata stabilita.

Dopo aver generato tutte le cifre in lpszDigits o dopo l'interruzione o l'annullamento della generazione di cifre, 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. La generazione di cifre in una chiamata viene annullata avviando un'altra richiesta di generazione di cifre o una richiesta di generazione del tono. Per annullare la generazione di cifre correnti, l'applicazione può richiamare lineGenerateDigits e specificare NULL per il parametro lpszDigits .

A seconda del provider di servizi e dell'hardware, l'applicazione può monitorare le cifre generate. In caso contrario, l'applicazione può disabilitare il monitoraggio delle cifre durante la generazione di cifre.