funzione TSPI_lineSetupTransfer (tspi.h)

Articolo
08/26/2023

La funzione TSPI_lineSetupTransfer avvia un trasferimento della chiamata specificata da hdCall. Stabilisce una chiamata di consultazione, lphdConsultCall, su cui la parte può essere composta che può diventare la destinazione del trasferimento.

Sintassi

LONG TSPIAPI TSPI_lineSetupTransfer(
  DRV_REQUESTID          dwRequestID,
  HDRVCALL               hdCall,
  HTAPICALL              htConsultCall,
  LPHDRVCALL             lphdConsultCall,
  LPLINECALLPARAMS const lpCallParams
);

Parametri

dwRequestID

Identificatore della richiesta asincrona.

hdCall

Handle della chiamata da trasferire. Lo stato della chiamata di hdCall può essere connesso.

htConsultCall

L'handle TAPI per la nuova chiamata di consultazione temporanea. Il provider di servizi deve salvarlo e usarlo in tutte le chiamate successive alla procedura LINEEVENT che segnala gli eventi sulla nuova chiamata di consultazione.

lphdConsultCall

Puntatore a un HDRVCALL che rappresenta l'identificatore del provider di servizi per la nuova chiamata di consultazione. Il provider di servizi deve riempire questa posizione con il relativo handle per la nuova chiamata di consultazione prima che questa procedura venga restituita. Questo handle viene ignorato da TAPI se la funzione genera un errore. Lo stato della chiamata di hdConsultCall non è applicabile.

Quando si imposta una chiamata per il trasferimento, viene allocata automaticamente un'altra chiamata (una chiamata di consultazione) per consentire all'applicazione (tramite TAPI) di comporre l'indirizzo (utilizzando TSPI_lineDial) della parte a cui deve essere trasferita la chiamata. La parte di origine può proseguire una conversazione su questa chiamata di consultazione prima di completare il trasferimento.

Questa procedura di trasferimento potrebbe non essere valida per alcuni dispositivi line. Invece di chiamare questa procedura, TAPI potrebbe dover trattenere una chiamata esistente (utilizzando TSPI_lineUnhold) per identificare la destinazione del trasferimento. Nei commutatori che supportano il trasferimento di chiamate tra indirizzi, la chiamata di consultazione può esistere su un indirizzo diverso rispetto alla chiamata da trasferire. Può inoltre essere necessario configurare la chiamata di consultazione come chiamata completamente nuova utilizzando TSPI_lineMakeCall, alla destinazione del trasferimento.

I flag transferHeld e transferMake nella struttura dei dati LINEADDRESSCAPS segnalano il modello usato dal provider di servizi.

lpCallParams

Puntatore a una struttura LINECALLPARAMS contenente parametri di chiamata da utilizzare per stabilire la chiamata di consultazione. Questo parametro può essere impostato su NULL se non sono desiderati parametri speciali di installazione delle chiamate (il provider di servizi usa le impostazioni predefinite).

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_INVALCALLHANDLE, LINEERR_INVALBEARERMODE, LINEERR_INVALCALLSTATE, LINEERR_INVALRATE, LINEERR_CALLUNAVAIL, LINEERR_INVALCALLPARAMS, LINEERR_NOMEM, LINEERR_INVALLINESTATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALMEDIAMODE, LINEERR_OPERATIONFAILED, LINEERR_INUSE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_BEARERMODEUNAVAIL, LINEERR_RATEUNAVAIL, LINEERR_INVALADDRESSMODE, LINEERR_USERUSERINFOTOOBIG.

Commenti

Il provider di servizi restituisce LINEERR_INVALCALLSTATE se la chiamata da trasferire non è in uno stato valido.

Questa operazione configura il trasferimento della chiamata specificata da hdCall. La fase di configurazione di un trasferimento stabilisce una chiamata di consultazione per inviare l'indirizzo della destinazione (la parte a cui essere trasferito) al commutatore, mentre la chiamata da trasferire viene mantenuta in attesa. Questa nuova chiamata è detta chiamata di consultazione (hdConsultCall) e può essere modificata (ad esempio, eliminata) indipendentemente dalla chiamata originale.

Quando la chiamata di consultazione ha raggiunto lo stato di chiamata dialtone , TAPI può continuare a trasferire la chiamata componendo l'indirizzo di destinazione e monitorandone lo stato di avanzamento oppure annullando una chiamata esistente. Il trasferimento della chiamata originale alla destinazione selezionata viene completato utilizzando TSPI_lineCompleteTransfer.

Mentre esiste la chiamata di consultazione, la chiamata originale passa in genere allo stato onholdPendingTransfer .

La funzione TSPI_lineUnhold può ripristinare le chiamate con lo stato della chiamata onHoldPendingTransfer. In questo caso, qualsiasi chiamata di consultazione passa in genere allo stato inattivo .

Negli ambienti di telefonia che seguono i modelli di trasferimento TransferHeld o transferMake , questa procedura restituisce LINEERR_OPERATIONFAILED e non alloca un handle di chiamata di consultazione.

Una chiamata di consultazione può essere annullata richiamando TSPI_lineDrop su di esso. Dopo l'eliminazione di una chiamata di consultazione, la chiamata originale viene in genere riconnessa allo stato connesso .

Questa funzione è diversa dalla funzione TAPI corrispondente in quanto segue il modello TSPI per iniziare la durata di una chiamata. TAPI e il provider di servizi scambiano handle opachi che rappresentano la chiamata tra loro. Inoltre, il provider di servizi è autorizzato a eseguire callback per la nuova chiamata prima che venga restituito da questa procedura. In ogni caso, il provider di servizi deve anche considerare l'handle restituito come "non ancora valido" fino a quando il messaggio corrispondente ASYNC_COMPLETION segnala l'esito positivo. In altre parole, non deve emettere alcun messaggio LINEEVENT per la nuova chiamata o includerlo nei conteggi delle chiamate in messaggi o strutture di dati di stato per la riga.