lineInitializeExA, fonction (tapi.h)

Article
11/20/2024

La fonction lineInitializeEx initialise l’utilisation de TAPI par l’application pour l’utilisation ultérieure de l’abstraction de ligne. Il 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 n’importe quel 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 média).

lpfnCallback

Adresse d’une fonction de rappel appelée pour déterminer l’état et les événements sur l’appareil en ligne, les adresses ou les appels, lorsque l’application utilise la méthode de notification d’événement « hidden window » (pour plus d’informations, voir 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 « handle d’événement » ou « port d’achèvement ».

lpszFriendlyAppName

Pointeur vers une chaîne de texte null-terminated text 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 est NULL, le nom du fichier de module de l’application est utilisé à la place (comme retourné par la fonction GetModuleFileName).

lpdwNumDevs

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

lpdwAPIVersion

Pointeur vers un emplacement DWORDdimensionné. L’application doit initialiser cette 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 passe dans 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 les messages ou structures plus récents en valeurs ou formats pris en charge par la version de l’application. Une fois cette requête 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 d’adapter l’installation sur un système avec une autre version 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 (en particulier, le mécanisme de notification d’événement sélectionné de l’application et les paramètres associés).

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_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 d’événements de téléphonie : fenêtre masquée, handle d’événement ou port d’achèvement.

Le mécanisme de fenêtre masquée est sélectionné en spécifiant LINEINITIALIZEEXOPTION_USEHIDDENWINDOW dans le membre dwOptions dans la structure LINEINITIALIZEEXPARAMS. Dans ce mécanisme (qui est le seul mécanisme disponible pour TAPI version 1.applications x), 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 publiés sur celui-ci 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 (qui peut se produire uniquement lorsque l’application appelle la fonction GetMessage GetMessage), Windows bascule le contexte de processus vers celui de l’application et appelle le WNDPROC dans TAPI. TAPI remet ensuite le message à l’application en appelant lelineCallbackProc , pointeur vers lequel l’application a fourni comme 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 de traiter régulièrement cette file d’attente afin d’é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 Descripteur d’événements est sélectionné en spécifiant LINEINITIALIZEEXOPTION_USEEVENT dans le membre dwOptions dans 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 manière quelconque (par exemple, ne doit pas appeler SetEvent, ResetEvent, CloseHandle, et ainsi de suite) ou des résultats de comportement non définis ; l’application ne peut attendre que sur 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 lorsqu’aucun événement n’est en attente. Le handle d’événement est fermé et l’objet d’événement détruit par TAPI pendant la fonction lineShutdown. L’application n’est pas nécessaire pour attendre le handle d’événement créé ; l’application peut choisir à la place d’appeler lineGetMessage et de bloquer l’attente d’un message.

Le mécanisme de port d’achèvement est sélectionné en spécifiant LINEINITIALIZEEXOPTION_USECOMPLETION PORT dans le membre dwOptions dans 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 que l’application spécifiée dans le membre hCompletionPort dans LINEINITIALIZEEXPARAMS , balisé avec la clé de saisie semi-automatique spécifiée dans le membre dwCompletionKey dans LINEINITIALIZEEXPARAMS. L’application doit avoir créé précédemment le port d’achèvement à l’aide de CreateIoCompletionPort. L’application récupère des événements à l’aide de GetQueuedCompletionStatus. Lors du retour de GetQueuedCompletionStatus, l’application a le paramètre dwCompletionKey spécifié écrit dans la DWORD pointée par le paramètre lpCompletionKey et un pointeur vers une structure LINEMESSAGE retournée à l’emplacement vers lequel lpOverlapped. Une fois que l’application a traité l’événement, il incombe à 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 la fermer ; l’application ne doit pas fermer le port d’achèvement tant qu’après l’appel de lineShutdown.

Lorsqu’une application multithread utilise le mécanisme Descripteur d’événements et que plusieurs threads attendent le handle, ou que le mécanisme de notification de port d’achèvement et 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 d’événements à partir de TAPI, mais est 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, en raison de l’ajout ou de la suppression d’un fournisseur de services de téléphonie, puis lineInitializeEx 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), auquel moment la nouvelle configuration devient effective et les applications sont une fois de plus autorisées à appeler lineInitializeEx.

Si la valeur d’erreur LINEERR_INVALPARAM est retournée, le paramètre spécifié n’est pas valide.

L’application peut faire référence à des appareils de ligne individuels à l’aide d’identificateurs d’appareils de ligne allant 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.

Note

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. 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.