funzione TSPI_lineMakeCall (tspi.h)

Articolo
08/26/2023

La funzione TSPI_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 TSPIAPI TSPI_lineMakeCall(
  DRV_REQUESTID          dwRequestID,
  HDRVLINE               hdLine,
  HTAPICALL              htCall,
  LPHDRVCALL             lphdCall,
  LPCWSTR                lpszDestAddress,
  DWORD                  dwCountryCode,
  LPLINECALLPARAMS const lpCallParams
);

Parametri

dwRequestID

Identificatore della richiesta asincrona.

hdLine

Handle alla riga in cui deve essere originata la nuova chiamata.

htCall

Handle TAPI alla nuova chiamata. Il provider di servizi deve salvarlo e usarlo in tutte le chiamate successive agli eventi di segnalazione delle procedure LINEEVENT nella chiamata.

lphdCall

Puntatore a un handle di chiamata. Il provider di servizi deve riempire questa posizione con il relativo handle per la chiamata prima che questa procedura venga restituita. Questo handle viene ignorato da TAPI se la funzione genera un errore.

lpszDestAddress

Puntatore a una stringa Unicode con terminazione null che specifica l'indirizzo di destinazione. Questo segue il formato numero chiamabile standard. Questo puntatore può essere specificato come NULL per gli indirizzi non connessi (come con un telefono frequente, che si connette sempre a un numero predefinito) o quando viene eseguita tutta la composizione usando TSPI_lineDial. In quest'ultimo caso , TSPI_lineMakeCall alloca un aspetto della chiamata disponibile che in genere rimane nello stato del 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 chiamata. Se viene specificato un valore pari a 0, viene usato un valore predefinito dall'implementazione.

lpCallParams

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

Valore restituito

Restituisce dwRequestID o un numero di errore se si verifica un errore. Il parametro effettivo lResult del ASYNC_COMPLETION corrispondente è 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_ADDRESSBLOCKED, LINEERR_INVALLINESTATE, LINEERR_BEARERMODEUNAVAIL, LINEERR_INVALRATE, LINEERR_CALLUNAVAIL, LINEERR_INVALLINEHANDLE, LINEERR_DIALBILLING, LINEERR_INVALADDRESS, LINEERR_DIALQUIET, LINEERR_INVALADDRESSID, LINEERR_DIALDIALTONE, LINEERR_INVALCALLPARAMS, LINEERR_DIALPROMPT, LINEERR_NOMEM, LINEERR_INUSE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESSMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALBEARERMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_ INVALCOUNTRYCODE, LINEERR_RATEUNAVAIL, LINEERR_INVALMEDIAMODE, LINEERR_USERUSERINFOTOOBIG.

Commenti

Il provider di servizi restituisce LINEERR_INVALLINESTATE se 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 TSPI_lineGetLineDevStatus aggiorna le informazioni in LINEDEVSTATUS.

Se il provider di servizi restituisce LINEERR_DIALBILLING, LINEERR_DIALQUIET, LINEERR_DIALDIALTONE o LINEERR_DIALPROMPT, deve eseguire nessuna delle azioni eseguite da TSPI_lineMakeCall. Ad esempio, nessuna composizione parziale e nessuna uscita. Questo perché il provider di servizi deve eseguire prima l'analisi del numero per i caratteri non supportati.

Dopo TSPI_lineMakeCall restituisce un messaggio di callback di risposta SUCCESS all'applicazione, il provider di servizi deve inviare LINE_CALLSTATE messaggi all'TSPI_lineOpen lpfnEventProcpassato per notificare a TAPI lo stato di avanzamento della chiamata. Una tipica sequenza segnalata può essere tono di chiamata, composizione, procedura, ringback e connessione; Il primo stato segnalato non è necessariamente LINECALLSTATE_DIALTONE. Il provider di servizi sceglie quanti stati vengono segnalati. È consigliabile inviare il maggior numero possibile di applicazioni in modo che le applicazioni possano intraprendere azioni appropriate.

Il provider di servizi esegue inizialmente il monitoraggio multimediale sulla nuova chiamata per almeno il set di tipi di supporti monitorati per la riga.

Se la stringa di composizione è NULL, il provider di servizi accetta la riga allo stato di dialtone (per un provider di servizi basato su Comm, ciò implica ATD) e invia un messaggio di stato di chiamata che indica LINECALLSTATE_DIALTONE.

Se la stringa di composizione termina in ';' (un punto e virgola), il provider di servizi chiama il numero parziale e invia il messaggio di LINECALLSTATE_DIALING. Questa chiamata viene completata dalle chiamate a TSPI_lineDial.

Se la stringa di composizione contiene caratteri (W, @, $, ?) non supportati dal provider di servizi, il provider di servizi deve analizzare la stringa di composizione e restituire (in modo sincrono) un errore corrispondente al primo carattere non valido.

Se il flag di LINECALLPARAMFLAGS_IDLE è impostato, il provider di servizi deve controllare lo stato della riga corrente (equivalente all'uscita dal gancio e al tono di rilevamento). Se questo flag IDLE è impostato e non esiste un tono di chiamata, la funzione ha esito negativo con l'errore LINEERR_CALLUNAVAIL. Se il flag IDLE non è impostato o esiste un tono di composizione, la composizione può continuare.

Questa funzione differisce dalla funzione TAPI corrispondente in cui segue il modello TSPI per iniziare la durata di una chiamata. TAPI e gli handle opachi del provider di servizi che rappresentano la chiamata tra loro. Inoltre, il provider di servizi è autorizzato a eseguire callback per la nuova chiamata prima di restituire da questa procedura. In qualsiasi caso, il provider di servizi deve anche considerare l'handle restituito come "non ancora valido" fino a quando la corrispondenza ASYNC_COMPLETION messaggio segnala l'esito positivo. Non deve inviare messaggi LINEEVENT per la nuova chiamata o includerlo nei conteggi delle chiamate nei messaggi o nelle strutture di dati di stato per la riga.