funzione lineMakeCall (tapi.h)

Articolo
08/26/2023

La funzione lineMakeCall inserisce una chiamata sulla riga specificata all'indirizzo di destinazione specificato. Facoltativamente, è possibile specificare parametri di chiamata se sono richiesti parametri di configurazione delle chiamate predefinite.

Sintassi

LONG lineMakeCall(
  HLINE                  hLine,
  LPHCALL                lphCall,
  LPCSTR                 lpszDestAddress,
  DWORD                  dwCountryCode,
  LPLINECALLPARAMS const lpCallParams
);

Parametri

hLine

Gestire il dispositivo della riga aperta in cui deve essere originata una chiamata.

lphCall

Puntatore a un handle HCALL. L'handle è valido solo dopo che il messaggio LINE_REPLY viene ricevuto dall'applicazione che indica che la funzione lineMakeCall è stata completata correttamente. Usare questo handle per identificare la chiamata quando si richiamano altre operazioni di telefonia sulla chiamata. L'applicazione è inizialmente l'unico proprietario di questa chiamata. Questo handle è void se la funzione restituisce un errore (in modo sincrono o asincrono dal messaggio di risposta).

lpszDestAddress

Puntatore all'indirizzo di destinazione. Questo segue il formato numero chiamabile standard. Questo puntatore può essere NULL per gli indirizzi non visualizzati (come con un telefono frequente) o quando viene eseguita tutta la composizione usando lineDial. In quest'ultimo caso, lineMakeCall alloca un aspetto di chiamata disponibile che in genere rimane nello stato di dialtone fino all'inizio della chiamata. I provider di servizi con funzionalità multiplexing inversa possono consentire a un'applicazione di specificare più indirizzi contemporaneamente.

dwCountryCode

Codice paese o area geografica della parte denominata. Se viene specificato un valore pari a 0, viene usato un valore predefinito dall'implementazione.

lpCallParams

Puntatore a una struttura LINECALLPARAMS . Questa struttura consente all'applicazione di specificare la modalità di configurazione della chiamata. Se viene specificato NULL , viene stabilita una chiamata vocale predefinita 3.1 kHz e viene selezionato un indirizzo di origine arbitrario nella riga. Questa struttura consente all'applicazione di selezionare elementi come la modalità di connessione della chiamata, la frequenza dei dati, la modalità multimediale prevista, l'indirizzo di origine, il blocco delle informazioni sull'ID chiamante e i parametri di composizione.

Valore restituito

Restituisce un identificatore di richiesta positivo se la funzione viene completata in modo asincrono o un numero di errore negativo se si verifica un errore. Il parametro dwParam2 del messaggio di LINE_REPLY corrispondente è zero se la funzione ha esito positivo o è un numero di errore negativo se si verifica un errore. I valori restituiti possibili sono:

LINEERR_ADDRESSBLOCKED, LINEERR_INVALLINEHANDLE, LINEERR_BEARERMODEUNAVAIL, LINEERR_INVALLINESTATE, LINEERR_CALLUNAVAIL, LINEERR_INVALMEDIAMODE, LINEERR_DIALBILLING, LINEERR_INVALPARAM, LINEERR_DIALDIALTONE, LINEERR_INVALPOINTER, LINEERR_DIALPROMPT, LINEERR_INVALRATE, LINEERR_DIALQUIET, LINEERR_NOMEM, LINEERR_INUSE, LINEERR_OPERATIONFAILED, LINEERR_INVALADDRESS, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESSID, LINEERR_RATEUNAVAIL, LINEERR_INVALADDRESSMODE, LINEERR_ RESOURCEUNAVAIL, LINEERR_INVALBEARERMODE, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALCALLPARAMS, LINEERR_UNINITIALIZED, LINEERR_INVALCOUNTRYCODE, LINEERR_USERUSERINFOTOOBIG.

Commenti

Se LINEERR_INVALLINESTATE viene restituito, la riga non è attualmente in uno stato in cui è possibile eseguire questa operazione. Un elenco di operazioni attualmente valide è disponibile nel membro dwLineFeatures (del tipo LINEFEATURE_) nella struttura LINEDEVSTATUS . La chiamata a lineGetLineDevStatus aggiorna le informazioni in LINEDEVSTATUS. Se LINEERR_DIALBILLING, LINEERR_DIALQUIET, LINEERR_DIALDIALTONE o LINEERR_DIALPROMPT viene restituito, nessuna delle azioni eseguite da lineMakeCall è stata eseguita; Ad esempio, nessuno dell'indirizzo chiamabile prima del carattere offensivo è stato composto, non è stato modificato lo stato hookswitch e così via.

Dopo aver completato la composizione, diversi messaggi LINE_CALLSTATE vengono in genere inviati all'applicazione per notificarlo sullo stato di avanzamento della chiamata. Non viene specificata in genere una sequenza valida di transizioni con stato di chiamata, perché non è possibile garantire una singola sequenza fissa di transizioni. Una sequenza tipica può causare la transizione di una chiamata da dialtone, composizione, procedura, ringback, alla connessione. Con righe non chiamate, la chiamata può in genere passare direttamente allo stato connesso .

Un'applicazione ha l'opzione per specificare un indirizzo di origine nel dispositivo riga specificato. Un provider di servizi che modella tutte le stazioni su un commutatore come indirizzi in un singolo dispositivo linea consente all'applicazione di originare chiamate da una di queste stazioni usando lineMakeCall.

I parametri di chiamata consentono all'applicazione di effettuare chiamate non vocali o richiedere opzioni di configurazione delle chiamate speciali non disponibili per impostazione predefinita.

Un'applicazione può comporre parzialmente usando lineMakeCall e continuare a comporre usando lineDial. Per altre informazioni sulla composizione parziale, vedere lineDial e TSPI_lineMakeCall. Per abbandonare un tentativo di chiamata, usare lineDrop.

Dopo che lineMakeCall restituisce un messaggio di risposta riuscita all'applicazione, viene inviato un messaggio LINE_CALLSTATE all'applicazione per indicare lo stato corrente della chiamata. Questo stato non è necessariamente LINECALLSTATE_DIALTONE.

Questa funzione può inviare dati attraverso il cavo in formato non crittografato; pertanto, un utente che esegue l'intercettazione sulla rete può essere in grado di leggere i dati. Il rischio di sicurezza di inviare i dati in testo chiaro deve essere considerato prima di usare questo metodo.

Attenzione TAPI scriverà i dati restituiti nel buffer a cui fa riferimento lphCall quando viene restituito il messaggio di LINE_REPLY. Ciò significa che il buffer deve rimanere valido finché non viene restituito il messaggio LINE_REPLY; in caso contrario, il danneggiamento dei dati e le eccezioni possono verificarsi.