lineInitialize, fonction (tapi.h)

Article
08/26/2023

La fonction lineInitialize est obsolète. Il continue d’être exporté par Tapi.dll et Tapi32.dll à des fins de compatibilité descendante avec les applications utilisant les versions d’API 1.3 et 1.4.

Les applications utilisant l’API version 2.0 ou ultérieure doivent utiliser lineInitializeEx à la place.

Pour TAPI versions 1.4 et antérieures : La fonction lineInitialize initialise l’utilisation de Tapi.dll par l’application pour une utilisation ultérieure de l’abstraction de ligne. La fonction inscrit le mécanisme de notification spécifié de l’application et retourne le nombre d’appareils de ligne disponibles pour l’application. Un appareil de ligne est tout appareil qui fournit une implémentation pour les fonctions avec préfixe de ligne dans TAPI.

Syntaxe

LONG lineInitialize(
  LPHLINEAPP   lphLineApp,
  HINSTANCE    hInstance,
  LINECALLBACK lpfnCallback,
  LPCSTR       lpszAppName,
  LPDWORD      lpdwNumDevs
);

Paramètres

lphLineApp

Pointeur vers un emplacement rempli avec le handle d’utilisation de l’application pour TAPI.

hInstance

Handle d’instance de l’application cliente ou de la DLL.

lpfnCallback

Adresse d’une fonction de rappel appelée pour déterminer status et les événements sur l’appareil de ligne, les adresses ou les appels. Pour plus d’informations, consultez lineCallbackFunc.

lpszAppName

Pointeur vers une chaîne de texte terminée par null qui contient uniquement des caractères affichables. Si ce paramètre n’est pas NULL, il contient un nom fourni par l’application. Ce nom est fourni dans la structure LINECALLINFO pour indiquer, de manière conviviale, quelle application provient ou a initialement accepté ou répondu à l’appel. Ces informations peuvent être utiles à des fins de journalisation des appels. Si lpszAppName a la valeur NULL, le nom de fichier de l’application est utilisé à la place.

lpdwNumDevs

Pointeur vers un emplacement de taille DWORD. Une fois cette demande terminée, cet emplacement est rempli avec le nombre d’appareils en ligne disponibles pour l’application.

Valeur retournée

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

LINEERR_INVALAPPNAME, LINEERR_OPERATIONFAILED, LINEERR_INIFILECORRUPT, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_REINIT, LINEERR_NODRIVER, LINEERR_NODEVICE, LINEERR_NOMEM, LINEERR_NOMULTIPLEINSTANCE.

Remarques

Si LINEERR_REINIT est retourné et que la réinitialisation TAPI a été demandée (par exemple à la suite de l’ajout ou de la suppression d’un fournisseur de services de téléphonie), les demandes lineInitialize 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 lineInitialize. Si la valeur d’erreur LINEERR_INVALPARAM est retournée, le paramètre hInstance spécifié n’est pas valide.

L’application peut faire référence à des appareils de ligne individuels à l’aide d’identificateurs de périphérique de ligne qui vont de zéro à dwNumDevs moins un. Une application ne doit pas supposer que ces appareils de ligne sont capables de tout ce qui est spécifié par le sous-ensemble de téléphonie de base sans interroger d’abord leurs fonctionnalités d’appareil à l’aide de lineGetDevCaps et lineGetAddressCaps.

Les applications ne doivent pas appeler lineInitialize sans ouvrir par la suite une ligne (au moins pour la surveillance). Si l’application ne surveille pas et n’utilise pas d’appareils, elle doit appeler lineShutdown afin que les ressources mémoire allouées par Tapi.dll puissent être libérées si elles ne sont pas nécessaires, et Tapi.dll elle-même peut être déchargée de la mémoire alors qu’elle n’est pas nécessaire.

Une autre raison d’effectuer un lineShutdown est que si un utilisateur modifie la configuration de l’appareil (ajoute ou supprime une ligne ou un téléphone), il n’existe aucun moyen pour TAPI de notifier une application dont le handle de ligne ou de téléphone est ouvert à ce moment-là. Une fois qu’une reconfiguration a eu lieu, entraînant l’envoi d’un message LINEDEVSTATE_REINIT, aucune application ne peut ouvrir un appareil tant que toutes les applications n’ont pas effectué un lineShutdown. Si un fournisseur de services ne parvient pas à s’initialiser correctement, cette fonction échoue et retourne l’erreur indiquée par le fournisseur de services.

Sur toutes les plateformes TAPI, lineInitialize équivaut à lineInitializeEx à l’aide de l’option LINEINITIALIZEEXOPTION_USEHIDDENWINDOW.