fungsi phoneInitializeExA (tapi.h)

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.

Sintaksis

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

lpdwNumDevs

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

lpdwAPIVersion

Arahkan keDWORD . Aplikasi harus menginisialisasiDWORD ini , sebelum memanggil fungsi ini, ke versi API tertinggi yang dirancang untuk mendukung (misalnya, nilai yang sama yang akan diteruskan ke parameter dwAPIHighVersion dari phoneNegotiateAPIVersion). 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 mendeteksi dan beradaptasi dengan telah diinstal pada sistem dengan versi TAPI yang lebih lama.

lpPhoneInitializeExParams

Pointer ke struktur jenis PHONEINITIALIZEEXPARAMS 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:

PHONEERR_INVALAPPNAME, PHONEERR_OPERATIONFAILED, PHONEERR_INIFILECORRUPT, PHONEERR_INVALPOINTER, PHONEERR_REINIT, PHONEERR_NOMEM, PHONEERR_INVALPARAM.

Komentar

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 dwOptions anggota 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 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 telepon CallbackFunc, 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 antrean tersebut 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 dwOptions anggota dalam struktur PHONEINITIALIZEEXPARAMS. Dalam mekanisme ini, TAPI membuat objek peristiwa atas nama aplikasi, dan mengembalikan handel ke objek di hEvent anggota 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 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 phoneGetMessage 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 phoneShutdown. Aplikasi tidak diperlukan untuk menunggu pada handel peristiwa yang dibuat; aplikasi dapat memilih untuk memanggil phoneGetMessage dan memblokir menunggu pesan diantrekan.
Mekanisme Port Penyelesaian dipilih dengan menentukan PORT PHONEINITIALIZEEXOPTION_USECOMPLETION di dwOptions anggota 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 dariGetQueuedCompletionStatus , aplikasi memiliki dwCompletionKey yang ditentukan yang ditulis ke DWORD yang ditujukkan oleh parameter lpCompletionKey, dan pointer ke struktur PHONEMESSAGE dikembalikan ke lokasi yang diarahkan oleh lpOverlapped. Setelah aplikasi memproses peristiwa, aplikasi harus memanggil LocalFree untuk merilis memori yang digunakan untuk berisi 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 teleponShutdown.

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 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 minus satu. Aplikasi tidak boleh berasumsi bahwa perangkat telepon ini mampu melakukan fungsi TAPI tertentu tanpa terlebih dahulu mengkueri kemampuan perangkat mereka dengan phoneGetDevCaps.

Nota

Header tapi.h mendefinisikan phoneInitializeEx sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta praprosem 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

PHONEINITIALIZEEXPARAMS

PHONEMESSAGE

PHONESTATUS

Fungsi Layanan Telepon Tambahan

Gambaran Umum Referensi TAPI 2.2

phoneCallbackFunc

phoneGetDevCaps

phoneGetMessage

phoneNegotiateAPIVersion

phoneShutdown

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2023-08-26