fungsi phoneInitializeExA (tapi.h)

Artikel
08/26/2023

Fungsi phoneInitializeEx menginisialisasi penggunaan TAPI aplikasi untuk penggunaan abstraksi telepon berikutnya. Ini mendaftarkan mekanisme pemberitahuan yang ditentukan aplikasi dan mengembalikan jumlah perangkat telepon yang tersedia untuk aplikasi. Perangkat telepon adalah perangkat apa pun yang menyediakan implementasi untuk fungsi awalan telepon di API Telepon.

Sintaks

LONG phoneInitializeExA(
  LPHPHONEAPP               lphPhoneApp,
  HINSTANCE                 hInstance,
  PHONECALLBACK             lpfnCallback,
  LPCSTR                    lpszFriendlyAppName,
  LPDWORD                   lpdwNumDevs,
  LPDWORD                   lpdwAPIVersion,
  LPPHONEINITIALIZEEXPARAMS lpPhoneInitializeExParams
);

Parameter

lphPhoneApp

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.

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 phoneCallbackFunc). 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 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 PHONESTATUS untuk menunjukkan, dengan cara yang mudah digunakan, aplikasi mana yang memiliki kepemilikan perangkat telepon. Jika lpszFriendlyAppName adalah NULL, nama file modul aplikasi digunakan sebagai gantinya (seperti yang dikembalikan oleh fungsi GetModuleFileName).

lpdwNumDevs

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

lpdwAPIVersion

Arahkan ke 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 dwAPIHighVersiondari phoneNegotiateAPIVersion). Nilai tinggi buatan tidak boleh digunakan; nilai harus ditetapkan 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 lebih lama.

lpPhoneInitializeExParams

Penunjuk ke struktur jenis PHONEINITIALIZEEXPARAMS 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 nomor kesalahan negatif jika terjadi kesalahan. Nilai yang mungkin dikembalikan adalah:

PHONEERR_INVALAPPNAME, PHONEERR_OPERATIONFAILED, PHONEERR_INIFILECORRUPT, PHONEERR_INVALPOINTER, PHONEERR_REINIT, PHONEERR_NOMEM, PHONEERR_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 PHONEINITIALIZEEXOPTION_USEHIDDENWINDOW di anggota dwOptions dalam struktur PHONEINITIALIZEEXPARAMS . Dalam mekanisme ini (yang merupakan satu-satunya mekanisme yang tersedia untuk TAPI versi 1.x aplikasi), TAPI membuat jendela dalam konteks aplikasi selama fungsi phoneInitializeEx , dan mensubkelas jendela sehingga semua pesan yang diposting ke dalamnya ditangani oleh WNDPROC di TAPI itu sendiri. Ketika TAPI memiliki pesan untuk dikirim 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 phoneCallbackFunc, pointer yang disediakan aplikasi sebagai parameter dalam panggilannya ke phoneInitializeEx (atau phoneInitialize, untuk aplikasi TAPI versi 1.3 dan 1.4). Mekanisme ini mengharuskan aplikasi memiliki antrean pesan (yang tidak diinginkan untuk proses layanan) dan untuk melayani yang mengantre secara teratur untuk menghindari penundaan pemrosesan peristiwa telepon. Jendela tersembunyi dihancurkan oleh TAPI selama fungsi phoneShutdown .
Mekanisme Penanganan Aktivitas dipilih dengan menentukan PHONEINITIALIZEEXOPTION_USEEVENT di anggota dwOptions dalam struktur PHONEINITIALIZEEXPARAMS . Dalam mekanisme ini, TAPI membuat objek peristiwa atas nama aplikasi, dan mengembalikan handel ke objek di anggota hEvent di PHONEINITIALIZEEXPARAMS. 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 menandakan peristiwa ini setiap kali pemberitahuan peristiwa telepon tertunda untuk aplikasi; aplikasi harus memanggil phoneGetMessage untuk mengambil konten pesan. Peristiwa direset oleh TAPI ketika tidak ada peristiwa yang tertunda. Penanganan aktivitas ditutup dan objek peristiwa dihancurkan oleh TAPI selama fungsi phoneShutdown . Aplikasi tidak diperlukan untuk menunggu pada handel peristiwa yang dibuat; aplikasi dapat memilih untuk memanggil teleponGetMessage dan memblokir menunggu pesan untuk diantrekan.
Mekanisme Port Penyelesaian dipilih dengan menentukan PORT PHONEINITIALIZEEXOPTION_USECOMPLETION di anggota dwOptions dalam struktur PHONEINITIALIZEEXPARAMS . Dalam mekanisme ini, setiap kali peristiwa telepon perlu dikirim ke aplikasi, TAPI mengirimkannya ke aplikasi menggunakan PostQueuedCompletionStatus ke port penyelesaian yang ditentukan aplikasi dalam anggota hCompletionPort di PHONEINITIALIZEEXPARAMS, ditandai dengan kunci penyelesaian yang ditentukan aplikasi dalam anggota dwCompletionKey di PHONEINITIALIZEEXPARAMS. 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 PHONEMESSAGE yang dikembalikan ke lokasi yang diarahkan oleh lpOverlapped. Setelah aplikasi memproses peristiwa, aplikasi harus memanggil LocalFree untuk merilis memori yang digunakan untuk memuat struktur PHONEMESSAGE . Karena aplikasi membuat port penyelesaian (sehingga memungkinkannya dibagikan untuk tujuan lain), aplikasi harus menutupnya; aplikasi tidak boleh menutup port penyelesaian sampai setelah memanggil phoneShutdown.

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

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

Jika nilai kesalahan PHONEERR_INVALPARAM dikembalikan, parameter hInstance yang ditentukan tidak valid.

Aplikasi ini dapat merujuk ke perangkat telepon individual dengan menggunakan pengidentifikasi perangkat telepon yang berkisar dari nol hingga dwNumDevs dikurangi satu. Aplikasi tidak boleh berasumsi bahwa perangkat telepon ini mampu melakukan fungsi TAPI tertentu tanpa terlebih dahulu mengkueri kemampuan perangkat mereka melalui teleponGetDevCaps.

Catatan

Header tapi.h mendefinisikan phoneInitializeEx 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.