fonction phoneInitializeExA (tapi.h)

Article
08/26/2023

La fonction phoneInitializeEx initialise l’utilisation de TAPI par l’application pour une utilisation ultérieure de l’abstraction du téléphone. Il enregistre le mécanisme de notification spécifié de l’application et retourne le nombre d’appareils téléphoniques disponibles pour l’application. Un appareil téléphonique est tout appareil qui fournit une implémentation pour les fonctions préfixées par téléphone dans l’API téléphonie.

Syntaxe

LONG phoneInitializeExA(
  LPHPHONEAPP               lphPhoneApp,
  HINSTANCE                 hInstance,
  PHONECALLBACK             lpfnCallback,
  LPCSTR                    lpszFriendlyAppName,
  LPDWORD                   lpdwNumDevs,
  LPDWORD                   lpdwAPIVersion,
  LPPHONEINITIALIZEEXPARAMS lpPhoneInitializeExParams
);

Paramètres

lphPhoneApp

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 la valeur NULL pour ce paramètre, auquel cas TAPI utilise le handle de module du fichier exécutable racine du processus.

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 phoneCallbackFunc). 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énements « event handle » ou « completion port ».

lpszFriendlyAppName

Pointeur vers une chaîne terminée par null qui contient uniquement des caractères pouvant être affichés. Si ce paramètre n’est pas NULL, il contient un nom fourni par l’application pour l’application. Ce nom est fourni dans la structure PHONESTATUS pour indiquer, de manière conviviale, quelle application est propriétaire de l’appareil téléphonique. Si lpszFriendlyAppName a la valeur NULL, le nom du module de l’application est utilisé à la place (comme retourné par la fonction GetModuleFileName).

lpdwNumDevs

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

lpdwAPIVersion

Pointeur vers un 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 dans le paramètre dwAPIHighVersion de phoneNegotiateAPIVersion). 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 antérieure de TAPI.

lpPhoneInitializeExParams

Pointeur vers une structure de type PHONEINITIALIZEEXPARAMS 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 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 :

PHONEERR_INVALAPPNAME, PHONEERR_OPERATIONFAILED, PHONEERR_INIFILECORRUPT, PHONEERR_INVALPOINTER, PHONEERR_REINIT, PHONEERR_NOMEM, PHONEERR_INVALPARAM.

Remarques

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

Le mécanisme De fenêtre masquée est sélectionné en spécifiant PHONEINITIALIZEEXOPTION_USEHIDDENWINDOW dans le membre dwOptions de la structure PHONEINITIALIZEEXPARAMS . 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 phoneInitializeEx 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 ne peut se produire que 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 phoneCallbackFunc, pointeur vers lequel l’application a fourni comme paramètre dans son appel à phoneInitializeEx (ou phoneInitialize, pour les applications TAPI version 1.3 et 1.4). 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 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 phoneShutdown .
Le mécanisme Event Handle est sélectionné en spécifiant PHONEINITIALIZEEXOPTION_USEEVENT dans le membre dwOptions de la structure PHONEINITIALIZEEXPARAMS . 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 PHONEINITIALIZEEXPARAMS. 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 ne peut attendre cet événement qu’à 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 phoneGetMessage 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 phoneShutdown . L’application n’est pas tenue d’attendre le handle d’événement créé ; l’application peut choisir d’appeler phoneGetMessage 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 PHONEINITIALIZEEXOPTION_USECOMPLETION PORT dans le membre dwOptions de la structure PHONEINITIALIZEEXPARAMS . Dans ce mécanisme, chaque fois qu’un événement de téléphonie doit être envoyé à l’application, TAPI l’envoie à l’application à l’aide de PostQueuedCompletionStatus vers le port d’achèvement spécifié par l’application dans le membre hCompletionPort dans PHONEINITIALIZEEXPARAMS, marqué avec la clé d’achèvement que l’application a spécifiée dans le membre dwCompletionKey dans PHONEINITIALIZEEXPARAMS. L’application doit avoir précédemment créé le port d’achèvement à l’aide de CreateIoCompletionPort. Les applications récupèrent les événements à l’aide de GetQueuedCompletionStatus. Au retour à partir de GetQueuedCompletionStatus, l’application a le dwCompletionKey spécifié écrit sur le DWORD pointé vers le paramètre lpCompletionKey , et un pointeur vers une structure PHONEMESSAGE renvoyé à l’emplacement vers lequel pointe lpOverlapped. Une fois que l’application a traité l’événement, l’application doit appeler LocalFree pour libérer la mémoire utilisée pour contenir la structure PHONEMESSAGE . É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 l’appel de phoneShutdown.

Lorsqu’une application multithread utilise le mécanisme Event Handle et que plusieurs threads attendent 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 d’é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 PHONEERR_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 phoneInitializeEx sont rejetées avec cette erreur jusqu’à ce que la dernière application arrête son utilisation de l’API (à l’aide de phoneShutdown). À ce moment-là, la nouvelle configuration devient effective et les applications sont à nouveau autorisées à appeler phoneInitializeEx.

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

L’application peut faire référence à des appareils téléphoniques individuels à l’aide d’identificateurs d’appareil téléphonique allant de zéro à dwNumDevs moins un. Une application ne doit pas supposer que ces appareils téléphoniques sont capables d’une fonction TAPI particulière sans interroger d’abord leurs fonctionnalités d’appareil par phoneGetDevCaps.

Notes

L’en-tête tapi.h définit phoneInitializeEx comme un 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.