fungsi lineInitializeExA (tapi.h)

Artikel
08/26/2023

Fungsi lineInitializeEx menginisialisasi penggunaan TAPI aplikasi untuk penggunaan abstraksi baris berikutnya. 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 API Telepon.

Sintaks

LONG lineInitializeExA(
  LPHLINEAPP               lphLineApp,
  HINSTANCE                hInstance,
  LINECALLBACK             lpfnCallback,
  LPCSTR                   lpszFriendlyAppName,
  LPDWORD                  lpdwNumDevs,
  LPDWORD                  lpdwAPIVersion,
  LPLINEINITIALIZEEXPARAMS lpLineInitializeExParams
);

Parameter

lphLineApp

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

hInstance

Penanganan instans aplikasi klien atau DLL. Aplikasi atau DLL dapat meneruskan NULL untuk parameter ini, dalam hal ini TAPI menggunakan handel modul dari root executable proses (untuk tujuan mengidentifikasi target handoff panggilan dan prioritas mode media).

lpfnCallback

Alamat fungsi panggilan balik yang dipanggil untuk menentukan status dan peristiwa pada perangkat baris, alamat, atau panggilan, ketika aplikasi menggunakan metode pemberitahuan peristiwa "jendela tersembunyi" (untuk informasi selengkapnya lihat lineCallbackFunc). Parameter ini diabaikan dan harus diatur ke NULL ketika aplikasi memilih untuk menggunakan mekanisme pemberitahuan peristiwa "penanganan aktivitas" atau "port penyelesaian".

lpszFriendlyAppName

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 lpszFriendlyAppName adalah NULL, nama file modul aplikasi digunakan sebagai gantinya (seperti yang dikembalikan oleh fungsi GetModuleFileName).

lpdwNumDevs

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

lpdwAPIVersion

Arahkan ke lokasi berukuran DWORD. Aplikasi harus menginisialisasi DWORD ini, sebelum memanggil fungsi ini, ke versi API tertinggi yang dirancang untuk mendukung (misalnya, nilai yang sama akan diteruskan ke parameter dwAPIHighVersionlineNegotiateAPIVersion). Nilai tinggi buatan tidak boleh digunakan; nilai harus diatur secara akurat. TAPI menerjemahkan pesan atau struktur yang lebih baru ke dalam nilai atau format yang didukung oleh versi aplikasi. Setelah berhasil menyelesaikan permintaan ini, lokasi ini diisi dengan versi API tertinggi yang didukung oleh TAPI, sehingga memungkinkan aplikasi untuk mendeteksi dan beradaptasi dengan telah diinstal pada sistem dengan versi TAPI yang berbeda.

lpLineInitializeExParams

Pointer ke struktur jenis LINEINITIALIZEEXPARAMS yang berisi parameter tambahan yang digunakan untuk membangun hubungan antara aplikasi dan TAPI (khususnya, mekanisme pemberitahuan peristiwa yang dipilih aplikasi dan parameter terkait).

Mengembalikan 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_INVALPOINTER, LINEERR_REINIT, LINEERR_NOMEM, LINEERR_INVALPARAM.

Keterangan

Aplikasi harus memilih salah satu dari tiga mekanisme di mana TAPI memberi tahu aplikasi peristiwa telepon: Jendela Tersembunyi, Handel Peristiwa, atau Port Penyelesaian.

Mekanisme Jendela Tersembunyi dipilih dengan menentukan LINEINITIALIZEEXOPTION_USEHIDDENWINDOW di anggota dwOptions dalam struktur LINEINITIALIZEEXPARAMS . Dalam mekanisme ini (yang merupakan satu-satunya mekanisme yang tersedia untuk TAPI versi 1.x aplikasi), TAPI membuat jendela dalam konteks aplikasi selama lineInitializeEx atau lineInitialize (untuk tapi versi 1.3 dan 1.4 aplikasi) fungsi, dan subkelas jendela sehingga semua pesan yang diposting ke dalamnya ditangani oleh WNDPROC di TAPI itu sendiri. Ketika TAPI memiliki pesan untuk dikirimkan ke aplikasi, TAPI memposting pesan ke jendela tersembunyi. Ketika pesan diterima (yang hanya dapat terjadi ketika aplikasi memanggil fungsi Windows GetMessage ), Windows mengalihkan konteks proses ke aplikasi dan memanggil WNDPROC di TAPI. TAPI kemudian mengirimkan pesan ke aplikasi dengan memanggil lineCallbackProc, pointer yang disediakan aplikasi sebagai parameter dalam panggilannya ke lineInitializeEx (atau lineInitialize). Mekanisme ini mengharuskan aplikasi memiliki antrean pesan (yang tidak diinginkan untuk proses layanan) dan untuk melayani antrean tersebut secara teratur untuk menghindari penundaan pemrosesan peristiwa telepon. Jendela tersembunyi dihancurkan oleh TAPI selama fungsi lineShutdown .

Mekanisme Penanganan Aktivitas dipilih dengan menentukan LINEINITIALIZEEXOPTION_USEEVENT di anggota dwOptions dalam struktur LINEINITIALIZEEXPARAMS . Dalam mekanisme ini, TAPI membuat objek peristiwa atas nama aplikasi, dan mengembalikan handel ke objek di anggota hEvent di LINEINITIALIZEEXPARAMS. Aplikasi tidak boleh memanipulasi peristiwa ini dengan cara apa pun (misalnya, tidak boleh memanggil SetEvent, ResetEvent, CloseHandle, dan sebagainya) atau hasil perilaku yang tidak terdefinisi; aplikasi hanya dapat menunggu pada peristiwa ini menggunakan fungsi seperti WaitForSingleObject atau MsgWaitForMultipleObjects. TAPI memberi sinyal peristiwa ini setiap kali pemberitahuan peristiwa telepon tertunda untuk aplikasi; aplikasi harus memanggil lineGetMessage untuk mengambil konten pesan. Peristiwa diatur ulang oleh TAPI ketika tidak ada peristiwa yang tertunda. Penanganan aktivitas ditutup dan objek peristiwa dihancurkan oleh TAPI selama fungsi lineShutdown . Aplikasi tidak diperlukan untuk menunggu pada handel peristiwa yang dibuat; aplikasi dapat memilih untuk memanggil lineGetMessage dan memintanya memblokir menunggu pesan diantrekan.

Mekanisme Port Penyelesaian dipilih dengan menentukan port LINEINITIALIZEEXOPTION_USECOMPLETION di anggota dwOptions dalam struktur LINEINITIALIZEEXPARAMS . Dalam mekanisme ini, setiap kali peristiwa telepon perlu dikirim ke aplikasi, TAPI mengirimkannya menggunakan PostQueuedCompletionStatus ke port penyelesaian yang ditentukan aplikasi dalam anggota hCompletionPort di LINEINITIALIZEEXPARAMS, ditandai dengan kunci penyelesaian yang ditentukan aplikasi dalam anggota dwCompletionKey di LINEINITIALIZEEXPARAMS. Aplikasi sebelumnya harus membuat port penyelesaian menggunakan CreateIoCompletionPort. Aplikasi mengambil peristiwa menggunakan GetQueuedCompletionStatus. Setelah kembali dari GetQueuedCompletionStatus, aplikasi memiliki dwCompletionKey yang ditentukan yang ditulis ke DWORD yang diarahkan oleh parameter lpCompletionKey , dan penunjuk ke struktur LINEMESSAGE yang dikembalikan ke lokasi yang diarahkan oleh lpOverlapped. Setelah aplikasi memproses peristiwa, aplikasi bertanggung jawab untuk memanggil LocalFree untuk merilis memori yang digunakan untuk berisi struktur LINEMESSAGE . Karena aplikasi membuat port penyelesaian (sehingga memungkinkannya dibagi untuk tujuan lain), aplikasi harus menutupnya; aplikasi tidak boleh menutup port penyelesaian sampai setelah memanggil lineShutdown.

Ketika aplikasi multithread menggunakan mekanisme Event Handle dan lebih dari satu utas menunggu handel, atau mekanisme pemberitahuan Port Penyelesaian dan lebih dari satu utas menunggu di port, dimungkinkan untuk peristiwa telepon diproses secara tidak berurutan. Ini bukan karena urutan pengiriman peristiwa dari TAPI, tetapi akan disebabkan oleh pengirisan waktu utas atau eksekusi utas pada prosesor terpisah.

Jika LINEERR_REINIT dikembalikan dan reinisialisasi TAPI telah diminta, misalnya sebagai akibat dari menambahkan atau menghapus penyedia layanan telepon, maka permintaan lineInitializeEx ditolak dengan kesalahan ini sampai aplikasi terakhir mematikan penggunaan API (menggunakan lineShutdown), pada saat konfigurasi baru menjadi efektif dan aplikasi sekali lagi diizinkan untuk memanggil lineInitializeEx.

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 fungsi TAPI tertentu tanpa terlebih dahulu mengkueri kemampuan perangkat mereka dengan lineGetDevCaps dan lineGetAddressCaps.

Catatan

Header tapi.h mendefinisikan lineInitializeEx sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta pra-prosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.