Function Reference Part 1


vpb_disable_event
 
 
Purpose Disables only the specified unsolicited  events while leaving the rest of the event mask unchanged.
Syntax int WINAPI vpb_disable_event(
    int handle,
    unsigned short mask
    );  
Inputs handle Handle for this channel.
  mask Mask which specifies which events are disabled. Multiple events can be disabled by OR-ing together VPB_Mxxx values eg. VPB_MRING, VPB_MDIGIT etc.
Outputs none  
Platform   VPB4, VPB8L

 
 

Notes

All events are enabled by default.

This function affects only the events specified in the mask argument.

Each channel has an independent event mask.

Example

include "\vpb\vpbapi.h"

include <stdio.h

void main() {
 
 

int handle;
 
 

handle = vpb_open(1,1);
 
 

// by default all events are enabled

// get the event mask,
 
 

int msk = vpb_get_event_mask(handle);

printf("Event Mask = 0x%x",msk);

// disable DIGIT events
 
 

vpb_disable_event(handle, VPB_MDIGIT);
 
 

// get the event mask
 
 

msk = vpb_get_event_mask(handle);

printf("\nEvent Mask = 0x%x\n",msk);

vpb_close(handle);

}

The mask enables the following events:
 
 
Event Value Description
VPB_RING VPB_MRING Detection of a ring signal.
VPB_DIGIT VPB_MDIGIT Detection of a DTMF signal.
VPB_TONEDETECT VPB_MTONEDETECT Detection of a programmable tone.
VPB_VOXON VPB_MVOXON Detection of voice.
VPB_VOXOFF VPB_MVOXOFF Detection of silence.

Multiple events may be enabled by OR-ing together the appropriate event values.
 
 

vpb enable event
 
 
Purpose Enables only the specified unsolicited events while leaving the rest of the event mask unchanged.
Syntax int WINAPI vpb_enable_event(
    int handle,
    unsigned short mask
    );  
Inputs handle Handle for this channel.
  mask Mask which specifies which events are enabled. Multiple events can be enabled by OR-ing together VPB_Mxxx values eg. VPB_MRING, VPB_MDIGIT etc.
Outputs none  
Platform   VPB4, VPB8L

 
 

Notes

All events are enabled by default.

This function affects only the events specified in the mask argument.

Each channel has an independent event mask.

Example

include <stdio.h

include "\vpb\vpbapi.h"
 
 

void main() {
 
 

int handle;
 
 

handle = vpb_open(1,1);
 
 

// by default all events are enabled

// disable DIGIT events
 
 

vpb_disable_event(handle, VPB_MDIGIT);
 
 

// get the event mask,
 
 

int msk = vpb_get_event_mask(handle);

printf("Event Mask = 0x%x",msk);

// enable DIGIT events
 
 

vpb_enable_event(handle, VPB_MDIGIT);
 
 

// get the event mask
 
 

msk = vpb_get_event_mask(handle);

printf("\nEvent Mask = 0x%x\n",msk);

vpb_close(handle);

}
 
 

vpb get event mask
 
 
Purpose Function to obtain the current event mask for a given channel.
Syntax int WINAPI vpb_get_event_mask(
    int handle
    );  
Inputs handle Handle for this channel.
Outputs returns Event mask for the channel.
Platform   VPB4, VPB8L

 
 

Notes

Each channel has an independent event mask.

Example

include <stdio.h

include "\vpb\vpbapi.h"
 
 

void main() {
 
 

int handle;
 
 

handle = vpb_open(1,1);
 
 

// by default all events are enabled

// disable DIGIT events
 
 

vpb_disable_event(handle, VPB_MDIGIT);
 
 

// get the event mask,
 
 

int msk = vpb_get_event_mask(handle);

printf("Event Mask = 0x%x",msk);

// enable DIGIT events
 
 

vpb_enable_event(handle, VPB_MDIGIT);
 
 

// get the event mask
 
 

msk = vpb_get_event_mask(handle);

printf("\nEvent Mask = 0x%x\n",msk);

vpb_close(handle);

}
 
 

vpb_set_event_mask
 
 
Purpose Function to set the entire event mask for a given channel.
Syntax int WINAPI vpb_set_event_mask(
    int handle,
    unsigned short mask
    );  
Inputs handle Handle for this channel.
  mask Mask which specifies the event mask for the entire channel. Events are considered enabled if asserted in mask. Multiple events can be enabled by OR-ing together VPB_Mxxx values eg. VPB_MRING, VPB_MDIGIT etc.
Outputs none  
Platform   VPB4, VPB8L

 
 

Notes

This function sets the entire event mask for the channel, unlike vpb_enable_event which only modifies the masking of specified events. Any events not included in the mask parameter are effectively disabled (see example).

Each channel has an independent event mask.

Example

include <stdio.h

include <conio.h

include "\vpb\vpbapi.h"
 
 

void main() {
 
 

int handle;
 
 

handle = vpb_open(1,1);
 
 

// enable DIGIT events

// Note: all other events remain disabled
 
 

vpb_set_event_mask(handle, VPB_MDIGIT);

// get event mask
 
 

int msk = vpb_get_event_mask(handle);

printf("Event Mask = 0x%x\n",msk);

// wait for key to finish

printf("Press any key to finish");

while(!kbhit());

vpb_close(handle);

}
 
 

vpb get event async
 
 
Purpose Gets an event from the API event queue. Asynchronous version.
Syntax int WINAPI vpb_get_event_async(
    VPB_EVENT *e
    );  
Inputs E Pointer to event structure.
Outputs Returns Returns VPB_OK if an event is available, otherwise VPB_NO_EVENTS if queue is empty.
Platform   VPB4, VPB8L

 
 

Notes

This function polls the API event queue to determine if any events are present. If so, the event data is copied to the VPB_EVENT structure pointed to by e.

Only enabled events are posted to the event queue.

Example

include <conio.h

include <stdio.h

include "\vpb\vpbapi.h"
 
 

void main() {
 
 

int handle;
 
 

handle = vpb_open(1,1);
 
 

// enable VOX events

vpb_set_event_mask(handle, VPB_MVOXON);
 
 

// wait for a VOX ON event

VPB_EVENT e;

do{

vpb_get_event_async(&e);
 
 

}while(e.type != VPB_VOXON);

printf("VOXON event detected!\n");
 
 

printf("Press any key when finished!");

while(!kbhit());
 
 

vpb_close(handle);
 
 

}

Asynchronous functions perform the operations required to initiate processing, then return before the processing required by that function is complete. For example vpb_play_file_async() starts a file playing, then returns (almost) immediately, before the file has finished playing. Asynchronous functions perform signal completion by posting a terminate event to the API event queue, for example vpb_play_file_async() posts the VPB_PLAYEND event to the event queue when it has finished playing the file.
 
 

Synchronous functions complete all operations before returning. For example vpb_play_file_sync() returns only when the file has finished playing.
 
 

typedef struct {

int type; // event type (see vpbapi.h)

int handle; // channel that generated event

int data; // optional data

} VPB_EVENT;
 
 

vpb get event sync
 
 
Purpose Gets an event from the API event queue. Synchronous version.
Syntax int WINAPI vpb_get_event_sync(
    VPB_EVENT *e
    unsigned int time_out
    );  
Inputs time_out Time limit (in ms) to get an event from the API queue.
Outputs e Pointer to event structure.
  returns Returns VPB_OK or VPB_TIME_OUT
Platform   VPB4, VPB8L

 
 

Notes

This function waits until an event is present on the API event queue, then returns with the event data copied to the VPB_EVENT structure pointed to by e. If the function time-outs before an event is posted, it returns a VPB_TIME_OUT. If the time_out parameter being passed to the function is equal to zero, and no events are present, the function waits indefinitely.

Only enabled events are posted to the event queue.

Example

include <conio.h

include <stdio.h

include "\vpb\vpbapi.h"
 
 

void main() {
 
 

int handle,ret;
 
 
 
 

handle = vpb_open(1,1);
 
 

// enable VOXON events
 
 

vpb_set_event_mask(handle, VPB_MVOXON);
 
 

// wait for 10 second for a ring on channel 1
 
 

VPB_EVENT e;

ret = vpb_get_event_sync(&e,10000);

if(ret == VPB_TIME_OUT)

printf("Timed out: VOXON event not detected!\n");

else

printf("VOXON event detected!\n");

printf("Press any key to end");

while(!kbhit());
 
 

vpb_close(handle);

}
 
 

vpb get event ch async
 
 
Purpose  
Syntax int WINAPI vpb_get_event_ch_async(
    int handle
    VPB_EVENT *e
    );  
Inputs handle Handle for the channel.
  e Pointer to event structure.
Outputs returns Returns VPB_OK if an event is available, otherwise VPB_NO_EVENTS if queue is empty.
Platform   VPB4, VPB8L

 
 

Notes

This function polls the API event queue for the specified channel to determine if any events are present from the specified channel. If so, the event data is copied to the VPB_EVENT structure pointed to by e.

Only enabled events are posted to the event queue.

Each channel maintains an individual event queue that is separate from the global event queue. Thus the same event will be present on the global and channel specific event queues. Thus it is best to consistently use either the channel specific (vpb_get_event_ch_async, vpb_get_event_ch_sync) or global get event (vpb_get_event_async, vpb_get_event_sync) functions. Mixed use of the functions will lead to events appearing twice.

Example

include <conio.h

include <stdio.h

include "\vpb\vpbapi.h"
 
 

void main() {
 
 

int handle;
 
 

handle = vpb_open(1,1);
 
 

// enable VOXON events
 
 

vpb_set_event_mask(handle, VPB_MVOXON);
 
 

// wait for ring on channel 1
 
 

VPB_EVENT e;

while(vpb_get_event_ch_async(handle,&e) == VPB_NO_EVENTS);

printf("VOXON event detected!\n");
 
 

printf("Press any key when finished!");

while(!kbhit());
 
 

vpb_close(handle);
 
 

}
 
 

vpb get event ch sync
 
 
Purpose Gets an event from the API event queue for a specific channel. Synchronous version.
Syntax int WINAPI vpb_get_event_ch_sync(
    int handle
    VPB_EVENT *e
    unsigned int time_out
    );  
Inputs handle Handle for the channel.
  time_out Time limit (in ms) to get an event in the API event queue.
Outputs e Pointer to event structure.
  returns Returns VPB_OK or VPB_TIME_OUT
Platform   VPB4, VPB8L

 
 

Notes

This function waits until an event is present on the API event queue from the specified channel, then returns with the event data copied to the VPB_EVENT structure pointed to by e. If the function time-outs before an event is posted, it returns a VPB_TIME_OUT. If the time_out parameter being passed to the function is equal to zero, and no events are present, the function waits indefinitely.

Only enabled events are posted to the event queue.

Each channel maintains an individual event queue that is separate from the global event queue. Thus the same event will be present on the global and channel specific event queues. Thus it is best to consistently use either the channel specific (vpb_get_event_ch_async, vpb_get_event_ch_sync) or global get event (vpb_get_event_async, vpb_get_event_sync) functions. Mixed use of the functions will lead to events appearing twice.

Example

include <conio.h

include <stdio.h

include "\vpb\vpbapi.h"
 
 

void main() {
 
 

int handle,ret;
 
 
 
 

handle = vpb_open(1,1);
 
 

// enable VOXON events
 
 

vpb_set_event_mask(handle, VPB_MVOXON);
 
 

// wait for 1 second for a ring on channel 1
 
 

VPB_EVENT e;

ret = vpb_get_event_ch_sync(handle,&e,10000);

if(ret == VPB_TIME_OUT)

printf("Timed out: VOXON event not detected!\n");

else

printf("VOXON event detected!\n");

printf("Press any key to end");

while(!kbhit());
 
 

vpb_close(handle);

}
 
 

vpb put event
 
 
Purpose Places an event on the API event queue. 
Syntax int WINAPI vpb_put_event(
    VPB_EVENT *e
    );  
Inputs e Pointer to event structure.
Outputs none  
Platform   VPB4, VPB8L

 
 

Notes

Useful for testing and for placing user defined events on the API event queue.

The event is placed on the API event queue regardless of mask status.

Example

include <stdio.h

include <conio.h

include "\vpb\vpbapi.h"
 
 

void main() {

int handle;

VPB_EVENT e;
 
 

handle = vpb_open(1,1);
 
 

// simulate ring event on channel 1
 
 

e.type = VPB_RING;

e.handle = 0;

e.data = 0;

vpb_put_event(&e);
 
 

// get simulated event
 
 

vpb_get_event_sync(&e,0);

printf("\nRing event detected!\n");
 
 

// wait for key to finish
 
 

printf("Press any key to finish");

while(!kbhit());
 
 

vpb_close(handle);

}

typedef struct {

char *term_digits; // string of digits to terminate collection

} VPB_PLAY;
 
 

vpb play file sync
 
 
Purpose Utility function to play a wave file to a channel. Synchronous version. Function returns when playing has completed.
Syntax int WINAPI vpb_play_file_sync(
    int  handle,
    char file_name[]
    );  
Inputs handle Handle for this channel.
  file_name Pointer to string containing file name (including path) of file to play
Outputs none  
Platform   VPB4 only

 
 

Notes

None.

Example

include <stdio.h

include "\vpb\vpbapi.h"
 

void main() {

int handle;

VPB_EVENT e;
 
 

handle = vpb_open(1,1);
 
 

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

// 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 file async
 
 
Purpose Utility function to play a 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_file_async(
    int  handle,
    char file_name[],
    int data
    );  
Inputs handle Handle for this channel.
  file_name Pointer to string containing file name (including path) of file to play.
  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.

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_file_async(handle, "test.wav", 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 voxfile sync
 
 
Purpose Utility function to play a vox to a channel. Synchronous version. Function returns when playing has completed.
Syntax int WINAPI vpb_play_voxfile_sync(
    int  handle,
    char file_name[]
    unsigned char mode
    );  
Inputs handle Handle for this channel.
  file_name Pointer to string containing file name (including path) of file to play
  mode Compression mode
Outputs none  
Platform   VPB4 only

 
 

Notes

None.

Example

include <stdio.h

include "\vpb\vpbapi.h"
 
 

void main() {

int handle;

VPB_EVENT e;
 
 

handle = vpb_open(1,1);
 
 

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

// play vox file on channel 1

// note: mulaw.vox is user supplied
 
 

vpb_play_voxfile_sync(handle, "mulaw.vox", VPB_MULAW);
 
 

// place channel back on hook
 
 

vpb_sethook_sync(handle, VPB_ONHOOK);
 
 

vpb_close(handle);

}