Loading...
Searching...
No Matches
VPBapi implementation detail
Internal implementation detail

Implementation support found in `vpbapi.cpp`. More...

Collaboration diagram for VPBapi implementation detail:

## Classes

struct | soft_bridge_info
struct | VPB_DEV
| Container type for device information. More...

## Enumerations

enum | DevState { VPB_OFF , VPB_ON }
| Device state flags. More...

## Functions

static soft_bridge_info *WINAPI | soft_bridge_new (void)
static soft_bridge_info *WINAPI | soft_bridge_find (int h1, int h2)
static soft_bridge_info *WINAPI | soft_bridge_find (int h1)
static void WINAPI | soft_bridge_delete (soft_bridge_info *bp)
void | CheckHandle (VPBPortHandle handle, const char *where)
| Check for a valid device handle.
void | ValidHandleCheck (VPBPortHandle handle)
const char *WINAPI | vpb_get_driver_version ()
| Return the driver version as a string.
void WINAPI | vpb_get_driver_version (int *major, int *minor, int *patchlevel)
| Return the driver version as major, minor, and patchlevel components.
void WINAPI | vpb_set_global_apiq_size (int size)
| Set the maximum number of events the global `APIQ` may hold.
void WINAPI | vpb_set_channel_apiq_size (int size)
| Set the maximum number of events per-channel `APIQ's` may hold.
void | set_country (int board, int port, const Country *country)
| Set the country data for port on board.
static void | set_country (VPBPortHandle handle, const Country *country)
const Country * | get_country (int board, int port)
| Return the country data for port on board.
static const Country * | get_country (VPBPortHandle handle)
void WINAPI | vpb_set_country (const Country *country)
| Set the global default country specific information.
int WINAPI | vpb_set_country (VPBPortHandle handle, const Country *country)
| Set the country specific information for an individual port.
const Country *WINAPI | vpb_get_port_country (VPBPortHandle handle)
| Get the current country data for port handle.
const Country *WINAPI | vpb_get_country_data (const std::string &name)
| Get country specific data by name.
const Country *WINAPI | vpb_get_country_data (int code)
| Get country specific data by numeric country code.
void | set_ps_impedance (int board, int port, int impedance)
void | set_vdaa_impedance (int board, int port, int impedance)
static void | ProcessVPBMessage (uint16_t mess[], unsigned short board)
static void * | MonitorMessageQueue (void *unused)
static void | ConfigVPB4 (Comm *c, int b)
static void | ConfigureVPB (Comm *c, unsigned short numboards)
static void | init_vpb ()
VPBPortHandle WINAPI | vpb_open (unsigned int board, unsigned int port, VPBOpenMode flags)
| Open a port on some board for use.
void WINAPI | vpb_reset (VPBPortHandle handle)
| Reset a port back to its idle state (on-hook, not ringing etc.).
static void | close_port (VPBPortHandle handle)
static void | CloseVPB (Comm *c, unsigned short numboards)
int WINAPI | vpb_close (VPBPortHandle handle)
| Close a previously opened port using the handle returned by `vpb_open()`.
int WINAPI | vpb_set_event_callback (VPBPortHandle handle, vpb_event_callback callback, void *context)
| Sets an event callback function to use instead of the `APIQ`.
int WINAPI | vpb_set_event_mask (VPBPortHandle handle, unsigned long mask)
| Set the event mask for handle.
unsigned long WINAPI | vpb_get_event_mask (VPBPortHandle handle)
| Return the current event mask for handle.
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.
int WINAPI | vpb_set_tone_event_mask (VPBPortHandle handle, unsigned long mask)
| Set the `TONE` event mask. The previous mask value will be overwritten.
unsigned long WINAPI | vpb_get_tone_event_mask (VPBPortHandle handle)
| Return the current `TONE` event mask for handle.
int WINAPI | vpb_enable_tone_event (VPBPortHandle handle, unsigned long mask)
| Enable the `TONE` events specified by mask for handle.
int WINAPI | vpb_disable_tone_event (VPBPortHandle handle, unsigned long mask)
| Disable the `TONE` events specified by mask for handle.
int WINAPI | vpb_put_event (VPB_EVENT *e)
| Places an event on the global and port specific event queues.
int WINAPI | vpb_get_event_count_ch (VPBPortHandle handle)
| Returns the number of events on the port specific event queue for handle.
int WINAPI | vpb_get_event_count ()
| Returns the number of events on the global event queue.
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.
int | putevt (VPB_EVENT *e, unsigned long mask)
| Internal function to place an event on the API event queue.
int WINAPI | vpb_get_event_async (VPB_EVENT *e)
| Fetch the next event from the global event queue.
int WINAPI | vpb_get_event_sync (VPB_EVENT *e, unsigned int time_out)
| Wait for an event on the global event queue.
int WINAPI | vpb_get_event_ch_sync (VPBPortHandle h, VPB_EVENT *e, unsigned int time_out)
| Wait for an event on a port specific event queue.
int WINAPI | vpb_get_event_ch_async (VPBPortHandle h, VPB_EVENT *e)
| Fetch the next event from a port specific event queue.
void WINAPI | vpb_sethook_async (VPBPortHandle handle, HookState hookstate)
| Signal a port to set its hook state. Returns immediately.
void WINAPI | vpb_sethook_sync (VPBPortHandle handle, HookState hookstate)
| Set the hook state of a port. Waits for it to change before returning.
void WINAPI | vpb_set_flashtime (VPBPortHandle handle, uint16_t min, uint16_t max)
| Set the window for detecting flash events on OpenPCI cards.
void | ring_station_async (int board, int port, int cadence)
| Internal function to control ringing on port of board.
void WINAPI | vpb_ring_station_async (VPBPortHandle handle, int cadence)
| Start or stop a station port ringing.
void WINAPI | vpb_sleep (long time)
| Put the current thread to sleep for some number of milliseconds.
int WINAPI | vpb_adpcm_open (void **pv)
void WINAPI | vpb_adpcm_close (void *pv)
void WINAPI | vpb_adpcm_reset (void *pv)
int WINAPI | vpb_adpcm_decode (void *pv, short linear[], unsigned short *size_lin, char adpcm[], unsigned short size_adpcm)
int WINAPI | vpb_adpcm_encode (void *pv, char adpcm[], unsigned short *size_adpcm, short linear[], unsigned short size_linear)
int WINAPI | vpb_comp_load (unsigned short board)
int WINAPI | vpb_echo_canc_force_adapt_on ()
int WINAPI | vpb_echo_canc_force_adapt_off ()
int WINAPI | vpb_echo_canc_enable ()
int WINAPI | vpb_echo_canc_disable ()
int WINAPI | vpb_echo_canc_get_sup_thresh (int handle, short *thresh)
| Get the current echo suppressor threshold.
int WINAPI | vpb_echo_canc_set_sup_thresh (int handle, short *thresh)
| Set the echo suppressor threshold.
int | get_driver_type (int board)
| Return the symbolic type of the driver for board.
VPB_MODEL | get_board_type (int board)
| Return the symbolic `VPB_MODEL` type of a board.
VPB_MODEL WINAPI | vpb_get_card_type (VPBPortHandle handle)
| Return the board model type for handle.
int WINAPI | vpb_get_type (int handle)
HookState WINAPI | vpb_get_hookstate (VPBPortHandle handle)
| Return the hook state of a port.
VPB_PORT | get_port_type (int board, int port)
| Return the type of a port on some board. `VPB_FXO` or `VPB_FXS`.
VPB_PORT WINAPI | vpb_get_port_type (VPBPortHandle handle)
| Return the `VPB_PORT` type for handle.
void | get_board_model (int board, char *s)
| Return a descriptive model name for board in s.
std::string WINAPI | vpb_get_model (VPBPortHandle handle)
| Return a string indicating the board model.
int WINAPI | vpb_get_model (VPBPortHandle handle, char *s)
| Return a string indicating the board model.
int WINAPI | vpb_get_model (char *s)
int WINAPI | vpb_get_num_cards ()
| Return the number of cards in the system.
int WINAPI | vpb_get_ports_per_card (int board)
| Return the number of ports on board.
int WINAPI | vpb_get_ports_per_card ()
void | set_codec_reg (int handle, unsigned short addr, unsigned short data, Comm *c)
| Write directly to a `V4PCI` codec register.
void WINAPI | vpb_set_codec_reg (int chdev, unsigned short addr, unsigned short data)
int WINAPI | vpb_bridge (VPBPortHandle h1, VPBPortHandle h2, BridgeMode mode)
| Create a full duplex bridge between ports h1 and h2.
int WINAPI | vpb_bridge (int h1, int h2, BridgeMode mode, int resource)
int WINAPI | vpb_soft_bridge (int h1, int h2, int mode)
int WINAPI | vpb_listen (VPBPortHandle h1, VPBPortHandle h2, BridgeMode mode)
| Create a half duplex bridge routing audio from src to dest.
int WINAPI | vpb_conf (int h, int resource, int mode)
int WINAPI | vpb_get_card_info (int board, VPB_CARD_INFO *detail)
| Return detail of the card model and revision for board.
int WINAPI | vpb_loopback_on (int h)
| Turns on software loop-back of tx->rx in the kernel.
int WINAPI | vpb_loopback_off (int h)
| Turns off software loop-back of tx->rx in the kernel.
int WINAPI | vpb_hostecho_on (int h)
| Enable the host echo canceller for handle.
int WINAPI | vpb_hostecho_off (int h)
| Disable the host echo canceller for handle.
int WINAPI | vpb_isdn_call (int h, char *number, char *cid, int layer1, int transcap, unsigned char *lowlayercompatibility)
int WINAPI | vpb_isdn_get_cinfo (int h, VPB_CALL_INFO *cinfo)
int WINAPI | vpb_isdn_get_layer1 (int h)
int WINAPI | vpb_isdn_get_transcap (int h)
int WINAPI | vpb_isdn_get_lowlayercompatibility (int h, unsigned char *lowlayercompatibility)
int WINAPI | vpb_isdn_get_cause (int h)
int WINAPI | vpb_isdn_proceeding (int h)
int WINAPI | vpb_loopvolt_get (int h, short *volts)
int WINAPI | vpb_loopvolt_get_threshold (int h, short *volts)
int WINAPI | vpb_loopvolt_set_threshold (int h, short volts)
int WINAPI | vpb_loopvolt_get_lowlimit (int h, short *volts)
int WINAPI | vpb_loopvolt_set_lowlimit (int h, short volts)
int WINAPI | vpb_loop_get_onhookwindow (int h, int *ms)
int WINAPI | vpb_loop_set_onhookwindow (int h, int ms)
int WINAPI | vpb_loop_get_offhookwindow (int h, int *ms)
int WINAPI | vpb_loop_set_offhookwindow (int h, int ms)
void WINAPI | vpb_set_mprintf (void(*func)(const char *format,...))
| Specify a function to handle `mprintf()` logging output.
const char * | vpb_model_desc (VPB_MODEL model)
| Return a descriptive string for a `VPB_MODEL` type.

## Variables

int | soft_bridge_info::h1
int | soft_bridge_info::h2
Fifo * | soft_bridge_info::txdf1
Fifo * | soft_bridge_info::txdf2
soft_bridge_info * | soft_bridge_info::next
DevState | VPB_DEV::devstate
| Flag to indicate if this device has been opened or not.
unsigned long | VPB_DEV::evtmask
| The current event mask.
unsigned long | VPB_DEV::tonemask
| The current tone event mask.
vpb_event_callback | VPB_DEV::event_callback
| Optional event callback.
void * | VPB_DEV::context
| User defined context info for `event_callback`.
HostFifo | VPB_DEV::APIQ
| Per channel API event Q object.
pthread_mutex_t | VPB_DEV::callback_mutex
| Mutex for atomic access to `event_callback` and `context`.
static pthread_t | mmq_thread
GENERIC_CRITICAL_SECTION | SoftBridgeSect
GENERIC_CRITICAL_SECTION | PutEvtSect
static VPB_DETECT | toned_dial
static VPB_DETECT | toned_ringback_aust
static VPB_DETECT | toned_ringback_308
static VPB_DETECT | toned_busy_308
static VPB_DETECT | toned_busy_aust
static VPB_DETECT | toned_grunt
static VPB_DETECT | toned_ringback_us
static VPB_DETECT | toned_busy_us
static VPB_DETECT | toned_fax
static VPB_TONE | au_ring2 = {400, 425, 450, -13, -13, -13, 400, 2000, &au_ring2}
static VPB_TONE | au_ring = {400, 425, 450, -13, -13, -13, 400, 200, &au_ring2}
static VPB_TONE | au_callwaiting2 = {425, 0, 0, -18, 0, 0, 200, 4400, &au_callwaiting2}
static VPB_TONE | au_callwaiting = {425, 0, 0, -18, 0, 0, 200, 200, &au_callwaiting2}
static VPB_TONE | au_tones []
static VPB_TONE | jp_callwaiting2 = {392, 408, 0, -18, -18, 0, 100, 3000, &jp_callwaiting2}
static VPB_TONE | jp_callwaiting = {392, 408, 0, -18, -18, 0, 100, 100, &jp_callwaiting2}
static VPB_TONE | jp_tones []
static VPB_TONE | uk_ring2 = {400, 450, 0, -13, -13, 0, 400, 2000, &uk_ring2}
static VPB_TONE | uk_ring = {400, 450, 0, -13, -13, 0, 400, 200, &uk_ring2}
static VPB_TONE | uk_congestion2 = {400, 0, 0, -13, 0, 0, 225, 525, &uk_congestion2}
static VPB_TONE | uk_congestion = {400, 0, 0, -13, 0, 0, 400, 350, &uk_congestion2}
static VPB_TONE | uk_tones []
static VPB_TONE | sg_dial = {425, 0, 0, -15, 0, 0, 0, 0, NULL}
static VPB_TONE | sg_ring2 = {400, 450, 0, -10, -10, 0, 400, 2000, &sg_ring2}
static VPB_TONE | sg_ring = {400, 450, 0, -10, -10, 0, 400, 200, &sg_ring2}
static VPB_TONE | sg_callwaiting2 = {425, 0, 0, -18, 0, 0, 300, 3200, &sg_callwaiting2}
static VPB_TONE | sg_callwaiting = {425, 0, 0, -18, 0, 0, 300, 200, &sg_callwaiting2}
static VPB_TONE | sg_stutter8 = {425, 0, 0, -15, 0, 0, 100, 100, &sg_dial}
static VPB_TONE | sg_stutter7 = {425, 0, 0, -15, 0, 0, 600, 200, &sg_stutter8}
static VPB_TONE | sg_stutter6 = {425, 0, 0, -15, 0, 0, 200, 200, &sg_stutter7}
static VPB_TONE | sg_stutter5 = {425, 0, 0, -15, 0, 0, 600, 200, &sg_stutter6}
static VPB_TONE | sg_stutter4 = {425, 0, 0, -15, 0, 0, 200, 200, &sg_stutter5}
static VPB_TONE | sg_stutter3 = {425, 0, 0, -15, 0, 0, 600, 200, &sg_stutter4}
static VPB_TONE | sg_stutter2 = {425, 0, 0, -15, 0, 0, 200, 200, &sg_stutter3}
static VPB_TONE | sg_stutter1 = {425, 0, 0, -15, 0, 0, 600, 200, &sg_stutter2}
static VPB_TONE | sg_stutter = {425, 0, 0, -15, 0, 0, 200, 200, &sg_stutter1}
static VPB_TONE | sg_tones []
static VPB_TONE | us_dial = { 350, 440, 0, -13, -13, 0, 0, 0, NULL }
static VPB_TONE | us_sit2 = {1800, 0, 0, -13, 0, 0, 330, 0, NULL}
static VPB_TONE | us_sit1 = {1400, 0, 0, -13, 0, 0, 330, 0, &us_sit2}
static VPB_TONE | us_sit = { 950, 0, 0, -13, 0, 0, 330, 0, &us_sit1}
static VPB_TONE | us_stutter2 = { 350, 440, 0, -13, -13, 0, 100, 100, &us_dial }
static VPB_TONE | us_stutter1 = { 350, 440, 0, -13, -13, 0, 100, 100, &us_stutter2 }
static VPB_TONE | us_stutter = { 350, 440, 0, -13, -13, 0, 100, 100, &us_stutter1 }
static VPB_TONE | us_tones []
static Country | Countries []
static const Country * | default_country = &Countries[0]

## Global variables

Comm * | vpb_c
| Global `Comm` object.
static VPB_DEV * | vpb_dev
| Global `VPB_DEV` array.
static soft_bridge_info * | soft_bridges
| Global soft bridge list head.
static HostFifo * | APIQ
| Global API event Q object.
static int | Init
| Device initialisation flag.
static unsigned short | numboards
| Total number of boards.
static unsigned short | Totalchans
| Total number of ports on all boards.
static unsigned short | sleepms
| sleep period for threads

## Constructors

| VPB_DEV::VPB_DEV ()
| Default constructor.
| VPB_DEV::~VPB_DEV ()
| Default destructor.

## Detailed Description

Implementation support found in `vpbapi.cpp`.

## Enumeration Type Documentation

## DevState

enum DevState

Device state flags.

Enumerator
VPB_OFF | The device is not open.
VPB_ON | The device is open.

## Function Documentation

## CheckHandle()

void CheckHandle | ( | VPBPortHandle | handle,
|  | const char * | where )

Check for a valid device handle.

The handle is valid if the device has been opened with a prior call to `vpb_open()`.

Exceptions

  VpbException | will be thrown, stating where, if handle is invalid.

References Totalchans, vpb_dev, and VPB_OFF.

Referenced by vpb_close(), vpb_deltonedet(), vpb_disable_event(), vpb_disable_tone_event(), vpb_enable_event(), vpb_enable_tone_event(), vpb_flush_events(), vpb_get_card_type(), vpb_get_event_ch_async(), vpb_get_event_ch_sync(), vpb_get_event_mask(), vpb_get_hookstate(), vpb_get_model(), vpb_get_model(), vpb_get_port_country(), vpb_get_port_type(), vpb_get_tone_event_mask(), vpb_gettonedet(), vpb_play_buf_start(), vpb_play_get_gain(), vpb_play_get_hw_gain(), vpb_play_set(), vpb_play_set_gain(), vpb_play_set_hw_gain(), vpb_record_buf_start(), vpb_record_get_gain(), vpb_record_get_hw_gain(), vpb_record_set(), vpb_record_set_gain(), vpb_record_set_hw_gain(), vpb_reset(), vpb_ring_station_async(), vpb_set_country(), vpb_set_event_callback(), vpb_set_event_mask(), vpb_set_flashtime(), vpb_set_tone_event_mask(), vpb_sethook_async(), and vpb_settonedet().

## putevt()

int putevt | ( | VPB_EVENT * | event,
|  | unsigned long | mask = 0 )

Internal function to place an event on the API event queue.

Parameters

  event | The event to place on the API queue.
  mask | The mask to use for this event (set to 0 if not required).

References APIQ, VPB_DEV::APIQ, VPB_DEV::callback_mutex, VPB_DEV::context, VPB_DEV::devstate, VPB_DEV::event_callback, VPB_DEV::evtmask, VPB_EVENT::handle, vpb_dev, and VPB_ON.

## set_codec_reg()

void set_codec_reg | ( | int | handle,
|  | unsigned short | addr,
|  | unsigned short | data,
|  | Comm * | comm )

Write directly to a `V4PCI` codec register.

Parameters

  handle | The handle returned by a call to `vpb_open()`.
  addr | 8-bit address of the codec register.
  data | 8-bit data to write to the register.
  comm | The comm object used to send the message.

Used to set a register of the TS5070 codecs, allows driver-level config of codec, rather than hard-coding in DSP firmware.

References Comm::PutMessageVPB().

Referenced by playrec_open().

## vpb_close()

int WINAPI vpb_close | ( | VPBPortHandle | handle = VPB_PORTHANDLE_NULL | ) |

Close a previously opened port using the handle returned by `vpb_open()`.

Parameters

  handle | The handle returned by a call to `vpb_open()`. If not specified, this will close all currently open ports.

Returns
  `VPB_OK` if all goes well.

Exceptions

  various | exceptions may be thrown in the event of an error.

References APIQ, CheckHandle(), get_board_type(), Init, numboards, playrec_close(), soft_bridges, Totalchans, VPB_BRIDGE_OFF, vpb_c, vpb_dev, VPB_ON, VPB_V4LOG, and VPB_V4PCI.

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

int WINAPI vpb_disable_tone_event | ( | VPBPortHandle | handle,
|  | unsigned long | mask )

Disable the `TONE` events specified by mask for handle.

Events not included in the mask are unaffected.

References CheckHandle(), and vpb_dev.

## vpb_echo_canc_get_sup_thresh()

int WINAPI vpb_echo_canc_get_sup_thresh | ( | int | handle,
|  | short * | thresh )

Get the current echo suppressor threshold.

This threshold is the same for all channels on all cards.

Parameters

  handle | A handle to an open port on the card.
  thresh | The returned echo suppressor threshold value.

Note
  This function is only supported for `V4PCI` cards.

Exceptions

  VpbException | will be thrown in the event of an error.

References DD_PCI, and vpb_c.

## vpb_echo_canc_set_sup_thresh()

int WINAPI vpb_echo_canc_set_sup_thresh | ( | int | handle,
|  | short * | thresh )

Set the echo suppressor threshold.

This threshold is the same for all channels on all cards.

Parameters

  handle | A handle to an open port on the card.
  thresh | The echo suppressor threshold value. `0x1000` gives `-18db`, `0x800` gives `-24db`, `0x0` for no suppressor.

Note
  This function is only supported for `V4PCI` cards.

Exceptions

  VpbException | will be thrown in the event of an error.

References DD_PCI, and vpb_c.

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

int WINAPI vpb_enable_tone_event | ( | VPBPortHandle | handle,
|  | unsigned long | mask )

Enable the `TONE` events specified by mask for handle.

Events not included in the mask are unaffected.

References CheckHandle(), and vpb_dev.

## vpb_get_country_data() [1/2]

const Country *WINAPI vpb_get_country_data | ( | const std::string & | name | ) |

Get country specific data by name.

Parameters

  name | A country name from the list here.

Returns
  `NULL` if name is not a pre-defined country name.

Referenced by VTCore::Reset(), vpb_cid_compose_wav(), and vpb_cid_t2_compose_wav().

## vpb_get_country_data() [2/2]

const Country *WINAPI vpb_get_country_data | ( | int | code | ) |

Get country specific data by numeric country code.

Parameters

  code | The ITU-T numeric country calling code. A comprehensive list of the numeric country codes is available here: http://wikipedia.org/wiki/List_of_country_calling_codes

Returns
  `NULL` if code is not a pre-defined numeric country code.

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

HookState WINAPI vpb_get_hookstate | ( | VPBPortHandle | handle | ) |

Return the hook state of a port.

Parameters

  handle | The handle of the port to query.

Returns
  `VPB_ONHOOK` or `VPB_OFFHOOK` if the query succeeds.

Exceptions

  VpbException | will be thrown in the event of an error.

Warning
  In environments where asynchronous operations may take place on handle, the real state of the port may have already changed again by the time this function returns. It is the responsibility of the user application to determine how much trust may be placed in the accuracy of this value at any point in the code where it is used.

References CheckHandle(), VTCore::hook_state(), vpb_c, VPB_OPCI, VPB_OSW, VPB_PRI, VPB_V4LOG, and VPB_V4PCI.

## vpb_get_model() [1/2]

std::string WINAPI vpb_get_model | ( | VPBPortHandle | handle | ) |

Return a string indicating the board model.

Parameters

  handle | The handle to a port on the board to query.

Returns
  The model string.

Exceptions

  VpbException | will be thrown if the handle is invalid.

Note
  You should not rely on any particular value to be returned by this function, it is intended for user friendly output only. If you need to check the model programmatically, use the `vpb_get_card_type()` function instead.

References CheckHandle(), and get_board_model().

## vpb_get_model() [2/2]

int WINAPI vpb_get_model | ( | VPBPortHandle | handle,
|  | char * | str )

Return a string indicating the board model.

Parameters

  handle | The handle to a port on the board to query.
  str | The returned model string.

Returns
  `VPB_OK` if the handle is valid.

Exceptions

  VpbException | may be thrown if the handle is invalid.

Note
  You should not rely on any particular value to be returned by this function, it is intended for user friendly output only. If you need to check the model programmatically, use the `vpb_get_card_type()` function instead.

References CheckHandle(), and get_board_model().

## vpb_get_num_cards()

int WINAPI vpb_get_num_cards | ( |  | ) |

Return the number of cards in the system.

Note
  This function may be called prior to `vpb_open()`.

References numboards.

Referenced by get_total_port_count().

## vpb_get_ports_per_card()

int WINAPI vpb_get_ports_per_card | ( | int | board | ) |

Return the number of ports on board.

Parameters

  board | The board number, starting from 0.

Note
  This function may be called prior to `vpb_open()`.

References vpb_c.

Referenced by get_total_port_count().

## vpb_loopback_off()

int WINAPI vpb_loopback_off | ( | int | handle | ) |

Turns off software loop-back of tx->rx in the kernel.

Useful for echo testing.

Parameters

  handle | The handle of the port to disable loopback operations.

Returns
  `VPB_OK` if all went well.

Exceptions

  various | exceptions may be thrown if all did not go well.

Note
  This function is not supported for all hardware types.

See also
  vpb_loopback_on()

References vpb_c.

## vpb_loopback_on()

int WINAPI vpb_loopback_on | ( | int | handle | ) |

Turns on software loop-back of tx->rx in the kernel.

Useful for echo testing.

Parameters

  handle | The handle of the port to enable loopback operations.

Returns
  `VPB_OK` if all went well.

Exceptions

  various | exceptions may be thrown if all did not go well.

Note
  This function is not supported for all hardware types.

See also
  vpb_loopback_off()

References vpb_c.

## vpb_open()

VPBPortHandle WINAPI vpb_open | ( | unsigned int | board,
|  | unsigned int | port,
|  | VPBOpenMode | flags = VPB_OPEN_DEFAULTS )

Open a port on some board for use.

Parameters

  board | The board number, starting from 0.
  port | The port number on board, starting from 0.
  flags | The `VPBOpenMode` flags which indicate additional operations to perform when opening the port.

Returns
  A handle to pass to other vpbapi functions when performing operations on the port.

Note
  When `vpb_open` is called to open the first port it performs a number of static initialisation tasks that will run in the background. Those tasks may not have completed by the time vpb_open returns to the caller. For most applications, they will have had plenty of time to complete by the time any other ports have been opened and any app specific initialisation has been performed, but for very trivial applications you may need to delay briefly before performing subsequent operations on the port. You should likewise avoid repeatedly opening and closing single ports in a tight loop. Such code will perform much more efficiently if you simply open all the ports that you require to access, then call `vpb_close()` (without any handle parameter) to close them all again when you are done with them, as the bulk of the initialisation will only be run for the first call to `vpb_open` in that case, and will not need to be repeated while any ports continue to remain open.

References numboards, vpb_c, vpb_dev, VPB_MODEL_UNKNOWN, VPB_ON, VPB_OPCI, VPB_OPEN_RESET, VPB_OSW, VPB_PRI, vpb_reset(), VPB_V4LOG, and VPB_V4PCI.

## vpb_reset()

void WINAPI vpb_reset | ( | VPBPortHandle | handle = VPB_PORTHANDLE_NULL | ) |

Reset a port back to its idle state (on-hook, not ringing etc.).

Parameters

  handle | The handle returned by a call to `vpb_open()`. If not specified, then all open ports will be reset.

The precise action performed depends on the type of port that handle refers to, but after this call it should be in the same state as it would be when initially powered up from a cold start.

Any hardware gains will be restored to their default levels, or to the levels specified if configuration files are present.

The locale specific hardware configuration will be reset according to (in order of priority):

1. The value explicitly set by a previous call to `vpb_set_country()`.
2. A port-specific `country` value specified in the configuration files.
3. The value of the `VPB_COUNTRY` environment variable.
4. The global locale selection specified in the configuration files.
5. The hardcoded default (ie. AUSTRALIA).

References CheckHandle(), Totalchans, vpb_c, vpb_dev, vpb_flush_digits(), vpb_flush_events(), VPB_FXO, VPB_FXS, vpb_get_port_type(), vpb_log_terminate(), vpb_monitor_terminate(), VPB_ON, VPB_ONHOOK, vpb_play_terminate(), VPB_PORT_UNKNOWN, vpb_record_terminate(), vpb_reset(), vpb_ring_station_async(), VPB_RING_STATION_OFF, vpb_sethook_async(), and vpb_tone_terminate().

Referenced by vpb_open(), and vpb_reset().

## vpb_ring_station_async()

void WINAPI vpb_ring_station_async | ( | VPBPortHandle | handle,
|  | int | cadence = -1 )

Start or stop a station port ringing.

Parameters

  handle | The handle of the port to control.
  cadence | The ring cadence value.

If the cadence parameter is not specified, the default cadence for a normal ring according to the port's country setting will be used. The valid cadence values are defined as follows:

- `0` - Stop ringing.
- `1` - Ring a guard tone cadence. Often used before sending caller id.
- `2` - Normal ring for Australian phone networks. (DR0)
- `3-9` - `DR1` to `DR7` of the `AS/ACIF` S002:2001 distinctive ring series.
- `10` - US ring cadence.

There is an additional special ring cadence `255`, which like `0`, stops the station ringing, but in addition will signal an OpenPCI `FXS` port to enter a mode where caller id information can be transmitted to a handset that is still on hook. ie. for US style caller id, you would generate one second of cadence `1` tone, stopped by a cadence `255` signal. The caller id tones can then be sent, and normal ringing commenced using cadence `2` - `10`. Convenience functions to do this are provided with the CTPort interface to ctserver.

Note
  Distinctive ring cadences are not supported by the OpenSwitch cards at the time of writing. Values `1` - `10` will all cause its normal ring cadence to be generated.

See also
  vpb_ring_with_cid()

References CheckHandle(), and ring_station_async().

Referenced by vpb_reset(), and vpb_ring_with_cid().

## vpb_set_country() [1/2]

void WINAPI vpb_set_country | ( | const Country * | country | ) |

Set the global default country specific information.

This data will be used for ports that have not had their country data set individually. If country is `NULL` it will restore the initial hardcoded default country settings (ie. AUSTRALIA).

References VPBREG::country, VPBREG::hostdsp, VPBREG::numch, HostDSP::SetCountry(), and vpb_c.

## vpb_set_country() [2/2]

int WINAPI vpb_set_country | ( | VPBPortHandle | handle,
|  | const Country * | country )

Set the country specific information for an individual port.

This will override the default country data for handle. If country is `NULL`, then handle will revert to using the global default data.

References CheckHandle(), and set_country().

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

void WINAPI vpb_set_flashtime | ( | VPBPortHandle | handle,
|  | uint16_t | min,
|  | uint16_t | max )

Set the window for detecting flash events on OpenPCI cards.

For FXS ports, this is automatically configured according to the locale specific values in the `Country` structure. For FXO ports, flash events are only generated if this function has been explicitly called (this is to maintain compatibility with older applications which manually processed the raw on/off hook events themselves).

Parameters

  handle | The handle of the port to configure.
  min | The minimum on-hook time for a valid flash signal in `ms`.
  max | The maximum on-hook time for a valid flash signal in `ms`.

References CheckHandle(), VPBREG::hostdsp, HostDSP::SetFlashTime(), and vpb_c.

## Variable Documentation

## au_tones

VPB_TONE au_tones[]

static

Initial value:
= {
{ 400, 425, 450, -13, -13, -13, 0, 0, NULL },
au_ring,
{ 400, 0, 0, -13, 0, 0, 375, 375, &au_tones[VPB_TONE_BUSY] },
{ 400, 0, 0, -23, 0, 0, 375, 375, &au_tones[VPB_TONE_BUSY] },
{ 400, 0, 0, -13, 0, 0, 2500, 500, &au_tones[VPB_TONE_UNOBTAINABLE] },
au_callwaiting,
{ 400, 425, 450, -13, -13, -13, 100, 40, &au_tones[VPB_TONE_STUTTERDIAL] }
}
VPB_TONE_UNOBTAINABLE
@ VPB_TONE_UNOBTAINABLE
Invalid number signal.
Definition vpbapi.h:1431
VPB_TONE_BUSY
@ VPB_TONE_BUSY
Called number busy tone.
Definition vpbapi.h:1429
VPB_TONE_STUTTERDIAL
@ VPB_TONE_STUTTERDIAL
Voicemail pending signal.
Definition vpbapi.h:1433

## jp_tones

VPB_TONE jp_tones[]

static

Initial value:
= {
{ 400, 0, 0, -13, 0, 0, 0, 0, NULL },
{ 390, 410, 0, -13, -13, 0, 1000, 2000, &jp_tones[VPB_TONE_RINGING] },
{ 400, 0, 0, -13, 0, 0, 500, 500, &jp_tones[VPB_TONE_BUSY] },
jp_tones[VPB_TONE_BUSY],
jp_tones[VPB_TONE_BUSY],
jp_callwaiting,
{ 400, 0, 0, -13, 0, 0, 125, 100, &jp_tones[VPB_TONE_STUTTERDIAL] },
}
VPB_TONE_RINGING
@ VPB_TONE_RINGING
Normal ringing tone.
Definition vpbapi.h:1428

## sg_tones

VPB_TONE sg_tones[]

static

Initial value:
= {
sg_dial,
sg_ring,
{ 425, 0, 0, -10, 0, 0, 750, 750, &sg_tones[VPB_TONE_BUSY] },
{ 425, 0, 0, -10, 0, 0, 250, 250, &sg_tones[VPB_TONE_CONGESTION] },
{ 425, 0, 0, -10, 0, 0, 2500, 550, &sg_tones[VPB_TONE_UNOBTAINABLE] },
sg_callwaiting,
sg_stutter
}
VPB_TONE_CONGESTION
@ VPB_TONE_CONGESTION
Network congestion tone.
Definition vpbapi.h:1430

## toned_dial

VPB_DETECT toned_dial

static

Initial value:
= {
2,
VPB_DIAL,
1,
400,
100,
0,
0,
-40,
0,
0,
10,
40,
{
{
VPB_RISING,
0,
0,
0
},
{
VPB_TIMER,
3000,
0,
0
}
}
}
VPB_DIAL
#define VPB_DIAL
dial tone detected (US/Aust/sudio308)
Definition vpbapi.h:1632

## toned_ringback_308

VPB_DETECT toned_ringback_308

static

Initial value:
= {
2,
VPB_RINGBACK_308,
1,
425,
100,
0,
0,
-20,
0,
0,
10,
40,
{
{
VPB_RISING,
0,
0,
0
},
{
VPB_FALLING,
0,
800,
1200
}
}
}
VPB_RINGBACK_308
#define VPB_RINGBACK_308
ringback detected (studio 308)
Definition vpbapi.h:1636

## toned_ringback_us

VPB_DETECT toned_ringback_us

static

Initial value:
= {
2,
VPB_RINGBACK,
1,
425,
200,
0,
0,
-20,
0,
0,
10,
40,
{
{
VPB_RISING,
0,
0,
0
},
{
VPB_FALLING,
0,
1600,
2400
}
}
}
VPB_RINGBACK
#define VPB_RINGBACK
ringback detected (US)
Definition vpbapi.h:1633

## uk_tones

VPB_TONE uk_tones[]

static

Initial value:
= {
{ 350, 440, 0, -13, -13, 0, 0, 0, NULL },
uk_ring,
au_tones[VPB_TONE_BUSY],
uk_congestion,
{ 400, 0, 0, -13, 0, 0, 0, 0, NULL },
{ 400, 0, 0, -13, 0, 0, 100, 2000, &uk_tones[VPB_TONE_CALLWAITING] },
{ 350, 440, 0, -13, -13, 0, 750, 750, &uk_tones[VPB_TONE_STUTTERDIAL] }
}
VPB_TONE_CALLWAITING
@ VPB_TONE_CALLWAITING
Call waiting signal.
Definition vpbapi.h:1432

## us_tones

VPB_TONE us_tones[]

static

Initial value:
= {
us_dial,
{ 440, 480, 0, -19, -19, 0, 2000, 4000, &us_tones[VPB_TONE_RINGING] },
{ 480, 620, 0, -24, -24, 0, 500, 500, &us_tones[VPB_TONE_BUSY] },
{ 480, 620, 0, -24, -24, 0, 250, 250, &us_tones[VPB_TONE_CONGESTION] },
us_sit,
{ 440, 0, 0, -13, 0, 0, 300, 10000, &us_tones[VPB_TONE_CALLWAITING] },
us_stutter
}

## vpb_c

Comm* vpb_c

Global `Comm` object.

Pointer to the global comm object.

Referenced by get_board_model(), get_board_type(), get_country(), get_driver_type(), get_port_type(), play_reset_hw_gain(), playrec_open(), record_reset_hw_gain(), VTCore::Reset(), ring_station_async(), set_country(), OpenPri::SetHookState(), V4PCI_DSP::SetHookState(), vpb_bridge(), vpb_close(), vpb_debug_tonedet(), vpb_echo_canc_get_sup_thresh(), vpb_echo_canc_set_sup_thresh(), vpb_get_card_info(), vpb_get_hookstate(), vpb_get_ports_per_card(), vpb_hostecho_off(), vpb_hostecho_on(), vpb_listen(), vpb_loopback_off(), vpb_loopback_on(), vpb_monitor_audio(), vpb_monitor_terminate(), vpb_open(), vpb_play_get_hw_gain(), vpb_play_set_hw_gain(), vpb_playtone_state(), vpb_record_get_hw_gain(), vpb_record_set_hw_gain(), vpb_reset(), vpb_set_country(), vpb_set_flashtime(), vpb_sethook_async(), and vpb_tone_terminate().