Négociation de version TAPI
Au fil du temps, différentes versions peuvent exister pour TAPI, les applications et les fournisseurs de services pour une ligne ou un téléphone. Les nouvelles versions peuvent définir de nouvelles fonctionnalités, de nouveaux champs pour les structures de données, etc. Les numéros de version indiquent donc comment interpréter différentes structures de données.
Pour permettre une interopérabilité optimale des différentes versions d’applications, des versions de TAPI proprement dites et des versions de fournisseurs de services par différents fournisseurs, TAPI fournit un mécanisme simple de négociation de versions en deux étapes pour les applications. Deux versions différentes doivent être convenues par l’application, TAPI, et le fournisseur de services pour chaque appareil de ligne. La première est le numéro de version pour la téléphonie de base et supplémentaire, et est appelée version de l’API. L’autre concerne les extensions spécifiques au fournisseur, le cas échéant, et est appelée version de l’extension. Le format des structures de données et des types de données utilisés par les fonctionnalités de base et supplémentaires de TAPI est défini par la version de l’API, tandis que la version de l’extension détermine le format des structures de données définies par les extensions spécifiques au fournisseur.
La négociation de version se déroule en deux phases. Dans la première phase, le numéro de version de l’API est négocié et l’identificateur d’extension associé à toutes les extensions spécifiques au fournisseur prises en charge sur l’appareil est obtenu. Dans la deuxième phase, la version de l’extension est négociée. Si l’application n’utilise aucune extension d’API, elle ignore la deuxième phase et les extensions ne sont pas activées par le fournisseur de services. Si l’application souhaite utiliser des extensions, mais que les extensions du fournisseur de services (identificateur d’extension) ne sont pas reconnues par l’application, l’application doit également ignorer la négociation de la version de l’extension. Chaque fournisseur a son propre ensemble de versions légales (reconnues) pour chaque ensemble de spécifications d’extension qu’il distribue.
La fonction lineNegotiateAPIVersion est utilisée pour négocier le numéro de version de l’API à utiliser. Il récupère également l’identificateur d’extension pris en charge par l’appareil de ligne, en retournant des zéros si aucune extension n’est prise en charge. Avec cet appel de fonction, l’application fournit la plage de versions de l’API avec laquelle elle est compatible. TAPI négocie à son tour avec le fournisseur de services de la ligne pour déterminer la plage de versions d’API qu’il prend en charge. TAPI sélectionne ensuite un numéro de version (généralement, mais pas nécessairement, le numéro de version le plus élevé) dans la plage de versions qui se chevauchent que l’application, la DLL et le fournisseur de services ont fournis. Ce numéro est retourné à l’application, ainsi que l’identificateur d’extension qui définit les extensions disponibles auprès du fournisseur de services de cette ligne.
Si l’application souhaite utiliser les extensions définies par l’identificateur d’extension retourné, elle doit d’abord appeler lineNegotiateExtVersion pour négocier la version de l’extension. Dans une phase de négociation similaire, l’application spécifie la version de l’API déjà convenue et la plage de versions d’extension qu’elle prend en charge. TAPI transmet ces informations au fournisseur de services pour la ligne. Le fournisseur de services vérifie la version de l’API et la plage de versions d’extension par rapport à sa propre version, puis sélectionne le numéro de version d’extension approprié, le cas échéant.
Lorsque l’application appelle plus tard lineGetDevCaps, elle retourne un ensemble de fonctionnalités d’appareil pour la ligne qui correspondent aux résultats de la négociation de version. Il s’agit notamment des fonctionnalités d’appareil de la ligne cohérentes avec la version de l’API et des fonctionnalités spécifiques à l’appareil de la ligne cohérentes avec la version de l’extension. L’application doit spécifier ces deux numéros de version lorsqu’elle ouvre une ligne. À ce stade, l’application, la DLL et le fournisseur de services s’engagent à utiliser les versions convenues. Si des extensions spécifiques à l’appareil ne doivent pas être utilisées, la version de l’extension doit être spécifiée comme zéro.
Dans un environnement où plusieurs applications ouvrent le même appareil de ligne, la première application à ouvrir l’appareil de ligne sélectionne les versions de toutes les applications futures qui souhaitent utiliser la ligne (les fournisseurs de services ne prennent pas en charge plusieurs versions simultanément.) De même, une application qui ouvre plusieurs appareils de ligne peut trouver plus facile de faire fonctionner tous les appareils en ligne sous le même numéro de version d’API.
Chaque fonction qui accepte un paramètre dwAPIVersion ou similaire doit définir ce paramètre sur la version d’API la plus élevée prise en charge par l’application ou la version de l’API négociée à l’aide de la fonction lineNegotiateAPIVersion ou phoneNegotiateAPIVersion sur un appareil particulier. Utilisez le tableau suivant comme guide :
| Fonction | Signification |
|---|---|
| lineGetAddressCaps | Utilisez la version retournée par lineNegotiateAPIVersion. |
| lineGetCountry | Utilisez la version la plus élevée prise en charge par l’application. |
| lineGetDevCaps | Utilisez la version retournée par lineNegotiateAPIVersion. |
| lineGetProviderList | Utilisez la version la plus élevée prise en charge par l’application. |
| lineGetTranslateCaps | Utilisez la version la plus élevée prise en charge par l’application. |
| lineNegotiateAPIVersion | Utilisez la version la plus élevée prise en charge par l’application. |
| lineNegotiateExtVersion | Utilisez la version retournée par lineNegotiateAPIVersion. |
| lineOpen | Utilisez la version retournée par lineNegotiateAPIVersion. |
| lineTranslateAddress | Utilisez la version la plus élevée prise en charge par l’application. |
| lineTranslateDialog | Utilisez la version la plus élevée prise en charge par l’application. |
| phoneGetDevCaps | Utilisez la version retournée par phoneNegotiateAPIVersion. |
| phoneNegotiateAPIVersion | Utilisez la version la plus élevée prise en charge par l’application. |
| phoneNegotiateExtVersion | Utilisez la version retournée par phoneNegotiateAPIVersion. |
| phoneOpen | Utilisez la version retournée par phoneNegotiateAPIVersion. |
Important
Lors de la négociation d’une version d’API, définissez toujours les numéros de version élevés et faibles sur la plage de versions que votre application peut prendre en charge. Par exemple, n’utilisez jamais 0x00000000 pour la version basse ou 0xFFFFFFFF pour la valeur élevée, car ces valeurs nécessitent que votre application prend en charge toutes les versions de TAPI, passées et futures.