<sect1>
<title>Timers</title>

<para>
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.
</para>

<para>
The following functions support the API timers:
</para>

<simplelist type="horiz" columns="1">

<member><function><link linkend="vpb-timer-open">vpb_timer_open()</link></function></member>
<member><function><link linkend="vpb-timer-close">vpb_timer_close()</link></function></member>
<member><function><link linkend="vpb-timer-start">vpb_timer_start()</link></function></member>
<member><function><link linkend="vpb-timer-stop">vpb_timer_stop()</link></function></member>
<member><function><link linkend="vpb-timer-restart">vpb_timer_restart()</link></function></member>
<member><function><link linkend="vpb-timer-get-unique-timer-id">vpb_timer_get_unique_timer_id()</link></function></member>
<member><function><link linkend="vpb-timer-change-period">vpb_timer_change_period()</link></function></member>

</simplelist>

<para>
Timers have two states, running, and stopped. When a timer
is first created with <function><link linkend="vpb-timer-open">vpb_timer_open()</link></function>,
the timer is in the stopped state. The timer can be placed in the running
state using <function><link linkend="vpb-timer-start">vpb_timer_start()</link></function> or
<function><link linkend="vpb-timer-restart">vpb_timer_restart()</link></function>.
</para>

<para>
When the timer period expires, it posts a
<function>VPB_TIMER</function> event and resets itself to the stopped
state. The timer can then be restarted using
<function><link linkend="vpb-timer-start">vpb_timer_start()</link></function> or
<function><link linkend="vpb-timer-restart">vpb_timer_restart()</link></function> and the cycle repeated.  The
timer can be restarted before its period has expired using
<function><link linkend="vpb-timer-restart">vpb_timer_restart()</link></function>.  Timer events are classed as
solicited events, they will always be posted to the event queue and
cannot be masked out.
</para>

</sect1>

<sect1>
<title>WAVE File and AU File Functions</title>

<para>
The following functions allow the user to manipulate WAVE and AU
files through the VPBAPI:
</para>

<simplelist type="horiz" columns="1">

<member><function><link linkend="vpb-wave-open-write">vpb_wave_open_write()</link></function></member>
<member><function><link linkend="vpb-wave-write">vpb_wave_write()</link></function></member>
<member><function><link linkend="vpb-wave-close-write">vpb_wave_close_write()</link></function></member>
<member><function><link linkend="vpb-wave-open-read">vpb_wave_open_read()</link></function></member>
<member><function><link linkend="vpb-wave-read">vpb_wave_read()</link></function></member>
<member><function><link linkend="vpb-wave-close-read">vpb_wave_close_read()</link></function></member>
<member><function><link linkend="vpb-wave-set-sample-rate">vpb_wave_set_sample_rate()</link></function></member>
<member><function><link linkend="vpb-wave-seek">vpb_wave_seek()</link></function></member>
<member><function><link linkend="vpb-wave-get-mode">vpb_wave_get_mode()</link></function></member>

</simplelist>

<para>
When writing to a wave file the user must initially open up a wave
file using <function><link linkend="vpb-wave-open-write">vpb_wave_open_write()</link></function> 
to set up the appropriate wave format and filename. Writing to the file is then
handled by <function><link linkend="vpb-wave-write">vpb_wave_write()</link></function>. 
The wave file must be closed by the <function><link linkend="vpb-wave-close-write">vpb_wave_close_write()</link></function>.  
</para>

<para>
Reading a wave file requires a similar procedure, initially opening up the wave file using 
<function><link linkend="vpb-wave-open-read">vpb_wave_open_read()</link></function> to
determine the file's wave format. Reading the file is then handled by
<function><link linkend="vpb-wave-read">vpb_wave_read()</link></function>. 
The wave file must be closed by
the <function><link linkend="vpb-wave-close-read">vpb_wave_close_read()</link></function>.  
</para>

<para>
The <function><link linkend="vpb-wave-get-mode">vpb_wave_get_mode()</link></function> obtains the compression
format of a wave file. This function is useful in instances where the
user-define play routines are required.  The
<function><link linkend="vpb-wave-seek">vpb_wave_seek()</link></function> moves 
the file pointer of the wave file to a specified location.
</para>

</sect1>

<sect1>
<title>Get Digits Functions</title>

<para>
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:
</para>

<simplelist type="horiz" columns="1">

<member><function><link linkend="vpb-get-digits-sync">vpb_get_digits_sync()</link></function></member>
<member><function><link linkend="vpb-get-digits-async">vpb_get_digits_async()</link></function></member>

</simplelist>

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

<para>
The synchronous version returns the appropriate termination code (see
<filename>vpbapi.h</filename>) once the function has ended.  A flush
function is also included to reset the user digit buffer.
<function><link linkend="vpb-flush-digits">vpb_flush_digits()</link></function> 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.
</para>

<sect2>
<title>Get Digit Termination codes</title>

<informaltable frame="all">
<tgroup cols="2">
  <thead>
    <row>
      <entry>Termination code</entry>
      <entry>Description</entry>
    </row>
  </thead>
  <tbody>
    <row>
      <entry>VPB_DIGIT_TERM</entry>
      <entry>
        Termination due to a user-defined termination-digit being pressed
      </entry>
    </row>
    <row>
      <entry>VPB_DIGIT_MAX</entry>
      <entry>
        Termination due to having reached the maximum number of digits
      </entry>
    </row>
    <row>
      <entry>VPB_DIGIT_TIME_OUT</entry>
      <entry>
        Termination due to the time limit to collect digits having expired
      </entry>
    </row>
    <row>
      <entry>VPB_DIGIT_INTER_DIGIT_TIME_OUT</entry>
      <entry>
        Termination due to the inter-digit time limit having expired
      </entry>
    </row>
  </tbody>
</tgroup>
</informaltable>

</sect2>
</sect1>

<sect1>
<title>Call Progress Functions</title>

<para>
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.
</para>

<simplelist type="horiz" columns="1">

<member><function><link linkend="vpb-get-call">vpb_get_call()</link></function></member>
<member><function><link linkend="vpb-set-call">vpb_set_call()</link></function></member>
<member><function><link linkend="vpb-call-sync">vpb_call_sync()</link></function></member>
<member><function><link linkend="vpb-call-async">vpb_call_async()</link></function></member>

</simplelist>

<para>
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.
</para>

<para>
The <function>VPB_CALL</function> and
<function>VPB_TONE_MAP</function> 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
<function>VPB_EVENT</function> structure. The synchronous version
returns the appropriate call progress return code (see
<filename>vpbapi.h</filename>) once the function has ended.
</para>

<sect2>
<title>Call Progress Return codes</title>

<informaltable frame="all">
<tgroup cols="2">
  <thead>
    <row>
      <entry>Return code</entry>
      <entry>Description</entry>
    </row>
  </thead>
  <tbody>
    <row>
      <entry>VPB_CALL_CONNECTED</entry>
      <entry>Call is connected</entry>
    </row>
    <row>
      <entry>VPB_CALL_NO_DIAL_TONE</entry>
      <entry>No dial tone is detected</entry>
    </row>
    <row>
      <entry>VPB_CALL_NO_RING_BACK</entry>
      <entry>No ring back is detected</entry>
    </row>
    <row>
      <entry>VPB_CALL_BUSY</entry>
      <entry>Call is busy</entry>
    </row>
    <row>
      <entry>VPB_CALL_NO_ANSWER</entry>
      <entry>No answer is detected</entry>
    </row>
    <row>
      <entry>VPB_CALL_DISCONNECTED</entry>
      <entry>Call is disconnected</entry>
    </row>
  </tbody>
</tgroup>
</informaltable>

</sect2>
</sect1>

<sect1>
<title>VOX Functions</title>

<para>
The VPBAPI allows the user to control the VOX firmware
for each channel.
</para>

<simplelist type="horiz" columns="1">

<member><function><link linkend="vpb-getvox">vpb_getvox()</link></function></member>
<member><function><link linkend="vpb-setvox">vpb_setvox()</link></function></member>

</simplelist>

<para>
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 <function><link linkend="vpb-setvox">vpb_setvox()</link></function> function.
</para>

</sect1>

<sect1>
<title>Miscellaneous Functions</title>

<simplelist type="horiz" columns="1">

<member><function><link linkend="vpb-get-model">vpb_get_model()</link></function></member>
<member><function><link linkend="vpb-sleep">vpb_sleep()</link></function></member>
<member><function><link linkend="vpb-sethook-sync">vpb_sethook_sync()</link></function></member>
<member><function><link linkend="vpb-sethook-async">vpb_sethook_async()</link></function></member>
<member><function><link linkend="vpb-translate-event">vpb_translate_event()</link></function></member>
<member><function><link linkend="vpb-open">vpb_open()</link></function></member>
<member><function><link linkend="vpb-close">vpb_close()</link></function></member>
<member><function><link linkend="vpb-seterrormode">vpb_seterrormode()</link></function></member>

</simplelist>


</sect1>