fungsi lineHandoff (tapi.h)

Artikel
08/26/2023

Fungsi lineHandoff memberikan kepemilikan panggilan yang ditentukan ke aplikasi lain. Aplikasi dapat ditentukan langsung dengan nama filenya atau secara tidak langsung sebagai aplikasi prioritas tertinggi yang menangani panggilan mode media yang ditentukan.

Sintaks

LONG lineHandoff(
  HCALL  hCall,
  LPCSTR lpszFileName,
  DWORD  dwMediaMode
);

Parameter

hCall

Tangani panggilan untuk diserahkan. Aplikasi harus menjadi pemilik panggilan. Status panggilan hCall dapat menjadi status apa pun.

lpszFileName

Penunjuk ke string yang dihentikan null. Jika parameter pointer ini non-NULL, parameter tersebut berisi nama file aplikasi yang merupakan target handoff. Jika NULL, target handoff adalah aplikasi prioritas tertinggi yang telah membuka baris untuk hak istimewa pemilik untuk mode media yang ditentukan. Nama file yang valid tidak menyertakan jalur file.

dwMediaMode

Mode media yang digunakan untuk mengidentifikasi target untuk handoff tidak langsung. Parameter dwMediaMode secara tidak langsung mengidentifikasi aplikasi target yaitu menerima kepemilikan panggilan. Parameter ini diabaikan jika lpszFileName bukan NULL. Parameter ini menggunakan satu dan hanya satu dari konstanta LINEMEDIAMODE_.

Mengembalikan nilai

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

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALMEDIAMODE, LINEERR_TARGETNOTFOUND, LINEERR_INVALPOINTER, LINEERR_TARGETSELF, LINEERR_NOMEM, LINEERR_UNINITIALIZED, LINEERR_NOTOWNER.

Keterangan

Fungsi lineHandoff mengembalikan LINEERR_TARGETSELF jika aplikasi panggilan mencoba handoff tidak langsung (yaitu, mengatur parameter lpszFileName ke NULL) dan TAPI menentukan bahwa aplikasi itu sendiri adalah aplikasi prioritas tertinggi untuk mode media tertentu. Jika LINEERR_TARGETNOTFOUND dikembalikan, target untuk handoff panggilan tidak ditemukan. Ini dapat terjadi jika aplikasi bernama tidak membuka baris yang sama dengan bit LINECALLPRIVILEGE_OWNER dalam parameter dwPrivilegeslineOpen. Atau, dalam kasus handoff mode media, tidak ada aplikasi yang telah membuka baris yang sama dengan bit LINECALLPRIVILEGE_OWNER dalam parameter dwPrivilegeslineOpen dan dengan mode media yang ditentukan dalam parameter dwMediaModeslineOpen.

Handoff panggilan memungkinkan kepemilikan panggilan diteruskan di antara aplikasi. Ada dua jenis handoff. Pada jenis pertama, jika aplikasi mengetahui nama file aplikasi target, aplikasi hanya dapat menentukan nama file tersebut. Jika instans aplikasi target telah membuka perangkat baris, kepemilikan panggilan diteruskan ke aplikasi lain; jika tidak, handoff gagal dan kesalahan dikembalikan. Bentuk handoff ini berhasil jika handel panggilan diserahkan ke nama file yang sama dengan aplikasi yang meminta handoff.

Jenis handoff kedua didasarkan pada mode media. Dalam hal ini, aplikasi secara tidak langsung menentukan aplikasi target melalui mode media. Aplikasi prioritas tertinggi yang saat ini telah membuka perangkat baris untuk mode media tersebut adalah target untuk handoff. Jika tidak ada aplikasi seperti itu, handoff gagal dan kesalahan dikembalikan.

Fungsi lineHandoff tidak mengubah mode media panggilan. Untuk mengubah mode media panggilan, aplikasi harus menggunakan lineSetMediaMode pada panggilan, menentukan mode media baru. Ini mengubah mode media panggilan seperti yang disimpan dalam struktur LINECALLINFO panggilan.

Jika handoff berhasil, aplikasi penerima menerima pesan LINE_CALLSTATE untuk panggilan. Pesan ini menunjukkan bahwa aplikasi penerima memiliki hak istimewa pemilik untuk panggilan (dwParam3). Selain itu, jumlah pemilik dan/atau pemantauan untuk panggilan mungkin telah berubah. Ini dilaporkan oleh pesan LINE_CALLINFO , dan aplikasi penerima kemudian dapat memanggil lineGetCallStatus dan lineGetCallInfo untuk mengambil informasi lebih lanjut tentang panggilan yang diterima.

Aplikasi penerima harus terlebih dahulu memeriksa mode media di LINECALLINFO. Jika hanya bendera mode media tunggal yang diatur, panggilan secara resmi dari mode media tersebut, dan aplikasi dapat bertindak sesuai. Jika UNKNOWN dan bendera mode media lainnya diatur, maka mode media panggilan secara resmi TIDAK DIKETAHUI tetapi diasumsikan sebagai salah satu mode media yang benderanya diatur dalam LINECALLINFO. Aplikasi harus berasumsi bahwa aplikasi harus memeriksa mode media prioritas tertinggi.

Jika pemeriksaan berhasil (baik untuk mode media tersebut atau untuk yang lain), aplikasi harus mengatur anggota mode media di LINECALLINFO ke mode media tunggal yang dikenali. Jika bendera mode media cocok dengan mode media LINECALLINFO , aplikasi dapat bertindak sesuai. Jika membuat penentuan untuk mode media lain, ia harus terlebih dahulu menyerahkan panggilan ke mode media tersebut.

Jika pemeriksaan gagal, aplikasi harus menghapus bendera mode media yang sesuai di LINECALLINFO dan menyerahkan panggilan, menentukan dwMediaMode sebagai LINEMEDIAMODE_UNKNOWN. Ini juga harus membatalkan alokasi handel panggilannya (atau kembali ke pemantauan).

Jika tidak ada mode media yang berhasil membuat penentuan, hanya bendera UNKNOWN yang tetap diatur di bidang mode media LINECALLINFO pada saat aplikasi media mencoba menyerahkan panggilan ke UNKNOWN. LineHandoff akhir gagal jika aplikasi adalah satu-satunya pemilik panggilan yang tersisa. Ini menginformasikan aplikasi bahwa ia harus menghilangkan panggilan dan membatalkan alokasi handelnya, dalam hal ini panggilan ditinggalkan. Hak istimewa aplikasi pemanggilan ke panggilan tidak berubah oleh operasi ini, tetapi aplikasi dapat mengubah hak istimewanya menjadi panggilan dengan lineSetCallPrivilege.