# Timers

The VPBAPI includes support for programmable timers that operate through the API event queue. The timers are useful for integrating timer functions into state machine based computer telephony applications.

The following functions support the API timers:

- `vpb_timer_open()`
- `vpb_timer_close()`
- `vpb_timer_start()`
- `vpb_timer_stop()`
- `vpb_timer_restart()`
- `vpb_timer_get_unique_timer_id()`
- `vpb_timer_change_period()`

Timers have two states, running, and stopped. When a timer is first created with `vpb_timer_open()`, the timer is in the stopped state. The timer can be placed in the running state using `vpb_timer_start()` or `vpb_timer_restart()`.

When the timer period expires, it posts a `VPB_TIMER` event and resets itself to the stopped state. The timer can then be restarted using `vpb_timer_start()` or `vpb_timer_restart()` and the cycle repeated. The timer can be restarted before its period has expired using `vpb_timer_restart()`. Timer events are classed as solicited events, they will always be posted to the event queue and cannot be masked out.

## WAVE File and AU File Functions

The following functions allow the user to manipulate WAVE and AU files through the VPBAPI:

- `vpb_wave_open_write()`
- `vpb_wave_write()`
- `vpb_wave_close_write()`
- `vpb_wave_open_read()`
- `vpb_wave_read()`
- `vpb_wave_close_read()`
- `vpb_wave_set_sample_rate()`
- `vpb_wave_seek()`
- `vpb_wave_get_mode()`

When writing to a wave file the user must initially open up a wave file using `vpb_wave_open_write()` to set up the appropriate wave format and filename. Writing to the file is then handled by `vpb_wave_write()`. The wave file must be closed by the `vpb_wave_close_write()`.

Reading a wave file requires a similar procedure, initially opening up the wave file using `vpb_wave_open_read()` to determine the file's wave format. Reading the file is then handled by `vpb_wave_read()`. The wave file must be closed by the `vpb_wave_close_read()`.

The `vpb_wave_get_mode()` obtains the compression format of a wave file. This function is useful in instances where the user-define play routines are required. The `vpb_wave_seek()` moves the file pointer of the wave file to a specified location.

## Get Digits Functions

The VPBAPI supports the collection of digits from a channel. This includes an asynchronous and synchronous version. The functions initiate collection of the digits from the channel and place them in a user digit buffer:

- `vpb_get_digits_sync()`
- `vpb_get_digits_async()`

The conditions of termination for the functions may be configured via the `VPB_DIGITS` structure. In the asynchronous version, the condition of termination is passed to the data field of the `VPB_EVENT` structure once the collection of digits from the channel to the user digit buffer has terminated.

The synchronous version returns the appropriate termination code (see `vpbapi.h`) once the function has ended. A flush function is also included to reset the user digit buffer. `vpb_flush_digits()` Ensure this is used to clear the user digit buffer of any digits from previous actions on the channel before executing any of the get digits functions.

## Get Digit Termination codes

Termination code | Description
VPB_DIGIT_TERM | Termination due to a user-defined termination-digit being pressed
VPB_DIGIT_MAX | Termination due to having reached the maximum number of digits
VPB_DIGIT_TIME_OUT | Termination due to the time limit to collect digits having expired
VPB_DIGIT_INTER_DIGIT_TIME_OUT | Termination due to the inter-digit time limit having expired

## Call Progress Functions

The VPBAPI enables a call to be placed using the call progress algorithm in both synchronous and asynchronous modes. It also enables the call progress parameters to be set or obtained for each channel.

- `vpb_get_call()`
- `vpb_set_call()`
- `vpb_call_sync()`
- `vpb_call_async()`

Call progress analysis determines whether a call is answered or not, whether the line is busy, or there are problems placing the call such as no dial tone, call disconnected or no ring back. The call progress algorithm consists of frequency and cadence analysis to determine the state of the call being placed.

The `VPB_CALL` and `VPB_TONE_MAP` structures are used to define the parameters of the call progress algorithm. In the asynchronous version, the status of the call is passed to the data field of the `VPB_EVENT` structure. The synchronous version returns the appropriate call progress return code (see `vpbapi.h`) once the function has ended.

## Call Progress Return codes

Return code | Description
VPB_CALL_CONNECTED | Call is connected
VPB_CALL_NO_DIAL_TONE | No dial tone is detected
VPB_CALL_NO_RING_BACK | No ring back is detected
VPB_CALL_BUSY | Call is busy
VPB_CALL_NO_ANSWER | No answer is detected
VPB_CALL_DISCONNECTED | Call is disconnected

## VOX Functions

The VPBAPI allows the user to control the VOX firmware for each channel.

- `vpb_getvox()`
- `vpb_setvox()`

The VOX algorithm switches on when the audio level exceeds onlevel. When the audio level falls beneath offlevel, a counter is started. When the counter exceeds runon milliseconds, the VOX algorithm switches off. The overload level is defined as 0 dB, the default on and off VOX levels are -12 and -18 dB respectively. The default runon duration is 2000 ms. The VOX parameters may be re-programmed using the `vpb_setvox()` function.

## Miscellaneous Functions

- `vpb_get_model()`
- `vpb_sleep()`
- `vpb_sethook_sync()`
- `vpb_sethook_async()`
- `vpb_translate_event()`
- `vpb_open()`
- `vpb_close()`
- `vpb_seterrormode()`