fonction phoneInitialize (tapi.h)

Article
03/02/2024

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

Les applications utilisant TAPI version 2.0 ou ultérieure doivent utiliser phoneInitializeEx à la place.

Pour TAPI versions 1.4 et antérieures : La fonction phoneInitialize initialise l’utilisation de TAPI par l’application pour l’utilisation ultérieure des fonctions téléphoniques dans l’API téléphonie. 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.

Syntaxe

LONG phoneInitialize(
  LPHPHONEAPP   lphPhoneApp,
  HINSTANCE     hInstance,
  PHONECALLBACK lpfnCallback,
  LPCSTR        lpszAppName,
  LPDWORD       lpdwNumDevs
);

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.

lpfnCallback

Adresse d’une fonction de rappel appelée pour déterminer status et les événements sur l’appareil téléphonique.

lpszAppName

Pointeur vers une chaîne terminée par null qui contient des caractères pouvant être affichés. Si ce paramètre n’a pas la valeur NULL, il contient un nom de l’application fourni par l’application. Ce nom est fourni dans la structure PHONESTATUS pour indiquer, de manière conviviale, quelle application est le propriétaire actuel de l’appareil téléphonique. Ces informations peuvent être utiles à des fins de journalisation et de status de création de rapports. Si lpszAppName a la valeur NULL, le nom de fichier de l’application est utilisé à la place.

lpdwNumDevs

Pointeur vers DWORD. Cet emplacement est chargé avec le nombre d’appareils téléphoniques disponibles pour l’application.

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_INIFILECORRUPT, PHONEERR_INVALPOINTER, PHONEERR_NOMEM, PHONEERR_OPERATIONFAILED, PHONEERR_REINIT, PHONEERR_RESOURCEUNAVAIL, PHONEERR_NODEVICE, PHONEERR_NODRIVER, PHONEERR_INVALPARAM

Remarques

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 de tout ce qui va au-delà de ce qui est spécifié par le sous-ensemble téléphonie assistée sans interroger d’abord les fonctionnalités de leurs appareils avec la fonction phoneGetDevCaps .

Les applications ne doivent pas appeler phoneInitialize sans ouvrir ultérieurement un téléphone (au moins pour la surveillance). Si l’application n’analyse pas et n’utilise pas d’appareils, elle doit appeler phoneShutdown afin que les ressources de mémoire allouées par TAPI puissent être libérées si elles ne sont pas nécessaires, et que TAPI lui-même puisse être déchargé de la mémoire alors qu’il n’est pas nécessaire.

Une autre raison d’effectuer une opération phoneShutdown 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 qui a une ligne ou un handle de téléphone ouvert à ce moment-là. Une fois qu’une reconfiguration a eu lieu, entraînant l’envoi d’un message PHONESTATE_REINIT, aucune application ne peut ouvrir un appareil tant que toutes les applications n’ont pas effectué une opération phoneShutdown.

Si un fournisseur de services ne parvient pas à s’initialiser correctement, la fonction phoneInitialize échoue et retourne l’erreur indiquée par le fournisseur de services. Si la valeur d’erreur PHONEERR_INVALPARAM est retournée, le paramètre hInstance spécifié n’est pas valide.