TAPI バージョン ネゴシエーション
時間の経過と同時に、TAPI、アプリケーション、および回線または電話のサービス プロバイダーには、異なるバージョンが存在する可能性があります。 新しいバージョンでは、新機能、データ構造に対する新しいフィールドなどを定義できます。 したがって、バージョン番号は、さまざまなデータ構造を解釈する方法を示します。
TAPI は、さまざまなバージョンのアプリケーション、TAPI 自体のバージョン、および異なるベンダーによるサービス プロバイダーのバージョンの最適な相互運用性を実現するために、アプリケーション用のシンプルな 2 段階バージョン ネゴシエーション メカニズムを提供します。 アプリケーション、TAPI、および各回線デバイスのサービス プロバイダーによって、2 つの異なるバージョンが合意されている必要があります。 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、およびサービス プロバイダーは、合意されたバージョンの使用にコミットされます。 デバイス固有の拡張機能を使用しない場合は、拡張機能のバージョンをゼロとして指定する必要があります。
複数のアプリケーションが同じ回線デバイスを開く環境では、回線デバイスを開く最初のアプリケーションは、その回線を使用するすべての将来のアプリケーションのバージョンを選択します (サービス プロバイダーは複数のバージョンを同時にサポートしていません)。同様に、複数の回線デバイスを開くアプリケーションでは、すべての回線デバイスを同じ API バージョン番号で簡単に操作できる場合があります。
dwAPIVersion または同様のパラメーターを受け取る関数はすべて、このパラメーターを、アプリケーションでサポートされている最高の API バージョンまたは特定のデバイスの lineNegotiateAPIVersion 関数または phoneNegotiateAPIVersion 関数を使用してネゴシエートされた API バージョンに設定する必要があります。 次の表をガイドとして使用します。
| 機能 | 説明 |
|---|---|
| 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 がサポートされている必要があるためです。