TSPI_lineForward, fonction (tspi.h)

Article
08/26/2023

La fonction TSPI_lineForward transfère les appels destinés à l’adresse spécifiée sur la ligne spécifiée, conformément aux instructions de transfert spécifiées. Lorsqu’une adresse d’origine (dwAddressID) est transférée, les appels entrants spécifiés pour cette adresse sont déviés vers l’autre numéro par le commutateur. Cette fonction fournit une combinaison de fonctionnalités de transfert et de ne pas déranger. Cette fonction peut également annuler le transfert spécifique actuellement en vigueur.

Syntaxe

LONG TSPIAPI TSPI_lineForward(
  DRV_REQUESTID           dwRequestID,
  HDRVLINE                hdLine,
  DWORD                   bAllAddresses,
  DWORD                   dwAddressID,
  LPLINEFORWARDLIST const lpForwardList,
  DWORD                   dwNumRingsNoAnswer,
  HTAPICALL               htConsultCall,
  LPHDRVCALL              lphdConsultCall,
  LPLINECALLPARAMS const  lpCallParams
);

Paramètres

dwRequestID

Identificateur de la requête asynchrone.

hdLine

Handle du fournisseur de services vers la ligne à transférer.

bAllAddresses

Spécifie si toutes les adresses d’origine sur la ligne ou uniquement celles spécifiées doivent être transférées. Si la valeur est TRUE, toutes les adresses sur la ligne sont transférées et dwAddressID est ignoré ; si la valeur est FALSE, seule l’adresse spécifiée en tant que dwAddressID est transférée. Ce paramètre n’est pas validé par TAPI lorsque cette fonction est appelée.

dwAddressID

Adresse sur la ligne spécifiée dont les appels entrants doivent être transférés. Ce paramètre est ignoré si bAllAddresses a la valeur TRUE. Ce paramètre n’est pas validé par TAPI lorsque cette fonction est appelée.

Un identificateur d’adresse est associé de manière permanente à une adresse ; l’identificateur reste constant entre les mises à niveau du système d’exploitation.

lpForwardList

Pointeur vers une structure de données de taille variable de type LINEFORWARDLIST qui décrit les instructions de transfert spécifiques.

dwNumRingsNoAnswer

Spécifie le nombre d’anneaux avant qu’un appel entrant ne soit considéré comme « aucune réponse ». Si dwNumRingsNoAnswer est hors plage, la valeur réelle est définie sur la valeur la plus proche dans la plage autorisée. Ce paramètre n’est pas validé par TAPI lorsque cette fonction est appelée.

htConsultCall

Handle TAPI pour un nouvel appel, si un tel appel doit être créé par le fournisseur de services. Dans certains environnements de téléphonie, le transfert d’un appel a pour effet secondaire de créer un appel de consultation utilisé pour consulter la partie à laquelle l’appel est transféré. Dans un tel environnement, le fournisseur de services crée l’appel de consultation et doit enregistrer cette valeur et l’utiliser dans tous les appels suivants à la procédure LINEEVENT rapportant des événements sur l’appel. Si aucun appel de consultation n’est créé, cette valeur peut être ignorée par le fournisseur de services.

lphdConsultCall

Pointeur vers un HDRVCALL représentant l’identificateur du fournisseur de services pour l’appel. Dans les environnements de téléphonie où le transfert d’un appel a pour effet secondaire de créer un appel de consultation utilisé pour consulter la partie vers laquelle le transfert est effectué, le fournisseur de services doit remplir cet emplacement avec son handle pour l’appel avant que cette procédure ne retourne. Le fournisseur de services est autorisé à effectuer des rappels concernant le nouvel appel avant qu’il ne revienne de cette procédure. Si aucun appel de consultation n’est créé, le HDRVCALL doit avoir la valeur NULL.

lpCallParams

Pointeur vers une structure de type LINECALLPARAMS. Ce pointeur est ignoré par le fournisseur de services, sauf si lineForward nécessite l’établissement d’un appel vers la destination de transfert (et lphdConsultCall est retourné, auquel cas lpCallParams est facultatif). Si la valeur est NULL, les paramètres d’appel par défaut sont utilisés. Sinon, les paramètres d’appel spécifiés sont utilisés pour établir htConsultCall.

Valeur retournée

Retourne dwRequestID ou un numéro d’erreur si une erreur se produit. Le paramètre réel lResult du ASYNC_COMPLETION correspondant 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_INVALLINEHANDLE, LINEERR_NOMEM, LINEERR_INVALADDRESS, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESSID, LINEERR_OPERATIONFAILED, LINEERR_INVALCOUNTRYCODE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPARAM, LINEERR_STRUCTURETOOSMALL.

Remarques

Le fournisseur de services retourne LINEERR_INVALPARAM si le paramètre de liste de transfert spécifié contient des informations non valides.

Le fournisseur de services n’effectue aucune numérotation s’il retourne LINEERR_INVALADDRESS.

Le fournisseur de services retourne la réussite à cette fonction pour indiquer uniquement que la demande est acceptée par le fournisseur de services, et non que le transfert est configuré au niveau du commutateur. Un message LINE_ADDRESSSTATE (transfert) est envoyé pour indiquer que le transfert est configuré au niveau du commutateur.

Le transfert de l’adresse ou des adresses reste en vigueur jusqu’à ce que cette fonction soit appelée à nouveau. La liste de transfert la plus récente remplace toute ancienne liste en vigueur. Si cette fonction est appelée, en spécifiant un pointeur NULL comme lpForwardList, le fournisseur de services doit annuler tout transfert effectué à ce moment-là. Si une adresse de destination NULL est spécifiée pour une entrée dans la liste de transfert, l’opération agit comme un « ne pas déranger ».

Le transfert status d’une adresse peut également être affecté en externe, par exemple, par le biais d’actions administratives au niveau du commutateur ou par un utilisateur d’une autre station. Il est possible que le fournisseur de services ne soit pas au courant de ce changement d’état et qu’il ne soit pas en mesure de rester synchronisé avec l’état de transfert connu du commutateur. Le fournisseur doit toujours indiquer ce qu’il sait être vrai et indiquer que l’état de transfert est inconnu dans le cas contraire.

Étant donné qu’un fournisseur de services peut ne pas connaître l’état de transfert de l’adresse sans aucun doute (c’est-à-dire qu’elle a peut-être été transférée ou non transmise de manière inconnue), TSPI_lineForward réussit, sauf s’il ne parvient pas à définir les nouvelles instructions de transfert. En d’autres termes, une demande d’annulation de tout transfert à un moment où il n’y a pas de transfert effectif réussit. Cela est dû au fait qu’il n’y a pas d’inforwarding ; vous pouvez uniquement appeler un nouvel ensemble d’instructions de transfert.

La réussite ou l’échec de cette opération ne dépend pas de l’ensemble précédent d’instructions de transfert, et il en va de même pour la définition d’instructions de transfert différentes. Si nécessaire, le fournisseur doit « tout annuler » avant de définir les nouvelles instructions de transfert. Étant donné que cela peut prendre du temps dans les environnements de téléphonie analogique, un fournisseur peut également vouloir comparer le transfert actuel avec le nouveau, et émettre uniquement des instructions au commutateur pour accéder à l’état final (en laissant le transfert inchangé inchangé).

L’appel de TSPI_lineForward lorsque lineFORWARDLIST a défini dwNumEntries sur zéro a le même effet que la fourniture d’un paramètre lpForwardListNULL ; elle annule tout transfert actuellement en vigueur.

Étant donné que la valeur NULL retournée dans lphdConsultCall est le seul moyen pour TAPI de déterminer si le fournisseur de services a créé un appel de consultation, le fournisseur de services ne peut pas utiliser NULL comme handle d’appel.

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 ASYNC_COMPLETION correspondant signale la réussite. En d’autres termes, il ne doit pas émettre de messages pour le nouvel appel ou l’inclure dans le nombre d’appels dans les messages ou les structures de données status pour la ligne.