Remarque
L’accès à cette page requiert une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page requiert une autorisation. Vous pouvez essayer de modifier des répertoires.
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 lineOpenA(
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 |
|---|---|
|
Cette valeur est utilisée pour ouvrir un appareil 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 ouvert. 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 téléphonie ont accepté de fonctionner. Ce nombre est obtenu avec lineNegotiateAPIVersion.
dwExtVersion
Numéro de version d’extension sous lequel l’application et le fournisseur de services acceptent de fonctionner. Ce nombre est égal à zéro si l’application n’utilise aucune extension. Ce nombre est obtenu avec lineNegotiateExtVersion.
dwCallbackInstance
Les données d’instance utilisateur sont passées à l’application avec chaque message associé à cette ligne ou avec des adresses ou des appels sur cette ligne. Ce paramètre n’est pas interprété par l’API téléphonie.
dwPrivileges
Privilege the application wants when notification of a call This parameter contains one or more of the LINECALLPRIVILEGE_ Constants. 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 par 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 dwAddress ID 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’affectation de l’appel initial TAPI 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. De plus, l’application n’est pas limitée d’effectuer des appels ou d’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. Il le fait en passant, dans le paramètre lpCallParams, un pointeur vers une structure LINECALLPARAMS dans laquelle les dwDevSpecificSize et dwDevSpecificOffset membres ont été définis pour délimiter un tableau de DWORD. Chaque élément de ce tableau doit contenir l’une des constantes LINEPROXYREQUEST_. Par exemple, une application de gestionnaire proxy qui prend en charge les cinq fonctions associées à l’agent passe dans un tableau de cinq DWORD (dwDevSpecificSize serait 20 décimales) contenant les cinq valeurs définies LINEPROXYREQUEST_.
L’application de gestionnaire de demandes 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 routées via le serveur sur lequel le fournisseur de services exécute réellement qui contrôle l’appareil de ligne. Par conséquent, il est plus efficace si l’application gère les requêtes proxy (comme le contrôle d’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 demandes 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’est significatif que si le LINECALLPRIVILEGE_OWNER bit 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 est utilisé uniquement 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 de retour
Retourne zéro si la requête réussit ou si un numéro d’erreur négatif 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’une surcommitment de ressource dynamique, telle que dans les cycles de processeur DSP ou la mémoire. Cette surcommitment peut être transitoire, causée par la surveillance du type de média ou des tonalités, et les modifications apportées à ces activités par d’autres applications peuvent permettre de rouvrir la ligne dans un court délai. Si LINEERR_REINIT est retourné et que la réinitialisation TAPI a été demandée (par exemple, en raison de l’ajout ou de la suppression d’un fournisseur de services de téléphonie), lineOpen demandes 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 une fois de plus autorisées à appeler lineInitializeEx.
L’ouverture d’une ligne donne toujours droit à l’application de 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’appel sur la ligne est déterminée par le paramètre dwMediaModes. La fonction lineOpen inscrit l’application comme ayant un intérêt pour l’analyse des appels ou la réception de propriété des appels qui sont des types multimé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 classés (appels de type multimédia inconnu), il peut spécifier LINECALLPRIVILEGE_OWNER et LINEMEDIAMODE_UNKNOWN. Sinon, l’application doit spécifier le type de média qui intéresse la gestion. L’application peut appeler la fonction lineSetCallPrivilege pour modifier les privilèges d’appel spécifiés par le LINECALLPRIVILEGES_Constants.
Les types de supports spécifiés avec lineOpen ajouter à la valeur par défaut pour la surveillance du type de média du fournisseur pour la détermination initiale du type d’appel entrant. La fonction lineMonitorMedia modifie le masque qui contrôle les messages LINE_MONITORMEDIA. Si un appareil de ligne est ouvert avec le privilège de propriétaire et qu’un type de support d’extension n’est pas inscrit, l’erreur LINEERR_INVALMEDIAMODE est retournée.
Une application qui a correctement ouvert un appareil de ligne peut toujours lancer des appels à l’aide de lineMakeCall, lineUnpark, linePickupet ligneSetupConference (avec une NULLhCall), ainsi qu’utiliser lineForward (en supposant que cela est autorisé par les fonctionnalités de l’appareil, l’état de ligne, et ainsi de suite).
Une application unique peut spécifier plusieurs indicateurs simultanément pour gérer plusieurs types de supports. Les conflits peuvent survenir si plusieurs applications ouvrent le même périphérique de ligne pour le même type de support. Ces conflits sont résolus par un schéma de priorité dans lequel l’utilisateur attribue des priorités relatives aux applications. Les utilisateurs peuvent définir des priorités d’application en appelant la fonction lineSetAppPriority
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 de surveillance à la fois où les appels existent sur la ligne, LINE_CALLSTATE messages pour ces appels existants ne sont pas générés automatiquement dans la nouvelle application de supervision. L’application peut interroger le nombre d’appels actuels sur la ligne pour déterminer le nombre d’appels qui existent et, si elle le souhaite, elle peut appeler lineGetNewCalls pour obtenir des handles à ces appels.
Une application qui gère la voix automatisée doit également sélectionner le mode d’ouverture vocal interactif et attribuer la priorité la plus basse pour la voix interactive. C’est pourquoi 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 INCONNU 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 les instanciations différentes 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 d’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 les versions du fournisseur de services.
LINEMAPPER permet à une application de sélectionner une ligne indirectement, au moyen des services qu’elle souhaite utiliser. Lors de l’ouverture d’un appareil de ligne à l’aide de LINEMAPPER, la valeur suivante est true : tous les membres du début de la LINECALLPARAMS structure de données 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 variable à laquelle ils font référence sont également pertinentes. Si dwAddressMode est une extension spécifique au fournisseur, des informations supplémentaires peuvent être contenues dans la dwDeviceSpecific membre de taille variable.
Note
L’en-tête tapi.h définit lineOpen comme alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.
Exigences
| Exigence | Valeur |
|---|---|
| plateforme cible | Windows |
| d’en-tête | tapi.h |
| bibliothèque | Tapi32.lib |
| DLL | Tapi32.dll |
Voir aussi
Informations de référence sur les services de téléphonie de base