funzione TSPI_lineSetupConference (tspi.h)

Articolo
08/26/2023

La funzione TSPI_lineSetupConference configura una conferenza telefonica per l'aggiunta della terza parte.

Sintassi

LONG TSPIAPI TSPI_lineSetupConference(
  DRV_REQUESTID          dwRequestID,
  HDRVCALL               hdCall,
  HDRVLINE               hdLine,
  HTAPICALL              htConfCall,
  LPHDRVCALL             lphdConfCall,
  HTAPICALL              htConsultCall,
  LPHDRVCALL             lphdConsultCall,
  DWORD                  dwNumParties,
  LPLINECALLPARAMS const lpCallParams
);

Parametri

dwRequestID

Identificatore della richiesta asincrona.

hdCall

Handle per la chiamata iniziale che identifica la prima parte di una conferenza telefonica. In alcuni ambienti, è necessario che esista una chiamata per avviare una conferenza telefonica. In altri ambienti di telefonia non esiste inizialmente alcuna chiamata e hdCall viene lasciato NULL. Lo stato della chiamata di hdCall può essere connesso.

hdLine

Handle per il dispositivo line in cui originare la conferenza telefonica se hdCall è NULL. Il parametro hdLine viene ignorato se hdCall è diverso da NULL. Il provider di servizi segnala il modello supportato tramite il flag setupConfNull della struttura di dati LINEADDRESSCAPS .

htConfCall

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

lphdConfCall

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

htConsultCall

Il TAPI gestisce la chiamata di consultazione. Quando si configura una chiamata per l'aggiunta di una nuova parte, viene automaticamente allocata una nuova chiamata temporanea (chiamata di consultazione). Il provider di servizi deve salvare il htConsultCall 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 una chiamata. Quando si configura una chiamata per l'aggiunta di una nuova parte, viene automaticamente allocata una nuova chiamata temporanea (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.

dwNumParties

Numero previsto di parti nella conferenza telefonica. Il provider di servizi è libero di eseguire questa operazione con questo numero in quanto lo si desidera. Ad esempio, il provider di servizi può ignorarlo o usarlo come suggerimento per allocare il bridge conferenza di dimensioni corretto all'interno dell'opzione. TAPI non convalida questo parametro quando viene chiamata questa funzione.

lpCallParams

Puntatore a una struttura LINECALLPARAMS contenente parametri di chiamata da utilizzare per stabilire la chiamata di consultazione. Questo parametro è impostato su NULL se non sono desiderati parametri speciali di installazione delle chiamate e il provider di servizi usa i parametri predefiniti.

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

Commenti

Il provider di servizi restituisce LINEERR_INVALLINEHANDLE se l'handle di riga specificato per la riga contenente la conferenza telefonica non è valida. Questo errore può anche indicare che l'ambiente di telefonia richiede una riga iniziale per configurare una conferenza, ma è stato fornito un handle di chiamata non NULL .

Il provider di servizi restituisce LINEERR_INVALCALLHANDLE se l'ambiente di telefonia richiede una chiamata iniziale per configurare una conferenza, ma è stato fornito un handle di chiamata NULL .

TSPI_lineSetupConference fornisce due modi per stabilire una nuova conferenza telefonica, a seconda che sia necessaria o meno una normale chiamata bidirezionale. Quando si configura una conferenza telefonica da una chiamata a due parti esistente, il parametro hdCall è un handle di chiamata valido che viene inizialmente aggiunto alla conferenza telefonica dalla richiesta di TSPI_lineSetupConference e hdLine viene ignorato. Nei commutatori in cui la configurazione della conferenza telefonica non inizia con una chiamata esistente, hdCall deve essere NULL e hdLine deve essere specificato per identificare il dispositivo line in cui avviare la conferenza telefonica. In entrambi i casi, viene allocata una chiamata di consultazione per la connessione alla parte che deve essere aggiunta alla chiamata. TAPI può usare TSPI_lineDial per comporre l'indirizzo dell'altra parte.

La conferenza telefonica passa in genere allo stato onHoldPendingConference, lo stato dialtone della chiamata di consultazione e la chiamata iniziale (se 1) allo stato conferenza.

È anche possibile configurare una conferenza telefonica usando una funzione TSPI_lineCompleteTransfer risolta in una conferenza a tre vie.

TAPI può essere in grado di alternare tra la chiamata di consultazione e la conferenza telefonica utilizzando TSPI_lineSwapHold.

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

Una chiamata di consultazione può essere annullata richiamando TSPI_lineDrop su di esso. Quando si elimina una chiamata di consultazione, in genere la chiamata di conferenza esistente torna allo stato connesso . TAPI e le relative applicazioni client devono osservare i messaggi LINE_CALLSTATE per determinare esattamente cosa accade alle chiamate. Ad esempio, se la chiamata alla conferenza torna a una normale chiamata a due parti, la chiamata alla conferenza diventa inattiva e la chiamata del partecipante originale può tornare alla connessione.

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.