fonction lineForward (tapi.h)

Article
03/02/2024

La fonction 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 actuellement en vigueur.

Syntaxe

LONG lineForward(
  HLINE                   hLine,
  DWORD                   bAllAddresses,
  DWORD                   dwAddressID,
  LPLINEFORWARDLIST const lpForwardList,
  DWORD                   dwNumRingsNoAnswer,
  LPHCALL                 lphConsultCall,
  LPLINECALLPARAMS const  lpCallParams
);

Paramètres

hLine

Gérez l’appareil de ligne.

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 de la ligne sont transférées et dwAddressID est ignorée ; si la valeur est FALSE, seule l’adresse spécifiée en tant que dwAddressID est transféré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.

Un identificateur d’adresse est associé de façon 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 qui décrit les instructions de transfert spécifiques, de type LINEFORWARDLIST.

dwNumRingsNoAnswer

Le nombre d’anneaux avant un appel est considéré comme une « réponse nulle ». Si dwNumRingsNoAnswer est hors plage, la valeur réelle est définie sur la valeur la plus proche dans la plage autorisée.

lphConsultCall

Pointeur vers un emplacement HCALL. Dans certains environnements de téléphonie, cet emplacement est chargé avec un handle pour un appel de consultation qui est utilisé pour consulter la partie vers laquelle est transféré, et l’application devient le seul propriétaire initial de cet appel. Ce pointeur doit être valide même dans les environnements où le transfert d’appel ne nécessite pas d’appel de consultation. Ce handle a la valeur NULL si aucun appel de consultation n’est créé.

lpCallParams

Pointeur vers une structure de type LINECALLPARAMS. Ce pointeur est ignoré, sauf si lineForward nécessite l’établissement d’un appel à la destination de transfert (et que lphConsultCallCall 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 hConsultCall.

Valeur retournée

Retourne un identificateur de requête positif si la fonction est terminée de manière asynchrone, ou un numéro d’erreur négatif si une erreur se produit. Le paramètre dwParam2 du message LINE_REPLY correspondant est égal à zéro si la fonction réussit ou s’il s’agit d’un numéro d’erreur négatif si une erreur se produit. Les valeurs de retour possibles sont les suivantes :

LINEERR_INVALLINEHANDLE, LINEERR_NOMEM, LINEERR_INVALADDRESSID, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESS, LINEERR_OPERATIONFAILED, LINEERR_INVALCOUNTRYCODE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALPARAM, LINEERR_UNINITIALIZED.

Remarques

Un transfert réussi indique uniquement que la demande a été acceptée par le fournisseur de services, et non que le transfert est configuré au niveau du commutateur. Un message LINE_ADDRESSSTATE (transfert) confirme que le transfert a été configuré au niveau du commutateur.

Le transfert de la ou des adresses reste en vigueur jusqu’à ce que cette fonction soit appelée à nouveau. La liste de transfert la plus récente remplace l’ancienne. Le transfert peut être annulé en spécifiant un pointeur NULLcomme lpForwardList. Si une adresse de destination NULL est spécifiée pour une entrée dans la liste de transfert, l’opération agit comme une opération ne pas déranger.

Le transfert status d’une adresse peut également être affecté en externe, par exemple, par des actions administratives au niveau du commutateur ou par un utilisateur à partir 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 maintenir la synchronisation avec l’état de transfert connu du commutateur.

Étant donné qu’un fournisseur de services peut ne pas connaître l’état de transfert de l’adresse « for sure » (c’est-à-dire qu’elle a peut-être été transférée ou non transmise d’une manière inconnue), 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ù aucun transfert n’est en vigueur réussit. Cela est dû au fait qu’il n’y a pas de « non-forwarding » : vous pouvez uniquement modifier l’ensemble précédent 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 la même chose est vraie lors de la définition d’instructions de transfert différentes. 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 pour le commutateur pour atteindre l’état final (en laissant le transfert inchangé non affecté).

L’appel de lineForward lorsque lineFORWARDLIST a défini dwNumEntries sur zéro a le même effet que la fourniture d’un paramètre NULL lpForwardList. Il annule tous les transfert actuellement en vigueur.