Negosiasi Versi TAPI

Seiring waktu, versi yang berbeda mungkin ada untuk TAPI, aplikasi, dan penyedia layanan untuk saluran atau telepon. Versi baru dapat menentukan fitur baru, bidang baru ke struktur data, dan sebagainya. Oleh karena itu, nomor versi menunjukkan cara menginterpretasikan berbagai struktur data.

Untuk memungkinkan interoperabilitas yang optimal dari berbagai versi aplikasi, versi TAPI itu sendiri, dan versi penyedia layanan oleh vendor yang berbeda, TAPI menyediakan mekanisme negosiasi versi dua langkah yang sederhana untuk aplikasi. Dua versi yang berbeda harus disepakati oleh aplikasi, TAPI, dan penyedia layanan untuk setiap perangkat baris. Yang pertama adalah nomor versi untuk Telepon Dasar dan Tambahan dan disebut sebagai versi API. Yang lainnya adalah untuk ekstensi khusus penyedia, jika ada, dan disebut sebagai versi ekstensi. Format struktur data dan jenis data yang digunakan oleh fitur dasar dan tambahan TAPI ditentukan oleh versi API, sementara versi ekstensi menentukan format struktur data yang ditentukan oleh ekstensi khusus vendor.

Negosiasi versi berlangsung dalam dua fase. Pada fase pertama, nomor versi API dinegosiasikan dan pengidentifikasi ekstensi yang terkait dengan ekstensi khusus vendor apa pun yang didukung pada perangkat diperoleh. Pada fase kedua, versi ekstensi dinegosiasikan. Jika aplikasi tidak menggunakan ekstensi API apa pun, aplikasi melewati fase kedua dan ekstensi tidak diaktifkan oleh penyedia layanan. Jika aplikasi memang ingin menggunakan ekstensi, tetapi ekstensi penyedia layanan (pengidentifikasi ekstensi) tidak dikenali oleh aplikasi, aplikasi harus melewati negosiasi untuk versi ekstensi juga. Setiap vendor memiliki serangkaian versi hukum (diakui) sendiri untuk setiap set spesifikasi ekstensi yang didistribusikannya.

Fungsi lineNegotiateAPIVersion digunakan untuk menegosiasikan nomor versi API untuk digunakan. Ini juga mengambil pengidentifikasi ekstensi yang didukung oleh perangkat baris, mengembalikan nol jika tidak ada ekstensi yang didukung. Dengan panggilan fungsi ini, aplikasi menyediakan rentang versi API yang kompatibel dengannya. TAPI pada gilirannya bernegosiasi dengan penyedia layanan baris untuk menentukan rentang versi API mana yang didukungnya. TAPI berikutnya memilih nomor versi (biasanya, meskipun belum tentu, nomor versi tertinggi) dalam rentang versi yang tumpang tindih yang disediakan aplikasi, DLL, dan penyedia layanan. Jumlah ini dikembalikan ke aplikasi, bersama dengan pengidentifikasi ekstensi yang menentukan ekstensi yang tersedia dari penyedia layanan baris tersebut.

Jika aplikasi ingin menggunakan ekstensi yang ditentukan oleh pengidentifikasi ekstensi yang dikembalikan, aplikasi harus terlebih dahulu memanggil lineNegotiateExtVersion untuk menegosiasikan versi ekstensi. Dalam fase negosiasi serupa, aplikasi menentukan versi API yang sudah disepakati dan rentang versi ekstensi yang didukungnya. TAPI meneruskan informasi ini ke penyedia layanan untuk baris tersebut. Penyedia layanan memeriksa versi API dan rentang versi ekstensi terhadap versinya sendiri, dan memilih nomor versi ekstensi yang sesuai, jika ada.

Ketika aplikasi kemudian memanggil lineGetDevCaps, aplikasi mengembalikan serangkaian kemampuan perangkat untuk baris yang sesuai dengan hasil negosiasi versi. Ini termasuk kemampuan perangkat baris yang konsisten dengan versi API dan kemampuan khusus perangkat baris yang konsisten dengan versi ekstensi. Aplikasi harus menentukan kedua nomor versi ini ketika membuka baris. Pada saat itu, aplikasi, DLL, dan penyedia layanan berkomitmen untuk menggunakan versi yang disepakati. Jika ekstensi khusus perangkat tidak digunakan, versi ekstensi harus ditentukan sebagai nol.

Di lingkungan di mana beberapa aplikasi membuka perangkat baris yang sama, aplikasi pertama yang membuka perangkat baris memilih versi untuk semua aplikasi di masa mendatang yang ingin menggunakan baris (penyedia layanan tidak mendukung beberapa versi secara bersamaan.) Demikian pula, aplikasi yang membuka beberapa perangkat baris mungkin merasa lebih mudah untuk mengoperasikan semua perangkat lini di bawah nomor versi API yang sama.

Setiap fungsi yang mengambil dwAPIVersion atau parameter serupa harus mengatur parameter ini ke versi API tertinggi yang didukung oleh aplikasi atau versi API yang dinegosiasikan menggunakan fungsi lineNegotiateAPIVersion atau phoneNegotiateAPIVersion pada perangkat tertentu. Gunakan tabel berikut sebagai panduan:

Fungsi	Makna
lineGetAddressCaps	Gunakan versi yang dikembalikan oleh lineNegotiateAPIVersion.
lineGetCountry	Gunakan versi tertinggi yang didukung oleh aplikasi.
lineGetDevCaps	Gunakan versi yang dikembalikan oleh lineNegotiateAPIVersion.
lineGetProviderList	Gunakan versi tertinggi yang didukung oleh aplikasi.
lineGetTranslateCaps	Gunakan versi tertinggi yang didukung oleh aplikasi.
lineNegotiateAPIVersion	Gunakan versi tertinggi yang didukung oleh aplikasi.
lineNegotiateExtVersion	Gunakan versi yang dikembalikan oleh lineNegotiateAPIVersion.
lineOpen	Gunakan versi yang dikembalikan oleh lineNegotiateAPIVersion.
lineTranslateAddress	Gunakan versi tertinggi yang didukung oleh aplikasi.
lineTranslateDialog	Gunakan versi tertinggi yang didukung oleh aplikasi.
phoneGetDevCaps	Gunakan versi yang dikembalikan oleh phoneNegotiateAPIVersion.
phoneNegotiateAPIVersion	Gunakan versi tertinggi yang didukung oleh aplikasi.
phoneNegotiateExtVersion	Gunakan versi yang dikembalikan oleh phoneNegotiateAPIVersion.
phoneBuka	Gunakan versi yang dikembalikan oleh phoneNegotiateAPIVersion.

 

Penting

Saat menegosiasikan versi API, selalu atur nomor versi tinggi dan rendah ke rentang versi yang dapat didukung aplikasi Anda. Misalnya, jangan pernah menggunakan 0x00000000 untuk versi rendah atau 0xFFFFFFFF tinggi karena nilai-nilai ini mengharuskan aplikasi Anda mendukung semua versi TAPI, baik di masa lalu maupun di masa mendatang.