phoneInitializeExA, fonction (tapi.h)

Article
11/20/2024

La fonction phoneInitializeEx initialise l’utilisation de TAPI par l’application pour une utilisation ultérieure de l’abstraction du téléphone. Il inscrit 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 n’importe quel 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 NULL pour ce paramètre, auquel cas TAPI utilise le handle de module de l’exécutable racine du processus.

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 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énement « handle d’événement » ou « port d’achèvement ».

lpszFriendlyAppName

Pointeur vers une chaîne null-terminated 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 PHONESTATUS pour indiquer, de manière conviviale, quelle application possède la propriété de l’appareil téléphonique. Si lpszFriendlyAppName est NULL, le nom de fichier du module de l’application est utilisé à la place (comme retourné par la fonction GetModuleFileName).

lpdwNumDevs

Pointeur vers unDWORD . 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 unDWORD . 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 passerait dans 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 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 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 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 :

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 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 PHONEINITIALIZEEXOPTION_USEHIDDENWINDOW dans le membre dwOptions dans 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 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 lephoneCallbackFunc , 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 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 phoneShutdown.
Le mécanisme Event Handle est sélectionné en spécifiant PHONEINITIALIZEEXOPTION_USEEVENT dans le membre dwOptions dans 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 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 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 nécessaire pour attendre le handle d’événement créé ; l’application peut plutôt choisir d’appeler phoneGetMessage et de bloquer l’attente d’un message.
Le mécanisme port d’achèvement est sélectionné en spécifiant PHONEINITIALIZEEXOPTION_USECOMPLETION PORT dans le membre dwOptions dans 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 au port d’achèvement que l’application spécifiée dans le membre hCompletionPort dans PHONEINITIALIZEEXPARAMS , balisé avec la clé de saisie semi-automatique que l’application spécifiée dans le membre dwCompletionKey dans PHONEINITIALIZEEXPARAMS. L’application doit avoir créé précédemment le port d’achèvement à l’aide de CreateIoCompletionPort. Les applications récupèrent des événements à l’aide de GetQueuedCompletionStatus. Lors du retour de GetQueuedCompletionStatus, l’application a la dwCompletionKey spécifiée écrite dans la DWORD pointée par le paramètre lpCompletionKey et un pointeur vers une structure PHONE MESSAGE retournée à l’emplacement vers lequel lpOverlapped. Une fois l’application traitée 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 la fermer ; l’application ne doit pas fermer le port d’achèvement tant qu’elle n’a pas appelé phoneShutdown.

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 PHONEERR_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), phoneInitializeEx demandes 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 stade, 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 spécifié n’est pas valide.

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

Note

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