fonction lineInitializeExA (tapi.h)

Article
03/04/2024

La fonction lineInitializeEx initialise l’utilisation de TAPI par l’application pour une utilisation ultérieure de l’abstraction de ligne. Il enregistre 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 l’API téléphonie.

Syntaxe

LONG lineInitializeExA(
  LPHLINEAPP               lphLineApp,
  HINSTANCE                hInstance,
  LINECALLBACK             lpfnCallback,
  LPCSTR                   lpszFriendlyAppName,
  LPDWORD                  lpdwNumDevs,
  LPDWORD                  lpdwAPIVersion,
  LPLINEINITIALIZEEXPARAMS lpLineInitializeExParams
);

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. L’application ou la DLL peut passer null pour ce paramètre, auquel cas TAPI utilise le handle de module de l’exécutable racine du processus (pour identifier les cibles de transfert d’appel et les priorités en mode multimédia).

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, lorsque l’application utilise la méthode de notification d’événement « fenêtre masquée » (pour plus d’informations, consultez lineCallbackFunc). Ce paramètre est ignoré et doit être défini sur NULL lorsque l’application choisit d’utiliser les mécanismes de notification d’événement « de handle d’événement » ou « port d’achèvement ».

lpszFriendlyAppName

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 lpszFriendlyAppName a la valeur NULL, le nom de fichier de module de l’application est utilisé à la place (comme retourné par la fonction GetModuleFileName).

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.

lpdwAPIVersion

Pointeur vers un emplacement de taille DWORD. L’application doit initialiser ce DWORD, avant d’appeler cette fonction, vers la version d’API la plus élevée qu’elle est conçue pour prendre en charge (par exemple, la même valeur qu’elle passerait au paramètre dwAPIHighVersion de lineNegotiateAPIVersion). Les valeurs artificiellement élevées ne doivent pas être utilisées ; la valeur doit être définie avec précision. TAPI traduit tous les messages ou structures plus récents en valeurs ou formats pris en charge par la version de l’application. Une fois cette demande terminée, cet emplacement est rempli avec la version d’API la plus élevée prise en charge par TAPI, ce qui permet à l’application de détecter et de s’adapter à l’installation sur un système avec une version différente de TAPI.

lpLineInitializeExParams

Pointeur vers une structure de type LINEINITIALIZEEXPARAMS contenant des paramètres supplémentaires utilisés pour établir l’association entre l’application et TAPI (plus précisément, le mécanisme de notification d’événement sélectionné de l’application et les paramètres associés).

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_INVALPOINTER, LINEERR_REINIT, LINEERR_NOMEM, LINEERR_INVALPARAM.

Remarques

Les applications doivent sélectionner l’un des trois mécanismes par lesquels TAPI notifie l’application des événements de téléphonie : Fenêtre masquée, Handle d’événement ou Port d’achèvement.

Le mécanisme Fenêtre masquée est sélectionné en spécifiant LINEINITIALIZEEXOPTION_USEHIDDENWINDOW dans le membre dwOptions de la structure LINEINITIALIZEEXPARAMS . Dans ce mécanisme (qui est le seul mécanisme disponible pour TAPI version 1.x applications), TAPI crée une fenêtre dans le contexte de l’application pendant la fonction lineInitializeEx ou lineInitialize (pour les applications TAPI version 1.3 et 1.4) et sous-classe la fenêtre afin que tous les messages qui y sont publiés soient gérés par un WNDPROC dans TAPI lui-même. Lorsque TAPI a un message à remettre à l’application, TAPI publie un message dans la fenêtre masquée. Lorsque le message est reçu (ce qui peut se produire uniquement lorsque l’application appelle la fonction Windows GetMessage ), Windows bascule le contexte de processus sur celui de l’application et appelle le WNDPROC dans TAPI. TAPI remet ensuite le message à l’application en appelant le lineCallbackProc, pointeur vers lequel l’application a fourni en tant que paramètre dans son appel à lineInitializeEx (ou lineInitialize). Ce mécanisme exige que l’application dispose d’une file d’attente de messages (ce qui n’est pas souhaitable pour les processus de service) et qu’elle traite cette file d’attente régulièrement pour éviter de retarder le traitement des événements de téléphonie. La fenêtre masquée est détruite par TAPI pendant la fonction lineShutdown .

Le mécanisme Event Handle est sélectionné en spécifiant LINEINITIALIZEEXOPTION_USEEVENT dans le membre dwOptions de la structure LINEINITIALIZEEXPARAMS . Dans ce mécanisme, TAPI crée un objet d’événement pour le compte de l’application et retourne un handle à l’objet dans le membre hEvent dans LINEINITIALIZEEXPARAMS. L’application ne doit pas manipuler cet événement de quelque manière que ce soit (par exemple, ne doit pas appeler SetEvent, ResetEvent, CloseHandle, et ainsi de suite) ou des résultats de comportement non définis ; l’application peut uniquement attendre cet événement à l’aide de fonctions telles que WaitForSingleObject ou MsgWaitForMultipleObjects. TAPI signale cet événement chaque fois qu’une notification d’événement de téléphonie est en attente pour l’application ; l’application doit appeler lineGetMessage pour extraire le contenu du message. L’événement est réinitialisé par TAPI quand aucun événement n’est en attente. Le handle d’événement est fermé et l’objet événement détruit par TAPI pendant la fonction lineShutdown . L’application n’est pas tenue d’attendre le handle d’événement créé ; l’application peut choisir à la place d’appeler lineGetMessage et de le bloquer en attendant qu’un message soit mis en file d’attente.

Le mécanisme De port d’achèvement est sélectionné en spécifiant LINEINITIALIZEEXOPTION_USECOMPLETION PORT dans le membre dwOptions de la structure LINEINITIALIZEEXPARAMS . Dans ce mécanisme, chaque fois qu’un événement de téléphonie doit être envoyé à l’application, TAPI l’envoie à l’aide de PostQueuedCompletionStatus au port d’achèvement spécifié par l’application dans le membre hCompletionPort dans LINEINITIALIZEEXPARAMS, marqué avec la clé d’achèvement spécifiée par l’application dans le membre dwCompletionKey dans LINEINITIALIZEEXPARAMS. L’application doit avoir précédemment créé le port d’achèvement à l’aide de CreateIoCompletionPort. L’application récupère les événements à l’aide de GetQueuedCompletionStatus. Lors du retour à partir de GetQueuedCompletionStatus, l’application a la dwCompletionKey spécifiée écrite sur le DWORD pointé vers par le paramètre lpCompletionKey , et un pointeur vers une structure LINEMESSAGE retournée à l’emplacement vers lequel lpOverlapped pointe. Une fois que l’application a traité l’événement, il est de la responsabilité de l’application d’appeler LocalFree pour libérer la mémoire utilisée pour contenir la structure LINEMESSAGE . Étant donné que l’application a créé le port d’achèvement (ce qui lui permet d’être partagé à d’autres fins), l’application doit le fermer ; l’application ne doit fermer le port d’achèvement qu’après avoir appelé lineShutdown.

Lorsqu’une application multithread utilise le mécanisme Event Handle et que plusieurs threads attendent sur le handle, ou que le mécanisme de notification du port d’achèvement et que plusieurs threads attendent sur le port, il est possible que les événements de téléphonie soient traités hors séquence. Cela n’est pas dû à la séquence de remise des événements à partir de TAPI, mais serait dû au découpage temporel des threads ou à l’exécution de threads sur des processeurs distincts.

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 requêtes lineInitializeEx sont rejetées avec cette erreur jusqu’à ce que la dernière application arrête son utilisation de l’API (à l’aide de lineShutdown), date à laquelle la nouvelle configuration devient effective et les applications sont à nouveau autorisées à appeler lineInitializeEx.

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 d’une fonction TAPI particulière sans interroger d’abord leurs fonctionnalités d’appareil par lineGetDevCaps et lineGetAddressCaps.

Notes

L’en-tête tapi.h définit lineInitializeEx 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. La combinaison 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.