fungsi TSPI_lineGenerateTone (tspi.h)

Artikel
03/03/2024

Fungsi TSPI_lineGenerateTone menghasilkan inband nada yang ditentukan selama panggilan yang ditentukan. Memanggil fungsi ini dengan nol untuk dwToneMode membatalkan pembuatan nada apa pun yang saat ini sedang berlangsung pada panggilan yang ditentukan. Memanggil TSPI_lineGenerateTone atau TSPI_lineGenerateDigits saat pembuatan nada sedang berlangsung membatalkan generasi nada atau generasi digit saat ini yang sedang berlangsung dan memulai pembuatan nada atau digit yang baru ditentukan.

Sintaks

LONG TSPIAPI TSPI_lineGenerateTone(
  HDRVCALL                 hdCall,
  DWORD                    dwEndToEndID,
  DWORD                    dwToneMode,
  DWORD                    dwDuration,
  DWORD                    dwNumTones,
  LPLINEGENERATETONE const lpTones
);

Parameter

hdCall

Pegangan penyedia layanan terhadap panggilan tempat pembuatan nada akan dilakukan. Status panggilan hdCall dapat menjadi status apa pun kecuali diam.

dwEndToEndID

Pengidentifikasi unik dan tidak terinterpresi dari permintaan untuk seluruh masa pakainya, yaitu, sampai pesan LINE_GENERATE yang cocok dikirim. Penyedia layanan menyertakan pengidentifikasi ini sebagai salah satu parameter dalam pesan.

dwToneMode

Menentukan nada yang akan dihasilkan. Nada dapat berupa standar atau kustom. Nada kustom terdiri dari satu set frekuensi arbitrer. Sejumlah kecil nada standar telah ditentukan sebelumnya. Durasi nada ditentukan oleh dwDuration untuk nada standar dan kustom. Jika dwToneMode diatur ke nol, pembuatan digit atau nada apa pun yang sedang berlangsung dibatalkan. Parameter ini menggunakan satu dan hanya satu dari konstanta LINETONEMODE_.

dwDuration

Durasi dalam milidetik di mana nada dipertahankan. Nilai 0 untuk dwDuration menggunakan durasi default untuk nada yang ditentukan. Nilai default-nya adalah:

KUSTOM: tak terbatas

RINGBACK: tak terbatas

SIBUK: tak terbatas

BIP: tak terbatas

TAGIHAN: tetap (siklus tunggal)

Parameter ini tidak divalidasi oleh TAPI ketika fungsi ini dipanggil.

dwNumTones

Jumlah entri dalam array lpTones . Parameter ini diabaikan jika dwToneMode tidak sama dengan LINETONEMODE_CUSTOM.

lpTones

Penunjuk ke array LINEGENERATETONE yang menentukan komponen nada. Parameter ini diabaikan untuk nada yang tidak biasa. Jika lpTones adalah nada multifrequency, berbagai nada dimainkan secara bersamaan.

Nilai kembali

Mengembalikan nol jika fungsi berhasil atau angka kesalahan jika terjadi kesalahan. Kemungkinan nilai yang dikembalikan adalah sebagai berikut:

LINEERR_INVALCALLHANDLE, LINEERR_NOMEM, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALTONEMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALTONE, LINEERR_RESOURCEUNAVAIL, LINEERR_RESOURCEUNAVAIL.

Keterangan

TSPI_lineGenerateTone mengembalikan nol (sukses) ketika pembuatan nada berhasil dimulai; bukan ketika generasi nada selesai. Fungsi ini memungkinkan pembuatan inband dari beberapa nada yang telah ditentukan sebelumnya, seperti ringback, nada sibuk, dan bip. Ini juga memungkinkan fabrikasi nada kustom dengan menentukan frekuensi komponen, irama, dan volume mereka, jika ini didukung oleh penyedia layanan. Karena nada ini dihasilkan sebagai nada inband, panggilan biasanya harus dalam keadaan terhubung agar pembuatan nada menjadi efektif. Ketika pembuatan nada selesai, atau ketika pembuatan nada dibatalkan, pesan LINE_GENERATE dikirim ke TAPI.

Catatan Hanya satu permintaan pembuatan inband (pembuatan nada atau pembuatan digit) yang diizinkan untuk berlangsung per panggilan. Ini menyiratkan bahwa jika pembuatan nada saat ini sedang berlangsung pada panggilan, memanggil TSPI_lineGenerateDigits atau TSPI_lineGenerateTone membatalkan pembuatan nada. Penyedia layanan harus mengakhiri pembuatan nada apa pun yang sedang berlangsung ketika fungsi TSPI_lineGenerateDigits atau TSPI_lineGenerateTone berikutnya dipanggil.

Fungsi yang sesuai di tingkat TAPI tidak menyertakan parameter formal dwEndToEndID. Pada tingkat tersebut, tidak ada penandaan end-to-end. TAPI menggunakan penandaan end-to-end di tingkat TSPI untuk membedakan satu permintaan TSPI_lineGenerateTone dari yang lain.