Voicetronix Programming Guide

Voicetronix Programming Guide
Legal Notice
Table of Contents
Introduction Programming Initialization and Shutdown Error Handling Events Playing and Recording
Audio DTMF and Programmable Tone Generation Tone Detection Automated Tone Training Timers
WAVE File and AU File Functions Get Digits Functions Call Progress Functions VOX Functions Pip
Functions Miscellaneous Functions Function Reference
Introduction
This document describes how to program Voicetronix computer telephony cards using the
Voicetronix Voice Processing Board API (VPBAPI).
Unless otherwise stated, the term VPB (Voice Processing Board) will refer to all Voicetronix cards. The
VPBs are programmed via the VPB Application Programmer Interface, a set of C callable functions
provided as a Windows 32 bit DLL (Windows), or a user-mode library (Linux & FreeBSD) . This will be
referred to as the VPBAPI, or just API.
For installation details please see the README file for your operating system, located in vpb-driver/.
Please refer to the README files, driver source code, and code examples for the latest
information on using Voicetronix cards.
FCC Compliance Statement for OpenLine4: Complies with Part 68 Rules, Certification #VTX-AUS-
46040-PT-T, AC-REN 0.6B, DC-REN NA.
Next >>>
Programming
<<< Previous Next >>>
Programming
Introduction
The Voicetronix cards are programmed via the VPB Application Programmer Interface (VPBAPI, or just
API). This is a set of C callable functions. The following sections describe the VPBAPI in detail, and also
include examples of the API functions in action. It is recommended that the user browse the header file
vpbapi.h to gain an overview of the API.
CompilingwiththeVPBAPI
LinuxandFreeBSD
Simply link libvpb.a with your application:
$ gcc test.cpp -o test -Wall -g -lvpb -pthread -lm
Windows
1 Create a new project (e.g. Win32 Console Application) and insert your source files.
1 2. Project-Settings-C/C++:
o set "Category" to "Code Generation"
o set "Use run-time library:" to "Debug Multithreaded"
3. Project-Settings-Link:
oTo the "Object/library modules" add ../debug/libvpb.lib (you might need to change the
path to libvpb.lib, depending on where you create your project).
1 Build your project.
2 Make sure libvpb.dll and plxapi.dll are in your path before running. One way is to set the
Project-Settings-Debug-Working Directory to a directory containing the DLL, or place the DLL in
a directory in your path (e.g. c:\winnt\system32)
1 6. Set the path for the firmware. The firmware is called vpbmain_pci.out, and is in vpb-
driver/firmware/. There are two ways to set the path:
oModify vpbreg.cpp, change the #define FIRMWARE_FILE_PCI to your path and
recompile libvpb.dll (see Readme.Win32.txt for information on how to recompile the
driver).
oSet an environment variable VPB_FIRMWARE to the path to the firmware file. Under NT go
to control panel-system-environment. After setting the env. variable, you will need to
restart MSVC before running so that the new env. variable is available to MSVC.
7. You should now be able to run your program from MSVC.
<<< Previous Home Next >>>

Voicetronix Initialization and
Programming Guide Shutdown
Voicetronix Programming
Guide
Initialization and Shutdown

This section describes the "housekeeping" functions used to initialize and shutdown a Voicetronix card.
The initialization function vpb_open() must be called before any other API functions will work:
Example 1. Initialization and Shutdown
This program demonstrates initialization and shutdown of a single channel, (number 2), on the first board
in the system. Each channel (or port) of the card has an associated number. On the OpenLine4 card,
channel 1 is the port furthest from the motherboard. Port 4 is closest to the motherboard.
The vpb_open() function returns a handle to the open channel. This handle then provides a reference to
all other operations with this channel. A call to vpb_open() is required for each channel that is to be
used. If a channel is not opened, then no operations can be performed with that channel.

Programming Error Handling
<<<
Previous Next >>>
Error Handling
Under certain conditions the API functions will be unable to successfully execute. In this case an error
condition will occur that requires handling by code outside of the API. The API provides three modes of
error handling:
 Exceptions
 Error codes
 Debug
The current error mode is set using the vpb_seterrormode() function. The default error mode is Debug.
Debug
If an error occurs in this mode, the program stops execution immediately and prints an error message.
This is useful during debugging as it brings any problems to the programmer's immediate attention.
However, such behavior is obviously not desirable in release versions of the software. Note that this
mode is only suitable for console mode programs, it will cause the program to hang when used with a
windows program.
ErrorCodes
In this case the function returns an integer corresponding to the nature of the error. The convention used
by the API is that positive numbers and zero indicate successful function completion, and negative
numbers represent an error condition. The error codes for the API functions are listed in vpberr.h.
There are other, undocumented error codes that lower levels of the API software may return, but these
are not defined in vpberr.h. These errors should not occur during normal operation. To convert an error
code into a more helpful error string, use vpb_strerror().
Exceptions
Exceptions are a form of error handling supported by C++. When an error occurs, an exception is
"thrown". In the case of the VPBAPI , the exception is a class VpbException that contains information
describing the error. The code member of the class corresponds to an error number defined exactly the
same way as in the error code error handling method. The other members contain strings describing the
API function that generated the error and a brief translation of the error code. The user must provide code
to catch the exception at some level in their program. The advantage of exceptions is that it is not
necessary to trap errors at every API call, which can become tedious from a programming point of view,
especially for API calls deep within nested function calls. Consider the following code fragments, first
using error codes:
Example 2. Error Handling Using Error Codes

And now using exceptions:
Example 3. Error Handling Using Exceptions
Using exceptions enables the programmer to send all run time errors to a single point in the code,
removing the need for handling errors after every API call. If the current function does not have try/catch
exception handling, then the compiler aborts the current function, climbing up the "call stack" until an
exception handler is found in a calling function. If no exception handler is found in the calling functions,
the program aborts. For more information on exceptions, see a C++ text, or your C++ compiler on-line
documentation.
Initialization and Shutdown Events

<<<
Previous Next >>>
Events
The VPBAPI uses an event driven programming model. There are two types of events, solicted, and
unsolicited. The following functions deal with events:
vpb_disable_event()
vpb_enable_event()vpb_get_event
_mask()
vpb_set_event_mask()vpb_get_eve
nt_async()vpb_get_event_sync()
vpb_get_event_ch_async()vpb_get
_event_ch_sync()
vpb_put_event()
Solicited events are generated as a response to a previous API function call. For example, when
vpb_play_file_async() is called, a solicited event of type VPB_PLAYEND is generated when the file has
finished playing.
Unsolicited events are generated in response to external conditions, for example due to a DTMF tone
being detected by the card.

Error Handling Playing and Recording Audio
<<<
Previous Next >>>
Playing and Recording Audio

SummaryofPlayFunctions
The API play functions are listed below:
vpb_play_file_sync()
vpb_play_file_async()
vpb_play_voxfile_sync()
vpb_play_voxfile_async()
vpb_play_terminate()
vpb_play_buf_start()
vpb_play_buf_sync()
vpb_play_buf_finish()
vpb_play_set()
vpb_play_set_gain()
vpb_play_get_gain()
The VPBAPI supports the playing of WAVE and VOX and AU files. It also accommodates the playing of
buffers from memory via the user defined play routines. The play functions can be configured to
terminate when a DTMF digit is received using vpb_play_set(). The play functions may be
prematurely stopped using vpb_play_terminate(). The API provides a function to alter the VPB audio
out levels within the range of -12 to 12 dB (0.1dB resolution). This is accomplished by
vpb_play_set_gain().
SummaryofRecordFunctions
The API record functions are listed below:
vpb_record_file_sync()
vpb_record_file_async()
vpb_record_voxfile_sync()
vpb_record_voxfile_async()
vpb_record_terminate()
vpb_record_buf_start()
vpb_record_buf_sync()
vpb_record_buf_finish()
vpb_record_set()
vpb_record_set_gain()
vpb_record_get_gain()
The VPBAPI supports the recording of audio files. It also accommodates the recording of audio to
memory via the user defined record routines. The record functions can be configured to terminate when
a DTMF digit is received using vpb_record_set(). The record functions may be prematurely stopped
using vpb_record_terminate(). The API provides a function to alter the VPB audio in levels within
the range of -12 to 12 dB (0.1dB resolution). This is accomplished by vpb_record_set_gain().
PlayingAudio
The API functions for playing audio are divided into two groups; file-based functions, and buffer-
based functions.
The file-based play functions are designed to make playing files straightforward. These functions support
WAVE and AU files sampled at 8 ksamples/s only, playing files that follow the WAVE and AU file
specification including for 16 bit Linear, 8 bit A-Law, 8 bit Mu-Law, and 4-bit OKIADPCM.
There are also file-based play functions that support VOX (headerless) audio files sampled at 8
ksamples/s including; 16 bit Linear, 8 bit A-Law, 8 bit Mu-Law and 4 bit OKI-ADPCM.
vpb_play_voxfile_sync()
The buffer-based play functions allow the development of custom play routines in situations where the
file-based functions are inappropriate, for example, when playing buffers from memory or when using
non WAVE/VOX file formats:
vpb_play_buf_sync()
Compression(encoding)modeusedtostoresamples
Mode Description
VPB_LINEAR 128kbit/s, 16 bit linear, 8kHz sampling rate
VPB_ALAW 64kbit/s, A-Law companded

VPB_MULAW 64kbit/s, Mu-Law companded
VPB_OKIADPCM 32kbit/s, Oki-ADPCM, 4 bit, 8kHz sampling

rate
VPB_OKIADPCM2 24kbit/s, Oki-ADPCM, 4 bit, 6kHz sampling
4 rate
RecordingAudio
The API functions for recording audio are divided into two groups; file-based functions and buffer-
based functions.
The file-based record functions are designed to make recording files straightforward. The functions
support WAVE files sampled at 8 ksamples/s, recording audio to files that follow the WAVE file layout
specification including 16 bit Linear, 8 bit A-Law, 8 bit Mu-Law and 4-bit OKI-ADPCM.
There are also file-based record functions that support VOX audio files sampled at 8 ksamples/s
including; 16 bit Linear, 8 bit A-Law, 8 bit Mu-Law and 4 bit OKI-ADPCM.
The user definedbuffer-based record functions allow the development of custom record routines in
situations where the utility functions are inappropriate, for example, when recording buffers to memory
or when using non WAVE/VOX file formats:

Events DTMF and
Programmable Tone
Generation

DTMF and Programmable Tone Generation
The following functions support tone generation on the VPB:
vpb_dial_async()vpb_dia
l_sync()
vpb_settone()vpb_getton
e()
Tones (including DTMF) tones are generated on a channel using the vpb_settone() function. All of the
standard DTMF tones are defined at initialization. Other user defined tones can be programmed at any
time using the vpb_settone() function. The standard DTMF tones can also be reprogrammed using the
vpb_settone() function. The tone generator parameters are constant across all VPB channels, they are
not programmable on a channel by channel, or board by board basis. Up to 10 programmable tones can
be defined, giving a total of 26 tones including the standard DTMF tones. Each tone can consist of up to
3 frequency components, each with independent amplitude, specified in dB with respect to the overload
level of 0dB. There are limits in the tone generator parameters. Attempting to program a tone outside of
these limits will generate an error.
Playing and Recording Audio Tone Detection
<<<
Previous Next >>>
Tone Detection
The following functions support programmable tone detection:
vpb_settonedet()
vpb_gettonedet()
vpb_debug_tonedet()
When a tone is detected, a VPB_TONEDETECT event is placed on the event queue with the tone identifier
placed in the data element of the event structure. There are 3 pre-defined tones, VPB_DIAL (dial tone),
VPB_RINGBACK (ringback), and VPB_BUSY (busy tone). These are configured for standard tones and may
be redefined if desired to suit the actual switch to which the VPB is connected. Up to VPB_MD (a
#define in vpbapi.h) tone detectors can be defined for each channel of each VPB. Counting the 3 pre-
defined tones, VPB_MD-3 new user defined tones are available for the user, or the pre-defined tones may
be redefined to give a total of VPB_MD user defined tones. To redefine a pre-defined tone, just specify the
pre-defined tone identifier in the tone_id parameter of the VPB_DETECT structure when programming the
tone.
Note: The VPB_MD (#define in vpbapi.h) is set by Voicetronix and should not be modified by the user.
Up to ten programmable tones (including the pre-defined tones) are available for the user. The tone
detectors of each channel are independent of the tone detectors of other channels. Thus each channel
must be programmed independently with the vpb_settonedet() API function.
ProgrammingtheToneDetectors
Tone detectors (either DIAL, BUSY, RINGBACK, GRUNT, or user [5..9] tone detectors) can be
programmed at driver start up using the VPB_TONE env. variable. The main reason for this feature is to
allow users to program the busy tone detector for different PBX models without having to modify and
recompile any code.
The format of the VPB_TONE env. variable is described in src/envtone.cpp.

To determine the parameters of a tone:
1 Sample the tone using unittest/recwav. For example to sample the busy tone, dial the port, start
recwav, then hangup the phone. To sample dial tone just run recwav without dialling the port
from another extension. Run recwave for about 30 seconds on pulsed tones so that you get at least
10 repetitions - this helps later with testing.
2 Use a waveform editor to view the tone and determine it's frequency and on-time (on-time is only
valid for pulsed tones such as busy only, dial tones usually stay on). I use a Windows shareware
editor called Goldwave. You can determine the frequency of the tone in Goldwave by clicking on
the waveform window in the "Device Controls window", this will give you a spectral view of the
tone. Each division is 400Hz. There may be similar tools available for Linux.
3 For a pulsed tone, determine the frequency and on-time. For continuous tone such as dial, just the
frequency is required.
4 To test your tone detector, the unittest/tonedebug program is useful. This program can play
your sampled tone, while at the same time it tries to detect the tone using the parameters you have
determined. These parameters can be entered on the command line of tonedebug, so testing
variations of the tone detector parameters is easy. Note that this program must run without any
phone lines connected to the card - it replays the tone you sampled, while simultaneously
sampling the same signal to the prototype tone detector you are testing.
5 Try setting the bandwidth to 100Hz, if that doesn't work, try 200Hz.
6 Once you are happy with the tone detector (for example, it detects all 10 repetitions of the tones
you sampled), you can then set the env. variable to describe the tone, and run your main
application.
Examples
Dialtone
The frequency is 500Hz, and we select a bandwidth of 100Hz. We would like the tone detector to "fire"
after 1 second (1000ms) of continuous dial tone. The dial tone we sampled with recwav is in the file
mydial.wav.
In the unittest dir:
$ ./tonedebug -c 500 100 1000 -w mydial.wav -t dial
which will produce: The frequency is 425Hz, and we select a bandwidth of 200Hz. By inspecting the
wave file we determine that this pulsed tone is on for 375ms. The wave file is called mybusy.wav.
$ ./tonedebug -p 425 200 375 -w mybusy.wav -t busy
which will produce something like:
In this case, all three busy tones sampled were detected OK. The "grunt" tone is a special tone detector
that just senses energy on the line.
To then set the busy tone detector using an env. variable (bash shell):
$ export VPB_TONE=BUSY,P,425,200,375
See also src/envtone.cpp for more information.
MoreDetailonProgrammingtheToneDetectors
The tone detection algorithm is split into two phases. The first phase checks an incoming signal to
determine if its signal parameters fit the templates defined in the tone detector, for example, the
frequency, bandwidth, level, and signal to noise ratio (SNR). The second phase looks at the on-off timing
of the signal, or cadence information. If both the signal parameters and the cadence parameters match, an
event is posted.
Each programmable tone has a unique identifier, i.e. a 16 bit integer that is placed in the data element of
the event when the tone is detected. The value of the tone identifier is not important, as long as it is
unique. If vpb_settonedet() is called with a non-unique identifier (one which has been used before),
then that programmable tone is redefined. If vpb_settonedet() is called with a unique identifier (one
which has not been used before), then a new programmable tone is defined.
The structure VPB_DETECT is used to define a programmable tone. Single or dual frequencies can be
specified, each with independent frequency, amplitude, and bandwidth. In addition, the allowable twist
for dual tones (difference in level between the two tones) can be defined. Attempting to define a tone
outside of the tone detector limits will cause an error.
For a single frequency tone to pass the signal processing phase, the following conditions must be true:
1 The level of the tone in the band specified by the frequency (freq1) and bandwidth (bandwidth1)
must be above the minimum level (minlevel1).
2 The signal energy must be greater than the rest of the energy in the received signal by the
specified signal to noise ratio (snr).
3 If the above conditions are met, then the signal is declared detected and is passed to the cadence
detection stage for cadence analysis. For a dual frequency tone to pass the signal processing
phase, the following conditions must be true:
4 The level of the first frequency component in the band specified by the frequency (freq1) and
bandwidth (bandwidth1) must be above the minimum level (minlevel1).
5 The level of the second frequency component in the band specified by the frequency (freq2) and
bandwidth (bandwidth2) must be above the minimum level (minlevel2).
6 The total signal energy in both bands must be greater than the rest of the energy in the received
signal by the specified signal to noise ratio (snr).
7 The difference in the energies of the two frequency components must be within the allowed twist.
If the above conditions are met, then the signal is declared detected and is passed to the cadence
detection stage for cadence analysis.
CadenceDetectionAlgorithm
The cadence detection parameters of the tone detector are defined by constructing a state machine for
each tone detector. The state machine is defined by a state transition table (stran), and the number of
states (nstates). The state transition table consists of an array of VPB_STRAN structures. The state
machine begins in state 0 and progresses to the next state when the state transition requirements are met
for that state. When the final state transition occurs, an event of type VPB_TONEDETECT is posted on the
API event queue. A maximum of VPB_MS (#define in vpbapi.h) cadence states are allowed for each
state machine.
There are three types of state transitions:
VPB_TIMER. A state transition occurs when no change (transition) in the signal occurs for the
fire time (tfire) in milliseconds. If a transition occurs before time tfire, the state machine
is reset to state 0. The VPB_TIMER transition provides a way to measure the on time of
signals without cadence, for example continuous dial tones.
VPB_DELAY. It waits the desired time, tfire ms and goes to the next state. The VPB_DELAY
transition provides a way to wait a desired time irrespective of any signal transitions.
VPB_RISING. A state transition occurs on the rising edge of the signal detection, that is,
when the signal goes from a non-detected to detected state. The state transition occurs if
the time spent in this state is between the minimal ( tmin) and maximum (tmax) time in
milliseconds. If at the rising edge the time spent in this state is not between tmin and tmax
ms, the state machine is reset to state 0. If tmin and tmax are both set to 0, then a state
transition occurs on the rising edge of the signal, regardless of the time spent in this state.
The VPB_RISING transition provides a way to determine how long the signal was off.
VPB_FALLING. A state transition occurs on the falling edge of the signal detection, that is
when the signal goes from a detected to non-detected state. The state transition occurs if
the time spent in this state is between tminand tmax ms. If at the falling edge the time
spent in this state is not between tmin and tmax ms, the state machine is reset to state
0. If tmin and tmax are both set to 0, then a state transition occurs on the falling edge of
the signal, regardless of the time spent in this state. The VPB_FALLING transition provides a
way to determine how long the signal was on.
ProgrammableToneDetectorTips
The cadence state machine approach has the advantage that non-periodic or variable cadences may be
detected, for example a tone that has a long on period, then a short on period. To detect several cycles
of a periodic cadence pattern, for example 3 on/off cycles of a busy tone, just repeat the cadence state
detector rising and falling edge transitions the desired number of times, up to the VPB_MS (#define in
vpbapi.h) limit.
When designing/debugging a tone detector, start with a simple cadence detector, for example just a single
rising edge state. Adjust the signal detection parameters first, then add and test the extra cadence states
one at a time. This will identify any problems with the last cadence state added. Don't forget to modify
the nstates parameter in the VPB_DETECT structure as extra states are added.
When designing/debugging a tone detector, start with wide bandwidths (several hundred Hz), and low
level thresholds (say -40 dB), then gradually tighten (reduce bandwidth, increase level) these
parameters to increase the robustness of the tone detector. Amplitude modulated signals have wider
bandwidths than pure sinusoids, and their amplitudes move up and down with the modulation
frequency. Amplitude modulated signals may therefore need lower level thresholds than unmodulated
tones. As a rule of thumb, use a bandwidth about four times as wide as the modulating frequency, for
example, 100 Hz for a 25 Hz modulating frequency. The level threshold may need to be very low to
detect the signal through the low level periods, so try -40 dB as a starting point for the level parameters.
Continuousdialtoneat425Hz,amplitudemodulatedat25Hz
This discussion refers to the toned_dial variable below.
This tone is amplitude modulated at 25 Hz, which spreads the bandwidth approximately 25 Hz either side
of the main frequency component. A bandwidth of 100 Hz is used to be sure that all of the dial tone
energy is captured, although only 50 Hz is strictly necessary. The level of amplitude modulated signals
can also be quite low (it varies up and down with the modulating signal), so a low amplitude threshold of
-40dB is used. The tone contains only a single frequency component so the 2nd frequency parameters are
set to 0, which instructs the tone detector software to ignore the 2nd frequency.
The signal to noise ratio (SNR) was set to 10 dB so that the detector requires most of the energy in the
signal to be contained in the 100 Hz bandwidth. This helps to reduce false triggering, for example by a
speech signal that may have energy around 400 Hz.
There are two cadence states specified. The first looks for a rising edge in the signal detection logic.
No time parameters are specified, so only the rising edge (from non-detected to detected signal
condition) is required to move the state machine to the second state.
The second state is a VPB_TIMER state. This timer "fires" when the signal has been detected for 2000 ms.
If the signal disappears in this time, the state machine is reset to the first state and no event is posted. If
the signal continues uninterrupted for 2000 ms, an event is posted to the API event queue and the state
machine resets itself to state 0. The event will contain VPB_DIAL in the data member of the VPB_EVENT
structure.
Note that the timer state provides an additional level of "filtering", as the signal must be continuous and
uninterrupted for 2000 ms. Any non-valid signals are unlikely to meet the signal detection conditions for
this time, and will be discarded by the state machine.
Example 4. toned_dial for 425Hz continuous dial tone, modulated at 25Hz
AustelBusyTone425Hzor400Hz,375mson,375msoff
This discussion refers to the toned_austel_busy variable below.

The Austel busy tone has two possible frequencies, 400 or 425 Hz, so a bandwidth of 100 Hz has been
used to make sure both possibilities are within the bandwidth of the signal detector. As the signal is a
single unmodulated tone, the amplitude will be relatively stable, so we can set a fairly high cut off level
of -20 dB. The cadence state machine has 3 states, which detect a single on/off cycle of the busy tone.
The first state detects the first rising edge, with no time parameters. The second state waits for the falling
edge, and checks that the signal on time was between 300 and 450 ms. The third state then waits for the
next rising edge, and checks if its off time was between 300 and 450 ms. If so, then a VPB_AUSTEL_BUSY
event is posted to the API queue. If any of these conditions fail then the state machine resets and no
events are generated.
Example 5. Austel busy tone
DTMFtonedetection
This example demonstrates the ability of the programmable tone detector to detect tones with two
frequency components, in this case the DTMF tone for 1, composed of 697 Hz, and 1209 Hz. The
variable toned_dtmf1 below illustrates the configuration for this tone.
The signal detection parameters are straightforward, both frequencies have the same level thresholds. The
twist parameter specifies the maximum permissible difference in the magnitudes of the two frequency
components of the tones, in this case it is 10 dB. The cadence state machine looks for a rising edge, then
the tone must be present for a minimum of 100 ms before a VPB_TONEDETECT event with the data member
set to DTMF_1 (user #defined to a unique tone identifier) is posted.
Example 6. DTMF tone detector
Example4 GruntDetectorusedtodetectwidebandsignalssuchasvoice
This discussion refers to the toned_grunt variable below.
Voice signals have a wide band signal characteristic, with most of the energy located between 50-
2000Hz. The grunt detector looks for wide band energy between 500Hz and 3500Hz. The lower
frequency band (500Hz) was selected as not to overlap with other telephony signals, such as dial and
busy tones which have their energy centred around 400Hz. The cadence state machine has 2 states to
detect a wideband signal. The first state waits for 1 second, ignoring any signal transitions. The second
state checks for a rising edge in the signal with an off time between 0-40 ms. If so, then a VPB_GRUNT
event is posted to the API queue. If any of these conditions fail then the state machine resets and no
events are generated.
Example 7. DTMF tone detector

DTMF and Automated Tone
Programmable Tone Training
Generation
Voicetronix Programming
Guide
Automated Tone Training

Introduction
To make programming the tone detectors easier, an automated tone training application, tonetrain, has
been developed, and is included in the vpb-driver software.
1 Record a sample of the tone.
2 Run tonetrain to analyse the sample and determine suitable tone detector parameters.
3 Test the tone detector parameters on your recorded tone
Compiling
First ensure you have already compiled the driver (see README in the root directory of vpb-driver).
$cd tonetrain
$./configure $make
Tutorial Setup
To sample tones you will need a Voicetronix card, for example an OpenLine4 or OpenSwitch12 card.
This card should be installed and tested. You will also need to connect a port of the Voicetronix card to
the telephone line that you wish to train tones for. Different telephone line and PBXs tend to generate
different tones. A second phone line or mobile (cell) telephone is also useful.
Make sure you have compiled, installed and tested the Voicetronix driver. You will also need to have
compiled recwav and tonedebug, both located in the unittest directory.
Samplefiles
There are some sample files in the tonetrain sub-directory. They are:
400-c-tone.wav - a continous tone of 400Hz 600-c-tone.wav - a continous tone of 600Hz hs-
dialtone.wav - dial tone from our PBX hs-ringback.wav - ring back tone from our local
exchange Using these files you can run tonetrainer and then plug the results back into
tonedebug
(this requires a Voicetronix board)
To record a sample, perform this command from the unittest directory:
$ ./recwav dialtone.wav 1 10
This will record 10 seconds of signal on port 1 or the Voicetronix card. Before recording,
recwav takes the line off hook, which will cause dial tone to be generated by your exchange
of PBX. If your telephone line is connected to a different port, change the second argument.
It is a very good idea to check that the sample file is of good quality, and contains only the tone to be
trained. You can play back the tone using playwav, or using a suitable command line or GUI utility.
If the sample file is of poor quality, then the automated tone training process will fail. It must contain
just the tone sample to be trained, for example no human speech or other tones.
Now to determine the tone parameters, perform this command:
$ tonetrain/tonetrain -e -w dialtone.wav
The -e option specifies the environment variable output format, the -w WaveFile
specifies a wave file input format.
You should get a result like this:
The arguments to the Environment variables are:
export VPB_TONE=<Tone ID>,<Tone Type>,<Tone Frequency1>,<{Type dependant}...>
Now perform this command to set the environment variable, note that we have changed the Tone ID from
5 to DIAL:
$ export VPB_TONE=DIAL,C,421,100,2000
This environment variable is read by the vpb driver when it starts. The driver uses this
information to configure the tone detector to recognise the tone you have just trained. For
more information on the tone detector parameters (and how to set them) please see the
previous section.
There are several other output formats for tonetrain, see the command line help for more
information.
$ ./tonedebug -e -w dialtone.wav
As with tonetrain, -e specifies the environment variable output format, the -w WaveFile option
specifies wave file input format for the sample used to test the tone detector.
RingbackToneExample
Ringback is the tone you hear in your telephone handset when the destination phone is ringing. It starts
just after dialling and stops when the destination phone is answered.
To record a sample, you will to have a destination number that will not get answered and is not busy!
Again we will use the recwav application:
$ ./recwav ringback.wav 1 10 --dial ,,555
This example assumes that the destination number you are calling is 555 (just like the
movies). The commas generate a 1 second pause in the dialling, which is useful as some
PBXes and exchanges like pauses before (and during dialling). You should hear the phone
at the destination number (in this case 555) ringing during the record process.
If you don't hear the destination phone ringing, then there may have been a problem dialling.
Investigate and correct this before proceeding.As with the dial tone example, it is a very good idea to
listen to the recorded sample to ensure it contains the correct ringback tone sample before proceeding
with the training stage.
You can then process it through tonetrain and tonedebug as before: $
tonetrain/tonetrain -e -w ringback.wav
$ export VPB_TONE=RINGBACK,P,453,100,1690 $
./tonedebug -e -w ringback.wav
BusyToneExample
To record a sample, you will to have a destination number that will be busy and wont go to voice mail
(you could use the number that you are calling from). Again we will use the recwav application:
$ ./recwav busy.wav 1 10 --dial ,,555 You can then run it through tonetrain and tonedebug as
before: $ tonetrain/tonetrain -e -w busytone.wav
$ export VPB_TONE=BUSY,P2,421,100,1000 $
./tonedebug -e -w busytone.wav
Tone Detection Timers

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()vp
b_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.
<<< Previous Automated Home Next >>> WAVE File
Tone Training and AU File Functions
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_ra
te()
vpb_wave_seek()vpb_wave_get_m
ode()
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.
<<< Previous Home Next >>> Get Digits

Timers Functions

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 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.
GetDigitTerminationcodes
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
<<< Previous WAVE Home Next >>> Call

File and AU File Progress Functions
Functions
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.
CallProgressReturncodes
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
Get Digits Functions VOX Functions

<<<
Previous Next >>>
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.
<<< Previous Call Home Next >>> Pip

Progress Functions Functions
Pip Functions
The following functions support pip generation on the OpenLog8i:
vpb_get_pip()vpb_set
_pip()vpb_pip_on()
vpb_pip_off()
There is a requirement by national communication authorities, in the instance of recording calls, that the
parties must be notified that their call is being recorded. The pip parameters, the length of the pip pulse
and the period between pulses, can be modified by vpb_set_pip(). The VPB_PIP structure contains these
parameters.

VOX Functions Miscellaneous Functions
<<<
Previous Next >>>
Miscellaneous Functions
vpb_get_model()vpb_sleep()
vpb_sethook_sync()vpb_sethook_async()vpb_translate_event()
vpb_open()vpb_close() vpb_seterrormode()

Pip Functions Function Reference
<<< Previous
Function Reference
vpb_config()
Synopsis
int WINAPI vpb_config(int num_cards, int *bases, char *firmware_file, int

Function
Set installation specific config info, call before vpb_open(). If this function is called, it overrides any
other settings (for example compile-time defaults or env vars).
vpb_set_call()
Synopsis
int WINAPI vpb_set_call(int handle, VPB_CALL *vpb_call)
Function
Function to set call progress parameters.
vpb_get_call()
Synopsis
int WINAPI vpb_get_call(int handle, VPB_CALL *vpb_call)
Function
Function to get current call progress parameters.
vpb_call_sync()
Synopsis
int WINAPI vpb_call_sync(int handle, char *dialstr)
Function
Place a call using call progress algorithm. Note: when this function is called, make sure dial tone has not
been detected yet.
vpb_call_async()
Synopsis
int WINAPI vpb_call_async(int handle, char *dialstr)

Function
vpb_cid_debug_on()
Synopsis
void WINAPI vpb_cid_debug_on(char debug_file_name[]) {
Function
Call this function to enable debugging of the CID module. Causes lots of debug info to be written to the
text file "debug_file_name".
vpb_cid_decode()
Synopsis
Function
As per cid-demodulate() but parse out all CID fields.
vpb_cid_demodulate()
Synopsis
int WINAPI vpb_cid_demodulate(char* number, int* nChars, short* in, int n)
Function
Attempts to decode CID information from an array of samples. Throws various exceptions should an
error occur. Returns the caller number in "number". Will return a null-str in "number" if no caller number
supplied.
vpb_start()
Synopsis
Initialises the API software (boots DSPs etc) when operating in "bayonne" mode. Calling this function
before vpb_open() starts the driver in "bayonne" mode. If vpb_open() is called without calling this
function first, the driver is started in "regular" mode. The major feature of bayonne mode is that the user
must set up a thread to periodically call (poll) the vpb_get_event_async_bayonne() function. Without this
thread the driver will not function. This has certain advantages where the user whishes to control the
number of threads in the system, and was specifically written for the bayonne package
(www.bayonne.cx). See the unittest tvpb.cpp for an example of a program implemented using bayonne
mode. In regular mode, the driver sets up all sorts of polling threads which leads to generally simpler
application code. In other words the choice of bayonne vs regular mode is the usual choice of flexibility
vs complexity :-). Most of the programs in the unittest directory use regular mode. Note: bayonne mode
was originally supported by the 2.0.x series vpb drivers, and regular mode by the 1.x.y series of drivers.
vpb_open()
Synopsis
int WINAPI vpb_open(unsigned int board, unsigned int channel)
Function
Opens a VPB device (channel), and returns a handle to that device. See also vpb_start().
vpb_close()
Synopsis
int WINAPI vpb_close(int devhandle)
Function
Closes a device. If this is the last device remaining, then the API is closed down (memory freeed, DSP
stopped etc).
vpb_stop()
Synopsis
int WINAPI vpb_stop()
Function
API is closed down (memory free-ed, DSP stopped etc). Only used for "bayonne" mode.
Synopsis
Function
Note: This function is only used in "bayonne" mode. Please do not call in "regular" mode - see also
vpb_start() This function returns an event from the specified VPB card. If an event is available it returns
VPB_OK, otherwise it returns VPB_NO_EVENTS. When this function returns, it should be called again
as soon as possible in a tight polling loop, as it is responsible for sequencing several time-sensitive
operations (e.g. playing DTMF tones). Avoid placing blocking functions in the polling loop that calls this
function, to ensure it is called regularly. Once every 20ms is recommended. IMPORTANT: This function
must be called regularly, as the driver uses this function to service time critical tasks in the driver. This
function must be polled regularly, even if no events are required for the program. Without it, other
functions, such as play/record, will not work.
vpb_set_event_callback()
Synopsis
Function
Sets the event callback function for each channel. By default no event callback functions are set, in this
case events are posted to the API event Q. If this function has been called with a non-null function
pointer, the event callback funcion is called with the event as an argument rather than posting the event to
the API Q. The user defined event callback function should be of the form: void
event_callback(VPB_EVENT *e); To disable the event callback, call this function with a NULL pointer
for the function argument.
vpb_set_event_mask()
Synopsis
int WINAPI vpb_set_event_mask(int handle, unsigned short mask)
Function
vpb_get_event_mask()
Synopsis
int WINAPI vpb_get_event_mask(int handle)
Function
Function to return the current event mask for a given device.
vpb_enable_event()
Synopsis
int WINAPI vpb_enable_event(int handle, unsigned short mask)
Function
Function to unmask (enable) only the specified events while leaving the rest of the event masks
unchanged.
vpb_disable_event()
Synopsis
int WINAPI vpb_disable_event(int handle, unsigned short mask)
Function
Function to mask out (disable) specified events only, while leaving the rest of the event masks
unchanged.
vpb_put_event()
Synopsis
int WINAPI vpb_put_event(VPB_EVENT *e)
Function
Function to place an event on the API event queue exported API version.
Synopsis
int WINAPI vpb_get_event_async(VPB_EVENT *e)
Function
Function to get an event from the API event queue. Returns VPB_OK if an event available, other wise
VPB_NO_EVENTS if Q empty.
vpb_get_event_sync()
Synopsis
int WINAPI vpb_get_event_sync(VPB_EVENT *e, unsigned int time_out)
Function
This function waits until an event is available on the API Q, then returns. The thread is put to sleep until
the event becomes available. Function returns VPB_OK if event returned, else VPB_TIME_OUT if sync
function times out. Use tme_out = 0 for no timeout.
vpb_get_event_ch_sync()
Synopsis
int WINAPI vpb_get_event_ch_sync(int h, VPB_EVENT *e, unsigned int time_out)
Function
This function waits until an event is available on the API Q, then returns. The thread is put to sleep until
the event becomes available. This version only returns events from a specified channel.
vpb_get_event_ch_async()
Synopsis
int WINAPI vpb_get_event_ch_async(int h, VPB_EVENT *e)
Function
This reads an event on a channels event queue if available.

Synopsis
int WINAPI vpb_sethook_async(int chdev, int hookstate)
Function
Function to set the hook status of a particular chnnel device. This version returns immediately.
vpb_sethook_sync()
Synopsis
int WINAPI vpb_sethook_sync(int chdev, int hookstate)
Function
Function to set the hook status of a particular chnnel device. This version returns after the hook status has
been changed.
vpb_set_station_sync()
Synopsis
int WINAPI vpb_set_station_sync(int chdev, int state)

Function
Function to set the status (on or off) of a station port channel device. This version returns after the status
has been changed. NOTE: DR 22/8/02 - this function is not normally required, as hook detector logic has
been modified to automatically turn off/on station audio with hook switch.
vpb_ring_station_async()
Synopsis
int WINAPI vpb_ring_station_async(int chdev, int state)
Function
Function to start/stop a station port ringing. This version rings stations with a pre-defined cadence.
Synopsis
int WINAPI vpb_ring_station_sync(int chdev, int state)
Function
Function to start/stop a station port ringing.
vpb_user_ring_station_sync()
Synopsis
int WINAPI vpb_user_ring_station_sync(int chdev, int state)
Function
Function to start/stop a station port ringing. This version allows the caller (user) to define the cadence.
Station will ring continuously when called with state==1, until called with state==0. Care should be taken
to ring no more than that 4 stations at any one time, to prevent overloading the OpenSwitch12 ring
generator. Excess load of the ring generator will not result in permanent damage, however the station
power supply to shut down, requiring a power down of the OpenSwitch12 (ie switching the PC off) to
reset. This function should not be used in conjunction with vpb_ring_station_sync, the cadenced ring
generator function, as the driver will get confused!
vpb_sleep()
Synopsis
void WINAPI vpb_sleep(long time)
Function
Function to put the current thread to sleep for a certain time in ms. Used during testing to reduce the
amount of time program spends in main polling loop so that the computational load of the timer callback
can be measured.
vpb_adpcm_open()
Synopsis
int WINAPI vpb_adpcm_open(void **pv)
Function
vpb_adpcm_close()
Synopsis
void WINAPI vpb_adpcm_close(void *pv)
Function
Closes down the ADPCM state variables, freeing memory. Call after all ADPCM operations have
finished.
vpb_adpcm_reset()
Synopsis
void WINAPI vpb_adpcm_reset(void *pv)
Function
Resets the ADPCM state variables.
vpb_adpcm_decode()
Synopsis
Function
Converts a buffer of compressed OKI ADPCM samples to a buffer of 16 bit linear samples.
vpb_adpcm_encode()
Synopsis Function
Converts a buffer of 16 bit linear samples to a buffer of compressed OKI ADPCM samples.
vpb_comp_load()
Synopsis
int WINAPI vpb_comp_load(unsigned short board)
Function
Interrogates the DSP to determine the computational loading. Causes a comp load statement to be printed
if mprintf's are enabled. Dont expose the function to the punters, keep it as undocumented for our use
only.
vpb_echo_canc_force_adapt_on()
Synopsis
int WINAPI vpb_echo_canc_force_adapt_on()
Function
Forces the echo cancellers to adapt all of the time, ie switches off near end speech detector. Used to
determine maximum computational load.
vpb_echo_canc_force_adapt_off()
Synopsis
int WINAPI vpb_echo_canc_force_adapt_off()
Function
Stops forced adaptation.

vpb_echo_canc_enable()
Synopsis
int WINAPI vpb_echo_canc_enable()

Enables the echo cancellers.
vpb_echo_canc_disable()
Synopsis
int WINAPI vpb_echo_canc_disable()
Function
Disables the echo cancellers, but keeps adaptation on.
vpb_echo_canc_get_sup_thresh()
Synopsis
int WINAPI vpb_echo_canc_get_sup_thresh(short *thresh)
Function
Gets the current echo suppressor threshold. This threshold is the same for all channels on all cards.
vpb_echo_canc_set_sup_thresh()
Synopsis
int WINAPI vpb_echo_canc_set_sup_thresh(short *thresh)
Function
Sets the current echo suppressor threshold. This threshold is the same for all channels on all cards.
0x1000 (4096) -18dB 0x800 (2048) -24dB 0 0 no supressor
vpb_get_model()
Synopsis
int WINAPI vpb_get_model(char *s) {
Function
Returns a string containing the VPB model, driver should be started first by at least one call to
vpb_open().
Synopsis
int WINAPI vpb_get_ports_per_card() {
Function
Returns the number of ports on each card.
vpb_set_codec_reg()
Synopsis
Function
Used to set a register of the TS5070 codecs, allows driver-level config of codec, rather than hard-coding
in DSP firmware.
vpb_get_num_cards()
Synopsis
int WINAPI vpb_get_num_cards()
Function
Returns the number of cards in the system. In current implemention need to call vpb_open() or
vpb_start() before calling this function. This means e.g. one channel should be opened before determining
how many cards there are! This is very silly and should be fixed some time!
vpb_bridge()
Synopsis
Function
Bridges two ports using the driver, to allow 2-way conferencing. The bridging is implemented at a low
level (firmware and/or hardware) by the driver to ensure a low delay connection between the ports. Note
that only ports on the same physical card can be bridged using this method on the V4PCI and ISA boards.
Two bridging resources are available on the V4PCI (1 & 2). V4PCI: For 3 or more way conferencing (or
bridging between ports on different cards) use "software bridging" using the play and record buf API
functions. This results in a higher delay (20ms or so), however this does not cause a problem due to the
echo canceller on each VPB port. OpenSwitch: This will auto-magically switch to a kernel-mode driver
version of bridging when bridging across boards. For more information on this look at the vpb_listen
function.
vpb_listen()
Synopsis
Function
Software bridge/listen for OpenSwitch boards. Starts a half duplex bridge between two handles. For a full
duplex bridge, both handles will need to listen between each other. This currently only works on
OpenSwitch boards.
vpb_conf()
Synopsis
Function
Multi party conferencing. Can be used across any number of OpenSwitch boards. There is a maximum of
10 conferences with a max of 10 people each. You may need to reduce the HW-record gain if you
experiance excesive feed back.
vpb_watchdog_enable()
Synopsis
int WINAPI vpb_watchdog_enable(int h, int enable) {
Function
Enables (enable == 1), or disables (enable == 0) V12PCI watchdog timer. There is one watchdog timer
per board, so only one call per board is required, any handle h from that board can be used. Once enabled,
it must be reset at least once every 8 seconds by vpb_watchdog_reset. If it is not reset the watchdog timer
will fire. Once fired, the hardware will assume the PC has crashed, and the first 4 station ports will be
connected to the first 4 loop ports to preserve basic phone functionality. Use of the watchdog timer
assumes a mixed station/loop configuration. Do not use the watchdog timer when the card is configured
as all loop or all station cards.
vpb_watchdog_reset()
Synopsis
int WINAPI vpb_watchdog_reset(int h) {
Function
Resets watchdog timer. Call at least once every 8 seconds to prevent watchdog timer firing. Does nothing
when watchdog timer is disabled. There is one watchdog timer per board, so only one call per board is
required, any handle h from that board can be used.
vpb_get_card_info()
Synopsis
int WINAPI vpb_get_card_info(int board, // Board number *detail // Card

VPB_CARD_INFO ) Info Structure to fill.
Function
Returns the card details in a structure VPB_CARD_INFO. Includes: Model name, Serial number,
Revision number, Manufacture Date All strings are null terminated. Note: Only supported under Linux at
this time!
vpb_get_digits_async()
Synopsis
int WINAPI vpb_get_digits_async(int handle, VPB_DIGITS *newdig, char *buf)
Function
Gets a buffer of digits based on the conditions passed to the function. Returns immediately, and posts a
comletetion event when the buffer has been obtained. If this function is called while already collecting
digits (by a prvious call to this function), the digit collection is reset, and digits collected so far are
discarded.
Synopsis
int WINAPI vpb_get_digits_sync(int handle, VPB_DIGITS *newdig, char *buf)
Function
Gets a buffer of digits based on the conditions passed to the function. Returns when digit buffer has been
obtained, with appropriate VPB_DIGIT_XXX return code.
vpb_flush_digits()
Synopsis
int WINAPI vpb_flush_digits(int handle)
Function
Clears the internal digit buffer, often called before vpb_get_digits_xxxx.
vpb_wave_open_write()
Synopsis
int WINAPI vpb_wave_open_write(void **ppv, char filename[], int mode)
Function
Opens a RIFF Wave file.
vpb_wave_open_read()
Synopsis
int WINAPI vpb_wave_open_read(void **ppv, char filename[])
Function
Opens a RIFF Wave file for reading.
vpb_wave_close_write()
Synopsis
void WINAPI vpb_wave_close_write(void *wv)

Closes a RIFF Wave file after writing.
vpb_wave_close_read()
Synopsis
void WINAPI vpb_wave_close_read(void *wv)
Function
Closes a RIFF Wave file after reading.
vpb_wave_write()
Synopsis
int WINAPI vpb_wave_write(void *wv, char buf[], long n)
Function
Writes a block of speech samples to a RIFF Wave file.
vpb_wave_read()
Synopsis
int WINAPI vpb_wave_read(void *wv, char buf[], long n)
Function
Reads a block of speech samples from a RIFF Wave file. Returns the number of bytes read.
vpb_wave_seek()
Synopsis
int WINAPI vpb_wave_seek(void *wv, long offset)
Function
Moves wave pointer to a specified location in samples, with respect to the beginning of the file.
Synopsis
void WINAPI vpb_wave_set_sample_rate(void *wv, unsigned short rate)
Function
Changes the sample rate of a wave file.
vpb_wave_get_mode()
Synopsis
int WINAPI vpb_wave_get_mode(void *wv, unsigned short *mode)
Function
Determines the compression mode of a wave file.
vpb_setagc()
Synopsis
int WINAPI vpb_setagc(int handle, VPB_AGC *agc)
Function
Sets the agc parameters for a specified channel.
vpb_getagc()
Synopsis
int WINAPI vpb_getagc(int handle, VPB_AGC *agc)
Function
Gets the agc parameters for a specified channel.
vpb_play_set()
Synopsis
int WINAPI vpb_play_set(int handle, VPB_PLAY *vpb_play)

Sets play parameters or this channel.
Synopsis
int WINAPI vpb_play_buf_start(int handle, unsigned short mode)
Function
API callable version of play_buf_start.
vpb_play_buf_sync()
Synopsis
int WINAPI vpb_play_buf_sync(int handle, char *buf, unsigned short length)
Function
API version of play_buf_sync(). Returns VPB_FINISH if playing should finish, else returns VPB_OK.
Synopsis
int WINAPI vpb_play_buf_finish(int handle)
Function
Completes the playing of a channel.
Synopsis
int WINAPI vpb_play_file_sync(int handle, char file_name[])
Function
Utility function to play a file to a channel. Function returns when playing is finished.
Synopsis
Function
Function to play a vox file to a channel. Function returns when playing is finished.
Synopsis
int WINAPI vpb_play_file_async(int handle, char file_name[], int data)
Function
Utility function to play a file to a channel. Function returns as soon as playing has started, and places an
event on the API Q when playing has finished.
Synopsis
Function
Utility function to play a vox file to a channel. Function returns as soon as playing has started, and places
an event on the API Q when playing has finished.
vpb_play_terminate()
Synopsis
int WINAPI vpb_play_terminate(int handle)
Function
Stops playing immediately. Does nothing if we are not playing. NOTE: this doesnt have to be in the same
thread context as vpb_play_buf_xxxx
Synopsis
int WINAPI vpb_record_set(int handle, VPB_RECORD *vpb_record)
Function
Sets record parameters or this channel.
Synopsis
int WINAPI vpb_record_buf_start(int handle, unsigned short mode)
Function
API callable version of record_buf_start. NOTE: All vpb_record_buf_xxxx functions for a given channel
must be executed in the same thread context.
Synopsis
int WINAPI vpb_record_buf_sync(int handle, char *buf, unsigned short length)
Function
API version of record_buf_sync(). NOTE: All vpb_record_buf_xxxx functions for a given channel
Synopsis
int WINAPI vpb_record_buf_finish(int handle)
Function
Completes the recording of a channel. NOTE: All vpb_record_buf_xxxx functions for a given channel
Synopsis Function
Utility function to record a file to a channel. Function returns when recording is finished.
Synopsis
Function
Utility function to record a vox file to a channel. Function returns when recording is finished.
Synopsis
Function
Utility function to record a file from a channel. Function returns as soon as recording has started, and
places an event on the API Q when recording has finished.
vpb_record_voxfile_async()
Synopsis
Function
Utility function to record a vox file from a channel. Function returns as soon as recording has started, and
places an event on the API Q when recording has finished.
vpb_record_terminate()
Synopsis Function
Stops recording immediately. Does nothing if we are not recording. NOTE: this doesnt have to be in the
same thread context as vpb_record_buf_xxxx
vpb_play_set_gain()
Synopsis
int WINAPI vpb_play_set_gain(int handle, float gain)
Function
Sets the gain of the play channel, using the hardware gain of the TS5070 codec on the VPB4. JK: 9/4/02
Modified to only set software gain and not the hardware gain of the TS5050 codec.
vpb_play_set_hw_gain()
Synopsis
int WINAPI vpb_play_set_hw_gain(int handle, float gain)
Function
Externally accessible wrapper around play_set_hw_gain.
vpb_play_get_gain()
Synopsis
int WINAPI vpb_play_get_gain(int handle, float *gain)

Function
Gets the total gain of the play channel. It comprising of a softare and hardware component (TS5070
codec) on the VPB4/V4PCI.
vpb_record_get_gain()
Synopsis
int WINAPI vpb_record_get_gain(int handle, float *gain)
Function
vpb_record_set_gain()
Synopsis
int WINAPI vpb_record_set_gain(int handle, float gain)
Function
Sets the total gain of the record channel. The total gain is comprised of a software and hardware
component (TS5070 codec). Previously it only comprised of the hardware component. JK 9/4/02
Modified to only set sofware record gain. Disabled hardware configured record gain.
vpb_record_set_hw_gain()
Synopsis
int WINAPI vpb_record_set_hw_gain(int handle, float gain)
Function
Externally accessible wrapper around record_set_hw_gain.
vpb_reset_record_fifo_alarm()
Synopsis
int WINAPI vpb_reset_record_fifo_alarm(int handle)
Function
Resets the latch that detects record DSP buffer overflows. After calling this function another event may
be generated if the buffer overflows.
vpb_reset_play_fifo_alarm()
Synopsis
int WINAPI vpb_reset_play_fifo_alarm(int handle)
Function
Resets the latch that detects record DSP buffer underflows. After calling this function another event may
be generated if the buffer underflows.
Synopsis
int WINAPI vpb_settonedet(int chdev, VPB_DETECT *d)
Function
Enables user to set a user programmed tone, or replace an exisiting tone. Performs translation of user
parameters to VPB message. The tones are defined on a per channel basis. This version (for the API),
stops the config mamanger before download- ing a tone to prevent computational overoad probs.
vpb_gettonedet()
Synopsis
int WINAPI vpb_gettonedet(int chdev, int id, VPB_DETECT *d)
Function
Enables user to extract a tone detectors parameters.
vpb_debug_tonedet()
Synopsis
int WINAPI vpb_debug_tonedet(int chdev, int id, char file_name[], int sec)
Function
Instructs API to produce a debug file of tone detector parameters for one channel.
vpb_dial_async()
Synopsis
Function
Sends a DTMF string down a channel device, accepts the following characters by default, plus user
defined chars if defined: 0 1 2 3 4 5 6 7 8 9 0 * # A B C D and: & (hook flash) , (pause)
Synopsis
Function
Sends a DTMF string down a channel device, accepts the following characters by default, plus user
defined chars if defined: 0 1 2 3 4 5 6 7 8 9 0 * # A B C D and: & (hook flash) , (pause)
vpb_settone()
Synopsis
Function
Enables user to set a user programmed tone, or replace an existing tone. Performs translation of user
parameters to VPB message.
vpb_gettone()
Synopsis
Function
Enables user to retrieve the parameters of a tone. Performs translation of user parameters from VPB
message.
vpb_playtone_async()
Synopsis
int WINAPI vpb_playtone_async(int handle, VPB_TONE *vpb_tone)
Plays a user defined tone immediately, API version.
vpb_playtone_sync()
Synopsis
int WINAPI vpb_playtone_sync(int handle, VPB_TONE *vpb_tone)
Function
Plays a user defined tone immediately, API version.
vpb_tone_terminate()
Synopsis
int WINAPI vpb_tone_terminate(int handle)
Function
Terminates playing of tones (programmable or DTMFs).
vpb_strerror()
Synopsis
char * WINAPI vpb_strerror(int code)
Function
Converts a numeric error code to a human-readable error description. Passes back a pointer to a string
which describes the error code.
vpb_setvox()
Synopsis
int WINAPI vpb_setvox(int handle, VPB_VOX *vox)
Function
Sets the vox parameters for a specified channel.

Synopsis
int WINAPI vpb_getvox(int handle, VPB_VOX *vox)

Function
Gets the vox parameters for a specified channel.
vpb_cid_set()
Synopsis
int WINAPI vpb_cid_set(VPB_CID *cid_struct, int type, void *value)
Function
VPBAPI function to load valid data of 'type' and 'value' into the passed CID structure. Loading some
fields will set associated fields to NULL automaticly as the fiedls are exclusive Return: Error if invalid
type of value out of range, else OK
vpb_cid_compose_dlp ()
Synopsis
int WINAPI vpb_cid_compose_dlp(VPB_CID *MESG, char *dlp)
Function
Build the message dlp from the VPB_CID structure.
vpb_cid_compose_wav ()
Synopsis
Function
Encodes the Data Link Packet recived into a CP-FSK wave including CSS & MSS bit headers. Returns
*BUFF_WAV containing *BUFF_PTR samples.
Synopsis
int WINAPI vpb_set_pip(VPB_PIP *vpb_pip)
Function
Sets the pip parameters for all channels.
vpb_set_pip_ch()
Synopsis
int WINAPI vpb_set_pip_ch(int handle, VPB_PIP *vpb_pip)
Function
Sets the pip parameters for a specifed channel.
vpb_get_pip()
Synopsis
int WINAPI vpb_get_pip(VPB_PIP *vpb_pip)
Function
Gets the pip parameters for the first channel.
vpb_get_pip_ch()
Synopsis
int WINAPI vpb_get_pip_ch(int handle, VPB_PIP *vpb_pip)
Function
Gets the pip parameters for the specified channel.
vpb_pip_on()
Synopsis
int WINAPI vpb_pip_on(int handle)

Enables pip generation for a channel.
vpb_pip_off()
Synopsis
int WINAPI vpb_pip_off(int handle)
Function
Disables pip generation for a channel.
vpb_seterrormode()
Synopsis
Function
Helper function that determines the way errors are handled in the RunTimeError function below. See
RunTimeError() for more info.
vpb_throw_exception()
Synopsis
void WINAPI vpb_throw_exception(int c, char trans[], char api_function[])
Function
Helper function that throws a VpbException.
vpb_timer_open()
Synopsis Function
Initialises a timer object for the specified channel device.
vpb_timer_close()
Synopsis
Function
Deletes a timer object.
vpb_timer_start()
Synopsis
Function
Starts a timer. When the period specified in vpb_timer_open expires, and event for this channel device is
generated. If timer is already active, this function throws a wobbly.
vpb_timer_restart()
Synopsis
Function
ReStarts an already active timer.

Synopsis
Function
Stops an active timer by removing it from the active list. This function allows the timer to be stopped
from the API.
vpb_timer_change_period()
Synopsis
Function
Changes the time out value of a timer that has already been initialised.
vpb_timer_get_unique_timer_id()
Synopsis
int WINAPI vpb_timer_get_unique_timer_id() {
Function
Allows the timer module to generate unique IDs for all of the VPB timer objects in the system.
vpb_translate_event()
Synopsis
void WINAPI vpb_translate_event(VPB_EVENT *e, char s[])
Function
Function to translate the current event into a string.

<<< Previous Home
Miscellaneous Functions

Voicetronix Programming Guide

Hochgeladen von

Dokumentinformationen

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

Voicetronix Programming Guide

Hochgeladen von

Copyright:

Verfügbare Formate

Voicetronix Programming Guide