libvpb  4.2.57
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Event handling
Collaboration diagram for Event handling:

Classes

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

Typedefs

typedef void(WINAPI * vpb_event_callback )(VPB_EVENT *e, void *context)
 The callback function type for vpb_set_event_callback().
 

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...
 

Functions

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.
 

Event mask values

#define VPB_MRING   (1<<VPB_RING)
 
#define VPB_MDIGIT   (1<<VPB_DIGIT)
 
#define VPB_MDTMF   (1<<VPB_DTMF)
 
#define VPB_MTONEDETECT   (1<<VPB_TONEDETECT)
 
#define VPB_MTIMEREXP   (1<<VPB_TIMEREXP)
 
#define VPB_MVOXON   (1<<VPB_VOXON)
 
#define VPB_MVOXOFF   (1<<VPB_VOXOFF)
 
#define VPB_MSTATION_OFFHOOK   (1<<VPB_STATION_OFFHOOK)
 
#define VPB_MSTATION_ONHOOK   (1<<VPB_STATION_ONHOOK)
 
#define VPB_MRING_OFF   (1<<VPB_RING_OFF)
 
#define VPB_MDROP   (1<<VPB_DROP)
 
#define VPB_MSTATION_FLASH   (1<<VPB_STATION_FLASH)
 
#define VPB_MLOOP_OFFHOOK   (1<<VPB_LOOP_OFFHOOK)
 
#define VPB_MLOOP_ONHOOK   (1<<VPB_LOOP_ONHOOK)
 
#define VPB_MLOOP_POLARITY   (1<<VPB_LOOP_POLARITY)
 
#define VPB_MLOOP_FLASH   (1<<VPB_LOOP_FLASH)
 
#define VPB_MDTMF_DOWN   (1<<VPB_DTMF_DOWN)
 
#define VPB_MALL_EVENTS   ((unsigned long)-1)
 

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_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

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.

References CheckHandle(), and VPB_DEV::evtmask.

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.

References CheckHandle(), and VPB_DEV::evtmask.

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

References VPB_EVENT::type, and VPB_EVT_NONE.

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

References CheckHandle(), VPB_EVENT::type, and VPB_EVT_NONE.

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

References CheckHandle(), sleepms, VPB_EVENT::type, and VPB_EVT_NONE.

Referenced by vpb_send_cid_t2_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()

References sleepms, VPB_EVENT::type, and VPB_EVT_NONE.

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?

References VPB_DEV::callback_mutex, CheckHandle(), VPB_DEV::context, and VPB_DEV::event_callback.

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.

Referenced by vpb_send_cid_t2_sync().