時間の経過と同時に、TAPI、アプリケーション、および回線または電話のサービス プロバイダーには、異なるバージョンが存在する可能性があります。 新しいバージョンでは、新機能、データ構造に対する新しいフィールドなどを定義できます。 したがって、バージョン番号は、さまざまなデータ構造を解釈する方法を示します。
さまざまなバージョンのアプリケーション、TAPI 自体のバージョン、および異なるベンダーによるサービス プロバイダーのバージョンの最適な相互運用性を実現するために、TAPI は、アプリケーション用のシンプルな 2 段階認証のネゴシエーション メカニズムを提供します。 2 つの異なるバージョンが、アプリケーション、TAPI、および各回線デバイスのサービス プロバイダーによって合意されている必要があります。 1 つ目は Basic テレフォニーと補助テレフォニーのバージョン番号で、API バージョンと呼ばれます。 もう 1 つはプロバイダー固有の拡張機能 (存在する場合) 用であり、拡張機能のバージョンと呼ばれます。 TAPI の基本機能と補助機能で使用されるデータ構造とデータ型の形式は API バージョンによって定義され、拡張機能のバージョンではベンダー固有の拡張機能によって定義されるデータ構造の形式が決まります。
バージョン ネゴシエーションは 2 つのフェーズで続行されます。 最初のフェーズでは、API バージョン番号がネゴシエートされ、デバイスでサポートされているベンダー固有の拡張機能に関連付けられている拡張機能識別子が取得されます。 2 番目のフェーズでは、拡張機能のバージョンがネゴシエートされます。 アプリケーションで API 拡張機能が使用されていない場合、2 番目のフェーズはスキップされ、拡張機能はサービス プロバイダーによってアクティブ化されません。 アプリケーションで拡張機能を使用する必要があるが、サービス プロバイダーの拡張機能 (拡張機能識別子) がアプリケーションで認識されない場合、アプリケーションは拡張機能バージョンのネゴシエーションもスキップする必要があります。 各ベンダーには、配布する拡張機能仕様のセットごとに、独自の有効な (認識された) バージョンのセットがあります。
lineNegotiateAPIVersion 関数は、使用する API バージョン番号をネゴシエートするために使用されます。 また、ライン デバイスでサポートされている拡張機能識別子も取得され、拡張機能がサポートされていない場合は 0 が返されます。 この関数呼び出しにより、アプリケーションは互換性のある API バージョンの範囲を提供します。 TAPI は次に、ラインのサービス プロバイダーとネゴシエートして、サポートされている API バージョンの範囲を決定します。 TAPI は次に、アプリケーション、DLL、およびサービス プロバイダーが提供した重複するバージョン範囲のバージョン番号 (通常は必ずしも最も高いバージョン番号ではありません) を選択します。 この番号は、その行のサービス プロバイダーから使用可能な拡張機能を定義する拡張機能識別子と共に、アプリケーションに返されます。
返された拡張機能識別子によって定義された拡張機能をアプリケーションで使用する場合は、最初に lineNegotiateExtVersion呼び出して拡張機能のバージョンをネゴシエートする必要があります。 同様のネゴシエーション フェーズでは、アプリケーションは既に合意されている API バージョンと、それがサポートする拡張機能のバージョン範囲を指定します。 TAPI は、この情報を回線のサービス プロバイダーに渡します。 サービス プロバイダーは、API のバージョンと拡張機能のバージョン範囲をそれ自体に対してチェックし、適切な拡張機能のバージョン番号 (存在する場合) を選択します。
アプリケーションは、後で lineGetDevCaps呼び出すと、バージョン ネゴシエーションの結果に対応する行のデバイス機能のセットを返します。 これには、API バージョンと一致する回線のデバイス機能と、拡張機能のバージョンと一致する回線のデバイス固有の機能が含まれます。 アプリケーションでは、行を開くときに、これらのバージョン番号の両方を指定する必要があります。 その時点で、アプリケーション、DLL、およびサービス プロバイダーは、合意されたバージョンの使用にコミットされます。 デバイス固有の拡張機能を使用しない場合は、拡張機能のバージョンを 0 として指定する必要があります。
複数のアプリケーションが同じ回線デバイスを開く環境では、回線デバイスを開く最初のアプリケーションは、その行を使用するすべての将来のアプリケーションのバージョンを選択します (サービス プロバイダーは複数のバージョンを同時にサポートしていません)。同様に、複数の回線デバイスを開くアプリケーションでは、すべての回線デバイスを同じ API バージョン番号で簡単に操作できる場合があります。
dwAPIVersion または同様のパラメーターを受け取る関数はすべて、このパラメーターを、アプリケーションでサポートされている最も高い API バージョン、または lineNegotiateAPIVersion を使用してネゴシエートされた API バージョン、または特定のデバイスの phoneNegotiateAPIVersion関数をに設定する必要があります。 ガイドとして次の表を使用します。
| 機能 | 意味 |
|---|---|
| lineGetAddressCapsをする | lineNegotiateAPIVersionによって返されるバージョン使用します。 |
| lineGetCountryをする | アプリケーションでサポートされている最高バージョンを使用します。 |
| lineGetDevCapsをする | lineNegotiateAPIVersionによって返されるバージョン使用します。 |
| lineGetProviderListをする | アプリケーションでサポートされている最高バージョンを使用します。 |
| lineGetTranslateCapsをする | アプリケーションでサポートされている最高バージョンを使用します。 |
| lineNegotiateAPIVersion | アプリケーションでサポートされている最高バージョンを使用します。 |
| lineNegotiateExtVersionをする | lineNegotiateAPIVersionによって返されるバージョン使用します。 |
| lineOpen | lineNegotiateAPIVersionによって返されるバージョン使用します。 |
| lineTranslateAddressをする | アプリケーションでサポートされている最高バージョンを使用します。 |
| lineTranslateDialogをする | アプリケーションでサポートされている最高バージョンを使用します。 |
| phoneGetDevCapsをする | phoneNegotiateAPIVersionによって返されるバージョン使用します。 |
| phoneNegotiateAPIVersionをする | アプリケーションでサポートされている最高バージョンを使用します。 |
| phoneNegotiateExtVersionをする | phoneNegotiateAPIVersionによって返されるバージョン使用します。 |
| phoneOpenをする | phoneNegotiateAPIVersionによって返されるバージョン使用します。 |
大事な
API バージョンをネゴシエートするときは、常に高いバージョン番号と低いバージョン番号を、アプリケーションでサポートできるバージョンの範囲に設定します。 たとえば、低いバージョンの場合は 0x00000000 を使用しないでください。また、高い値には、過去 0xFFFFFFFFと将来の両方の TAPI のすべてのバージョンをアプリケーションでサポートする必要があるためです。