fungsi phoneInitialize (tapi.h)

Artikel
08/26/2023

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

Aplikasi yang menggunakan TAPI versi 2.0 atau yang lebih baru harus menggunakan phoneInitializeEx sebagai gantinya.

Untuk TAPI Versi 1.4 dan Yang Lebih Lama: Fungsi phoneInitialize menginisialisasi penggunaan TAPI aplikasi untuk penggunaan fungsi telepon berikutnya di API Telepon. Ini mendaftarkan mekanisme pemberitahuan yang ditentukan aplikasi dan mengembalikan jumlah perangkat telepon yang tersedia untuk aplikasi.

Sintaks

LONG phoneInitialize(
  LPHPHONEAPP   lphPhoneApp,
  HINSTANCE     hInstance,
  PHONECALLBACK lpfnCallback,
  LPCSTR        lpszAppName,
  LPDWORD       lpdwNumDevs
);

Parameter

lphPhoneApp

Penunjuk 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 di perangkat telepon.

lpszAppName

Penunjuk ke string yang dihentikan null yang berisi karakter yang dapat ditampilkan. Jika parameter ini non-NULL, parameter ini berisi nama aplikasi yang disediakan aplikasi. Nama ini disediakan dalam struktur PHONESTATUS untuk menunjukkan, dengan cara yang mudah digunakan, aplikasi mana yang merupakan pemilik perangkat telepon saat ini. Informasi ini dapat berguna untuk tujuan pengelogan dan pelaporan status. Jika lpszAppName adalah NULL, nama file aplikasi akan digunakan sebagai gantinya.

lpdwNumDevs

Arahkan ke DWORD. Lokasi ini dimuat dengan jumlah perangkat telepon yang tersedia untuk aplikasi.

Mengembalikan nilai

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

PHONEERR_INVALAPPNAME, PHONEERR_INIFILECORRUPT, PHONEERR_INVALPOINTER, PHONEERR_NOMEM, PHONEERR_OPERATIONFAILED, PHONEERR_REINIT, PHONEERR_RESOURCEUNAVAIL, PHONEERR_NODEVICE, PHONEERR_NODRIVER, PHONEERR_INVALPARAM

Keterangan

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 apa pun selain apa yang ditentukan oleh subset Telepon Terbantu tanpa terlebih dahulu mengkueri kemampuan perangkat mereka dengan fungsi phoneGetDevCaps .

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

Alasan lain untuk melakukan phoneShutdown 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 PHONESTATE_REINIT dikirim, tidak ada aplikasi yang dapat membuka perangkat sampai semua aplikasi telah melakukan phoneShutdown.

Jika ada penyedia layanan yang gagal menginisialisasi dengan benar, fungsi phoneInitialize gagal dan mengembalikan kesalahan yang ditunjukkan oleh penyedia layanan. Jika nilai kesalahan PHONEERR_INVALPARAM dikembalikan, parameter hInstance yang ditentukan tidak valid.