lineGatherDigits (tapi.h)

Artikel
03/08/2023

Fungsi lineGatherDigits memulai pengumpulan digit yang di-buffer pada panggilan yang ditentukan. Aplikasi menentukan buffer untuk menempatkan digit dan jumlah maksimum digit yang akan dikumpulkan.

Sintaks

LONG lineGatherDigits(
  HCALL  hCall,
  DWORD  dwDigitModes,
  LPSTR  lpsDigits,
  DWORD  dwNumDigits,
  LPCSTR lpszTerminationDigits,
  DWORD  dwFirstDigitTimeout,
  DWORD  dwInterDigitTimeout
);

Parameter

hCall

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

dwDigitModes

Mode digit yang akan dipantau. Parameter ini menggunakan satu atau beberapa konstanta LINEDIGITMODE_.

lpsDigits

Penunjuk ke buffer tempat digit yang terdeteksi akan disimpan sebagai karakter teks. Digit mungkin tidak muncul di buffer satu per satu saat dikumpulkan. Hanya setelah pesan LINE_GATHERDIGITS diterima jika konten buffer diasumsikan valid. Jika lpsDigitsADALAH NULL, pengumpulan digit yang saat ini sedang berlangsung pada panggilan dihentikan dan dwNumDigits diabaikan. Jika tidak, lpsDigits diasumsikan memiliki ruang untuk digit dwNumDigits .

dwNumDigits

Jumlah digit yang akan dikumpulkan sebelum pesan LINE_GATHERDIGITS dikirim ke aplikasi. Parameter dwNumDigits diabaikan ketika lpsDigits adalah NULL. Fungsi ini gagal jika dwNumDigits adalah nol.

lpszTerminationDigits

String digit penghentian yang dihentikan null sebagai karakter teks. Jika salah satu digit dalam string terdeteksi, digit penghentian tersebut ditambahkan ke buffer, koleksi digit dihentikan, dan pesan LINE_GATHERDIGITS dikirim ke aplikasi.

Daftar karakter yang valid tergantung pada konstanta yang disediakan dalam dwDigitModes. Untuk daftar karakter yang valid untuk setiap mode yang mungkin, lihat konstanta LINEDIGITMODE_.

Jika pointer ini NULL, atau jika menunjuk ke string kosong, fungsi berperilaku seolah-olah tidak ada digit penghentian yang disediakan.

dwFirstDigitTimeout

Durasi waktu dalam milidetik di mana digit pertama diharapkan. Jika digit pertama tidak diterima dalam jangka waktu ini, koleksi digit dibatalkan dan pesan LINE_GATHERDIGITS dikirim ke aplikasi. Buffer hanya berisi karakter NULL , yang menunjukkan bahwa tidak ada digit yang diterima dan pengumpulan digit waktu habis digit pertama yang dihentikan. Kemampuan perangkat baris panggilan menentukan rentang yang valid untuk parameter ini atau menunjukkan bahwa batas waktu tidak didukung.

dwInterDigitTimeout

Durasi waktu maksimum dalam milidetik antara digit berturut-turut. Jika tidak ada digit yang diterima dalam jangka waktu ini, koleksi digit dibatalkan dan pesan LINE_GATHERDIGITS dikirim ke aplikasi. Buffer hanya berisi digit yang dikumpulkan hingga titik ini diikuti oleh karakter NULL , yang menunjukkan bahwa pengumpulan digit batas waktu antardigit dihentikan. Kemampuan perangkat baris panggilan menentukan rentang yang valid untuk parameter ini atau menunjukkan bahwa batas waktu tidak didukung.

Menampilkan nilai

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

LINEERR_INVALCALLHANDLE, LINEERR_NOMEM, LINEERR_INVALCALLSTATE, LINEERR_NOTOWNER, LINEERR_INVALDIGITMODE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALDIGITS, LINEERR_OPERATIONFAILED, LINEERR_INVALPARAM, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED.

Keterangan

Koleksi digit dihentikan ketika jumlah digit yang diminta telah dikumpulkan. Ini juga dihentikan ketika salah satu digit yang terdeteksi cocok dengan digit dalam szTerminationDigits sebelum jumlah digit yang ditentukan telah dikumpulkan. Digit penghentian yang terdeteksi juga ditempatkan di buffer dan buffer parsial dikembalikan.

Cara lain untuk membatalkan koleksi digit terjadi ketika salah satu batas waktu kedaluwarsa. dwFirstDigitTimeout kedaluwarsa jika digit pertama tidak diterima dalam periode waktu ini. Digit dwInterDigitTimout kedaluwarsa jika digit kedua, ketiga, (dan seterusnya) tidak diterima dalam periode waktu tersebut dari digit yang terdeteksi sebelumnya, dan buffer parsial dikembalikan.

Metode keempat untuk mengakhiri pengumpulan digit adalah dengan memanggil fungsi ini lagi saat koleksi sedang berlangsung. Sesi koleksi lama dihentikan, digit apa pun yang dikumpulkan hingga titik tersebut disalin ke buffer yang disediakan dari panggilan sebelumnya ke fungsi ini, dan buffer dikirim ketika pesan LINE_GATHERDIGITS dikirim ke aplikasi. Mekanisme untuk mengakhiri pengumpulan digit tanpa memulai pengumpulan digit lain adalah dengan memanggil fungsi ini dengan lpsDigits sama dengan NULL.

Fungsi ini dianggap berhasil jika koleksi digit telah dimulai dengan benar, bukan jika koleksi digit telah dihentikan. Dalam semua kasus di mana buffer parsial dikembalikan, digit yang valid (jika ada) diikuti oleh karakter NULL .

Meskipun fungsi ini dapat dipanggil dalam status panggilan apa pun, digit biasanya hanya dapat dikumpulkan saat panggilan dalam status tersambung .

Pesan LINE_GATHERDIGITS dikirim hanya ke aplikasi yang memulai permintaan. Ini juga dikirim ketika buffer parsial dikembalikan karena batas waktu atau digit penghentian yang cocok, atau ketika permintaan dibatalkan oleh permintaan lineGatherDigits lain pada panggilan. Hanya satu permintaan gather-digit yang dapat aktif pada panggilan pada waktu tertentu di semua aplikasi yang merupakan pemilik panggilan. Mengingat perilaku asinkron operasi, aplikasi yang mengeluarkan beberapa permintaan lineGatherDigits berturut-turut cepat mungkin dapat melakukannya dan menerima beberapa pesan LINE_GATHERDIGITS nanti. Meskipun ini akan menjadi perilaku aplikasi yang tidak biasa, aplikasi dapat menghitung jumlah pesan ini untuk memungkinkan pesan pembatalan dicocokkan dengan permintaan sebelumnya. Bagaimanapun, hanya permintaan terbaru yang harus diasumsikan valid.

Catatan Ketika aplikasi memanggil operasi asinkron apa pun yang menulis data kembali ke memori aplikasi, aplikasi harus menjaga memori tersebut tersedia untuk ditulis hingga pesan LINE_REPLY atau LINE_GATHERDIGITS diterima.

Aplikasi dapat menggunakan lineMonitorDigits untuk mengaktifkan atau menonaktifkan deteksi digit yang tidak di-buffer. Setiap kali digit terdeteksi dengan cara ini, pesan LINE_MONITORDIGITS dikirim ke aplikasi. Deteksi digit yang di-buffer dan tidak dibuffer dapat diaktifkan secara bersamaan untuk panggilan yang sama.

Pengumpulan digit pada panggilan konferensi hanya berlaku untuk hConfCall, bukan untuk panggilan yang berpartisipasi individu.

Jika fungsi lineGatherDigits digunakan untuk membatalkan permintaan sebelumnya untuk mengumpulkan digit, fungsi menyalin digit apa pun yang dikumpulkan hingga titik tersebut ke buffer yang ditentukan dalam panggilan fungsi asli. Fungsi kemudian mengirim pesan LINE_GATHERDIGITS ke aplikasi, terlepas dari apakah parameter lpszDigits dalam panggilan kedua menentukan NULL atau alamat yang berbeda.