TAPI-Versionsverhandlung
Im Laufe der Zeit können verschiedene Versionen für TAPI, Anwendungen und Dienstanbieter für eine Leitung oder ein Telefon vorhanden sein. Neue Versionen können neue Features, neue Felder für Datenstrukturen usw. definieren. Versionsnummern geben daher an, wie verschiedene Datenstrukturen interpretiert werden.
Um eine optimale Interoperabilität verschiedener Versionen von Anwendungen, Versionen von TAPI selbst und Versionen von Dienstanbietern durch verschiedene Anbieter zu ermöglichen, bietet TAPI einen einfachen, zweistufigen Versionsverhandlungsmechanismus für Anwendungen. Zwei verschiedene Versionen müssen von der Anwendung, TAPI und dem Dienstanbieter für jedes Leitungsgerät vereinbart werden. Die erste ist die Versionsnummer für die standard- und ergänzende Telefonie und wird als API-Version bezeichnet. Die andere ist für anbieterspezifische Erweiterungen, falls vorhanden, und wird als Erweiterungsversion bezeichnet. Das Format der Datenstrukturen und Datentypen, die von den grundlegenden und zusätzlichen Funktionen von TAPI verwendet werden, wird von der API-Version definiert, während die Erweiterungsversion das Format der Datenstrukturen bestimmt, die von den anbieterspezifischen Erweiterungen definiert werden.
Die Versionsaushandlung erfolgt in zwei Phasen. In der ersten Phase wird die API-Versionsnummer ausgehandelt und der Erweiterungsbezeichner abgerufen, der allen herstellerspezifischen Erweiterungen zugeordnet ist, die auf dem Gerät unterstützt werden. In der zweiten Phase wird die Erweiterungsversion ausgehandelt. Wenn die Anwendung keine API-Erweiterungen verwendet, überspringt sie die zweite Phase, und Erweiterungen werden vom Dienstanbieter nicht aktiviert. Wenn die Anwendung Erweiterungen verwenden möchte, aber die Erweiterungen des Dienstanbieters (der Erweiterungsbezeichner) von der Anwendung nicht erkannt werden, sollte die Anwendung auch die Aushandlung für die Erweiterungsversion überspringen. Jeder Anbieter verfügt über einen eigenen Satz von gesetzlichen (anerkannten) Versionen für jeden Satz von Erweiterungsspezifikationen, die er verteilt.
Die lineNegotiateAPIVersion-Funktion wird verwendet, um die zu verwendende API-Versionsnummer auszuhandeln. Es ruft auch den erweiterungsbezeichner ab, der vom Zeilengerät unterstützt wird, und gibt Nullen zurück, wenn keine Erweiterungen unterstützt werden. Mit diesem Funktionsaufruf stellt die Anwendung den API-Versionsbereich bereit, mit dem sie kompatibel ist. TAPI verhandelt wiederum mit dem Dienstanbieter der Linie, um zu ermitteln, welcher API-Versionsbereich unterstützt wird. TAPI wählt als Nächstes eine Versionsnummer (in der Regel jedoch nicht unbedingt die höchste Versionsnummer) im überlappenden Versionsbereich aus, den die Anwendung, die DLL und der Dienstanbieter bereitgestellt haben. Diese Nummer wird an die Anwendung zurückgegeben, zusammen mit dem Erweiterungsbezeichner, der die vom Dienstanbieter dieser Zeile verfügbaren Erweiterungen definiert.
Wenn die Anwendung die durch den zurückgegebenen Erweiterungsbezeichner definierten Erweiterungen verwenden möchte, muss sie zuerst lineNegotiateExtVersion aufrufen, um die Erweiterungsversion auszuhandeln. In einer ähnlichen Aushandlungsphase gibt die Anwendung die bereits vereinbarte API-Version und den unterstützten Erweiterungsversionsbereich an. TAPI übergibt diese Informationen an den Dienstanbieter für die Zeile. Der Dienstanbieter überprüft die API-Version und den Erweiterungsversionsbereich anhand ihres eigenen und wählt die entsprechende Erweiterungsversionsnummer aus, sofern vorhanden.
Wenn die Anwendung später lineGetDevCaps aufruft, gibt sie eine Reihe von Gerätefunktionen für die Zeile zurück, die den Ergebnissen der Versionsaushandlung entsprechen. Dazu gehören die Gerätefunktionen der Linie, die mit der API-Version konsistent sind, und die gerätespezifischen Funktionen der Linie, die mit der Erweiterungsversion konsistent sind. Die Anwendung muss beide Versionsnummern angeben, wenn sie eine Zeile öffnet. Zu diesem Zeitpunkt sind die Anwendung, die DLL und der Dienstanbieter verpflichtet, die vereinbarten Versionen zu verwenden. Wenn keine gerätespezifischen Erweiterungen verwendet werden sollen, sollte die Erweiterungsversion als Null angegeben werden.
In einer Umgebung, in der mehrere Anwendungen dasselbe Leitungsgerät öffnen, wählt die erste Anwendung zum Öffnen des Leitungsgeräts die Versionen für alle zukünftigen Anwendungen aus, die die Leitung verwenden möchten (Dienstanbieter unterstützen nicht mehrere Versionen gleichzeitig.) Ebenso kann es für eine Anwendung, die mehrere Zeilengeräte öffnet, einfacher sein, alle Leitungsgeräte unter derselben API-Versionsnummer zu betreiben.
Jede Funktion, die einen dwAPIVersion-Parameter oder einen ähnlichen Parameter verwendet, muss diesen Parameter auf die höchste API-Version festlegen, die von der Anwendung unterstützt wird, oder auf die API-Version, die mit der funktion lineNegotiateAPIVersion oder phoneNegotiateAPIVersion auf einem bestimmten Gerät ausgehandelt wird. Verwenden Sie die folgende Tabelle als Richtlinie:
| Funktion | Bedeutung |
|---|---|
| lineGetAddressCaps | Verwenden Sie die von lineNegotiateAPIVersion zurückgegebene Version. |
| lineGetCountry | Verwenden Sie die höchste Version, die von der Anwendung unterstützt wird. |
| lineGetDevCaps | Verwenden Sie die von lineNegotiateAPIVersion zurückgegebene Version. |
| lineGetProviderList | Verwenden Sie die höchste Version, die von der Anwendung unterstützt wird. |
| lineGetTranslateCaps | Verwenden Sie die höchste Version, die von der Anwendung unterstützt wird. |
| lineNegotiateAPIVersion | Verwenden Sie die höchste Version, die von der Anwendung unterstützt wird. |
| lineNegotiateExtVersion | Verwenden Sie die von lineNegotiateAPIVersion zurückgegebene Version. |
| lineÖffnen | Verwenden Sie die von lineNegotiateAPIVersion zurückgegebene Version. |
| lineTranslateAddress | Verwenden Sie die höchste Version, die von der Anwendung unterstützt wird. |
| lineTranslateDialog | Verwenden Sie die höchste Version, die von der Anwendung unterstützt wird. |
| phoneGetDevCaps | Verwenden Sie die von phoneNegotiateAPIVersion zurückgegebene Version. |
| phoneNegotiateAPIVersion | Verwenden Sie die höchste Version, die von der Anwendung unterstützt wird. |
| phoneNegotiateExtVersion | Verwenden Sie die von phoneNegotiateAPIVersion zurückgegebene Version. |
| phoneOpen | Verwenden Sie die von phoneNegotiateAPIVersion zurückgegebene Version. |
Wichtig
Legen Sie beim Aushandeln einer API-Version immer die hohen und niedrigen Versionsnummern auf den Versionsbereich fest, den Ihre Anwendung unterstützen kann. Verwenden Sie beispielsweise niemals 0x00000000 für die niedrige Version oder 0xFFFFFFFF für die hohe Version, da diese Werte erfordern, dass Ihre Anwendung alle früheren und zukünftigen TAPI-Versionen unterstützt.