fungsi lineGenerateTone (tapi.h)

Artikel
08/26/2023

Fungsi lineGenerateTone menghasilkan nada inband yang ditentukan selama panggilan yang ditentukan. Memanggil fungsi ini dengan nol untuk dwToneMode membatalkan pembuatan nada yang saat ini sedang berlangsung pada panggilan yang ditentukan. Memanggil lineGenerateTone atau lineGenerateDigits saat pembuatan nada sedang berlangsung membatalkan pembuatan nada atau pembuatan digit saat ini dan memulai pembuatan nada atau digit yang baru ditentukan.

Sintaks

LONG lineGenerateTone(
  HCALL                    hCall,
  DWORD                    dwToneMode,
  DWORD                    dwDuration,
  DWORD                    dwNumTones,
  LPLINEGENERATETONE const lpTones
);

Parameter

hCall

Tangani ke panggilan tempat nada akan dihasilkan. Aplikasi harus menjadi pemilik panggilan. Status panggilan hCall dapat menjadi status apa pun.

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 dengan dwDuration untuk nada standar dan kustom. Parameter dwToneMode hanya dapat memiliki satu set bit. Jika tidak ada bit yang ditetapkan (nilai 0 diteruskan), pembuatan nada dibatalkan. Parameter ini menggunakan salah satu konstanta LINETONEMODE_.

dwDuration

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

KUSTOM: Nada dipertahankan hingga dimatikan, biasanya oleh interaksi pengguna atau batas waktu peralatan.

RINGBACK: Nada dipertahankan sampai dimatikan, biasanya oleh interaksi pengguna atau batas waktu peralatan.

SIBUK: Nada dipertahankan sampai dimatikan, biasanya oleh interaksi pengguna atau batas waktu peralatan.

BEEP: Nada dipertahankan sampai dimatikan, biasanya oleh interaksi pengguna atau batas waktu peralatan.

TAGIHAN: Tetap (siklus tunggal).

dwNumTones

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

lpTones

Penunjuk ke array LINEGENERATETONE yang menentukan komponen nada. Parameter ini diabaikan untuk nada konstanta LINETONEMODE_ standar seperti LINETONEMODE_BUSY. Jika lpTones adalah nada multifrequency, berbagai nada dimainkan secara bersamaan.

Mengembalikan nilai

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

LINEERR_INVALCALLHANDLE, LINEERR_NOTOWNER, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALPOINTER, LINEERR_OPERATIONFAILED, LINEERR_INVALTONEMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALTONE, LINEERR_UNINITIALIZED, LINEERR_NOMEM.

Keterangan

Fungsi lineGenerateTone dianggap telah berhasil diselesaikan ketika pembuatan nada telah berhasil dimulai, bukan ketika pembuatan 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. 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 aplikasi.

Hanya satu permintaan pembuatan inband (pembuatan nada atau pembuatan digit) yang diizinkan untuk berlangsung per panggilan di semua aplikasi yang merupakan pemilik panggilan. Ini menyiratkan bahwa jika pembuatan nada saat ini sedang berlangsung pada panggilan, memanggil lineGenerateDigits membatalkan pembuatan nada.

Jika nilai kesalahan LINEERR_INVALPOINTER dikembalikan, parameter lpTones yang ditentukan tidak valid atau nilai yang ditentukan oleh parameter dwNumTones terlalu besar.