TSPI_lineGatherDigits (tspi.h)

Artikel
08/26/2023

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

Sintaks

LONG TSPIAPI TSPI_lineGatherDigits(
  HDRVCALL hdCall,
  DWORD    dwEndToEndID,
  DWORD    dwDigitModes,
  LPWSTR   lpsDigits,
  DWORD    dwNumDigits,
  LPCWSTR  lpszTerminationDigits,
  DWORD    dwFirstDigitTimeout,
  DWORD    dwInterDigitTimeout
);

Parameter

hdCall

Penanganan penyedia layanan ke panggilan tempat pengumpulan digit 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_GATHERDIGITS yang cocok dikirim. Penyedia layanan menyertakan pengidentifikasi ini sebagai salah satu parameter dalam pesan.

dwDigitModes

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

Nilai	Makna
LINEDIGITMODE_PULSE	Deteksi digit sebagai klik yang dapat didengar yang merupakan hasil dari penggunaan urutan pulsa putar. Digit yang valid untuk mode pulsa adalah '0' hingga '9'.
LINEDIGITMODE_DTMF	Mendeteksi digit sebagai nada DTMF. Digit yang valid untuk mode DTMF adalah '0' hingga '9', 'A', 'B', 'C', 'D', '*', '#'.

lpsDigits

Penunjuk ke buffer tempat digit yang terdeteksi akan disimpan sebagai karakter teks. Penyedia layanan dapat, tetapi tidak diperlukan untuk, menempatkan digit di buffer satu per satu saat dikumpulkan. Ketika pesan LINE_GATHERDIGITS dikirim, konten buffer harus selesai. Jika lpsDigits ditentukan sebagai NULL , pengumpulan digit yang saat ini sedang berlangsung pada panggilan dibatalkan dan parameter dwNumDigits diabaikan. Jika tidak, lpsDigits diasumsikan memiliki ruang untuk digit dwNumDigits .

dwNumDigits

Jumlah digit yang akan dikumpulkan sebelum pesan LINE_GATHERDIGITS dikirim ke TAPI. Parameter dwNumDigits diabaikan ketika lpsDigits adalah NULL. Fungsi ini harus mengembalikan LINEERR_INVALPARAM jika dwNumDigits adalah nol.

lpszTerminationDigits

Penunjuk ke string Unicode null-dihentikan dari digit penghentian 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 TAPI.

Karakter yang valid untuk mode pulsa adalah '0' hingga '9'. Karakter yang valid untuk mode DTMF adalah '0' hingga '9', 'A', 'B', 'C', 'D', '*', '#'. 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 dihentikan dan pesan LINE_GATHERDIGITS dikirim ke TAPI. Satu karakter NULL ditulis ke buffer, menunjukkan 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. Parameter ini tidak divalidasi oleh TAPI ketika fungsi ini dipanggil.

dwInterDigitTimeout

Durasi waktu maksimum dalam milidetik antara digit berturut-turut. Jika tidak ada digit yang diterima dalam jangka waktu ini, koleksi digit dihentikan dan pesan LINE_GATHERDIGITS dikirim ke TAPI. Satu karakter NULL ditulis ke buffer, menunjukkan bahwa pengumpulan digit yang dihentikan batas waktu antardigit. Struktur LINEDEVCAPS harus menentukan rentang yang valid untuk parameter ini atau menunjukkan bahwa batas waktu tidak didukung. Parameter ini tidak divalidasi oleh TAPI ketika fungsi ini dipanggil.

Nilai kembali

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

LINEERR_INVALCALLHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_NOMEM, LINEERR_INVALTIMEOUT, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALDIGITMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALDIGITS, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPARAM.

Keterangan

Penyedia layanan mengembalikan LINEERR_INVALPARAM jika parameter dwNumDigits tidak valid.

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

Koleksi digit dapat dihentikan dengan cara berikut:

Jumlah digit yang diminta mungkin telah dikumpulkan.
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.
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.
Memanggil operasi ini lagi saat pengumpulan sedang berlangsung. Sesi koleksi lama dihentikan dan konten buffer lama tidak terdefinisi. Untuk membatalkan pengumpulan digit tanpa memulai operasi lain, operasi ini dipanggil dengan lpsDigits sama dengan NULL.

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

Pesan LINE_GATHERDIGITS biasanya dikirim ketika buffer digit terisi. Ini juga dikirim ketika buffer parsial dikembalikan karena batas waktu atau digit penghentian yang cocok, atau ketika permintaan dibatalkan melalui permintaan TSPI_lineGatherDigits lain pada panggilan. Hanya satu permintaan pengumpulan digit yang dapat aktif pada satu waktu. Penyedia layanan harus mengakhiri operasi pengumpulan yang luar biasa dengan pesan LINE_GATHERDIGITS saat TSPI_lineGatherDigits dipanggil.

Ketika operasi yang terkait dengan panggilan ke fungsi TSPI_lineGatherDigits dibatalkan (dengan panggilan berikutnya ke fungsi), penyedia layanan menyalin digit apa pun yang dikumpulkan hingga titik tersebut ke buffer yang ditentukan dalam panggilan asli.

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

Penyedia layanan diizinkan beberapa variasi dalam kualitas waktu yang digunakannya untuk fungsi ini, termasuk tidak melakukan pengaturan waktu sama sekali. Kualitas waktu dilaporkan dalam LINEDEVCAPS, dalam anggota dwGatherDigitsMinTimeout dan dwGatherDigitsMaxTimeout.

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_lineGatherDigits dari yang lain.