TSPI_lineSetupTransfer, fonction (tspi.h)

Article
08/26/2023

La fonction TSPI_lineSetupTransfer lance un transfert de l’appel spécifié par hdCall. Il établit un appel de consultation, lphdConsultCall, sur lequel la partie peut être appelée et qui peut devenir la destination du transfert.

Syntaxe

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

Paramètres

dwRequestID

Identificateur de la requête asynchrone.

hdCall

Handle de l’appel à transférer. L’état d’appel de hdCall peut être connecté.

htConsultCall

Le handle TAPI pour le nouvel appel de consultation temporaire. Le fournisseur de services doit l’enregistrer et l’utiliser dans tous les appels ultérieurs à la procédure LINEEVENT rapportant des événements sur le nouvel appel de consultation.

lphdConsultCall

Pointeur vers un HDRVCALL représentant l’identificateur du fournisseur de services pour le nouvel appel de consultation. 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.

Lors de la configuration d’un appel pour transfert, un autre appel (appel de consultation) est automatiquement alloué pour permettre à l’application (via TAPI) de composer l’adresse (à l’aide de TSPI_lineDial) de la partie vers laquelle l’appel doit être transféré. La partie d’origine peut poursuivre une conversation au cours de cet appel de consultation avant de terminer le transfert.

Cette procédure de transfert peut ne pas être valide pour certains appareils de ligne. Au lieu d’appeler cette procédure, TAPI peut avoir besoin de détenir un appel détenu existant (à l’aide de TSPI_lineUnhold) pour identifier la destination du transfert. Sur les commutateurs qui prennent en charge le transfert d’appels inter-adresses, l’appel de consultation peut exister sur une adresse différente de l’appel à transférer. Il peut également être nécessaire de configurer l’appel de consultation comme un appel entièrement nouveau à l’aide de TSPI_lineMakeCall, à la destination du transfert.

Les indicateurs transferHeld et transferMake dans la structure de données LINEADDRESSCAPS indiquent le modèle utilisé par le fournisseur de services.

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 peut être défini sur NULL si aucun paramètre de configuration d’appel spécial n’est souhaité (le fournisseur de services utilise les valeurs 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_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.

Remarques

Le fournisseur de services retourne LINEERR_INVALCALLSTATE si l’appel à transférer n’est pas dans un état valide.

Cette opération configure le transfert de l’appel spécifié par hdCall. La phase de configuration d’un transfert établit un appel de consultation pour envoyer l’adresse de la destination (la partie à transférer) au commutateur, tandis que l’appel à transférer est maintenu en attente. Ce nouvel appel est appelé appel de consultation (hdConsultCall) et peut être manipulé (par exemple, supprimé) indépendamment de l’appel d’origine.

Lorsque l’appel de consultation a atteint l’état de l’appel de numérotation , TAPI peut continuer à transférer l’appel soit en composant l’adresse de destination et en suivant sa progression, soit en détenir un appel existant. Le transfert de l’appel d’origine vers la destination sélectionnée est effectué à l’aide de TSPI_lineCompleteTransfer.

Bien que l’appel de consultation existe, l’appel d’origine passe généralement à l’état onholdPendingTransfer .

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

Dans les environnements de téléphonie qui suivent les modèles de transfert transferHeld ou transferMake , cette procédure retourne LINEERR_OPERATIONFAILED et n’alloue pas de handle d’appel de consultation.

Un appel de consultation peut être annulé en appelant TSPI_lineDrop sur celui-ci. Après avoir supprimé un appel de consultation, l’appel d’origine revient généralement à l’état connecté .

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.