Loading...
Searching...
No Matches
Port initialisation
Public API functions
Collaboration diagram for Port initialisation:

## Topics

| Card information

## Typedefs

typedef int | VPBOpenMode
| Symbolic type for `vpb_open()` mode flags.

## mode flags for vpb_open()

const VPBOpenMode | VPB_OPEN_NONE = 0x00
| Just open the port.
const VPBOpenMode | VPB_OPEN_RESET = 0x10
| Reset the port state.
const VPBOpenMode | VPB_OPEN_DEFAULTS = VPB_OPEN_RESET
| The default flags for `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.
void WINAPI | vpb_reset (VPBPortHandle handle=VPB_PORTHANDLE_NULL)
| Reset a port back to its idle state (on-hook, not ringing etc.).
int WINAPI | vpb_close (VPBPortHandle handle=VPB_PORTHANDLE_NULL)
| Close a previously opened port using the handle returned by `vpb_open()`.

## Detailed Description

## Function Documentation

## 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_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().