lineOpen (tapi.h)

Artikel
03/08/2023

Fungsi lineOpen membuka perangkat baris yang ditentukan oleh pengidentifikasi perangkatnya dan mengembalikan handel baris untuk perangkat baris yang terbuka yang sesuai. Handel baris ini digunakan dalam operasi berikutnya pada perangkat baris.

Sintaks

LONG lineOpen(
  HLINEAPP               hLineApp,
  DWORD                  dwDeviceID,
  LPHLINE                lphLine,
  DWORD                  dwAPIVersion,
  DWORD                  dwExtVersion,
  DWORD_PTR              dwCallbackInstance,
  DWORD                  dwPrivileges,
  DWORD                  dwMediaModes,
  LPLINECALLPARAMS const lpCallParams
);

Parameter

hLineApp

Tangani pendaftaran aplikasi dengan TAPI.

dwDeviceID

Mengidentifikasi perangkat baris yang akan dibuka. Ini bisa menjadi pengidentifikasi perangkat yang valid atau nilainya.

Nilai	Makna
LINEMAPPER	Nilai ini digunakan untuk membuka perangkat baris dalam sistem yang mendukung properti yang ditentukan dalam lpCallParams. Aplikasi dapat menggunakan lineGetID untuk menentukan pengidentifikasi perangkat baris yang dibuka.

lphLine

Penunjuk ke handel HLINE yang kemudian dimuat dengan handel yang mewakili perangkat baris yang dibuka. Gunakan handel ini untuk mengidentifikasi perangkat saat memanggil fungsi lain pada perangkat baris terbuka.

dwAPIVersion

Nomor versi API di mana aplikasi dan TELEPHONY API telah setuju untuk beroperasi. Jumlah ini diperoleh dengan lineNegotiateAPIVersion.

dwExtVersion

Nomor versi ekstensi tempat aplikasi dan penyedia layanan setuju untuk beroperasi. Angka ini nol jika aplikasi tidak menggunakan ekstensi apa pun. Jumlah ini diperoleh dengan lineNegotiateExtVersion.

dwCallbackInstance

Data instans pengguna diteruskan kembali ke aplikasi dengan setiap pesan yang terkait dengan baris ini atau dengan alamat atau panggilan di baris ini. Parameter ini tidak ditafsirkan oleh API Telepon.

dwPrivileges

Hak istimewa yang diinginkan aplikasi ketika diberi tahu tentang panggilan Parameter ini berisi satu atau beberapa konstanta LINECALLPRIVILEGE_. Untuk aplikasi yang menggunakan TAPI versi 2.0 atau yang lebih baru, nilai untuk parameter ini juga dapat dikombinasikan dengan satu atau beberapa konstanta LINEOPENOPTION_.

Jika opsi LINEOPENOPTION_SINGLEADDRESS ditentukan, maka aplikasi hanya tertarik pada panggilan baru yang muncul pada alamat yang ditentukan oleh anggota dwAddressID dalam struktur LINECALLPARAMS yang diarahkan oleh parameter lpCallParams (yang harus ditentukan).

Jika LINEOPENOPTION_SINGLEADDRESS ditentukan tetapi lpCallParams tidak valid atau dwAddressID yang disertakan tidak ada di baris, pembukaan gagal dengan LINERR_INVALADDRESSID.

Selain mengatur anggota dwAddressID dari struktur LINECALLPARAMS ke alamat yang diinginkan, aplikasi juga harus mengatur dwAddressMode di LINECALLPARAMS ke LINEADDRESSMODE_ADDRESSID.

Opsi LINEOPENOPTION_SINGLEADDRESS hanya memengaruhi penugasan TAPI atas kepemilikan panggilan awal panggilan yang dibuat oleh penyedia layanan menggunakan pesan LINE_NEWCALL . Aplikasi yang membuka baris dengan LINECALLPRIVILEGE_MONITOR terus menerima handel pemantauan ke semua panggilan yang dibuat di baris. Selain itu, aplikasi tidak dibatasi dengan cara apa pun untuk melakukan panggilan atau melakukan operasi lain yang memengaruhi alamat lain pada baris yang dibuka.

Ketika opsi LINEOPENOPTION_PROXY ditentukan (hanya TAPI 2.0 atau lebih tinggi), aplikasi juga harus menunjukkan permintaan proksi tertentu mana yang disiapkannya untuk ditangani. Ini melakukannya dengan meneruskan, dalam parameter lpCallParams , penunjuk ke struktur LINECALLPARAMS di mana anggota dwDevSpecificSize dan dwDevSpecificOffset telah diatur untuk memisahkan array DWORD. Setiap elemen array ini akan berisi salah satu konstanta LINEPROXYREQUEST_. Misalnya, aplikasi handler proksi yang mendukung kelima fungsi terkait Agen akan meneruskan array lima DWORDs (dwDevSpecificSize adalah 20 desimal) yang berisi lima nilai LINEPROXYREQUEST_ yang ditentukan.

Aplikasi handler permintaan proksi dapat berjalan pada komputer apa pun yang memiliki otorisasi untuk mengontrol perangkat baris. Namun, permintaan selalu dirutekan melalui server tempat penyedia layanan menjalankan yang benar-benar mengontrol perangkat baris. Dengan demikian, paling efisien jika aplikasi menangani permintaan proksi (seperti kontrol agen ACD) dijalankan langsung di server bersama dengan penyedia layanan.

Upaya berikutnya, oleh aplikasi yang sama atau aplikasi lain, untuk membuka perangkat baris dan mendaftar untuk menangani permintaan proksi yang sama dengan aplikasi yang sudah terdaftar gagal dengan LINEERR_NOTREGISTERED.

Untuk berhenti menangani permintaan di baris, aplikasi hanya memanggil lineClose.

Kombinasi bendera lainnya mengembalikan kesalahan LINEERR_INVALPRIVSELECT.

dwMediaModes

Jenis media atau mode yang menarik bagi aplikasi. Parameter ini digunakan untuk mendaftarkan aplikasi sebagai target potensial untuk panggilan masuk dan memanggil handoff untuk jenis media yang ditentukan. Parameter ini bermakna hanya jika bit LINECALLPRIVILEGE_OWNER di dwPrivileges diatur (dan diabaikan sebaliknya). Parameter ini menggunakan satu atau beberapa konstanta LINEMEDIAMODE_.

lpCallParams

Penunjuk ke struktur jenis LINECALLPARAMS. Pointer ini hanya digunakan jika LINEMAPPER atau LINEOPENOPTION_PROXY digunakan; jika tidak , lpCallParams diabaikan. Ini menjelaskan parameter panggilan yang harus dapat disediakan perangkat baris.

Nilai kembali

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

LINEERR_ALLOCATED, LINEERR_LINEMAPPERFAILED, LINEERR_BADDEVICEID, LINEERR_NODRIVER, LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_NOMEM, LINEERR_INCOMPATIBLEEXTVERSION, LINEERR_OPERATIONFAILED, LINEERR_INVALAPPHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALMEDIAMODE, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_INVALPRIVSELECT, LINEERR_REINIT, LINEERR_NODEVICE, LINEERR_OPERATIONUNAVAIL.

Keterangan

Jika LINEERR_ALLOCATED dikembalikan, baris tidak dapat dibuka karena kondisi "persisten", seperti port seri yang dibuka secara eksklusif oleh proses lain. Jika LINEERR_RESOURCEUNAVAIL dikembalikan, baris tidak dapat dibuka karena overcommitment sumber daya dinamis seperti dalam siklus prosesor DSP atau memori. Overcommitment ini dapat bertahap, disebabkan oleh pemantauan jenis media atau nada, dan perubahan dalam aktivitas ini oleh aplikasi lain dapat memungkinkan untuk membuka kembali garis dalam waktu singkat. Jika LINEERR_REINIT dikembalikan dan reinisialisasi TAPI telah diminta (misalnya, sebagai akibat dari menambahkan atau menghapus penyedia layanan telepon), maka permintaan lineOpen 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.

Membuka baris selalu memberi izin kepada aplikasi untuk melakukan panggilan pada alamat apa pun yang tersedia di baris. Kemampuan aplikasi untuk menangani panggilan masuk atau menjadi target handoff panggilan pada baris ditentukan oleh parameter dwMediaModes . Fungsi lineOpen mendaftarkan aplikasi sebagai memiliki minat dalam memantau panggilan atau menerima kepemilikan panggilan yang merupakan jenis media yang ditentukan. Jika aplikasi hanya ingin memantau panggilan, maka aplikasi dapat menentukan LINECALLPRIVILEGE_MONITOR. Jika aplikasi hanya ingin melakukan panggilan keluar, aplikasi dapat menentukan LINECALLPRIVILEGE_NONE. Jika aplikasi bersedia mengontrol panggilan yang tidak diklasifikasikan (panggilan jenis media yang tidak diketahui), aplikasi dapat menentukan LINECALLPRIVILEGE_OWNER dan LINEMEDIAMODE_UNKNOWN. Jika tidak, aplikasi harus menentukan jenis media yang tertarik untuk ditangani. Aplikasi dapat memanggil fungsi lineSetCallPrivilege untuk mengubah hak istimewa panggilan yang ditentukan oleh LINECALLPRIVILEGES_Constants.

Jenis media yang ditentukan dengan lineBuka tambahkan ke nilai default untuk pemantauan jenis media penyedia untuk penentuan jenis panggilan masuk awal. Fungsi lineMonitorMedia memodifikasi masker yang mengontrol LINE_MONITORMEDIA pesan. Jika perangkat baris dibuka dengan hak istimewa pemilik dan jenis media ekstensi tidak terdaftar, maka kesalahan LINEERR_INVALMEDIAMODE dikembalikan.

Aplikasi yang berhasil membuka perangkat baris selalu dapat memulai panggilan menggunakan lineMakeCall, lineUnpark, linePickup, dan lineSetupConference (dengan NULLhCall), serta menggunakan lineForward (dengan asumsi bahwa melakukannya diizinkan oleh kemampuan perangkat, status baris, dan sebagainya).

Satu aplikasi dapat menentukan beberapa bendera secara bersamaan untuk menangani beberapa jenis media. Konflik dapat muncul jika beberapa aplikasi membuka perangkat baris yang sama untuk jenis media yang sama. Konflik ini diselesaikan dengan skema prioritas di mana pengguna menetapkan prioritas relatif untuk aplikasi. Pengguna dapat mengatur prioritas aplikasi dengan memanggil fungsi lineSetAppPriority . Hanya aplikasi prioritas tertinggi untuk jenis media tertentu yang pernah menerima kepemilikan (tidak diminta) dari panggilan jenis media tersebut. Kepemilikan dapat diterima ketika panggilan masuk pertama kali tiba atau ketika panggilan diserahkan. Fungsi lineHandoff dipanggil untuk menyerahkan kepemilikan panggilan ke aplikasi lain. Jika pengguna tidak menetapkan prioritas ke aplikasi, dan beberapa aplikasi membuka perangkat baris yang sama, secara default, aplikasi yang disebut lineOpen terlebih dahulu akan memiliki prioritas tertinggi.

Aplikasi apa pun (termasuk aplikasi prioritas yang lebih rendah) selalu dapat memperoleh kepemilikan dengan lineGetNewCalls atau lineGetConfRelatedCalls. Jika aplikasi membuka baris untuk pemantauan pada saat panggilan ada di baris, LINE_CALLSTATE pesan untuk panggilan yang ada tidak secara otomatis dihasilkan ke aplikasi pemantauan baru. Aplikasi dapat mengkueri jumlah panggilan saat ini di baris untuk menentukan berapa banyak panggilan yang ada, dan, jika mau, aplikasi dapat memanggil lineGetNewCalls untuk mendapatkan handel untuk panggilan ini.

Aplikasi yang menangani suara otomatis juga harus memilih mode buka suara interaktif dan diberi prioritas terendah untuk suara interaktif. Alasan untuk ini adalah bahwa penyedia layanan melaporkan semua jenis media suara sebagai suara interaktif. Jika penentuan jenis media tidak dilakukan oleh aplikasi untuk jenis media UNKNOWN, dan tidak ada aplikasi suara interaktif yang membuka perangkat baris, panggilan suara tidak akan dapat mencapai aplikasi suara otomatis, dan akan dihilangkan.

Aplikasi yang sama, atau instansiasi yang berbeda dari aplikasi yang sama, dapat membuka baris yang sama beberapa kali dengan parameter yang sama atau berbeda.

Ketika aplikasi membuka perangkat baris, aplikasi harus menentukan versi API yang dinegosiasikan dan, jika ingin menggunakan ekstensi baris, aplikasi harus menentukan versi ekstensi khusus perangkat baris. Nomor versi ini seharusnya diperoleh dengan lineNegotiateAPIVersion dan lineNegotiateExtVersion. Penomoran versi memungkinkan pencampuran dan pencocokan versi aplikasi yang berbeda dengan versi API dan versi penyedia layanan yang berbeda.

LINEMAPPER memungkinkan aplikasi untuk memilih baris secara tidak langsung—melalui layanan yang diinginkannya. Saat membuka perangkat baris menggunakan LINEMAPPER, hal berikut ini benar: Semua anggota dari awal struktur data LINECALLPARAMS melalui dwAddressMode relevan. Jika dwAddressMode LINEADDRESSMODE_ADDRESSID itu berarti bahwa alamat apa pun di baris dapat diterima, jika tidak jika dwAddressMode LINEADDRESSMODE_DIALABLEADDR, menunjukkan bahwa alamat asal tertentu (nomor telepon) dicari, atau jika itu adalah ekstensi khusus penyedia, maka dwOrigAddressSize/Offset dan bagian dari bagian variabel yang mereka rujuk juga relevan. Jika dwAddressMode adalah ekstensi khusus penyedia, informasi tambahan dapat dimuat dalam anggota dwDeviceSpecific berukuran bervariasi.