TSPI_lineSetupConference, fonction (tspi.h)

Article
08/26/2023

La fonction TSPI_lineSetupConference configure une téléconférence pour l’ajout du tiers.

Syntaxe

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

Paramètres

dwRequestID

Identificateur de la requête asynchrone.

hdCall

Handle de l’appel initial qui identifie la première partie d’une téléconférence. Dans certains environnements, un appel doit exister pour démarrer une téléconférence. Dans d’autres environnements de téléphonie, aucun appel n’existe initialement et hdCall reste NULL. L’état d’appel de hdCall peut être connecté.

hdLine

Handle de l’appareil de ligne sur lequel la téléconférence doit provenir si hdCall a la valeur NULL. Le paramètre hdLine est ignoré si hdCall n’a pas la valeur NULL. Le fournisseur de services indique le modèle qu’il prend en charge via l’indicateur setupConfNull de la structure de données LINEADDRESSCAPS .

htConfCall

Handle TAPI pour la nouvelle téléconférence. Le fournisseur de services doit l’enregistrer et l’utiliser dans tous les appels suivants à la procédure LINEEVENT rapportant des événements sur le nouvel appel.

lphdConfCall

Pointeur vers un HDRVCALL représentant l’identificateur du fournisseur de services pour la téléconférence nouvellement créée. Le fournisseur de services doit remplir cet emplacement avec son handle pour le nouvel appel avant que cette procédure ne retourne. Ce handle est ignoré par TAPI si la fonction génère une erreur. L’état de l’appel de hdConfCall n’est pas applicable.

htConsultCall

Handle TAPI pour l’appel de consultation. Lors de la configuration d’un appel pour l’ajout d’une nouvelle partie, un nouvel appel temporaire (appel de consultation) est automatiquement alloué. Le fournisseur de services doit enregistrer le htConsultCall et l’utiliser dans tous les appels suivants à la procédure LINEEVENT signalant des événements sur le nouvel appel de consultation.

lphdConsultCall

Pointeur vers un HDRVCALL représentant l’identificateur du fournisseur de services pour un appel. Lors de la configuration d’un appel pour l’ajout d’une nouvelle partie, un nouvel appel temporaire (appel de consultation) est automatiquement alloué. Le fournisseur de services doit remplir cet emplacement avec son handle pour le nouvel appel de consultation avant le retour de cette procédure. Ce handle est ignoré par TAPI si la fonction génère une erreur. L’état de l’appel de hdConsultCall n’est pas applicable.

dwNumParties

Nombre attendu de parties à la téléconférence. Le fournisseur de services est libre de faire avec ce numéro à sa guise. Par exemple, le fournisseur de services peut l’ignorer ou l’utiliser comme indicateur pour allouer le pont de conférence de taille appropriée à l’intérieur du commutateur. TAPI ne valide pas ce paramètre lorsque cette fonction est appelée.

lpCallParams

Pointeur vers une structure LINECALLPARAMS contenant des paramètres d’appel à utiliser lors de l’établissement de l’appel de consultation. Ce paramètre est défini sur NULL si aucun paramètre de configuration d’appel spécial n’est souhaité et si le fournisseur de services utilise des paramètres par défaut.

Valeur retournée

Retourne dwRequestID, ou un numéro d’erreur si une erreur se produit. Le paramètre réel lResult de la ASYNC_COMPLETION correspondante est égal à zéro si la fonction réussit, ou un numéro d’erreur si une erreur se produit. Les valeurs de retour possibles sont les suivantes :

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.

Remarques

Le fournisseur de services retourne LINEERR_INVALLINEHANDLE si le handle de ligne spécifié pour la ligne contenant la téléconférence n’est pas valide. Cette erreur peut également indiquer que l’environnement de téléphonie nécessite une ligne initiale pour configurer une conférence, mais qu’un handle d’appel non NULL a été fourni à la place.

Le fournisseur de services retourne LINEERR_INVALCALLHANDLE si l’environnement de téléphonie nécessite un appel initial pour configurer une conférence, mais qu’un handle d’appel NULL a été fourni à la place.

TSPI_lineSetupConference offre deux façons d’établir une nouvelle téléconférence, selon qu’un appel biparte normal est nécessaire pour préexister ou non. Lors de la configuration d’une téléconférence à partir d’un appel biparte existant, le paramètre hdCall est un handle d’appel valide qui est initialement ajouté à la téléconférence par la demande TSPI_lineSetupConference et hdLine est ignoré. Sur les commutateurs où la configuration de la téléconférence ne commence pas par un appel existant, hdCall doit avoir la valeur NULL et hdLine doit être spécifié pour identifier l’appareil de ligne sur lequel lancer la téléconférence. Dans les deux cas, un appel de consultation est alloué pour la connexion à la partie qui doit être ajoutée à l’appel. TAPI peut utiliser TSPI_lineDial pour composer l’adresse de l’autre partie.

La téléconférence passe généralement à l’état onHoldPendingConference, à l’état de numérotation de l’appel de consultation et à l’appel initial (le cas échéant) à l’état conférence.

Une téléconférence peut également être configurée à l’aide d’une fonction TSPI_lineCompleteTransfer qui est résolue en une conférence triple.

TAPI peut être en mesure de basculer entre l’appel de consultation et la téléconférence à l’aide de TSPI_lineSwapHold.

La fonction TSPI_lineUnhold peut récupérer les appels dont l’état d’appel est onHoldPendingConference. Si cette opération est effectuée, tout appel de consultation passe généralement à l’état inactif .

Un appel de consultation peut être annulé en appelant TSPI_lineDrop sur celui-ci. Lors de la suppression d’un appel de consultation, la téléconférence existante revient généralement à l’état connecté . TAPI et ses applications clientes doivent observer les messages LINE_CALLSTATE pour déterminer exactement ce qui se passe aux appels. Par exemple, si la téléconférence revient à un appel régulier à deux parties, la téléconférence devient inactive et l’appel du participant d’origine peut revenir à la connexion.

Cette fonction diffère de la fonction TAPI correspondante en ce qu’elle suit le modèle TSPI pour commencer la durée de vie d’un appel. TAPI et le fournisseur de services échangent des handles opaques représentant l’appel entre eux. En outre, le fournisseur de services est autorisé à effectuer des rappels pour le nouvel appel avant qu’il ne revienne de cette procédure. Dans tous les cas, le fournisseur de services doit également traiter le handle qu’il a retourné comme « non encore valide » jusqu’à ce que le message de ASYNC_COMPLETION correspondant signale la réussite. En d’autres termes, il ne doit pas émettre de messages LINEEVENT pour le nouvel appel ou l’inclure dans le nombre d’appels dans les messages ou status structures de données pour la ligne.