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.
Sintaksis
LONG lineInitializeExA(
LPHLINEAPP lphLineApp,
HINSTANCE hInstance,
LINECALLBACK lpfnCallback,
LPCSTR lpszFriendlyAppName,
LPDWORD lpdwNumDevs,
LPDWORD lpdwAPIVersion,
LPLINEINITIALIZEEXPARAMS lpLineInitializeExParams
);
Parameter
lphLineApp
Penunjuk 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 akar yang dapat dieksekusi dari 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 nullnull yang hanya berisi karakter yang dapat ditampilkan. Jika parameter ini tidak 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 lpszFriendlyAppNameNULL, nama file modul aplikasi digunakan sebagai gantinya (sebagaimana dikembalikan oleh fungsi GetModuleFileName).
lpdwNumDevs
Penunjuk ke DWORDlokasi berukuran. Setelah berhasil menyelesaikan permintaan ini, lokasi ini diisi dengan jumlah perangkat baris yang tersedia untuk aplikasi.
lpdwAPIVersion
Penunjuk ke DWORDlokasi berukuran. Aplikasi harus menginisialisasiDWORD ini , sebelum memanggil fungsi ini, ke versi API tertinggi yang dirancang untuk didukung (misalnya, nilai yang sama yang akan diteruskan ke parameter dwAPIHighVersion dari lineNegotiateAPIVersion). 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 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. Kemungkinan nilai pengembalian adalah:
LINEERR_INVALAPPNAME, LINEERR_OPERATIONFAILED, LINEERR_INIFILECORRUPT, LINEERR_INVALPOINTER, LINEERR_REINIT, LINEERR_NOMEM, LINEERR_INVALPARAM.
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 dalam 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 fungsi TAPI versi 1.3 dan 1.4), 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 dalam dwOptions anggota 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 ditentukan; 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 direset oleh TAPI ketika tidak ada peristiwa yang tertunda. Handel peristiwa 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 memblokir menunggu pesan untuk diantrekan.
Mekanisme Port Penyelesaian dipilih dengan menentukan PORT LINEINITIALIZEEXOPTION_USECOMPLETION di dwOptions anggota 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 dariGetQueuedCompletionStatus , aplikasi memiliki yang ditentukan dwCompletionKey ditulis ke DWORD yang ditujukkan oleh parameter lpCompletionKey, dan penunjuk ke struktur LINEMESSAGE yang dikembalikan ke lokasi yang ditunjukkan 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 dibagikan 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, ada kemungkinan peristiwa telepon diproses dari urutan. Ini bukan karena urutan pengiriman peristiwa dari TAPI, tetapi akan disebabkan oleh pemotongan 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 itu 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.
Nota
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.
Persyaratan
| Syarat |
Nilai |
| Platform Target |
Windows |
| Header |
tapi.h |
| Pustaka |
Tapi32.lib |
| DLL |
Tapi32.dll |
Lihat juga
Referensi Layanan Telepon Dasar
LINECALLINFO
LINEINITIALIZEEXPARAMS
LINEMESSAGE
Gambaran Umum Referensi TAPI 2.2
lineCallbackFunc
lineGetAddressCaps
lineGetDevCaps
lineGetMessage
lineInitialize
lineNegotiateAPIVersion
lineShutdown