Function Reference Part 2

 

 
 
 
 

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);

}