fungsi TSPI_lineForward (tspi.h)

Artikel
08/26/2023

Fungsi TSPI_lineForward meneruskan panggilan yang ditujukan untuk alamat yang ditentukan pada baris yang ditentukan, sesuai dengan instruksi penerusan yang ditentukan. Ketika alamat asal (dwAddressID) diteruskan, panggilan masuk yang ditentukan untuk alamat tersebut dibelokan ke nomor lain dengan sakelar. Fungsi ini menyediakan kombinasi fitur maju dan jangan diganggu. Fungsi ini juga dapat membatalkan penerusan tertentu yang saat ini berlaku.

Sintaks

LONG TSPIAPI TSPI_lineForward(
  DRV_REQUESTID           dwRequestID,
  HDRVLINE                hdLine,
  DWORD                   bAllAddresses,
  DWORD                   dwAddressID,
  LPLINEFORWARDLIST const lpForwardList,
  DWORD                   dwNumRingsNoAnswer,
  HTAPICALL               htConsultCall,
  LPHDRVCALL              lphdConsultCall,
  LPLINECALLPARAMS const  lpCallParams
);

Parameter

dwRequestID

Pengidentifikasi permintaan asinkron.

hdLine

Handel penyedia layanan ke baris yang akan diteruskan.

bAllAddresses

Menentukan apakah semua alamat asal pada baris atau hanya alamat yang ditentukan yang akan diteruskan. Jika TRUE, semua alamat pada baris diteruskan dan dwAddressID diabaikan; jika FALSE, hanya alamat yang ditentukan sebagai dwAddressID yang diteruskan. Parameter ini tidak divalidasi oleh TAPI ketika fungsi ini dipanggil.

dwAddressID

Alamat pada baris yang ditentukan yang panggilan masuknya akan diteruskan. Parameter ini diabaikan jika bAllAddresses TRUE. Parameter ini tidak divalidasi oleh TAPI ketika fungsi ini dipanggil.

Pengidentifikasi alamat secara permanen dikaitkan dengan alamat; pengidentifikasi tetap konstan di seluruh peningkatan sistem operasi.

lpForwardList

Penunjuk ke struktur data berukuran bervariasi dari jenis LINEFORWARDLIST yang menjelaskan instruksi penerusan tertentu.

dwNumRingsNoAnswer

Menentukan jumlah dering sebelum panggilan masuk dianggap sebagai "tanpa jawaban." Jika dwNumRingsNoAnswer di luar rentang, nilai aktual diatur ke nilai terdekat dalam rentang yang diizinkan. Parameter ini tidak divalidasi oleh TAPI ketika fungsi ini dipanggil.

htConsultCall

TAPI menangani panggilan baru, jika panggilan seperti itu harus dibuat oleh penyedia layanan. Di beberapa lingkungan telepon, meneruskan panggilan memiliki efek samping dari pembuatan panggilan konsultasi yang digunakan untuk berkonsultasi dengan pihak yang sedang diteruskan. Dalam lingkungan seperti itu, penyedia layanan membuat panggilan konsultasi baru dan harus menyimpan nilai ini dan menggunakannya dalam semua panggilan berikutnya ke acara pelaporan prosedur LINEEVENT pada panggilan. Jika tidak ada panggilan konsultasi yang dibuat, nilai ini dapat diabaikan oleh penyedia layanan.

lphdConsultCall

Penunjuk ke HDRVCALL yang mewakili pengidentifikasi penyedia layanan untuk panggilan. Di lingkungan telepon tempat penerusan panggilan memiliki efek samping dari pembuatan panggilan konsultasi yang digunakan untuk berkonsultasi dengan pihak yang sedang diteruskan, penyedia layanan harus mengisi lokasi ini dengan handelnya untuk panggilan sebelum prosedur ini kembali. Penyedia layanan diizinkan untuk melakukan panggilan balik mengenai panggilan baru sebelum kembali dari prosedur ini. Jika tidak ada panggilan konsultasi yang dibuat, HDRVCALL harus dibiarkan NULL.

lpCallParams

Penunjuk ke struktur jenis LINECALLPARAMS. Pointer ini diabaikan oleh penyedia layanan kecuali lineForward memerlukan pembentukan panggilan ke tujuan penerusan (dan lphdConsultCall dikembalikan, dalam hal ini lpCallParams bersifat opsional). Jika NULL, parameter panggilan default akan digunakan. Jika tidak, parameter panggilan yang ditentukan digunakan untuk membuat htConsultCall.

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_INVALLINEHANDLE, LINEERR_NOMEM, LINEERR_INVALADDRESS, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESSID, LINEERR_OPERATIONFAILED, LINEERR_INVALCOUNTRYCODE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPARAM, LINEERR_STRUCTURETOOSMALL.

Keterangan

Penyedia layanan mengembalikan LINEERR_INVALPARAM jika parameter daftar terusan yang ditentukan berisi informasi yang tidak valid.

Penyedia layanan tidak melakukan panggilan jika kembali LINEERR_INVALADDRESS.

Penyedia layanan mengembalikan keberhasilan ke fungsi ini untuk menunjukkan bahwa hanya permintaan yang diterima oleh penyedia layanan, bukan berarti penerusan disiapkan di switch. Pesan LINE_ADDRESSSTATE (penerusan) dikirim untuk memberikan bahwa penerusan disiapkan di sakelar.

Penerusan alamat atau alamat tetap berlaku sampai fungsi ini dipanggil lagi. Daftar penerusan terbaru menggantikan yang lama yang berlaku. Jika fungsi ini dipanggil, menentukan pointer NULL sebagai lpForwardList, penyedia layanan harus membatalkan penerusan apa pun yang sedang dilakukan pada saat itu. Jika alamat tujuan NULL ditentukan untuk entri dalam daftar penerusan, operasi bertindak sebagai "jangan diganggu."

Status penerusan alamat juga dapat terpengaruh secara eksternal, misalnya, melalui tindakan administratif di switch, atau oleh pengguna dari stasiun lain. Penyedia layanan mungkin tidak mengetahui perubahan status ini, dan mungkin tidak dapat tetap sinkron dengan status penerusan yang diketahui oleh sakelar. Penyedia harus selalu menunjukkan apa yang diketahuinya benar, dan menunjukkan bahwa status penerusan tidak diketahui sebaliknya.

Karena penyedia layanan mungkin tidak mengetahui status penerusan alamat tanpa keraguan (artinya, mungkin telah diteruskan atau tidak terduga dengan cara yang tidak diketahui), TSPI_lineForward berhasil kecuali gagal mengatur instruksi penerusan baru. Dengan kata lain, permintaan bahwa semua penerusan dibatalkan pada satu waktu ketika tidak ada penerusan yang berlaku berhasil. Hal ini karena tidak ada yang tak terduga; Anda hanya dapat memanggil serangkaian instruksi penerusan baru.

Keberhasilan atau kegagalan operasi ini tidak bergantung pada serangkaian instruksi penerusan sebelumnya, dan hal yang sama berlaku saat mengatur instruksi penerusan yang berbeda. Jika perlu, penyedia harus "membatalkan semuanya" sebelum mengatur instruksi penerusan baru. Karena ini mungkin memakan waktu di lingkungan telepon analog, penyedia mungkin juga ingin membandingkan penerusan saat ini dengan yang baru, dan hanya mengeluarkan instruksi ke sakelar untuk sampai ke status akhir (membiarkan penerusan yang tidak berubah tidak terpengaruh).

Memanggil TSPI_lineForward ketika LINEFORWARDLIST memiliki dwNumEntries yang diatur ke nol memiliki efek yang sama seperti menyediakan parameter lpForwardListNULL; ini membatalkan semua penerusan yang saat ini berlaku.

Karena nilai NULL yang dikembalikan ke lphdConsultCall adalah satu-satunya cara bagi TAPI untuk menentukan apakah penyedia layanan membuat panggilan konsultasi, penyedia layanan tidak dapat menggunakan NULL sebagai handel panggilan.

Fungsi ini berbeda dari fungsi TAPI yang sesuai karena mengikuti model TSPI untuk memulai masa pakai panggilan. TAPI dan handel buram pertukaran penyedia layanan 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 laporan ASYNC_COMPLETION yang cocok berhasil. Dengan kata lain, ini tidak boleh mengeluarkan pesan apa pun untuk panggilan baru atau menyertakannya dalam jumlah panggilan dalam pesan atau struktur data status untuk baris tersebut.