fungsi TSPI_providerInit (tspi.h)

Artikel
08/26/2023

Fungsi TSPI_providerInit menginisialisasi penyedia layanan dan memberinya parameter yang diperlukan untuk operasi berikutnya.

Sintaks

LONG TSPIAPI TSPI_providerInit(
  DWORD            dwTSPIVersion,
  DWORD            dwPermanentProviderID,
  DWORD            dwLineDeviceIDBase,
  DWORD            dwPhoneDeviceIDBase,
  DWORD_PTR        dwNumLines,
  DWORD_PTR        dwNumPhones,
  ASYNC_COMPLETION lpfnCompletionProc,
  LPDWORD          lpdwTSPIOptions
);

Parameter

dwTSPIVersion

Versi definisi TSPI tempat fungsi ini harus beroperasi. Pemanggil dapat menggunakan TSPI_lineNegotiateTSPIVersion dengan INITIALIZE_NEGOTIATION dwDeviceID khusus untuk menegosiasikan versi yang dijamin dapat diterima oleh penyedia layanan.

dwPermanentProviderID

Pengidentifikasi permanen, unik dalam penyedia layanan pada sistem ini, dari penyedia layanan yang sedang diinisialisasi.

dwLineDeviceIDBase

Pengidentifikasi perangkat terendah untuk perangkat baris yang didukung oleh penyedia layanan ini.

dwPhoneDeviceIDBase

Pengidentifikasi perangkat terendah untuk perangkat telepon yang didukung oleh penyedia layanan ini.

dwNumLines

Jumlah perangkat baris yang didukung penyedia layanan ini. Nilai yang dikembalikan adalah jumlah perangkat baris yang dilaporkan dalam TSPI_providerEnumDevices.

dwNumPhones

Jumlah perangkat telepon yang didukung penyedia layanan ini. Nilai yang dikembalikan adalah jumlah perangkat telepon yang dilaporkan dalam TSPI_providerEnumDevices.

lpfnCompletionProc

Prosedur yang dipanggil penyedia layanan untuk melaporkan penyelesaian semua prosedur pengoperasian secara asinkron pada perangkat saluran dan telepon.

lpdwTSPIOptions

Pointer ke lokasi memori berukuran DWORD, tempat penyedia layanan dapat menulis nilai yang menentukan nilai LINETSPIOPTIONS_. Parameter ini memungkinkan penyedia layanan untuk mengembalikan bit yang menunjukkan perilaku opsional yang diinginkan TAPI. TAPI mengatur opsi DWORD ke 0 sebelum memanggil TSPI_providerInit, jadi jika penyedia layanan tidak menginginkan salah satu opsi ini, itu hanya dapat membiarkan DWORD diatur ke 0.

Saat ini, hanya satu bit yang didefinisikan untuk dikembalikan melalui pointer ini: LINETSPIOPTION_NONREENTRANT. Penyedia layanan menetapkan bit ini jika tidak dirancang untuk operasi multitasking, multitugas, multiprosesor yang sepenuhnya preemptif, multiprosesor (misalnya, memperbarui data global yang dilindungi oleh mutex). Ketika bit ini diatur, TAPI hanya melakukan satu panggilan pada satu waktu ke penyedia layanan; ini tidak memanggil titik masuk lain, atau titik masuk lagi, sampai penyedia layanan kembali dari panggilan fungsi asli. Tanpa set bit ini, TAPI dapat memanggil beberapa titik masuk penyedia layanan, termasuk beberapa kali ke titik masuk yang sama, secara bersamaan (sebenarnya secara bersamaan dalam sistem multiprosedur).

CatatanPenting: Harus ditekankan bahwa pengaturan bit ini menurunkan performa. Sangat disarankan bahwa ini hanya digunakan untuk pengembangan tetapi bukan penyedia layanan produksi yang dikirim.

TAPI tidak menserialisasikan akses ke fungsi TSPI yang menampilkan kotak dialog ( TUISPI_lineConfigDialog, TUISPI_lineConfigDialogEdit, TUISPI_phoneConfigDialog, TUISPI_providerConfig, TUISPI_providerInstall, TUISPI_providerRemove) sehingga tidak memblokir fungsi TSPI lainnya agar tidak dipanggil; penyedia layanan harus menyertakan perlindungan internal pada fungsi-fungsi ini.

Nilai kembali

Mengembalikan nol jika fungsi berhasil atau angka kesalahan jika terjadi kesalahan. Kemungkinan nilai yang dikembalikan adalah sebagai berikut:

LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL, LINEERR_INIFILECORRUPT, LINEERR_NOMULTIPLEINSTANCE.

Keterangan

Fungsi ini dijamin akan dipanggil sebelum salah satu fungsi lain diawali dengan TSPI_line atau TSPI_phone kecuali TSPI_lineNegotiateTSPIVersion. Ini dipasangkan secara ketat dengan panggilan berikutnya ke TSPI_providerShutdown Pasangan ini dapat tumpang tindih, misalnya, ketika utilitas telefoni Panel Kontrol disediakan dengan Windows Telephony dalam versi 1.4 dan yang lebih lama digunakan saat operasi telefoni sedang berlangsung. Panggilan ke fungsi ini harus diabaikan (mengembalikan keberhasilan) jika sudah ada pasangan yang luar biasa.

Penyedia layanan harus melakukan pemeriksaan konsistensi sebanyak yang praktis pada saat itu. TSPI_providerInit dipanggil untuk memastikan bahwa siap dijalankan. Namun, beberapa kesalahan konsistensi atau penginstalan tidak dapat dideteksi hingga operasi dicoba. Kesalahan LINEERR_NODRIVER dapat digunakan untuk melaporkan kesalahan nonspesfik tersebut pada saat terdeteksi.

Tidak ada fungsi yang sesuai langsung di tingkat TAPI. Pada tingkat tersebut, beberapa instans penggunaan yang berbeda dapat menjadi luar biasa, dengan "handel aplikasi" dikembalikan untuk mengidentifikasi instans dalam operasi berikutnya. Pada tingkat TSPI, arsitektur antarmuka hanya mendukung satu instans penggunaan untuk setiap penyedia layanan yang berbeda.