fungsi TSPI_lineSetupConference (tspi.h)

Artikel
08/26/2023

Fungsi TSPI_lineSetupConference menyiapkan panggilan konferensi untuk penambahan pihak ketiga.

Sintaks

LONG TSPIAPI TSPI_lineSetupConference(
  DRV_REQUESTID          dwRequestID,
  HDRVCALL               hdCall,
  HDRVLINE               hdLine,
  HTAPICALL              htConfCall,
  LPHDRVCALL             lphdConfCall,
  HTAPICALL              htConsultCall,
  LPHDRVCALL             lphdConsultCall,
  DWORD                  dwNumParties,
  LPLINECALLPARAMS const lpCallParams
);

Parameter

dwRequestID

Pengidentifikasi permintaan asinkron.

hdCall

Handel ke panggilan awal yang mengidentifikasi pihak pertama dari panggilan konferensi. Di beberapa lingkungan, panggilan harus ada untuk memulai panggilan konferensi. Di lingkungan telepon lainnya, tidak ada panggilan awalnya dan hdCall dibiarkan NULL. Status panggilan hdCall dapat dihubungkan.

hdLine

Handel ke perangkat baris untuk memulai panggilan konferensi jika hdCallADALAH NULL. Parameter hdLine diabaikan jika hdCall bukan NULL. Penyedia layanan melaporkan model mana yang didukungnya melalui bendera setupConfNull dari struktur data LINEADDRESSCAPS .

htConfCall

TAPI menangani panggilan konferensi baru. Penyedia layanan harus menyimpan ini dan menggunakannya dalam semua panggilan berikutnya ke prosedur LINEEVENT yang melaporkan peristiwa pada panggilan baru.

lphdConfCall

Penunjuk ke HDRVCALL yang mewakili pengidentifikasi penyedia layanan untuk panggilan konferensi yang baru dibuat. Penyedia layanan harus mengisi lokasi ini dengan handelnya untuk panggilan baru sebelum prosedur ini kembali. Handel ini diabaikan oleh TAPI jika fungsi menghasilkan kesalahan. Status panggilan hdConfCall tidak berlaku.

htConsultCall

TAPI menangani panggilan konsultasi. Saat menyiapkan panggilan untuk penambahan pihak baru, panggilan sementara baru (panggilan konsultasi) dialokasikan secara otomatis. Penyedia layanan harus menyimpan htConsultCall dan menggunakannya dalam semua panggilan berikutnya ke prosedur LINEEVENT yang melaporkan peristiwa pada panggilan konsultasi baru.

lphdConsultCall

Pointer ke HDRVCALL yang mewakili pengidentifikasi penyedia layanan untuk panggilan. Saat menyiapkan panggilan untuk penambahan pihak baru, panggilan sementara baru (panggilan konsultasi) dialokasikan secara otomatis. Penyedia layanan harus mengisi lokasi ini dengan handelnya untuk panggilan konsultasi baru sebelum prosedur ini kembali. Handel ini diabaikan oleh TAPI jika fungsi menghasilkan kesalahan. Status panggilan hdConsultCall tidak berlaku.

dwNumParties

Jumlah pihak yang diharapkan dalam panggilan konferensi. Penyedia layanan bebas untuk melakukan dengan nomor ini sesuka hati. Misalnya, penyedia layanan dapat mengabaikannya, atau menggunakannya sebagai petunjuk untuk mengalokasikan jembatan konferensi ukuran yang tepat di dalam sakelar. TAPI tidak memvalidasi parameter ini ketika fungsi ini dipanggil.

lpCallParams

Pointer ke struktur LINECALLPARAMS yang berisi parameter panggilan untuk digunakan saat membuat panggilan konsultasi. Parameter ini diatur ke NULL jika tidak ada parameter penyiapan panggilan khusus yang diinginkan dan penyedia layanan menggunakan parameter default.

Mengembalikan nilai

Mengembalikan dwRequestID, atau nomor kesalahan jika terjadi kesalahan. Parameter aktual lResult dari ASYNC_COMPLETION yang sesuai adalah nol jika fungsi berhasil, atau nomor kesalahan jika terjadi kesalahan. Kemungkinan nilai yang dikembalikan adalah sebagai berikut:

LINEERR_INVALCALLHANDLE, LINEERR_INVALADDRESSMODE, LINEERR_INVALLINEHANDLE, LINEERR_INVALBEARERMODE, LINEERR_INVALCALLSTATE, LINEERR_INVALCALLPARAMS, LINEERR_CALLUNAVAIL, LINEERR_INVALLINESTATE, LINEERR_CONFERENCEFULL, LINEERR_INVALMEDIAMODE, LINEERR_NOMEM, LINEERR_INVALRATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INUSE, LINEERR_OPERATIONFAILED, LINEERR_RATEUNAVAIL, LINEERR_RESOURCEUNAVAIL, LINEERR_USERUSERINFOTOOBIG, LINEERR_BEARERMODEUNAVAIL.

Keterangan

Penyedia layanan mengembalikan LINEERR_INVALLINEHANDLE jika handel baris yang ditentukan untuk baris yang berisi panggilan konferensi tidak valid. Kesalahan ini juga dapat menunjukkan bahwa lingkungan telepon memerlukan baris awal untuk menyiapkan konferensi tetapi handel panggilan non-NULL disediakan sebagai gantinya.

Penyedia layanan mengembalikan LINEERR_INVALCALLHANDLE jika lingkungan telepon memerlukan panggilan awal untuk menyiapkan konferensi tetapi handel panggilan NULL disediakan sebagai gantinya.

TSPI_lineSetupConference menyediakan dua cara untuk membuat panggilan konferensi baru, tergantung pada apakah panggilan dua pihak normal diperlukan untuk melakukan pra-ada atau tidak. Saat menyiapkan panggilan konferensi dari panggilan dua pihak yang ada, parameter hdCall adalah handel panggilan yang valid yang awalnya ditambahkan ke panggilan konferensi oleh permintaan TSPI_lineSetupConference dan hdLine diabaikan. Pada pengalih di mana penyetelan panggilan konferensi tidak dimulai dengan panggilan yang ada, hdCall harus NULL dan hdLine harus ditentukan untuk mengidentifikasi perangkat baris tempat memulai panggilan konferensi. Dalam kedua kasus, panggilan konsultasi dialokasikan untuk terhubung ke pihak yang akan ditambahkan ke panggilan. TAPI dapat menggunakan TSPI_lineDial untuk memanggil alamat pihak lain.

Panggilan konferensi biasanya beralih ke status onHoldPendingConference , status dialton panggilan konsultasi dan panggilan awal (jika satu) ke status konferensi .

Panggilan konferensi juga dapat disiapkan menggunakan fungsi TSPI_lineCompleteTransfer yang diselesaikan menjadi konferensi tiga arah.

TAPI mungkin dapat beralih antara panggilan konsultasi dan panggilan konferensi menggunakan TSPI_lineSwapHold.

Fungsi TSPI_lineUnhold dapat memulihkan panggilan yang memiliki status panggilan onHoldPendingConference. Jika ini dilakukan, setiap panggilan konsultasi biasanya masuk ke status menganggur .

Panggilan konsultasi dapat dibatalkan dengan memanggil TSPI_lineDrop di atasnya. Saat menjatuhkan panggilan konsultasi, panggilan konferensi yang ada biasanya beralih kembali ke status tersambung . TAPI dan aplikasi kliennya harus mengamati pesan LINE_CALLSTATE untuk menentukan dengan tepat apa yang terjadi pada panggilan. Misalnya, jika panggilan konferensi kembali ke panggilan dua pihak biasa, panggilan konferensi menjadi menganggur dan panggilan peserta asli dapat kembali tersambung.

Fungsi ini berbeda dari fungsi TAPI yang sesuai karena mengikuti model TSPI untuk memulai masa pakai panggilan. TAPI dan penyedia layanan bertukar handel buram yang mewakili panggilan satu sama lain. Selain itu, penyedia layanan diizinkan untuk melakukan panggilan balik untuk panggilan baru sebelum kembali dari prosedur ini. Bagaimanapun, penyedia layanan juga harus memperlakukan handel yang dikembalikan sebagai "belum valid" sampai setelah pesan ASYNC_COMPLETION yang cocok melaporkan keberhasilan. Dengan kata lain, tidak boleh mengeluarkan pesan LINEEVENT apa pun untuk panggilan baru atau menyertakannya dalam jumlah panggilan dalam pesan atau struktur data status untuk baris tersebut.