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