fungsi lineInitialize (tapi.h)

Artikel
03/08/2023

Fungsi lineInitialize sudah usang. Ini terus diekspor oleh Tapi.dll dan Tapi32.dll untuk kompatibilitas mundur dengan aplikasi menggunakan API versi 1.3 dan 1.4.

Aplikasi yang menggunakan API versi 2.0 atau yang lebih baru harus menggunakan lineInitializeEx sebagai gantinya.

Untuk TAPI Versi 1.4 dan Yang Lebih Lama: Fungsi lineInitialize menginisialisasi penggunaan Tapi.dll aplikasi untuk penggunaan abstraksi baris berikutnya. Fungsi ini mendaftarkan mekanisme pemberitahuan yang ditentukan aplikasi dan mengembalikan jumlah perangkat baris yang tersedia untuk aplikasi. Perangkat baris adalah perangkat apa pun yang menyediakan implementasi untuk fungsi awalan baris di TAPI.

Sintaks

LONG lineInitialize(
  LPHLINEAPP   lphLineApp,
  HINSTANCE    hInstance,
  LINECALLBACK lpfnCallback,
  LPCSTR       lpszAppName,
  LPDWORD      lpdwNumDevs
);

Parameter

lphLineApp

Arahkan ke lokasi yang diisi dengan handel penggunaan aplikasi untuk TAPI.

hInstance

Penanganan instans aplikasi klien atau DLL.

lpfnCallback

Alamat fungsi panggilan balik yang dipanggil untuk menentukan status dan peristiwa pada perangkat baris, alamat, atau panggilan. Untuk informasi selengkapnya, lihat lineCallbackFunc.

lpszAppName

Penunjuk ke string teks yang dihentikan null yang hanya berisi karakter yang dapat ditampilkan. Jika parameter ini bukan NULL, parameter ini berisi nama yang disediakan aplikasi untuk aplikasi. Nama ini disediakan dalam struktur LINECALLINFO untuk menunjukkan, dengan cara yang mudah digunakan, aplikasi mana yang berasal, atau awalnya diterima atau menjawab panggilan. Informasi ini dapat berguna untuk tujuan pengelogan panggilan. Jika lpszAppNameADALAH NULL, nama file aplikasi akan digunakan sebagai gantinya.

lpdwNumDevs

Arahkan ke lokasi berukuran DWORD. Setelah berhasil menyelesaikan permintaan ini, lokasi ini diisi dengan jumlah perangkat baris yang tersedia untuk aplikasi.

Menampilkan nilai

Mengembalikan nol jika permintaan berhasil atau angka kesalahan negatif jika terjadi kesalahan. Nilai yang mungkin dikembalikan adalah:

LINEERR_INVALAPPNAME, LINEERR_OPERATIONFAILED, LINEERR_INIFILECORRUPT, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_REINIT, LINEERR_NODRIVER, LINEERR_NODEVICE, LINEERR_NOMEM, LINEERR_NOMULTIPLEINSTANCE.

Keterangan

Jika LINEERR_REINIT dikembalikan dan reinisialisasi TAPI telah diminta (misalnya sebagai akibat dari menambahkan atau menghapus penyedia layanan telepon), maka permintaan lineInitialize ditolak dengan kesalahan ini sampai aplikasi terakhir mematikan penggunaan API (menggunakan lineShutdown). Pada saat itu, konfigurasi baru menjadi efektif dan aplikasi sekali lagi diizinkan untuk memanggil lineInitialize. Jika nilai kesalahan LINEERR_INVALPARAM dikembalikan, parameter hInstance yang ditentukan tidak valid.

Aplikasi ini dapat merujuk ke perangkat baris individual dengan menggunakan pengidentifikasi perangkat baris yang berkisar dari nol hingga dwNumDevs dikurangi satu. Aplikasi tidak boleh berasumsi bahwa perangkat baris ini mampu melakukan apa pun di luar apa yang ditentukan oleh subset Telepon Dasar tanpa terlebih dahulu mengkueri kemampuan perangkat mereka menggunakan lineGetDevCaps dan lineGetAddressCaps.

Aplikasi tidak boleh memanggil lineInitialize tanpa kemudian membuka baris (setidaknya untuk pemantauan). Jika aplikasi tidak memantau dan tidak menggunakan perangkat apa pun, aplikasi harus memanggil lineShutdown sehingga sumber daya memori yang dialokasikan oleh Tapi.dll dapat dirilis jika tidak diperlukan, dan Tapi.dll itu sendiri dapat dibongkar dari memori saat tidak diperlukan.

Alasan lain untuk melakukan lineShutdown adalah bahwa jika pengguna mengubah konfigurasi perangkat (menambahkan atau menghapus saluran atau telepon), tidak ada cara bagi TAPI untuk memberi tahu aplikasi yang membuka handel saluran atau telepon pada saat itu. Setelah konfigurasi ulang terjadi, menyebabkan pesan LINEDEVSTATE_REINIT dikirim, tidak ada aplikasi yang dapat membuka perangkat sampai semua aplikasi telah melakukan lineShutdown. Jika ada penyedia layanan yang gagal menginisialisasi dengan benar, fungsi ini gagal dan mengembalikan kesalahan yang ditunjukkan oleh penyedia layanan.

Pada semua platform TAPI, lineInitialize setara dengan lineInitializeEx menggunakan opsi LINEINITIALIZEEXOPTION_USEHIDDENWINDOW.