libvpb  4.2.61
Collaboration diagram for Event handling:

Modules

 Audio play and record
 

Classes

struct  VPB_EVENT
 Container for VPB event data. More...
 

Enumerations

enum  VPB_EVT_TYPE {
  VPB_EVT_NONE = -1 , VPB_RING = 0 , VPB_DIGIT = 1 , VPB_TONEDETECT = 2 ,
  VPB_TIMEREXP = 3 , VPB_VOXON = 4 , VPB_VOXOFF = 5 , VPB_DTMF = 8 ,
  VPB_STATION_OFFHOOK = 9 , VPB_STATION_ONHOOK = 10 , VPB_RING_OFF = 11 , VPB_DROP = 12 ,
  VPB_STATION_FLASH = 13 , VPB_LOOP_OFFHOOK = 14 , VPB_LOOP_ONHOOK = 15 , VPB_LOOP_POLARITY = 16 ,
  VPB_DTMF_DOWN = 17 , VPB_LOOP_FLASH = 18 , VPB_PLAYEND = 100 , VPB_RECORDEND = 101 ,
  VPB_DIALEND = 102 , VPB_TONE_DEBUG_END = 103 , VPB_CALLEND = 104 , VPB_ISDN_ANS = 110 ,
  VPB_ISDN_BUSY = 111 , VPB_ISDN_CINFO = 112 , VPB_ISDN_CALL_FAIL = 113 , VPB_ISDN_ANS_FAIL = 114 ,
  VPB_ISDN_PROCEEDING = 115 , VPB_ISDN_RINGING = 116 , VPB_USER_EVT = 255
}
 VPB_EVENT type values More...
 

Event mask values

typedef void(WINAPI * vpb_event_callback) (VPB_EVENT *e, void *context)
 The callback function type for vpb_set_event_callback().
 
int WINAPI vpb_enable_event (VPBPortHandle handle, unsigned long mask)
 Enable the events specified by mask for handle. More...
 
int WINAPI vpb_disable_event (VPBPortHandle handle, unsigned long mask)
 Disable the events specified by mask for handle. More...
 
unsigned long WINAPI vpb_get_event_mask (VPBPortHandle handle)
 Return the current event mask for handle.
 
int WINAPI vpb_set_event_mask (VPBPortHandle handle, unsigned long mask)
 Set the event mask for handle.
 
int WINAPI vpb_get_event_async (VPB_EVENT *event)
 Fetch the next event from the global event queue. More...
 
int WINAPI vpb_get_event_ch_async (VPBPortHandle handle, VPB_EVENT *event)
 Fetch the next event from a port specific event queue. More...
 
int WINAPI vpb_get_event_sync (VPB_EVENT *event, unsigned int time_out=0)
 Wait for an event on the global event queue. More...
 
int WINAPI vpb_get_event_ch_sync (VPBPortHandle handle, VPB_EVENT *event, unsigned int time_out=0)
 Wait for an event on a port specific event queue. More...
 
int WINAPI vpb_put_event (VPB_EVENT *event)
 Places an event on the global and port specific event queues.
 
void WINAPI vpb_translate_event (VPB_EVENT *event, char *str)
 Converts a given event into a string describing it. More...
 
int WINAPI vpb_set_event_callback (VPBPortHandle handle, vpb_event_callback callback, void *context=NULL)
 Sets an event callback function to use instead of the APIQ. More...
 
int WINAPI vpb_get_event_count (void)
 Returns the number of events on the global event queue.
 
int WINAPI vpb_get_event_count_ch (VPBPortHandle handle)
 Returns the number of events on the port specific event queue for handle.
 
void WINAPI vpb_flush_events (VPBPortHandle handle)
 Clear all unread events from the queue for handle.
 
void WINAPI vpb_flush_events ()
 Clear all unread events from the global event queue.
 
#define VPB_MRING   (1<<VPB_RING)
 The callback function type for vpb_set_event_callback().
 
#define VPB_MDIGIT   (1<<VPB_DIGIT)
 The callback function type for vpb_set_event_callback().
 
#define VPB_MDTMF   (1<<VPB_DTMF)
 The callback function type for vpb_set_event_callback().
 
#define VPB_MTONEDETECT   (1<<VPB_TONEDETECT)
 The callback function type for vpb_set_event_callback().
 
#define VPB_MTIMEREXP   (1<<VPB_TIMEREXP)
 The callback function type for vpb_set_event_callback().
 
#define VPB_MVOXON   (1<<VPB_VOXON)
 The callback function type for vpb_set_event_callback().
 
#define VPB_MVOXOFF   (1<<VPB_VOXOFF)
 The callback function type for vpb_set_event_callback().
 
#define VPB_MSTATION_OFFHOOK   (1<<VPB_STATION_OFFHOOK)
 The callback function type for vpb_set_event_callback().
 
#define VPB_MSTATION_ONHOOK   (1<<VPB_STATION_ONHOOK)
 The callback function type for vpb_set_event_callback().
 
#define VPB_MRING_OFF   (1<<VPB_RING_OFF)
 The callback function type for vpb_set_event_callback().
 
#define VPB_MDROP   (1<<VPB_DROP)
 The callback function type for vpb_set_event_callback().
 
#define VPB_MSTATION_FLASH   (1<<VPB_STATION_FLASH)
 The callback function type for vpb_set_event_callback().
 
#define VPB_MLOOP_OFFHOOK   (1<<VPB_LOOP_OFFHOOK)
 The callback function type for vpb_set_event_callback().
 
#define VPB_MLOOP_ONHOOK   (1<<VPB_LOOP_ONHOOK)
 The callback function type for vpb_set_event_callback().
 
#define VPB_MLOOP_POLARITY   (1<<VPB_LOOP_POLARITY)
 The callback function type for vpb_set_event_callback().
 
#define VPB_MLOOP_FLASH   (1<<VPB_LOOP_FLASH)
 The callback function type for vpb_set_event_callback().
 
#define VPB_MDTMF_DOWN   (1<<VPB_DTMF_DOWN)
 The callback function type for vpb_set_event_callback().
 
#define VPB_MALL_EVENTS   ((unsigned long)-1)
 The callback function type for vpb_set_event_callback().
 

Detailed Description

An event driven programming model is used by libvpb. There are primarily two different kinds of events, solicted and unsolicited.

Solicited events
Solicited events are generated as a response to a previous API function call, for example when vpb_play_file_async() is called, a solicited event of the type VPB_PLAYEND is generated when the file has finished playing.
Unsolicited events
Unsolicited events are generated in response to external conditions, for example when a DTMF tone has been detected by the card.

Enumeration Type Documentation

◆ VPB_EVT_TYPE

VPB_EVENT type values

Enumerator
VPB_EVT_NONE 

Invalid event value. Used where no event is returned from api functions that take a VPB_EVENT return parameter.

VPB_USER_EVT 

User defined event message. Different types of user events may be differentiated using the VPB_EVENT::data or VPB_EVENT::extra fields as appropriate.

Function Documentation

◆ vpb_disable_event()

int WINAPI vpb_disable_event ( VPBPortHandle  handle,
unsigned long  mask 
)

Disable the events specified by mask for handle.

Events not included in the mask are unaffected.

◆ vpb_enable_event()

int WINAPI vpb_enable_event ( VPBPortHandle  handle,
unsigned long  mask 
)

Enable the events specified by mask for handle.

Events not included in the mask are unaffected.

◆ vpb_get_event_async()

int WINAPI vpb_get_event_async ( VPB_EVENT event)

Fetch the next event from the global event queue.

This function will always return immediately whether there is an event on the queue or not.

Parameters
eventThe returned event from the queue, if any.
Returns
VPB_OK if an event is returned, or VPB_NO_EVENTS if the queue is currently empty.
Note
Reading events from the global queue does not clear them from the port specific queues. You should excercise caution if reading them from both sources.
See also
vpb_get_event_ch_async(), vpb_get_event_sync(), vpb_get_event_ch_sync()

◆ vpb_get_event_ch_async()

int WINAPI vpb_get_event_ch_async ( VPBPortHandle  handle,
VPB_EVENT event 
)

Fetch the next event from a port specific event queue.

This function will always return immediately whether there is an event on the queue or not.

Parameters
handleThe handle to the port of interest.
eventThe returned event from the queue.
Returns
VPB_OK if an event is returned, or VPB_NO_EVENTS if the queue is currently empty.
Note
Reading events from the port specific queues does not clear them from the global queue. You should excercise caution if reading them from both sources.
See also
vpb_get_event_async(), vpb_get_event_sync(), vpb_get_event_ch_sync()

◆ vpb_get_event_ch_sync()

int WINAPI vpb_get_event_ch_sync ( VPBPortHandle  handle,
VPB_EVENT event,
unsigned int  time_out = 0 
)

Wait for an event on a port specific event queue.

This function will return immediately if there is already an event on the queue, else it will block until one arrives or the time out expires.

Parameters
handleThe handle to the port of interest.
eventThe returned event from the queue.
time_outAn optional maximum time to wait, in milliseconds. If the time_out is set to 0 this function will block indefinitely until an event arrives.
Returns
VPB_OK if an event occurred, or VPB_TIME_OUT if time_out elapsed with no event to return.
Note
Reading events from the port specific queues does not clear them from the global queue. You should excercise caution if reading them from both sources.
See also
vpb_get_event_sync(), vpb_get_event_async(), vpb_get_event_ch_async()

◆ vpb_get_event_sync()

int WINAPI vpb_get_event_sync ( VPB_EVENT event,
unsigned int  time_out = 0 
)

Wait for an event on the global event queue.

This function will return immediately if there is already an event on the queue, else it will block until one arrives or the time out expires.

Parameters
eventThe returned event from the queue.
time_outAn optional maximum time to wait, in milliseconds. If the time_out is set to 0 this function will block indefinitely until an event arrives.
Returns
VPB_OK if an event occurred, or VPB_TIME_OUT if time_out elapsed with no event to return.
Note
Reading events from the global queue does not clear them from the port specific queues. You should excercise caution if reading them from both sources.
See also
vpb_get_event_ch_sync(), vpb_get_event_async(), vpb_get_event_ch_async()

◆ vpb_set_event_callback()

int WINAPI vpb_set_event_callback ( VPBPortHandle  handle,
vpb_event_callback  callback,
void *  context = NULL 
)

Sets an event callback function to use instead of the APIQ.

Parameters
handleThe handle returned by a call to vpb_open().
callbackA pointer to the function to call, or NULL to disable the use of a callback for this port again.
contextAn optional pointer to user defined data that will be passed to the callback function.

By default no event callback functions are set, and events are posted to the API event queues. If a callback is set using this function for some port, it will be called with the event as an argument instead of placing it in the queue.

Any event which is processed after this function returns will be subject to the new callback state, however since events are buffered at the kernel driver level, this may also include some events that occurred before the call was made, but which had not been processed at that time.

Note
The context data, if any, and the callback function must be prepared to begin accepting events, before this function is called, and may be active when a call to change or remove the callback is made. They must remain valid until a call is made to the new callback function, or until the next event has been posted to the api queue in the event of callbacks being disabled.
Todo:
Should this block until it is safe to release the context data and/or the function definition itself?

◆ vpb_translate_event()

void WINAPI vpb_translate_event ( VPB_EVENT event,
char *  str 
)

Converts a given event into a string describing it.

Parameters
eventThe event to process.
strThe returned string.
Note
The precise form of the returned string should not be relied upon and may change with time and different user locales. It is intended for user friendly information reporting only.