Fonction lineOpen (tapi.h)

Article
03/04/2024

La fonction lineOpen ouvre l’appareil de ligne spécifié par son identificateur d’appareil et retourne un handle de ligne pour l’appareil de ligne ouvert correspondant. Ce handle de ligne est utilisé dans les opérations suivantes sur l’appareil de ligne.

Syntaxe

LONG lineOpen(
  HLINEAPP               hLineApp,
  DWORD                  dwDeviceID,
  LPHLINE                lphLine,
  DWORD                  dwAPIVersion,
  DWORD                  dwExtVersion,
  DWORD_PTR              dwCallbackInstance,
  DWORD                  dwPrivileges,
  DWORD                  dwMediaModes,
  LPLINECALLPARAMS const lpCallParams
);

Paramètres

hLineApp

Gérez l’inscription de l’application avec TAPI.

dwDeviceID

Identifie l’appareil de ligne à ouvrir. Il peut s’agir d’un identificateur d’appareil valide ou de la valeur.

Valeur	Signification
LINEMAPPER	Cette valeur est utilisée pour ouvrir un périphérique de ligne dans le système qui prend en charge les propriétés spécifiées dans lpCallParams. L’application peut utiliser lineGetID pour déterminer l’identificateur de l’appareil de ligne ouvert.

lphLine

Pointeur vers un handle HLINE qui est ensuite chargé avec le handle représentant l’appareil de ligne ouverte. Utilisez ce handle pour identifier l’appareil lors de l’appel d’autres fonctions sur l’appareil en ligne ouverte.

dwAPIVersion

Numéro de version de l’API sous lequel l’application et l’API de téléphonie ont accepté de fonctionner. Ce nombre est obtenu avec lineNegotiateAPIVersion.

dwExtVersion

Numéro de version de l’extension sous lequel l’application et le fournisseur de services acceptent d’opérer. Ce nombre est égal à zéro si l’application n’utilise aucune extension. Ce nombre est obtenu avec lineNegotiateExtVersion.

dwCallbackInstance

Les données instance l’utilisateur transmises à l’application avec chaque message associé à cette ligne ou à des adresses ou des appels sur cette ligne. Ce paramètre n’est pas interprété par l’API Téléphonie.

dwPrivileges

Privilège souhaité par l’application lorsqu’elle est informée d’un appel Ce paramètre contient une ou plusieurs constantes LINECALLPRIVILEGE_. Pour les applications utilisant TAPI version 2.0 ou ultérieure, les valeurs de ce paramètre peuvent également être combinées avec une ou plusieurs constantes LINEOPENOPTION_.

Si l’option LINEOPENOPTION_SINGLEADDRESS est spécifiée, l’application s’intéresse uniquement aux nouveaux appels qui apparaissent sur l’adresse spécifiée par le membre dwAddressID dans la structure LINECALLPARAMS pointée vers le paramètre lpCallParams (qui doit être spécifié).

Si LINEOPENOPTION_SINGLEADDRESS est spécifié, mais que lpCallParams n’est pas valide ou que le dwAddressID inclus n’existe pas sur la ligne, l’ouverture échoue avec LINERR_INVALADDRESSID.

En plus de définir le membre dwAddressID de la structure LINECALLPARAMS sur l’adresse souhaitée, l’application doit également définir dwAddressMode dans LINECALLPARAMS sur LINEADDRESSMODE_ADDRESSID.

L’option LINEOPENOPTION_SINGLEADDRESS affecte uniquement l’attribution par TAPI de la propriété d’appel initiale des appels créés par le fournisseur de services à l’aide d’un message LINE_NEWCALL . Une application qui ouvre la ligne avec LINECALLPRIVILEGE_MONITOR continue de recevoir des handles de surveillance pour tous les appels créés sur la ligne. En outre, l’application n’est en aucun cas limitée à effectuer des appels ou à effectuer d’autres opérations qui affectent d’autres adresses sur la ligne ouverte.

Lorsque l’option LINEOPENOPTION_PROXY est spécifiée (TAPI 2.0 ou version ultérieure uniquement), l’application doit également indiquer les demandes de proxy spécifiques qu’elle est prête à gérer. Pour ce faire, il passe, dans le paramètre lpCallParams , un pointeur vers une structure LINECALLPARAMS dans laquelle les membres dwDevSpecificSize et dwDevSpecificOffset ont été définis pour délimiter un tableau de S DWORD. Chaque élément de ce tableau doit contenir l’une des constantes LINEPROXYREQUEST_. Par exemple, une application de gestionnaire de proxy qui prend en charge les cinq fonctions liées à l’agent passerait dans un tableau de cinq DWORDs (dwDevSpecificSize aurait une valeur décimale 20) contenant les cinq valeurs LINEPROXYREQUEST_ définies.

L’application de gestionnaire de requêtes proxy peut s’exécuter sur n’importe quel ordinateur disposant de l’autorisation de contrôler l’appareil de ligne. Toutefois, les requêtes sont toujours acheminées via le serveur sur lequel le fournisseur de services s’exécute qui contrôle en fait l’appareil de ligne. Par conséquent, il est plus efficace si l’application qui gère les demandes proxy (par exemple, le contrôle de l’agent ACD) s’exécute directement sur le serveur avec le fournisseur de services.

Les tentatives suivantes, par la même application ou d’autres applications, d’ouvrir l’appareil de ligne et de s’inscrire pour gérer les mêmes demandes proxy qu’une application déjà inscrite échouent avec LINEERR_NOTREGISTERED.

Pour arrêter la gestion des requêtes sur la ligne, l’application appelle simplement lineClose.

D’autres combinaisons d’indicateurs retournent l’erreur LINEERR_INVALPRIVSELECT.

dwMediaModes

Type de média ou modes d’intérêt pour l’application. Ce paramètre est utilisé pour inscrire l’application en tant que cible potentielle pour l’appel entrant et le transfert d’appel pour le type de média spécifié. Ce paramètre n’a de sens que si le bit LINECALLPRIVILEGE_OWNER dans dwPrivileges est défini (et ignoré dans le cas contraire). Ce paramètre utilise une ou plusieurs constantes LINEMEDIAMODE_.

lpCallParams

Pointeur vers une structure de type LINECALLPARAMS. Ce pointeur n’est utilisé que si LINEMAPPER ou LINEOPENOPTION_PROXY est utilisé ; sinon , lpCallParams est ignoré. Il décrit le paramètre d’appel que l’appareil de ligne doit être en mesure de fournir.

Valeur retournée

Retourne zéro si la requête réussit ou un numéro d’erreur négatif si une erreur se produit. Les valeurs de retour possibles sont les suivantes :

LINEERR_ALLOCATED, LINEERR_LINEMAPPERFAILED, LINEERR_BADDEVICEID, LINEERR_NODRIVER, LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_NOMEM, LINEERR_INCOMPATIBLEEXTVERSION, LINEERR_OPERATIONFAILED, LINEERR_INVALAPPHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALMEDIAMODE, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_INVALPRIVSELECT, LINEERR_REINIT, LINEERR_NODEVICE, LINEERR_OPERATIONUNAVAIL.

Remarques

Si LINEERR_ALLOCATED est retourné, la ligne ne peut pas être ouverte en raison d’une condition « persistante », telle que celle d’un port série ouvert exclusivement par un autre processus. Si LINEERR_RESOURCEUNAVAIL est retourné, la ligne ne peut pas être ouverte en raison d’un dépassement de ressource dynamique, comme dans les cycles de processeur DSP ou la mémoire. Ce surengagement peut être temporaire, causé par la surveillance du type ou des tons de média, et les modifications apportées à ces activités par d’autres applications peuvent permettre de rouvrir la ligne dans un court laps de temps. Si LINEERR_REINIT est retourné et que la réinitialisation TAPI a été demandée (par exemple, suite à l’ajout ou à la suppression d’un fournisseur de services de téléphonie), les demandes lineOpen sont rejetées avec cette erreur jusqu’à ce que la dernière application arrête son utilisation de l’API (à l’aide de lineShutdown) ; à ce moment-là, la nouvelle configuration devient effective et les applications sont à nouveau autorisées à appeler lineInitializeEx.

L’ouverture d’une ligne autorise toujours l’application à passer des appels sur n’importe quelle adresse disponible sur la ligne. La capacité de l’application à traiter les appels entrants ou à être la cible des remises d’appels sur la ligne est déterminée par le paramètre dwMediaModes . La fonction lineOpen inscrit l’application comme ayant un intérêt à surveiller les appels ou à recevoir la propriété des appels qui sont des types de médias spécifiés. Si l’application souhaite simplement surveiller les appels, elle peut spécifier LINECALLPRIVILEGE_MONITOR. Si l’application souhaite simplement effectuer des appels sortants, elle peut spécifier LINECALLPRIVILEGE_NONE. Si l’application est prête à contrôler les appels non classifiés (appels de type multimédia inconnu), elle peut spécifier LINECALLPRIVILEGE_OWNER et LINEMEDIAMODE_UNKNOWN. Sinon, l’application doit spécifier le type de média qu’elle souhaite gérer. L’application peut appeler la fonction lineSetCallPrivilege pour modifier les privilèges d’appel spécifiés par le LINECALLPRIVILEGES_Constants.

Les types de médias spécifiés avec lineOpen ajoutent à la valeur par défaut pour la surveillance du type de média du fournisseur pour la détermination du type d’appel entrant initial. La fonction lineMonitorMedia modifie le masque qui contrôle LINE_MONITORMEDIA messages. Si un appareil de ligne est ouvert avec le privilège propriétaire et qu’un type de support d’extension n’est pas inscrit, l’LINEERR_INVALMEDIAMODE d’erreur est retournée.

Une application qui a correctement ouvert un appareil de ligne peut toujours lancer des appels à l’aide de lineMakeCall, lineUnpark, linePickup et lineSetupConference (avec un hCallNULL), ainsi que d’utiliser lineForward (en supposant que cela est autorisé par les fonctionnalités de l’appareil, l’état de la ligne, etc.).

Une seule application peut spécifier plusieurs indicateurs simultanément pour gérer plusieurs types de médias. Des conflits peuvent se produire si plusieurs applications ouvrent le même appareil de ligne pour le même type de média. Ces conflits sont résolus par un schéma de priorité dans lequel l’utilisateur affecte des priorités relatives aux applications. Les utilisateurs peuvent définir des priorités d’application en appelant la fonction lineSetAppPriority . Seule l’application de priorité la plus élevée pour un type de média donné recevra jamais la propriété (non sollicitée) d’un appel de ce type de média. La propriété peut être reçue lorsqu’un appel entrant arrive pour la première fois ou lorsqu’un appel est remis. La fonction lineHandoff est appelée pour transmettre la propriété d’un appel à une autre application. Si l’utilisateur n’attribue pas de priorités à l’application et que plusieurs applications ouvrent le même appareil de ligne, par défaut, l’application qui a appelé lineOpen en premier aura la priorité la plus élevée.

Toute application (y compris toute application de priorité inférieure) peut toujours acquérir la propriété avec lineGetNewCalls ou lineGetConfRelatedCalls. Si une application ouvre une ligne pour la surveillance à un moment où les appels existent sur la ligne, LINE_CALLSTATE messages pour ces appels existants ne sont pas générés automatiquement vers la nouvelle application de supervision. L’application peut interroger le nombre d’appels actuels sur la ligne pour déterminer le nombre d’appels existants et, si elle le souhaite, elle peut appeler lineGetNewCalls pour obtenir des handles pour ces appels.

Une application qui gère la voix automatisée doit également sélectionner le mode ouvert vocal interactif et se voir attribuer la priorité la plus faible pour la voix interactive. La raison en est que les fournisseurs de services signalent tous les types de médias vocaux en tant que voix interactive. Si la détermination du type de média n’est pas effectuée par l’application pour le type de média UNKNOWN et qu’aucune application vocale interactive n’a ouvert l’appareil de ligne, les appels vocaux ne peuvent pas atteindre l’application vocale automatisée et sont supprimés.

La même application, ou différentes instanciations de la même application, peuvent ouvrir la même ligne plusieurs fois avec les mêmes paramètres ou différents.

Lorsqu’une application ouvre un appareil de ligne, elle doit spécifier la version de l’API négociée et, si elle souhaite utiliser les extensions de la ligne, elle doit spécifier la version de l’extension spécifique à l’appareil de la ligne. Ces numéros de version doivent avoir été obtenus avec lineNegotiateAPIVersion et lineNegotiateExtVersion. La numérotation des versions permet le mélange et la mise en correspondance de différentes versions d’application avec différentes versions d’API et versions de fournisseur de services.

LINEMAPPER permet à une application de sélectionner une ligne indirectement au moyen des services qu’elle souhaite obtenir. Lors de l’ouverture d’un appareil de ligne à l’aide de LINEMAPPER, les éléments suivants sont vrais : tous les membres du début de la structure de données LINECALLPARAMS via dwAddressMode sont pertinents. Si dwAddressMode est LINEADDRESSMODE_ADDRESSID cela signifie qu’une adresse sur la ligne est acceptable, sinon si dwAddressMode est LINEADDRESSMODE_DIALABLEADDR, indiquant qu’une adresse d’origine spécifique (numéro de téléphone) est recherchée, ou s’il s’agit d’une extension spécifique au fournisseur, dwOrigAddressSize/Offset et la partie de la variable à laquelle ils font référence sont également pertinents. Si dwAddressMode est une extension spécifique au fournisseur, des informations supplémentaires peuvent être contenues dans le membre dwDeviceSpecific de taille variable.