libvpb  4.2.61
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. More...
 
int WINAPI vpb_get_digits_async (int handle, VPB_DIGITS *digits, char *digbuf)
 Get a buffer of DTMF digits. More...
 
CollectEndReason WINAPI vpb_get_digits_sync (int handle, VPB_DIGITS *digits, char *digbuf)
 Get a buffer of DTMF digits. More...
 

Detailed Description

Enumeration Type Documentation

◆ 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.

◆ 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
handleThe handle to the port to collect digits from.
digitsThe conditions defining how digits are collected.
digbufA 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
variousexceptions may be thrown in the event of an error.

◆ 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
handleThe handle to the port to collect digits from.
digitsThe conditions defining how digits are collected.
digbufA 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
variousexceptions 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.