Function Reference Part 3


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,&params);

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,&params);

// obtain new VOX parameters

vpb_getvox(handle,&params);

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

}