vpb_timer_open
Purpose | Creates a timer. Once started, a VPB_TIMER event is placed by a timer in the event queue after its period has expired. | |||
Syntax | int WINAPI vpb_timer_open( | |||
void | **timer | |||
int | handle, | |||
int | id, | |||
unsigned long | period | |||
); | ||||
Inputs | handle | Handle for this channel. | ||
id | Identifier of timer, this value is placed in the data element of the VPB_EVENT structure when a timer event is posted. | |||
period | Period of timer in ms. | |||
Outputs | timer | Pointer to pointer to state variables for this timer. | ||
Platform | VPB4, VPB8L |
Notes
The id parameter can be used to uniquely identify a timer from other timers on the same channel.
Example
#include <stdio.h>
#include <conio.h>
#include "\vpb\vpbapi.h"
void main() {
int handle;
void *timer;
VPB_EVENT e;
handle = vpb_open(1,1);
// open and close a timer with id
0, 1000 ms period
vpb_timer_open(&timer, handle, 0, 1000);
// start timer
vpb_timer_start(timer);
printf("Timer started, waiting, .....\n");
// wait for a VPB_TIMER event
do{
vpb_get_event_sync(&e,0);
}while((e.handle != handle) || (e.type
!= VPB_TIMEREXP));
printf("Timer expired!\n");
printf("Press any key to finish!");
while(!kbhit());
// shut down
vpb_timer_close(timer);
vpb_close(handle);
}
vpb_timer_close
Purpose | Closes a timer. | |||
Syntax | int WINAPI vpb_timer_close( | |||
void | *timer | |||
); | ||||
Inputs | timer | Pointer to state variables for this timer. | ||
Outputs | none | |||
Platform | VPB4, VPB8L |
Notes
None.
Example
See vpb_timer_open().
vpb_timer_start
Purpose | Starts a timer. | |||
Syntax | int WINAPI vpb_timer_start( | |||
void | *timer | |||
); | ||||
Inputs | timer | Pointer to state variables for this timer. | ||
Outputs | none | |||
Platform | VPB4, VPB8L |
Notes
Timer must have been opened by vpb_timer_open()before calling this function.
After this function is called, a VPB_TIMER event is posted on the event queue after the timer?s period expires.
If the timer is already running an error occurs.
Example
#include <conio.h>
#include <stdio.h>
#include "\vpb\vpbapi.h"
#define TIMER_ID 0
void main() {
int handle;
void *timer;
VPB_EVENT e;
handle = vpb_open(1,1);
// open and start a timer with 1000
ms period
vpb_timer_open(&timer, handle, TIMER_ID, 1000);
vpb_timer_start(timer);
printf("Timer started, waiting, .....\n");
// wait for timer event
do {
vpb_get_event_sync(&e,0);
} while((e.type != VPB_TIMEREXP)
|| (e.data != TIMER_ID));
printf("Timer expired!\n");
printf("Press any key to finish!");
while(!kbhit());
// shut down
vpb_timer_close(timer);
vpb_close(handle);
}
vpb_timer_stop
Purpose | Stops a timer without posting an event. | |||
Syntax | int WINAPI vpb_timer_stop( | |||
void | *timer | |||
); | ||||
Inputs | timer | Pointer to state variables for this timer. | ||
Outputs | none | |||
Platform | VPB4, VPB8L |
Notes
Timer must have been opened by vpb_timer_open()before calling this function.
Example
#include <stdio.h>
#include "\vpb\vpbapi.h"
#define TIMER_ID 0
void main() {
int handle;
void *timer;
handle = vpb_open(1,1);
// open and start a timer with 1000
ms period
vpb_timer_open(&timer, handle, TIMER_ID, 1000);
vpb_timer_start(timer);
// stop timer prematurely
vpb_timer_stop(timer);
printf("Timer stopped!\n");
// shut down
vpb_timer_close(timer);
vpb_close(handle);
}
vpb_timer_restart
Purpose | Restarts a currently running timer. The timer "clock" restarts from 0. | |||
Syntax | int WINAPI vpb_timer_restart( | |||
void | *timer | |||
); | ||||
Inputs | timer | Pointer to state variables for this timer. | ||
Outputs | none | |||
Platform | VPB4, VPB8L |
Notes
Timer must have been opened by vpb_timer_open()before calling this function.
If the timer has stopped, this function performs the same function as vpb_timer_start().
Example
#include <conio.h>
#include <stdio.h>
#include "\vpb\vpbapi.h"
#define TIMER_ID 0
void main() {
int handle;
void *timer;
VPB_EVENT e;
handle = vpb_open(1,1);
// open and start a timer with 1000
ms period
vpb_timer_open(&timer, handle, TIMER_ID, 1000);
vpb_timer_start(timer);
printf("Timer started!\n");
// wait a little while
vpb_sleep(500);
// restart the timer
vpb_timer_restart(timer);
printf("Timer restarted!\n");
// wait for timer event
do {
vpb_get_event_sync(&e,0);
} while((e.type != VPB_TIMEREXP)
|| (e.data != TIMER_ID));
printf("Timer expired!\n");
printf("Press any key to finish");
while(!kbhit());
// shut down
vpb_timer_close(timer);
vpb_close(handle);
}
vpb_timer_get_unique_timer_id
Purpose | Obtains a unique timer ID. | |||
Syntax | int WINAPI vpb_timer_get_unique_timer_id( | |||
); | ||||
Inputs | none | |||
Outputs | returns | A unique timer id. | ||
Platform | VPB4, VPB8L |
Notes
This function is useful when multiple timers are required for a given channel, this function can be used to automatically allocate a unique ID to each of them.
Example
void main() {
int handle;
void *timer;
int id;
handle = vpb_open(1,1);
// obtain a TIMER ID
id = vpb_timer_get_unique_timer_id();
printf("TIMER ID = %d\n",id);
// open a timer with 1000 ms period
vpb_timer_open(&timer, handle, id, 1000);
// close timer
vpb_timer_close(timer);
vpb_close(handle);
}
vpb_timer_change_period
Purpose | Changes the time out period of an already open timer. | |||
Syntax | int WINAPI vpb_timer_change_period( | |||
void | *timer | |||
unsigned long | newperiod | |||
); | ||||
Inputs | timer | Pointer to timer state variables. | ||
newperiod | New timer period in ms. | |||
Outputs | none | |||
Platform | VPB4, VPB8L |
Notes
The new period becomes valid immediately after calling this function.
This function affects the timer period in both the stopped and running states.
Example
#include <stdio.h>
#include "\vpb\vpbapi.h"
#include <stdio.h>
#include "\vpb\vpbapi.h"
void main() {
int handle;
void *timer;
VPB_EVENT e;
handle = vpb_open(1,1);
// open a timer with 2000 ms period
vpb_timer_open(&timer, handle, 0, 2000);
// start timer
vpb_timer_start(timer);
printf("start timer....\n");
// change to 3000 ms period
vpb_timer_change_period(timer, 3000);
printf("change timer period\n");
do{
vpb_get_event_sync(&e,0);
}while((e.type!=VPB_TIMEREXP) || (e.data!=0));
printf("timer stopped\n");
// shut down
vpb_timer_close(timer);
vpb_close(handle);
}
vpb_flush_digits
Purpose | Clears the user digit buffer. | |||
Syntax | int WINAPI vpb_flush_digits( | |||
int | handle | |||
); | ||||
Inputs | handle | Handle for this channel. | ||
Outputs | none | |||
Platform | VPB4 |
Notes
This function should be used before vpb_get_digits_sync()and vpb_get_digits_async()to clear the user digit buffer of any digits that may have resulted from previous actions on the channel.
Example
#include <stdio.h>
#include <string.h>
#include "\vpb\vpbapi.h"
#include <conio.h>
static char *term_str[] = {
"Terminating Digit",
"Maximum Digits",
"Time Out",
"Inter-Digit Time Out",
};
void main(){
int handle;
VPB_DIGITS vd;
char buf[VPB_MAX_STR];
int ret;
char str[VPB_MAX_STR];
vd.term_digits = "#*";
vd.max_digits = 3;
vd.digit_time_out = 20000;
vd.inter_digit_time_out = 10000;
// open channel 1
handle = vpb_open(1,1);
vpb_get_model(str);
if(strcmp(str,"VPB4")==0)
vpb_sethook_async(handle,VPB_OFFHOOK);
printf("press any key, then press any digit\n");
while(!kbhit());
getch();
// flush the user digit buffer
vpb_flush_digits(handle);
ret = vpb_get_digits_sync(handle, &vd, buf);
// The terminating code will be inter-digit time out
// and the digit buffer empty
printf("ret code: %s , digit str: '%s'\n",term_str[ret],buf);
printf("press no digits\n");
vpb_flush_digits(handle);
ret = vpb_get_digits_sync(handle,
&vd, buf);
printf("ret code: %s , digit str:
'%s'\n",term_str[ret],buf);
if(strcmp(str,"VPB4")==0)
vpb_sethook_sync(handle,VPB_ONHOOK);
// close channel
vpb_close(handle);
}
vpb_get_digits_sync
Purpose | |||||
Syntax | int WINAPI vpb_get_digits_sync( | ||||
int | handle, | ||||
VPB_DIGITSIDH_VPB_DIGITS | *digits | ||||
char | *digbuf | ||||
); | |||||
Inputs | handle | Handle for this channel. | |||
digits | Pointer to terminating conditions for the user digit buffer. | ||||
Outputs | digbuf | Pointer to local buffer where digits are collected. | |||
returns | Appropriate termination code. | ||||
Platform | VPB4 only |
Notes
Make sure that thevpb_flush_digits()is called before this function to clear the user digit buffer.
Ensure that the local buffer where the digits are collected remains in scope for the duration of the function.
Example
#include <stdio.h>
#include <conio.h>
#include <string.h>
#include "\vpb\vpbapi.h"
// translation of VPB_DIGIT termination
return codes
static char *term_str[] = {
"Terminating Digit",
"Maximum Digits",
"Time Out",
"Inter-Digit Time Out",
};
void main(){
int handle;
VPB_DIGITS vd;
char buf[VPB_MAX_STR];
char str[VPB_MAX_STR];
int ret;
vd.term_digits = "#*";
vd.max_digits = 3;
vd.digit_time_out = 20000;
vd.inter_digit_time_out = 10000;
vpb_get_model(str);
// open channel 1
handle = vpb_open(1,1);
if(strcmp(str,"VBP4")==0)
vpb_sethook_async(handle,VPB_OFFHOOK);
printf("press some digits, then press any key\n");
while(!kbhit());
getch();
// obtain digits from channel
ret = vpb_get_digits_sync(handle, &vd, buf);
printf("ret code: %s , digit str:
'%s'\n",term_str[ret],buf);
// close channel
if(strcmp(str,"VBP4")==0)
vpb_sethook_sync(handle,VPB_ONHOOK);
vpb_close(handle);
}
vpb_get_digits_async
Purpose | Collects digits from the channel. Asynchronous version. | |||
Syntax | int WINAPI vpb_get_digits_async( | |||
int | handle, | |||
VPB_DIGITSIDH_VPB_DIGITS | *digits | |||
char | *digbuf | |||
); | ||||
Inputs | handle | Handle for this channel. | ||
digits | Pointer to terminating conditions for the user digit buffer. | |||
Outputs | digbuf | Pointer to local buffer where digits are collected. | ||
Platform | VPB4 only |
Notes
Make sure that the vpb_flush_digits()is called before this function to clear the user digit buffer.
Ensure that the local buffer where the digits are collected remains in scope for the duration of the function.
The function posts a completion event when the digits have been collected, with the terminating condition passed to the data field of the VPB_EVENTstructure.
If this function is called while already collecting digits (by a previous call to this function), the user digit buffer is reset, discarding digits collected so far.
Example
#include <stdio.h>
#include <conio.h>
#include <string.h>
#include "\vpb\vpbapi.h"
// translation of VPB_DIGIT termination
return codes
static char *term_str[] = {
"Terminating Digit",
"Maximum Digits",
"Time Out",
"Inter-Digit Time Out",
};
void main(){
int handle;
VPB_DIGITS vd;
VPB_EVENT e;
char buf[VPB_MAX_STR];
char str[VPB_MAX_STR];
vd.term_digits = "#*";
vd.max_digits = 3;
vd.digit_time_out = 20000;
vd.inter_digit_time_out = 10000;
// open channel 1
handle = vpb_open(1,1);
vpb_get_model(str);
if(strcmp(str,"VPB4")==0)
vpb_sethook_async(handle,VPB_OFFHOOK);
printf("press some digits, then press any key\n");
while(!kbhit());
getch();
// obtain digits collected from the
channel
vpb_get_digits_async(handle, &vd, buf);
do{
vpb_get_event_sync(&e,0);
}while((e.handle!=handle) || (e.type != VPB_DIGIT));
printf("term. code: %s , digit str:
'%s'\n",term_str[e.data],buf);
// close channel
if(strcmp(str,"VPB4")==0)
vpb_sethook_sync(handle,VPB_ONHOOK);
vpb_close(handle);
}
vpb_wave_open_write
Purpose | Opens a wave file that will be written to. | |||
Syntax | int WINAPI vpb_wave_open_write( | |||
void | **ppv, | |||
char | file_name[], | |||
int | mode | |||
); | ||||
Inputs | ppv | Pointer to pointer to storage required by the wave function. | ||
file_name | Pointer to string containing name of wave file (including path). | |||
mode | Compression mode. | |||
Outputs | none | |||
Platform | VPB4, VPB8L |
Notes
This function does not require any VPB hardware to run. If using this function in conjunction with the user defined record functions, ensure that the compression modes are the same.
Example
See vpb_wave_write().
vpb_wave_write
Purpose | Writes a block of samples to a wave file. | |||
Syntax | int WINAPI vpb_wave_write( | |||
void | *wv, | |||
char | buf[], | |||
long | n | |||
); | ||||
Inputs | wv | Pointer to wave file. | ||
buf | Pointer to source buffer. | |||
n | Number of bytes to write. | |||
Outputs | returns | Number of bytes written. | ||
Platform | VPB4, VPB8L |
Notes
This function does not require any VPB hardware to run. The vpb_wave_open_write()is required to be called before this function.
Example
#include <conio.h>
#include <stdio.h>
#include <string.h>
#include "\vpb\vpbapi.h"
#define N 8000 // length of buffer
(1 second)
void main() {
int handle;
char buf[N];
void *ws;
char str[VPB_MAX_STR];
handle = vpb_open(1,1);
vpb_get_model(str);
// prompt user to dial
printf("Dial the extension connected to channel 1...\n");
printf("Press any key to continue....\n");
while(!kbhit());
getch();
// open wave file to write
vpb_wave_open_write(&ws,"test2.wav",VPB_ALAW);
// save handle and wave file state
variables
if(strcmp(str,"VPB4")==0){
// take channel 1 off hook
vpb_sethook_async(handle, VPB_OFFHOOK);
}
// initialise user defined record routine
vpb_record_buf_start(handle,VPB_ALAW);
printf("\nrecording........press any key to stop");
while(!kbhit()){
// record buffer using user defined
play routine
vpb_record_buf_sync(handle, buf, N);
// save to wave file
vpb_wave_write(ws,buf,N);
}
// close user defined play routine
vpb_record_buf_finish(handle);
// close wave file
vpb_wave_close_write(ws);
// prompt user to hangup
if(strcmp(str,"VPB4")==0){
printf("\nPress any key to hangup....\n");
while(!kbhit());
getch();
// hangup
vpb_sethook_sync(handle, VPB_ONHOOK);
}
vpb_close(handle);
}
vpb_wave_close_write
Purpose | Closes the wave file that has been written to. | |||
Syntax | int WINAPI vpb_wave_close_write( | |||
void | *wv | |||
); | ||||
Inputs | wv | Pointer to wave file. | ||
Outputs | none | |||
Platform | VPB4, VPB8L |
Notes
This function does not require any VPB hardware to run. The function releases any memory that has been used by the vpb_wave_open_write().
Example
See vpb_wave_write().
vpb_wave_open_read
Purpose | Opens a wave file that will be read from. | |||
Syntax | int WINAPI vpb_wave_open_read( | |||
void | **ppv, | |||
char | file_name[] | |||
); | ||||
Inputs | ppv | Pointer to pointer to storage required by the wave function. | ||
file_name | Pointer to string containing name of wave file (including path). | |||
Outputs | none | |||
Platform | VPB4, VPB8L |
Notes
This function does not require any VPB hardware to run.
Example
See vpb_wave_read().
vpb_wave_read
Purpose | Reads a block of samples from a wave file. | |||
Syntax | int WINAPI vpb_wave_read( | |||
void | *wv, | |||
char | buf[], | |||
long | N | |||
); | ||||
Inputs | wv | Pointer to wave file. | ||
buf | Pointer to destination buffer. | |||
n | Number of bytes to read. | |||
Outputs | returns | Number of bytes read. | ||
Platform | VPB4, VPB8L |
Notes
This function does not require any VPB hardware to run.
The vpb_wave_open_read()is required to be called before this function.
Example
#include <conio.h>
#include <stdio.h>
#include "\vpb\vpbapi.h"
#define N 8000 // length of buffer
(1 second)
void main() {
int handle;
char buf[N];
unsigned short n;
void *ws;
unsigned short mode;
handle = vpb_open(1,1);
// prompt user to dial
printf("Dial the extension connected to channel 1...\n");
printf("Press any key to continue....\n");
while(!kbhit());
getch();
// open wave file to read
// Note: test.wav is a user supplied
file
vpb_wave_open_read(&ws,"test.wav");
// obtain the compression mode of
the wave file
vpb_wave_get_mode(ws,&mode);
// take channel 1 off hook
vpb_sethook_async(handle, VPB_OFFHOOK);
// initialise user defined play routine
vpb_play_buf_start(handle,mode);
// continuously play wave file until
keyboard hit
printf("Play wave file continuously
until key pressed");
while(!kbhit()){
if((n=vpb_wave_read(ws,buf,N)) == NULL){
vpb_wave_seek(ws,0);
n=vpb_wave_read(ws,buf,N);
}
// play buffer using user defined
play routine
vpb_play_buf_sync(handle, buf, n);
}
// close user defined play routine
vpb_play_buf_finish(handle);
// close wave file
vpb_wave_close_read(ws);
// prompt user to hangup
printf("\nPress any key to hangup....\n");
while(!kbhit());
getch();
// hangup
vpb_sethook_sync(handle, VPB_ONHOOK);
vpb_close(handle);
}
vpb_wave_close_read
Purpose | Closes the wave file that has been read from. | |||
Syntax | int WINAPI vpb_wave_close_read( | |||
Void | *wv | |||
); | ||||
Inputs | wv | Pointer to wave file. | ||
Outputs | none | |||
Platform | VPB4, VPB8L |
Notes
This function does not require any VPB hardware to run. The function releases any memory that has been used by the vpb_wave_open_read().
Example
See vpb_wave_read().
vpb_wave_set_sample_rate
Purpose | Changes the sample rate parameter of a wave file. | |||
Syntax | int WINAPI vpb_wave_set_sample_rate( | |||
void | *wv, | |||
unsigned int | rate | |||
); | ||||
Inputs | wv | Pointer to wave file. | ||
rate | Sampling rate of the wave file. | |||
Outputs | none | |||
Platform | VPB8L only |
Notes
This function is used on the VPB8L platform (where it has a 6 or 8 ksamples/s sampling rate option). It sets the sampling rate of the wave file when using the user-defined record routines.
Example
// This VPB8L test program demonstrates sampling of 24 kbit/s
// APDCM, which is sampled at 6 kHz. The ADPCM is decoded and
// saved as 6 kHz linear data to
a wave file.
#include <assert.h>
#include <stdlib.h>
#include <stdio.h>
#include <conio.h>
#include "\vpb\vpbapi.h"
#define N 160
void main(void)
{
int h;
int i;
char adpcm[N/2];
void *w, *adpcm_states;
unsigned short nlinear;
short linear[N];
h = vpb_open(1, 1);
vpb_wave_open_write(&w, "adpcm24.wav",VPB_LINEAR);
vpb_wave_set_sample_rate(w, 6000);
vpb_adpcm_open(&adpcm_states);
// record until key pressed
vpb_record_buf_start(h,VPB_OKIADPCM24);
i= 0;
while(!kbhit()) {
vpb_record_buf_sync(h, adpcm, N/2);
vpb_adpcm_decode(adpcm_states, linear, &nlinear, adpcm, N/2);
vpb_wave_write(w, (char*)linear, nlinear*sizeof(short));
printf("frames: %d\r",i++);
}
vpb_adpcm_close(adpcm_states);
vpb_wave_close_write(w);
vpb_record_buf_finish(h);
vpb_close(h);
}
vpb_wave_seek
Purpose | Moves the wave pointer to a specified location in samples with respect to the beginning of the wave file. | |||
Syntax | int WINAPI vpb_wave_seek( | |||
void | *wv, | |||
long | offset | |||
); | ||||
Inputs | wv | Pointer to wave file. | ||
offset | Number of bytes from beginning of wave file. | |||
Outputs | none | |||
Platform | VPB4, VPB8L |
Notes
None.
Example
See vpb_wave_read().
vpb_wave_get_mode
Purpose | Determines the compression mode of the wave file. | |||
Syntax | int WINAPI vpb_wave_get_mode( | |||
void | *wv | |||
unsigned short | *mode | |||
); | ||||
Inputs | wv | Pointer to wave file. | ||
Outputs | mode | Pointer to compression mode of the wave file. | ||
Platform | VPB4, VPB8L |
Notes
See mode for the compression mode options available for each platform.
Example
See vpb_wave_read().
vpb_get_call
Purpose | Obtains the call progress parameters for a channel. | |||
Syntax | int WINAPI vpb_get_call( | |||
int | handle | |||
VPB_CALLIDH_VPB_CALL | *vpb_call | |||
); | ||||
Inputs | handle | Handle for this channel. | ||
Outputs | vpb_call | Pointer to structure containing call progress parameters. | ||
Platform | VPB4 |
Notes
See VPB_CALLIDH_VPB_CALL for the default values of the call progress parameters. The time duration for the parameters are in ms (milliseconds).
Example
See vpb_call_sync().
vpb_set_call
Purpose | Sets the call progress parameters for a channel. | |||
Syntax | int WINAPI vpb_set_call( | |||
int | handle | |||
VPB_CALLIDH_VPB_CALL | *vpb_call | |||
); | ||||
Inputs | handle | Handle for this channel. | ||
vpb_call | Pointer to structure containing call progress parameters. | |||
Outputs | none | |||
Platform | VPB4 |
Notes
See VPB_CALLIDH_VPB_CALL for the default values of the call progress parameters. The time duration for the parameters are in ms (milliseconds). If only modifying some of the call progress parameters, make sure the rest of the parameters have the default values. This may be accomplished by the vpb_get_call().
Example
See vpb_call_sync().
vpb_call_sync
Purpose | Places a call using the call progress algorithm. Synchronous version. | |||
Syntax | int WINAPI vpb_call_sync( | |||
int | handle | |||
char | *dialstr | |||
); | ||||
Inputs | handle | Handle for this channel. | ||
dialstr | Pointer to string of chars that correspond to tones to dial. | |||
Outputs | returns | Call progress return code. | ||
Platform | VPB4 |
Notes
Ensure dial tone has not been detected before the function is called.
Example
#include <conio.h>
#include <stdio.h>
#include "\vpb\vpbapi.h"
// description of call progress result
codes
static char *call_str[] = {
"Connected",
"No Dial Tone",
"No Ring Back",
"Busy",
"No Answer",
"Disconnected",
"Invalid Data"
};
void main() {
int handle,ret;
VPB_CALL cpp;
handle = vpb_open(1,1);
// get default call progress parameters
vpb_get_call(handle,&cpp);
printf("number of dial tones = %d\n \
time limit for dial tone = %dms\n \
wait time for initial ringback = %dms\n \
time limit when call is considered connected = %dms\n \
time limit when call is answered after ringback = %dms\n",\
cpp.dialtones,cpp.dialtone_timeout,cpp.ringback_timeout,\
cpp.inter_ringback_timeout,cpp.answer_timeout);
// change time limit for dial tone
parameter to 2.5 sec
cpp.dialtone_timeout = 2500;
// set call progress parameters
vpb_set_call(handle,&cpp);
printf("time limit for dial tone
= %dms\n",cpp.dialtone_timeout);
// place channel off hook
vpb_sethook_sync(handle,VPB_OFFHOOK);
// sync call and print result
// Note: user specified number for
dial string
ret = vpb_call_sync(handle, "13");
printf("\n->>>>>>>>>>>>Call result sync: %s\n",call_str[ret]);
// hang up
vpb_sethook_sync(handle,VPB_ONHOOK);
vpb_close(handle);
}
vpb_call_async
PurposeSyntax | int WINAPI vpb_call_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 |
Notes
Ensure dial tone has not been detected before the function is called.
Example
#include <conio.h>
#include <stdio.h>
#include "\vpb\vpbapi.h"
void main() {
int handle;
VPB_EVENT e;
char s[VPB_MAX_STR];
int finished = 0;
handle = vpb_open(1,1);
vpb_sethook_sync(handle,VPB_OFFHOOK);
while(!kbhit()) {
// call async
// Note: user specified number for
dial string
vpb_call_async(handle, "12");
do {
vpb_get_event_sync(&e, 0);
vpb_translate_event(&e, s);
printf("%s",s);
// try again by hanging up and going
off hook!
if (e.type == VPB_CALLEND) {
vpb_sethook_sync(handle,VPB_ONHOOK);
vpb_sethook_sync(handle,VPB_OFFHOOK);
}
} while(e.type != VPB_CALLEND);
}
// hang up
vpb_sethook_sync(handle,VPB_ONHOOK);
vpb_close(handle);
}
vpb_getvox
Purpose | Gets the VOX parameters from a particular channel. | |||
Syntax | int WINAPI vpb_getvox( | |||
int | handle | |||
VPB_VOXIDH_VPB_VOX | *vox | |||
); | ||||
Inputs | handle | Handle for this channel. | ||
vox | Pointer to structure containing the VOX parameters. | |||
Outputs | none | |||
Platform | VPB4, VPB8L |
Notes
The on-level and off-level thresholds in the firmware lack some precision (to two decimal places) due to the float to integer conversions. For example, instead of -12 dB as the default value for the VOX on-level, it may contain -12.00173 dB.
Example
#include "\vpb\vpbapi.h"
void main(){
int handle;
VPB_VOX params;
// open channel 1
handle = vpb_open(1,1);
// obtain default VOX parameters
vpb_getvox(handle,¶ms);
printf("onlevel threshold = %f dB <default>\n", params.onlevel);
printf("offlevel threshold = %f dB <default>\n", params.offlevel);
printf("run off time = %d (ms) <default>\n", params.runon);
// set VOX paramters, VOX off level
-24dB run on 3 s
params.offlevel = -24.0;
params.runon = 3000;
vpb_setvox(handle,¶ms);
// obtain new VOX parameters
vpb_getvox(handle,¶ms);
printf("onlevel threshold = %f dB\n",params.onlevel);
printf("offlevel threshold = %f dB\n",params.offlevel);
printf("run off time = %d (ms)\n",params.runon);
vpb_close(handle);
}
vpb_setvox
Purpose | Sets the VOX parameters for a particular channel. | |||
Syntax | int WINAPI vpb_setvox( | |||
int | handle | |||
VPB_VOXIDH_VPB_VOX | *vox | |||
); | ||||
Inputs | handle | Handle for this channel. | ||
vox | Pointer to structure containing the VOX parameters. | |||
Outputs | none | |||
Platform | VPB4, VPB8L |
Notes
The on-level and off-level thresholds in the firmware lack precision (to two decimal places) due to the float to integer conversions. For example, instead of -12 dB as the default value for the VOX on-level, it may contain -12.00173 dB.
Example
See vpb_getvox().
vpb_get_pip
Purpose | Gets the pip parameters. | |||
Syntax | int WINAPI vpb_get_pip( | |||
VPB_PIPIDH_VPB_PIP | *vpb_pip | |||
); | ||||
Inputs | none | |||
Outputs | vpb_pip | Pointer to structure containing the pip parameters. | ||
Platform | VPB8L only |
Notes
The default value for the width of the pulse is 425 ms. The default value for the period between pulses is 15s.
Example
See vpb_pip_on().
vpb_set_pip
Purpose | Sets the pip parameters. | |||
Syntax | int WINAPI vpb_set_pip( | |||
VPB_PIPIDH_VPB_PIP | *vpb_pip | |||
); | ||||
Inputs | vpb_pip | Pointer to structure containing the pip parameters. | ||
Outputs | none | |||
Platform | VPB8L only |
Notes
The default value for the width of the pulse is 425 ms. The default value for the period between pulses is 15s.
Example
See vpb_pip_on().
vpb_pip_on
Purpose | Enables the pip signal of a channel. | |||
Syntax | int WINAPI vpb_pip_on( | |||
int | handle | |||
); | ||||
Inputs | handle | Handle for this channel. | ||
Outputs | none | |||
Platform | VPB8L only |
Notes
The default value for the width of the pulse is 425 ms. The default value for the period between pulses is 15s.
Example
#include <stdio.h>
#include "\vpb\vpbapi.h"
void main() {
int handle;
VPB_EVENT e;
VPB_PIP vpb_pip;
// open channel
handle = vpb_open(1,1);
// get pip parameters
vpb_get_pip(&vpb_pip);
printf("width of pip = %d ms",vpb_pip.width);
printf("period between pip pulse = %d ms",vpb_pip.period);
// set pip period to 20 sec
vpb_pip.period = 20000;
vpb_set_pip(&vpb_pip);
printf("width of pip = %d ms",vpb_pip.width);
printf("period between pip pulse = %d ms",vpb_pip.period);
// enable pip
vpb_pip_on(handle);
// wait for a vox on event
do{
vpb_get_event_sync(&e,0);
}while((e.handle != handle) || (e.type != VPB_VOXON));
// record
printf("Recording linear on ch 1 : ");
vpb_record_file_async(handle, "log.wav", VPB_LINEAR);
// wait for a vox off event
do{
vpb_get_event_sync(&e,0);
}while((e.handle != handle) || (e.type != VPB_VOXOFF));
// terminate recordings
vpb_record_terminate(handle);
// stop recording disable pip and shut down
vpb_pip_off(handle);
vpb_close(handle);
}
vpb_pip_off
Purpose | Disables the pip signal of a channel. | |||
Syntax | int WINAPI vpb_pip_off( | |||
int | handle | |||
); | ||||
Inputs | handle | Handle for this channel. | ||
Outputs | none | |||
Platform | VPB8L only |
Notes
None.
Example
See vpb_pip_on()
vpb_sleep
Purpose | Puts the current thread to sleep for a specified time. | |||
Syntax | int WINAPI vpb_sleep( | |||
long | time_ms | |||
); | ||||
Inputs | time_ms | Time for thread to sleep. | ||
Outputs | none | |||
Platform | VPB4, VPB8L |
Notes
This function is useful for introducing a delay when polling for events using vpb_get_event_async() to reduce the load on the PC. As events happen relatively slowly, small delays in processing do not affect the functioning of computer telephony programs.
Example
#include <stdio.h>
#include <conio.h>
#include "\vpb\vpbapi.h"
void main() {
int handle;
VPB_EVENT e;
char s[VPB_MAX_STR];
handle = vpb_open(1,1);
// enable VOXON events only
vpb_set_event_mask(handle, VPB_MVOXON);
// poll for VOXON events
printf("Press any key to exit\n");
while(!kbhit()) {
if(vpb_get_event_async(&e) == VPB_OK){
vpb_translate_event(&e,s);
printf("event: %s\n",s);
}
vpb_sleep(20);
}
vpb_close(handle);
}
vpb_get_model
Purpose | Returns a string containing the VPB model. | |||
Syntax | int WINAPI vpb_get_model( | |||
char | *s | |||
); | ||||
Inputs | none | |||
Outputs | s | Pointer to string containing the model of VPB card | ||
Platform | VPB4, VPB8L |
Notes
None.
Example
See vpb_record_file_sync().
vpb_sethook_sync
Purpose | Sets the hook status of a channel (with an internal delay of 300 ms). | |||
Syntax | int WINAPI vpb_sethook_sync( | |||
int | handle, | |||
Int | hookstate | |||
); | ||||
Inputs | handle | Handle for this channel. | ||
hookstate | VPB_ONHOOK or VPB_OFFHOOK. | |||
Outputs | none | |||
Platform | VPB4 only |
Notes
There is a small delay (less than 100 ms) between calling this function and the completion of the function. When placing a line on hook this function allows for a delay (300ms) to guarantee the line is placed on hook before exiting the function. This is conveniently used when exiting the programme and shutting down the VPB.
Example
#include <stdio.h>
#include <conio.h>
#include "\vpb\vpbapi.h"
void main() {
int handle;
handle = vpb_open(1,1);
// take channel off hook
printf("Press any key to take off hook\n");
while(!kbhit());
getch();
vpb_sethook_async(handle, VPB_OFFHOOK);
// place channel on hook
printf("Press any key to place on hook\n");
while(!kbhit());
getch();
vpb_sethook_sync(handle, VPB_ONHOOK);
vpb_close(handle);
}
vpb_sethook_async
Purpose | Sets the hook status of a channel (with no delay). | |||
Syntax | int WINAPI vpb_sethook_async( | |||
int | handle, | |||
int | hookstate | |||
); | ||||
Inputs | handle | Handle for this channel. | ||
hookstate | VPB_ONHOOK or VPB_OFFHOOK. | |||
Outputs | none | |||
Platform | VPB4 only |
Notes
If the line is placed on hook well before the program exits a delay is not necessary.
Example
See vpb_sethook_sync().
vpb_translate_event
Purpose
Syntax |
int WINAPI vpb_translate_event( | ||||
VPB_EVENT | *e, | ||||
char | s[] | ||||
); | |||||
Inputs | e | Pointer to event to translate. | |||
s | Pointer to string with at least VPB_MAX_CHAR characters. | ||||
Outputs | none | ||||
Platform | VPB4, VPB8L |
Notes
None.
Example
#include <conio.h>
#include <stdio.h>
#include "\vpb\vpbapi.h"
void main() {
int handle;
char s[VPB_MAX_STR];
handle = vpb_open(1,1);
// unmask (enable) events
vpb_set_event_mask(handle, VPB_MVOXON);
// wait for VOXON on channel 1
VPB_EVENT e;
vpb_get_event_sync(&e,0);
vpb_translate_event(&e, s);
printf("event: %s\n",s);
printf("Press any key to finish");
while(!kbhit());
vpb_close(handle);
}
vpb_open
Purpose | Opens a channel on the VPB. | |||
Syntax | int WINAPI vpb_open( | |||
unsigned int | board, | |||
unsigned int | channel | |||
); | ||||
Inputs | board | The VPB to open channel on, numbering starts at 1 | ||
channel | Channel on the VPB to open, from 1 to 4. | |||
Outputs | handle | Handle for this channel. | ||
Platform | VPB4, VPB8L |
Notes
A channel must be opened before any other operations may be performed with it.
The first time this function is called it initialises the driver software and the VPB firmware. This may cause a slight delay (around 1 second).
This function should not be called simultaneously by different threads (multitasking not supported). Instead, use a single thread to initialise all channels.
Example
#include <stdio.h>
#include "\vpb\vpbapi.h"
void main() {
int handle;
// open (and close) channel 4 of
board 1
handle = vpb_open(1,4);
vpb_close(handle);
}
vpb_close
Purpose | Closes a channel on the VPB. | |||
Syntax | int WINAPI vpb_close( | |||
int | handle | |||
); | ||||
Inputs | handle | Handle for this channel. | ||
Outputs | none | |||
Platform | VPB4, VPB8L |
Notes
This function should not be called simultaneously by different threads.
Example
See vpb_open().
vpb_seterrormode
Purpose | Determines the way run time errors are handled. | |||
Syntax | int WINAPI vpb_seterrormode( | |||
int | mode | |||
); | ||||
Inputs | mode | VPB_DEVELOPMENT, VPB_ERROR_CODE, or VPB_EXCEPTION. | ||
Outputs | none | |||
Platform | VPB4, VPB8L |
Notes
See the discussion on error handling.
Example
See the discussion on error handling.
vpb_adpcm_open
Purpose | Opens an OKI ADPCM decoder. | |||
Syntax | int WINAPI vpb_adpcm_open( | |||
void | **adpcm | |||
); | ||||
Inputs | adpcm | Ptr to state variables for ADPCM decoder | ||
Outputs | none | |||
Platform | VPB4, VPB8L |
Notes
There should be one ADPCM decoder opened for each channel that you wish to decode concurrently.
Opening a new ADPCM decoder resets the ADPCM decoder?s state variables to an initial state, this should be done every time a new sequence of data is decoded.
Example
See vpb_adpcm_decode.
vpb_adpcm_close
Purpose | Closes an OKI ADPCM decoder. | |||
Syntax | int WINAPI vpb_adpcm_close( | |||
void | *adpcm | |||
); | ||||
Inputs | adpcm | Ptr to state variables for ADPCM decoder | ||
Outputs | none | |||
Platform | VPB4, VPB8L |
Notes
Call after ADPCM decoding is complete.
Example
See vpb_adpcm_decode.
vpb_adpcm_decode
Purpose | Decodes a buffer of OKI ADPCM samples to 16 bit linear samples. | |||
Syntax | int WINAPI vpb_adpcm_decode( | |||
void | *adpcm, | |||
short | linearbuf[] | |||
unsigned short | *nlinear | |||
char | Adpcmbuf[] | |||
unsigned short | nadpcmbytes | |||
); | ||||
Inputs | adpcm | Pointer to state variables for ADPCM decoder | ||
adpcmbuf | Buffer of compressed OKI-APDCM samples, 2 4-bit samples per byte | |||
nadpcmbytes | Number of bytes in ADPCM buffer | |||
Outputs | linearbuf | Buffer of decoder linear samples, one sample per 16 bit word | ||
*nlinear | Number of decoded linear samples returned in linearbuf | |||
Platform | VPB4, VPB8L |
Notes
This function can be used to decode OKI ADPCM samples recorded using the VPB ADPCM recording mode.
Example
// This program converts an ADPCM VOX (raw) file to
// a linear wave file, useful for replaying vox files
// over a sound blaster, as OKI-ADPCM is not supported
// by many Windows multimedia sound
players.
#include <assert.h>
#include <conio.h>
#include <stdio.h>
#include "\vpb\vpbapi.h"
#define N 160 // 20 ms frames
void main(void)
{
FILE *fvox;
void *wave;
char adpcm[N/2]; // two samples per byte
short linear[N]; // one sample per short
unsigned short nlinear;
void *states; // adpcm decoder states
fvox = fopen("adpcm.vox","rb");
assert(fvox);
vpb_wave_open_write(&wave, "adpcm.wav", VPB_LINEAR);
vpb_adpcm_open(&states);
while(fread(adpcm, sizeof(char), N/2, fvox) == N/2) {
vpb_adpcm_decode(states, linear, &nlinear, adpcm, N/2);
vpb_wave_write(wave, (char*)linear, sizeof(short)*N);
}
fclose(fvox);
vpb_wave_close_write(wave);
vpb_adpcm_close(states);
}