fonction lineSetTerminal (tapi.h)

Article
08/26/2023

La fonction lineSetTerminal permet à une application de spécifier les informations de terminal relatives à la ligne, à l’adresse ou à l’appel spécifiés qui doivent être routées. La fonction lineSetTerminal peut être utilisée pendant que les appels sont en cours sur la ligne pour permettre à une application d’acheminer ces événements vers différents appareils en fonction des besoins.

Syntaxe

LONG lineSetTerminal(
  HLINE hLine,
  DWORD dwAddressID,
  HCALL hCall,
  DWORD dwSelect,
  DWORD dwTerminalModes,
  DWORD dwTerminalID,
  DWORD bEnable
);

Paramètres

hLine

Gérer sur un appareil de ligne ouverte.

dwAddressID

Adresse sur l’appareil de ligne ouverte donné. 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.

hCall

Gérer à un appel. L’état d’appel de hCall peut être n’importe quel état, si dwSelect est CALL.

dwSelect

Indique si le paramètre de terminal est demandé pour la ligne, l’adresse ou simplement l’appel spécifié. Si la ligne ou l’adresse est spécifiée, les événements s’appliquent à la ligne ou à l’adresse elle-même ou servent de paramètre initial par défaut pour tous les nouveaux appels sur la ligne ou l’adresse. Ce paramètre utilise l’une des constantes LINECALLSELECT_.

dwTerminalModes

Classe d’événements de bas niveau à acheminer vers le terminal donné. Ce paramètre utilise une ou plusieurs constantes LINETERMMODE_.

dwTerminalID

Identificateur de l’appareil terminal où les événements donnés doivent être routés. Les identificateurs de terminal sont de petits entiers compris entre zéro et un de moins que dwNumTerminals, où dwNumTerminals et les modes de terminal que chaque terminal est capable de gérer sont retournés par lineGetDevCaps.

Ces identificateurs de terminal n’ont aucune relation avec d’autres identificateurs d’appareil et sont définis par le fournisseur de services à l’aide des fonctionnalités de l’appareil.

bEnable

Si la valeur est TRUE, dwTerminalID est valide et les classes d’événements spécifiées sont routées vers ou depuis ce terminal. Si la valeur est FALSE, ces événements ne sont pas routés vers ou depuis l’appareil terminal avec l’identificateur égal à dwTerminalID.

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 nombre d’erreur négatif si une erreur se produit. Les valeurs de retour possibles sont les suivantes :

LINEERR_INVALADDRESSID, LINEERR_NOMEM, LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSELECT, LINEERR_OPERATIONFAILED, LINEERR_INVALLINEHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALTERMINALID, LINEERR_UNINITIALIZED, LINEERR_INVALTERMINALMODE.

Remarques

Une application peut utiliser cette fonction pour acheminer certaines classes d’événements de ligne de bas niveau vers l’appareil terminal spécifié ou pour supprimer le routage de ces événements. Par exemple, la voix peut être acheminée vers un appareil d’E/S audio (casque), les lampes et les événements d’affichage peuvent être acheminés vers l’appareil téléphonique local, et les événements de bouton et les événements de sonnerie peuvent être complètement supprimés.

Cette fonction peut être appelée à tout moment, même lorsqu’un appel est actif sur l’appareil de ligne donné. Cela permet à un utilisateur de passer de l’ensemble de téléphones locaux à un autre appareil d’E/S audio. Cette fonction peut être appelée plusieurs fois pour acheminer simultanément les mêmes événements vers plusieurs terminaux. Pour rediriger les événements vers un autre terminal, l’application doit d’abord désactiver le routage vers le terminal existant, puis acheminer les événements vers le nouveau terminal.

Les affectations d’identificateur de terminal sont effectuées par le fournisseur de services de la ligne. Les fonctionnalités de l’appareil indiquent uniquement les identificateurs de terminal dont dispose le fournisseur de services. Les fournisseurs de services qui ne prennent pas en charge ce type de routage d’événements indiquent qu’ils n’ont pas de périphérique terminal (dwNumTerminals dans LINEDEVCAPS est égal à zéro).

L’appel de lineSetTerminal sur une ligne ou une adresse affecte tous les appels existants sur cette ligne ou adresse, mais n’affecte pas les appels sur d’autres adresses. Il définit également la valeur par défaut pour les appels futurs sur cette ligne ou cette adresse. Une ligne ou une adresse qui a plusieurs appels connectés actifs à la fois peut avoir un routage différent en vigueur pour chaque appel.

La désactivation du routage des événements de bas niveau vers un terminal lorsque ces événements ne sont pas routés vers ou depuis ce terminal ne génère pas nécessairement d’erreur tant que la fonction réussit (les événements spécifiés ne sont pas routés vers ou depuis ce terminal).

TAPI achemine les tonalités et les messages de progression des appels vers le même emplacement que celui défini par la fonction lineSetTerminal pour « media ». Par exemple, si les signaux audio sont envoyés au téléphone, les signaux occupés (analogiques) ou les messages Q.931 indiquant occupé (numérique) seront également.