Loading...
Searching...
No Matches
DTMF digit collection
Public API functions » Port initialisation » Card information » Port control » Event handling » Audio play and record » Error handling » Programmable tone generator » Programmable tone detector » Wav audio support
Collaboration diagram for DTMF digit collection:

## Classes

struct | VPB_DIGITS
| Digit collection parameters. More...

## Enumerations

enum | CollectEndReason { VPB_DIGIT_TERM = 0 , VPB_DIGIT_MAX = 1 , VPB_DIGIT_TIME_OUT = 2 , VPB_DIGIT_INTER_DIGIT_TIME_OUT = 3 }
| The termination reason passed in the `VPB_EVENT::data` field of a `VPB_DIGIT` event. More...

## Functions

int WINAPI | vpb_flush_digits (int handle)
| Clears the internal digit buffer for handle.
int WINAPI | vpb_get_digits_async (int handle, VPB_DIGITS *digits, char *digbuf)
| Get a buffer of `DTMF` digits.
CollectEndReason WINAPI | vpb_get_digits_sync (int handle, VPB_DIGITS *digits, char *digbuf)
| Get a buffer of `DTMF` digits.

## Detailed Description

## Enumeration Type Documentation

## CollectEndReason

enum CollectEndReason

The termination reason passed in the `VPB_EVENT::data` field of a `VPB_DIGIT` event.

Enumerator
VPB_DIGIT_TERM | A termination digit was collected.
VPB_DIGIT_MAX | The specified maximum number of digits were collected.
VPB_DIGIT_TIME_OUT | The specified time for collecting digits expired.
VPB_DIGIT_INTER_DIGIT_TIME_OUT | The specified time for collecting further digits expired.

## Function Documentation

## vpb_flush_digits()

int WINAPI vpb_flush_digits | ( | int | handle | ) |

Clears the internal digit buffer for handle.

This function is often called before commencing collection if any digits entered prior to that time should be discarded.

Referenced by vpb_reset(), and vpb_send_cid_t2_sync().

## vpb_get_digits_async()

int WINAPI vpb_get_digits_async | ( | int | handle,
|  | VPB_DIGITS * | digits,
|  | char * | digbuf )

Get a buffer of `DTMF` digits.

This function will return immediately and post a `VPB_DIGIT` event for handle when collection is completed. If it is called while collection is already in progress for handle, the process is reset and any digits collected prior to that will be discarded.

Parameters

  handle | The handle to the port to collect digits from.
  digits | The conditions defining how digits are collected.
  digbuf | A pointer to storage for at least VPB_DIGITS::max_digits + 1 characters. The returned string of digits will be `NULL` terminated.

Returns
  `VPB_OK` if collection starts successfully.

Exceptions

  various | exceptions may be thrown in the event of an error.

References VPB_DIGITS::digit_time_out, VPB_DIGITS::inter_digit_time_out, VPB_DIGITS::max_digits, Timer::start(), Timer::stop(), VPB_DIGITS::term_digits, and validate_digits().

## vpb_get_digits_sync()

CollectEndReason WINAPI vpb_get_digits_sync | ( | int | handle,
|  | VPB_DIGITS * | digits,
|  | char * | digbuf )

Get a buffer of `DTMF` digits.

This function will block until collection is completed. If it is called while async collection is already in progress for handle, the process is reset and any digits collected prior to that will be discarded. If it is called while synchronous collection is already in progress an exception will be thrown. If it is interrupted by a call to start async collection an exception will be thrown.

Parameters

  handle | The handle to the port to collect digits from.
  digits | The conditions defining how digits are collected.
  digbuf | A pointer to storage for at least VPB_DIGITS::max_digits + 1 characters. The returned string of digits will be `NULL` terminated.

Returns
  The `CollectEndReason` indicating why collection was terminated.

Exceptions

  various | exceptions may be thrown in the event of an error.

Note
  In most cases, this probably isn't the function you want and you should use `vpb_get_digits_async()` instead. This function does no checking for other events (such as hangup) while it is waiting for digits and there is no graceful way to interrupt it if you are checking for them elsewhere in some other thread. Most code should integrate the async digit collection with its normal event processing loop, as the cases where DTMF digits really are the only thing you need to be watching for tend to be the exception rather than the rule.

References Timer::check_timeout_ms(), VPB_DIGITS::digit_time_out, VPB_DIGITS::inter_digit_time_out, VPB_DIGITS::max_digits, Timer::start(), Timer::stop(), VPB_DIGITS::term_digits, validate_digits(), VPB_DIGIT_INTER_DIGIT_TIME_OUT, VPB_DIGIT_MAX, VPB_DIGIT_TERM, and VPB_DIGIT_TIME_OUT.