vpb_play_voxfile_async
Purpose | Utility function to play a vox file to a channel. Asynchronous version. Function returns as soon as playing has started, and then places an event on the API queue when playing has finished. | |||
Syntax | int WINAPI vpb_play_voxfile_async( | |||
int | handle, | |||
char | file_name[], | |||
unsigned char | mode | |||
int | data | |||
); | ||||
Inputs | handle | Handle for this channel. | ||
file_name | Pointer to string containing file name (including path) of file to play. | |||
mode | Compression mode | |||
data | Optional user defined data returned in terminating event. | |||
Outputs | none | |||
Platform | VPB4 only |
Notes
The user defined data is useful to identify which file has finished playing when the VPB_PLAYEND terminate event is posted on the queue. The terminate event data member contains an error code if the function suffers a run time error while executing, otherwise it is set to the user defined data.
Example
#include <stdio.h>
#include "\vpb\vpbapi.h"
void main() {
int handle;
VPB_EVENT e;
handle = vpb_open(1,1);
vpb_sethook_async(handle, VPB_OFFHOOK);
// play linear file on channel 1
vpb_play_voxfile_async(handle, "linear.vox",
VPB_LINEAR, 0);
// wait for terminate event
do {
vpb_get_event_sync(&e,0);
} while((e.type != VPB_PLAYEND) ||
(e.handle != handle));
vpb_sethook_sync(handle, VPB_ONHOOK);
vpb_close(handle);
}
vpb_play_terminate
Purpose | Terminates playing on a channel. | |||
Syntax | int WINAPI vpb_play_file_terminate( | |||
int | handle | |||
); | ||||
Inputs | handle | Handle for this channel. | ||
Outputs | none | |||
Platform | VPB4 only |
Notes
This function is useful to prematurely stop playing in both user defined and utility asynchronous play functions.
There will be a small time delay between calling this function and the actual end of playing. When called to terminate vpb_play_file_async(), a terminating event VPB_PLAYEND is generated. When this event has been generated, the actual playing has ended.
Example
include <stdio.h>
#include "\vpb\vpbapi.h"
void main() {
int handle;
VPB_EVENT e;
handle = vpb_open(1,1);
vpb_sethook_async(handle,VPB_OFFHOOK);
// play wave file on channel 1
vpb_play_file_async(handle, "test.wav",
0);
// wait 100ms before terminating
vpb_sleep(1000);
// stop playing prematurely
vpb_play_terminate(handle);
// wait for terminate event
do {
vpb_get_event_sync(&e,0);
}while((e.type != VPB_PLAYEND) ||
(e.handle != handle));
vpb_sethook_sync(handle,VPB_ONHOOK);
vpb_close(handle);
}
vpb_play_buf_start
Purpose | Sets up a channel ready for playing in user defined play routines. | |||
Syntax | int WINAPI vpb_play_buf_start( | |||
int | handle, | |||
unsigned short | mode | |||
); | ||||
Inputs | handle | Handle for this channel. | ||
mode | Compression mode of file. | |||
Outputs | none | |||
Platform | VPB4 only |
Notes
Used in conjunction with vpb_play_buf_sync() and vpb_play_buf_finish().
Example
See example in vpb_wave_read().
vpb_play_buf_sync
Purpose | Plays a buffer of speech samples to a channel that has been initialised with vpb_play_buf_start(). | |||
Syntax | int WINAPI vpb_play_buf_sync( | |||
int | handle | |||
char | *buf, | |||
unsigned short | length | |||
); | ||||
Inputs | handle | Handle for this channel. | ||
buf | Pointer to buffer of samples to play to channel. | |||
length | Number of bytes to play to channel. | |||
Outputs | returns | VPB_OK or VPB_FINISH | ||
Platform | VPB4 only |
Notes
Used in conjunction with vpb_play_buf_start()and vpb_play_buf_finish().
This function is thread safe. It can be called from a thread separate from the main process thread to implement asynchronous functions.
Example
See example in vpb_wave_read().
vpb_play_buf_finish
Purpose | Completes playing in user defined play routines. | |||
Syntax | int WINAPI vpb_play_buf_finish( | |||
int | handle | |||
); | ||||
Inputs | handle | Handle for this channel. | ||
Outputs | none | |||
Platform | VPB4 only |
Notes
Used in conjunction with vpb_play_buf_start()and vpb_play_buf_sync().
Example
See example in vpb_wave_read().
vpb_play_set
Purpose | Sets the terminating condition for playing on a channel. | |||
Syntax | int WINAPI vpb_play_set( | |||
int | handle, | |||
VPB_PLAYIDH_vpb_play | *vpb_play | |||
); | ||||
Inputs | handle | Handle for this channel | ||
vpb_play | Pointer to structure containing terminating conditions for the play functions | |||
Outputs | none | |||
Platform | VPB4 only |
Notes
This function is used in conjunction with the play routines to allow DTMF digits (from the channel) to terminate the play routine.
Example
#include <stdio.h>
#include <conio.h>
#include "\vpb\vpbapi.h"
void main() {
int handle;
VPB_EVENT e;
VPB_PLAY play;
// terminate play on any of these digits
play.term_digits = "123";
// open a channel
handle = vpb_open(1,1);
// set the play terminating configuration
vpb_play_set(handle,&play);
// wait for someone to ring this
channel
do {
vpb_get_event_sync(&e,0);
} while((e.type != VPB_RING) || (e.handle
!= handle));
// take channel off hook
vpb_sethook_async(handle, VPB_OFFHOOK);
// note: test.wav is user supplied (lengthy file)
// playing will terminate on a 1,2
or 3 digit
printf("play, dial 1,2 or 3 to terminate\n");
// play wave file on channel 1
vpb_play_file_sync(handle, "test.wav");
// place channel back on hook
vpb_sethook_sync(handle, VPB_ONHOOK);
vpb_close(handle);
}
vpb_play_set_gain
Purpose | Sets the gain of the channel for playing audio. | |||
Syntax | int WINAPI vpb_play_set_gain( | |||
int | handle, | |||
float | gain | |||
); | ||||
Inputs | handle | Handle for this channel. | ||
gain | Gain for the play channel. | |||
Outputs | none | |||
Platform | VPB4 only |
Notes
This function is used to alter the audio out levels of the channel using the hardware gain of the codec on the VPB4. The audio out levels can vary from +12dB to –12dB with a resolution of 0.1dB.
Example
#include <stdio.h>
#include "\vpb\vpbapi.h"
void main() {
int handle;
VPB_EVENT e;
float play_gain;
handle = vpb_open(1,1);
// get default gain of the channel
vpb_play_get_gain(handle,&play_gain);
printf("play channel gain = %fdB\n",play_gain);
// wait for someone to ring this
channel
do {
vpb_get_event_sync(&e,0);
} while((e.type != VPB_RING) || (e.handle
!= handle));
// take channel off hook
vpb_sethook_async(handle, VPB_OFFHOOK);
// set gain of play channel to -12dB
vpb_play_set_gain(handle,-12.0);
// get new gain of channel
vpb_play_get_gain(handle,&play_gain);
printf("play channel gain = %fdB\n",play_gain);
// play wave file on channel 1
// note: test.wav is user supplied
vpb_play_file_sync(handle, "test.wav");
// place channel back on hook
vpb_sethook_sync(handle, VPB_ONHOOK);
vpb_close(handle);
}
vpb_play_get_gain
Purpose | Gets the gain of the channel for playing audio. | |||
Syntax | int WINAPI vpb_play_get_gain( | |||
int | handle, | |||
float | *gain | |||
); | ||||
Inputs | handle | Handle for this channel. | ||
gain | Pointer to gain for the play channel. | |||
Outputs | none | |||
Platform | VPB4 only |
Notes
None.
Example
See vpb_play_set_gain().
#typedef struct {
char *term_digits; // string of digits to terminate collection
unsigned int time_out; // record terminates after time_out ms
// if set to 0 (default) no time out
} VPB_RECORD;
vpb_record_file_sync
Purpose | Utility function to record a file from a channel. Synchronous version. Function returns when recording has completed. | |||
Syntax | int WINAPI vpb_record_file_sync( | |||
int | handle, | |||
char | file_name[], | |||
unsigned short | mode | |||
); | ||||
Inputs | handle | Handle for this channel | ||
file_name | Pointer to string containing file name (including path) of file to record to. | |||
mode | Compression mode of file | |||
Outputs | none | |||
Platform | VPB4, VPB8L |
Notes
None.
Example
#include <stdio.h>
#include <conio.h>
#include <string.h>
#include "\vpb\vpbapi.h"
void main() {
int handle;
VPB_RECORD rec;
char str[VPB_MAX_STR];
VPB_EVENT e;
handle = vpb_open(1,1);
// get vpb model
vpb_get_model(str);
// set parameters to record 5s on
channel 1
rec.term_digits = "";
rec.time_out = 5000;
vpb_record_set(handle,&rec);
printf("\nDial number and then press any key");
while (!_kbhit());
printf("\n Recording......");
// if VPB4 place channel offhook
if(strcmp(str,"VPB4")==0)
vpb_sethook_async(handle,VPB_OFFHOOK);
else{
do{
vpb_get_event_ch_async(handle,&e);
}while (e.type!=VPB_VOXON);
}
// record linear file on channel
1
vpb_record_file_sync(handle, "test.wav",
VPB_LINEAR);
// hang up if VPB4
if(strcmp(str,"VPB4")==0)
vpb_sethook_sync(handle,VPB_ONHOOK);
vpb_close(handle);
}
vpb_record_file_async
Purpose | Utility function to record a file from a channel. Asynchronous version. Function returns as soon as recording has started, and places an event on the API queue when recording has finished. | |||
Syntax | int WINAPI vpb_record_file_async( | |||
int | handle, | |||
char | file_name[], | |||
unsigned short | mode, | |||
); | ||||
Inputs | Handle | Handle for this channel | ||
file_name | Pointer to string containing file name (including path) of file to record to. | |||
Mode | Compression mode of file | |||
Outputs | None | |||
Platform | VPB4, VPB8L |
Notes
The terminate event data member contains an error code if the function suffers a run time error while executing, otherwise it is set to 0.
Example
#include <stdio.h>
#include <conio.h>
#include <string.h>
#include "\vpb\vpbapi.h"
void main() {
int handle;
VPB_EVENT e;
VPB_RECORD rec;
char str[VPB_MAX_STR];
handle = vpb_open(1,1);
vpb_get_model(str);
// record 5s on channel 1
rec.term_digits = "";
rec.time_out = 10000;
vpb_record_set(handle,&rec);
printf("\nDial number then press any key");
while(!_kbhit());
// if VPB4 place channel offhook
if(strcmp(str,"VPB4")==0)
vpb_sethook_async(handle,VPB_OFFHOOK);
else{
do{
vpb_get_event_ch_async(handle,&e);
}while(e.type != VPB_VOXON);
}
printf("\nRecording....");
// record linear file on channel
1
vpb_record_file_async(handle, "test.wav", VPB_LINEAR);
do {
vpb_get_event_sync(&e, 1000);
} while(e.type != VPB_RECORDEND);
// place channel offhook if VPB4
if(strcmp(str,"VPB4")==0)
vpb_sethook_sync(handle,VPB_ONHOOK);
vpb_close(handle);
}
vpb_record_voxfile_sync
Purpose | Utility function to record a vox file from a channel. Synchronous version. Function returns when recording has completed. | |||
Syntax | int WINAPI vpb_record_voxfile_sync( | |||
int | handle, | |||
char | file_name[], | |||
unsigned short | mode | |||
); | ||||
Inputs | handle | Handle for this channel | ||
file_name | Pointer to string containing file name (including path) of file to record to. | |||
mode | Compression mode of file | |||
Outputs | none | |||
Platform | VPB4, VPB8L |
Notes
None.
Example
#include <stdio.h>
#include <stdio.h>
#include <conio.h>
#include <string.h>
#include "\vpb\vpbapi.h"
void main() {
int handle;
VPB_RECORD rec;
char str[VPB_MAX_STR];
VPB_EVENT e;
handle = vpb_open(1,1);
// get vpb model
vpb_get_model(str);
// set parameters to record 5s on
channel 1
rec.term_digits = "";
rec.time_out = 5000;
vpb_record_set(handle,&rec);
printf("\nDial number and then press any key");
while (!_kbhit());
printf("\n Recording......");
// if VPB4 place channel offhook
if(strcmp(str,"VPB4")==0)
vpb_sethook_async(handle,VPB_OFFHOOK);
else{
do{
vpb_get_event_ch_async(handle,&e);
}while (e.type!=VPB_VOXON);
}
// record linear file on channel
1
vpb_record_voxfile_sync(handle, "test.vox",
VPB_LINEAR);
// hang up if VPB4
if(strcmp(str,"VPB4")==0)
vpb_sethook_sync(handle,VPB_ONHOOK);
vpb_close(handle);
}
vpb_record_voxfile_async
Purpose | Utility function to record a vox file from a channel. Asynchronous version. Function returns as soon as recording has started, and places an event on the API queue when recording has finished. | |||
Syntax | int WINAPI vpb_record_voxfile_async( | |||
int | handle, | |||
char | file_name[], | |||
unsigned short | mode, | |||
); | ||||
Inputs | handle | Handle for this channel | ||
file_name | Pointer to string containing file name (including path) of file to record to. | |||
mode | Compression mode of file | |||
Outputs | none | |||
Platform | VPB4, VPB8L |
Notes
The terminate event data member contains an error code if the function suffers a run time error while executing, otherwise it is set to 0.
Example
#include <conio.h>
#include <string.h>
#include "\vpb\vpbapi.h"
void main() {
int handle;
VPB_EVENT e;
VPB_RECORD rec;
char str[VPB_MAX_STR];
handle = vpb_open(1,1);
vpb_get_model(str);
// record 5s on channel 1
rec.term_digits = "";
rec.time_out = 10000;
vpb_record_set(handle,&rec);
printf("\nDial number then press any key");
while(!_kbhit());
// if VPB4 place channel offhook
if(strcmp(str,"VPB4")==0)
vpb_sethook_async(handle,VPB_OFFHOOK);
else{
do{
vpb_get_event_ch_async(handle,&e);
}while(e.type != VPB_VOXON);
}
printf("\nRecording....");
// record linear file on channel
1
vpb_record_voxfile_async(handle, "test.vox", VPB_LINEAR);
do {
vpb_get_event_sync(&e, 1000);
} while(e.type != VPB_RECORDEND);
// place channel offhook if VPB4
if(strcmp(str,"VPB4")==0)
vpb_sethook_sync(handle,VPB_ONHOOK);
vpb_close(handle);
}
vpb_record_terminate
Purpose | Terminates recording on a channel. | |||
Syntax | int WINAPI vpb_record_file_terminate( | |||
int | handle | |||
); | ||||
Inputs | handle | Handle for this channel | ||
Outputs | none | |||
Platform | VPB4, VPB8L |
Notes
This function is useful to prematurely stop recording in both user defined and utility asynchronous record functions.
There will be a small time delay between calling this function and the actual end of recording. When called to terminate vpb_record_file_async(), a terminating event VPB_RECORDEND is generated. When this event has been generated, the actual recording has ended.
Example
#include <stdio.h>
#include <conio.h>
#include <string.h>
#include "\vpb\vpbapi.h"
void main() {
int handle;
VPB_EVENT e;
char str[VPB_MAX_STR];
handle = vpb_open(1,1);
vpb_get_model(str);
printf("\nDial number, then press any key");
while(!_kbhit());
// if VPB4, place channel offhook
if(strcmp(str,"VPB4")==0)
vpb_sethook_async(handle,VPB_OFFHOOK);
else{
do{
vpb_get_event_ch_async(handle,&e);
}while(e.type!=VPB_VOXON);
}
// record linear file on channel 1
printf("\nRecording.........");
vpb_record_file_async(handle, "test.wav",
VPB_LINEAR);
// wait 3 seconds and then terminate
vpb_sleep(3000);
vpb_record_terminate(handle);
// wait for terminate event
do {
vpb_get_event_sync(&e,0);
} while((e.type != VPB_RECORDEND)
&& (e.handle != handle));
// if VPB4 place channel offhook
if(strcmp(str,"VPB4")==0)
vpb_sethook_sync(handle,VPB_ONHOOK);
vpb_close(handle);
}
vpb_record_set_gain
Purpose | Sets the gain of the channel for recording audio. | |||
Syntax | int WINAPI vpb_record_set_gain( | |||
int | handle, | |||
float | gain | |||
); | ||||
Inputs | handle | Handle for this channel. | ||
gain | Gain for the record channel. | |||
Outputs | none | |||
Platform | VPB4 only |
Notes
This function is used to alter the audio in levels of the channel using the hardware gain of the codec on the VPB4. The audio in levels can vary from +12dB to –12dB with a resolution of 0.1dB.
Example
#include <stdio.h>
#include "\vpb\vpbapi.h"
void main() {
int handle;
VPB_EVENT e;
float rec_gain;
handle = vpb_open(1,1);
// obtain the default gain of the
channel
vpb_record_get_gain(handle,&rec_gain);
printf("default recording channel
gain = %fdB\n",rec_gain);
// place channel offhook
vpb_sethook_async(handle,VPB_OFFHOOK);
// set recording gain to +12 dB
vpb_record_set_gain(handle,12.0);
// obtain the new gain of the channel
vpb_record_get_gain(handle,&rec_gain);
printf("new recording channel gain = %fdB\n",rec_gain);
printf("Recording....\n");
// record linear file on channel
1
vpb_record_file_async(handle, "test.wav",
VPB_LINEAR);
// wait 3 seconds and then terminate
vpb_sleep(3000);
vpb_record_terminate(handle);
// wait for terminate event
do {
vpb_get_event_sync(&e,0);
} while((e.type != VPB_RECORDEND)
&& (e.handle != handle));
// place channel offhook
vpb_sethook_sync(handle,VPB_ONHOOK);
vpb_close(handle);
}
vpb_record_get_gain
Purpose | Gets the gain of the channel for recording audio. | |||
Syntax | int WINAPI vpb_record_get_gain( | |||
int | handle, | |||
float | *gain | |||
); | ||||
Inputs | handle | Handle for this channel. | ||
gain | Pointer to gain for the record channel. | |||
Outputs | none | |||
Platform | VPB4 only |
Notes
None.
Example
See vpb_record_set_gain().
vpb_record_buf_start
Purpose | Sets up a channel ready for recording in user defined record routines. | |||
Syntax | int WINAPI vpb_record_buf_start( | |||
int | handle, | |||
unsigned short | mode | |||
); | ||||
Inputs | handle | Handle for this channel. | ||
mode | Compression mode of file. | |||
Outputs | none | |||
Platform | VPB4, VPB8L |
Notes
Used in conjunction with vpb_record_buf_sync()and vpb_record_buf_finish().
Example
See example vpb_wave_write().
vpb_record_buf_sync
Purpose | Records a buffer of speech samples from a channel that has been initialised with vpb_record_buf_start(). | |||
Syntax | int WINAPI vpb_record_buf_sync( | |||
int | handle, | |||
char | *buf, | |||
unsigned short | length | |||
); | ||||
Inputs | handle | Handle for this channel. | ||
length | Number of bytes to record from channel. | |||
Outputs | buf | Pointer to buffer of samples to record from channel. | ||
Platform | VPB4, VPB8L |
Notes
Used in conjunction with vpb_record_buf_start()and vpb_record_buf_finish().
This function is thread safe, it can be called from a thread separate from the main process thread to implement asynchronous functions.
Example
See example vpb_wave_write().
vpb_record_buf_finish
Purpose | Completes recording in user defined record routines. | |||
Syntax | int WINAPI vpb_record_buf_finish( | |||
int | handle | |||
); | ||||
Inputs | handle | Handle for this channel. | ||
Outputs | none | |||
Platform | VPB4, VPB8L |
Notes
Used in conjunction with vpb_record_buf_start()and vpb_record_buf_sync().
Example
See example vpb_wave_write().
vpb_record_set
Purpose | Sets the terminating condition for recording on a channel. | |||
Syntax | int WINAPI vpb_record_set( | |||
int | handle, | |||
VPB_RECORD | *vpb_record | |||
); | ||||
Inputs | handle | Handle for this channel | ||
vpb_record | Pointer to structure containing terminating conditions for the record functions | |||
Outputs | none | |||
Platform | VPB4, VPB8L |
Notes
This function is used in conjunction with the record routines
to allow DTMF digits (from the channel) to terminate the record routines.
Example
#include <stdio.h>
#include <conio.h>
#include <string.h>
#include "\vpb\vpbapi.h"
void main() {
int handle;
VPB_EVENT e;
VPB_RECORD record;
char str[VPB_MAX_STR];
// terminate play on any of these digits
record.term_digits = "4";
record.time_out = 0;
vpb_get_model(str);
// open a channel
handle = vpb_open(1,1);
// set the play terminating configuration
vpb_record_set(handle,&record);
// if VPB4, wait for someone to ring this channel
if(strcmp(str,"VPB4")==0){
do {
vpb_get_event_async(&e);
} while((e.type != VPB_RING) || (e.handle != handle));
// take channel off hook
vpb_sethook_async(handle, VPB_OFFHOOK);
}
else{
do {
vpb_get_event_ch_async(handle,&e);
} while(e.type != VPB_VOXON);
}
// recording will terminate on a
1,2 or 3 digit
printf("record, dial 4 to terminate\n");
// record wave file on channel 1
vpb_record_file_async(handle, "test.wav",VPB_LINEAR);
// wait for termination
do {
vpb_get_event_ch_async(handle,&e);
}while(e.type!=VPB_RECORDEND);
printf("\nrecording ended....");
if(strcmp(str,"VPB4")==0){
printf("\nplace handset onhook");
// place channel back on hook
vpb_sethook_async(handle, VPB_ONHOOK);
}
vpb_close(handle);
}
vpb_dial_async
Purpose | Plays DTMF and user programmable tones to a channel. Asynchronous function, places VPB_DIALEND event on queue when last tone in string has been played. | |||
Syntax | int WINAPI vpb_dial_async( | |||
int | handle, | |||
char | *dialstr | |||
); | ||||
Inputs | handle | Handle for this channel. | ||
dialstr | Pointer to string of chars that correspond to tones to dial. | |||
Outputs | none | |||
Platform | VPB4 only |
Notes
See discussion on tone generation.
Each character in string represents a single tone to play.
The string can be a mix of user defined and standard DTMF tones.
A comma "," character produces a pause.
An ampersand "&" produces a hook flash.
Example
#include <stdio.h>
#include <conio.h>
#include "\vpb\vpbapi.h"
void main() {
int handle;
VPB_EVENT e;
handle = vpb_open(1,1);
// take off hook, pause, and dial
a number
vpb_sethook_async(handle, VPB_OFFHOOK);
vpb_dial_async(handle, ",12");
// wait for terminate event
do {
vpb_get_event_sync(&e,0);
} while((e.type != VPB_DIALEND) &&
(e.handle != handle));
// wait for key to finish
printf("Press any key to finish");
while(!kbhit());
// place back on hook and exit
vpb_sethook_sync(handle, VPB_ONHOOK);
vpb_close(handle);
}
vpb_dial_sync
Purpose | Plays DTMF and user programmable tones to a channel. Synchronous version. | |||
Syntax | int WINAPI vpb_dial_sync( | |||
int | handle, | |||
char | *dialstr | |||
); | ||||
Inputs | handle | Handle for this channel. | ||
dialstr | Pointer to string of chars that correspond to tones to dial. | |||
Outputs | none | |||
Platform | VPB4 only |
Notes
See discussion on tone generation.
Each character in string represents a single tone to play.
The string can be a mix of user defined and standard DTMF tones.
A comma "," character produces a pause.
An ampersand "&" produces a hook flash.
Example
#include <stdio.h>
#include <conio.h>
#include "\vpb\vpbapi.h"
void main() {
int handle;
handle = vpb_open(1,1);
// take off hook, pause, and dial
a number
vpb_sethook_async(handle, VPB_OFFHOOK);
vpb_dial_sync(handle, ",12");
// wait for key to finish
printf("Press any key to finish");
while(!kbhit());
// place back on hook and exit
vpb_sethook_sync(handle, VPB_ONHOOK);
vpb_close(handle);
}
vpb_settone
Purpose | Defines a user programmable tone, or redefines an existing tone. | |||
Syntax | int WINAPI vpb_settone( | |||
char | ident, | |||
VPB_TONE | *vpb_tone | |||
); | ||||
Inputs | ident | Single character identifier for this tone. | ||
vpb_tone | Pointer to structure containing new tone parameters. | |||
Outputs | none | |||
Platform | VPB4 only |
Notes
See discussion on tone generation.
If this tone is a new user defined tone, use a different identifier than any existing user defined or standard DTMF tone.
The new tone becomes available for use on any channel after calling this function.
If a frequency component is not required, set its level to a very low level (for example –100dB).
Example
#include <stdio.h>
#include <conio.h>
#include "\vpb\vpbapi.h"
// single frequency tone at 1000
Hz, 1s on, 0.5s off
VPB_TONE new_tone = {
1000, // frequency of first tone (1000Hz)
0, // frequency of second tone (not used)
0, // frequency of third tone (not used)
-12, // first tone level (12dB beneath overload)
-100, // second tone level (not used)
-100, // third tone level (not used)
1000, // on time ms
500 // off time ms
};
void main() {
int handle;
handle = vpb_open(1,1);
vpb_settone('Z', &new_tone);
// take off hook, play new tone
vpb_sethook_async(handle, VPB_OFFHOOK);
// wait for key to play new tone
printf("Press any key to play the new tone\n");
while(!kbhit());
getch();
vpb_dial_sync(handle, "Z");
// wait for key to play new tone
combined with standard DTMFs
printf("Press any key to play the new tone combined with standard DTMFs\n");
while(!kbhit());
getch();
vpb_dial_sync(handle, "12Z3");
// wait for key to finish
printf("Press any key to finish\n");
while(!kbhit());
// place back on hook and exit
vpb_sethook_sync(handle, VPB_ONHOOK);
vpb_close(handle);
}
vpb_gettone
Purpose | |||||
Syntax | int WINAPI vpb_gettone( | ||||
char | ident, | ||||
VPB_TONE | *vpb_tone | ||||
); | |||||
Inputs | ident | Single character identifier for the tone. | |||
Outputs | vpb_tone | Pointer to structure that will be filled with the tone parameters. | |||
Platform | VPB4 only |
Notes
See discussion on tone generation.
If the identifier is does not correspond to an existing tone, an error is generated.
Example
#include <stdio.h>
#include <conio.h>
#include "\vpb\vpbapi.h"
void main() {
int handle;
VPB_TONE tone;
handle = vpb_open(1,1);
// make a new tone based on DTMF 0
// new tone has half of the level
of the old tone
vpb_gettone('0', &tone);
tone.level1 -= 6;
tone.level2 -= 6;
vpb_settone('Z', &tone);
// take off hook, play new tone and
old tone a few times
vpb_sethook_async(handle, VPB_OFFHOOK);
vpb_dial_sync(handle, "Z0Z0Z0");
// wait for key to finish
printf("Press any key to finish");
while(!kbhit());
// place line back on hook
vpb_sethook_sync(handle, VPB_ONHOOK);
vpb_close(handle);
}
vpb_settonedet
Purpose | Defines a user programmable tone detector, or redefines an existing tone detector. | |||
Syntax | int WINAPI vpb_settonedet( | |||
int | handle, | |||
VPB_DETECT | *d | |||
); | ||||
Inputs | handle | Handle for this channel. | ||
d | Pointer to structure containing tone detector parameters. | |||
Outputs | none | |||
Platform | VPB4 only |
Notes
See discussion on programmable tone detection.
If this tone is a new user defined tone, use a different identifier than any existing user defined or pre-defined tone detector.
The new tone becomes available for use on any channel after calling this function.
Example
#include <stdio.h>
#include <conio.h>
#include "\vpb\vpbapi.h"
// tone detector parameter for DTMF1
#define DTMF_1 10
static VPB_DETECT toned_dtmf1 = {
2, // number of states
DTMF_1, // tone id
2, // number of tones
697, // f1: centre frequency
100, // bw1: bandwidth
1209, // f2: centre frequency
100, // bw2: bandwidth
-20, // A1: -20dBm0
-20, // A2: -20dBm0
10, // twist: 10dB
10, // SNR: 10dB
40 // glitch duration 40ms
VPB_RISING, // state 0
0,
0,
0,
VPB_TIMER, // state 1
100,
0,
0
};
void main() {
int handle;
char s[VPB_MAX_STR];
VPB_EVENT e;
handle = vpb_open(1,1);
vpb_settonedet(handle, &toned_dtmf1);
// take off hook, wait for tone
printf("Dial channel 1, then press a key on PC\n");
while(!kbhit());
getch();
vpb_sethook_sync(handle, VPB_OFFHOOK);
printf("Press '1' on phone\n");
printf("Press any key on PC to hangup\n");
// the programmable tone must satisfy the 100ms
// tfire parameter for the detector to fire.
while(!kbhit()) {
if (vpb_get_event_async(&e) == VPB_OK) {
vpb_translate_event(&e, s);
printf(s);
}
}
// hangup and wait for key press
vpb_sethook_sync(handle, VPB_ONHOOK);
getch();
printf("Press any key on PC to finish");
while(!kbhit());
vpb_close(handle);
}
vpb_gettonedet
Purpose | Obtains the parameters of a programmable tone detector. | |||
Syntax | int WINAPI vpb_gettonedet( | |||
int | handle, | |||
int | id, | |||
VPB_DETECT | *d | |||
); | ||||
Inputs | handle | Handle for this channel. | ||
id | Identifier of tone detector. | |||
Outputs | d | Pointer to structure that is filled with tone detector parameters. | ||
Platform | VPB4 only |
Notes
This function is useful for modifying the parameters of a tone detector or to modify existing tone parameters.
See discussion on programmable tone detection.
Example
#include <stdio.h>
#include <conio.h>
#include "\vpb\vpbapi.h"
static VPB_DETECT toned;
void main() {
int handle;
char s[VPB_MAX_STR];
handle = vpb_open(1,1);
vpb_gettonedet(handle, VPB_DIAL, &toned);
printf("Tone Detector parameters retrieved!\n");
printf("%d cadence states - how interesting!\n",toned.nstates);
printf("Press any key to finish\n");
while(!kbhit());
vpb_close(handle);
}
vpb_debug_tonedet
Purpose | Causes debug information to be output to a text file for a single tone detector. | |||
Syntax | int WINAPI vpb_debug_tonedet( | |||
int | handle, | |||
int | id, | |||
char | file_name[], | |||
int | sec | |||
); | ||||
Inputs | handle | Handle for this channel. | ||
id | Identifier of tone detector to debug. | |||
file_name | Text file where results are saved. | |||
sec | Number of seconds to log data for. | |||
Outputs | none | |||
Platform | VPB4 only |
Notes
See discussion on programmable tone detection.
Logging starts as soon as this function is called.
This function logs the tone detector signal detection
and cadence state information for the specified time. The format is such
that every line of the text file represents 20 ms of tone detector processing.
The columns of each line are defined below:
Parameter | Description |
Ch | channel |
Id | tone id |
t1 | true (equal to 1) if the first frequency component is above minlevel1 threshold. |
t2 | true (equal to 1) if the second frequency component is above minlevel2 threshold. |
Tw | true if the twist condition is met (dual frequency tones only) |
Snr | true if the snr condition is met |
T | logical AND of above conditions indicating signal is present if true. The state of this variable is passed to the cadence detection algorithm. |
Ton | amount of time (in ms) spent with signal ON. |
Toff | amount of time (in ms) spent with signal OFF. |
R | true if rising edge present |
F | true if falling edge present |
S | current cadence state |
Ns | total number of cadence states, when this number equals s above, an event is generated |
Example
#include <stdio.h>
#include <conio.h>
#include "\vpb\vpbapi.h"
void main() {
int handle;
handle = vpb_open(1,1);
// start logging tone detector data
for dial tone
vpb_debug_tonedet(handle, VPB_DIAL, "log.txt", 3);
vpb_sethook_async(handle, VPB_OFFHOOK);
printf("Press any key to hangup\n");
while(!kbhit());
getch();
vpb_sethook_async(handle, VPB_ONHOOK);
printf("Press any key to finish\n");
while(!kbhit());
vpb_close(handle);
}
vpb_tonedet_make_default
Purpose | Stores a programmable tone to the registry, where it becomes the a default tone (for all channels) next time the VPBAPI is booted. | |||
Syntax | int WINAPI vpb_tonedet_make_default( | |||
VPB_DETECT | *d | |||
); | ||||
Inputs | d | Pointer to structure that is filled with tone detector parameters. | ||
Outputs | None | |||
Platform | VPB4 only |
Notes
See discussion on programmable tone detection.
Example
// This program set the current dial tone detector
// as the default dial tone detector, in other words
// it does nothing!
#include <stdio.h>
#include "\vpb\vpbapi.h"
void main() {
int h;
VPB_DETECT det;
vpb_seterrormode(VPB_DEVELOPMENT);
h = vpb_open(1,1);
vpb_gettonedet(h, VPB_DIAL, &det);
vpb_tonedet_make_default(&det);
vpb_close(h);
}