fonction phoneOpen (tapi.h)

Article
08/26/2023

La fonction phoneOpen ouvre l’appareil téléphonique spécifié. Un appareil téléphonique peut être ouvert à l’aide du privilège propriétaire ou du privilège de surveillance. Une application qui ouvre le téléphone avec le privilège propriétaire peut contrôler les lampes, l’affichage, la sonnerie et hookswitch ou hookswitchs du téléphone. Une application qui ouvre l’appareil téléphonique avec le privilège moniteur est avertie uniquement des événements qui se produisent sur le téléphone, tels que des modifications de hookswitch ou des appuis sur un bouton.

La propriété d’un appareil téléphonique est exclusive. En d’autres termes, une seule application peut avoir un appareil téléphonique ouvert avec des privilèges de propriétaire à la fois. Toutefois, l’appareil téléphonique peut être ouvert plusieurs fois avec le privilège de surveillance.

Syntaxe

LONG phoneOpen(
  HPHONEAPP hPhoneApp,
  DWORD     dwDeviceID,
  LPHPHONE  lphPhone,
  DWORD     dwAPIVersion,
  DWORD     dwExtVersion,
  DWORD_PTR dwCallbackInstance,
  DWORD     dwPrivilege
);

Paramètres

hPhoneApp

Gérez l’inscription de l’application avec TAPI.

dwDeviceID

Identificateur de l’appareil téléphonique à ouvrir.

lphPhone

Pointeur vers un handle HPHONE qui identifie l’appareil téléphonique ouvert. Utilisez ce handle pour identifier l’appareil lors de l’appel d’autres fonctions de contrôle téléphonique.

dwAPIVersion

Numéro de version de l’API sous lequel l’application et l’API téléphonie ont accepté de fonctionner. Ce nombre est obtenu à partir de phoneNegotiateAPIVersion.

dwExtVersion

Numéro de version d’extension sous lequel l’application et le fournisseur de services acceptent de fonctionner. Ce nombre est égal à zéro si l’application n’utilise aucune extension. Ce numéro est obtenu à partir de phoneNegotiateExtVersion.

dwCallbackInstance

L’utilisateur instance données renvoyées à l’application avec chaque message. Ce paramètre n’est pas interprété par l’API téléphonie.

dwPrivilege

Privilège demandé. Ce paramètre utilise une seule des constantes PHONEPRIVILEGE_.

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 :

PHONEERR_ALLOCATED, PHONEERR_NODRIVER, PHONEERR_BADDEVICEID, PHONEERR_NOMEM, PHONEERR_INCOMPATIBLEAPIVERSION, PHONEERR_OPERATIONFAILED, PHONEERR_INCOMPATIBLEEXTVERSION, PHONEERR_OPERATIONUNAVAIL, PHONEERR_INVALAPPHANDLE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPOINTER, PHONEERR_UNINITIALIZED, PHONEERR_INVALPRIVILEGE, PHONEERR_REINIT, PHONEERR_INUSE, PHONEERR_NODEVICE, PHONEERR_INIFILECORRUPT.

Remarques

Lors de l’ouverture d’un appareil téléphonique avec des privilèges de moniteur, l’application reçoit des messages lorsque des événements se produisent qui modifient le status du téléphone. Les messages envoyés à l’application incluent des PHONE_BUTTON et des PHONE_STATE. Ce dernier fournit une indication de l’élément status du téléphone qui a changé.

Lors de l’ouverture d’un téléphone avec des privilèges de propriétaire, l’appareil téléphonique peut être manipulé de manière à affecter l’état de l’appareil téléphonique. Une application doit uniquement ouvrir un téléphone à l’aide des privilèges de propriétaire si elle souhaite manipuler activement l’appareil téléphonique, et elle doit fermer l’appareil téléphonique lorsque vous avez terminé pour permettre à d’autres applications de contrôler le téléphone.

Lorsqu’une application ouvre un appareil téléphonique, elle doit spécifier la version de l’API négociée et, si elle souhaite utiliser les extensions du téléphone, la version de l’extension spécifique à l’appareil du téléphone. Ce numéro de version doit avoir été obtenu avec les fonctions phoneNegotiateAPIVersion et phoneNegotiateExtVersion . La numérotation des versions permet la combinaison et la correspondance de différentes versions d’application avec des versions d’API et des versions de fournisseur de services différentes.