Loading...
Searching...
No Matches
Event handling
Public API functions » Port initialisation » Card information » Port control
Collaboration diagram for Event handling:

## Topics

| 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.
int WINAPI | vpb_disable_event (VPBPortHandle handle, unsigned long mask)
| Disable the events specified by mask for handle.
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.
int WINAPI | vpb_get_event_ch_async (VPBPortHandle handle, VPB_EVENT *event)
| Fetch the next event from a port specific event queue.
int WINAPI | vpb_get_event_sync (VPB_EVENT *event, unsigned int time_out=0)
| Wait for an event on the global event queue.
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.
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.
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`.
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

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

References CheckHandle(), and vpb_dev.

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

References CheckHandle(), and vpb_dev.

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

  event | The 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 APIQ, VPB_EVENT::type, and VPB_EVT_NONE.

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

  handle | The handle to the port of interest.
  event | The 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 APIQ, CheckHandle(), VPB_EVENT::type, vpb_dev, and VPB_EVT_NONE.

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

  handle | The handle to the port of interest.
  event | The returned event from the queue.
  time_out | An 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 APIQ, CheckHandle(), VPB_EVENT::type, vpb_dev, and VPB_EVT_NONE.

Referenced by vpb_send_cid_t2_sync().

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

  event | The returned event from the queue.
  time_out | An 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 APIQ, VPB_EVENT::type, and VPB_EVT_NONE.

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

  handle | The handle returned by a call to `vpb_open()`.
  callback | A pointer to the function to call, or `NULL` to disable the use of a callback for this port again.
  context | An 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, VPB_DEV::event_callback, and vpb_dev.

## vpb_translate_event()

void WINAPI vpb_translate_event | ( | VPB_EVENT * | event,
|  | char * | str )

Converts a given event into a string describing it.

Parameters

  event | The event to process.
  str | The 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.