libvpb  4.2.61
Port initialisation
Collaboration diagram for Port initialisation:

Modules

 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. More...
 
void WINAPI vpb_reset (VPBPortHandle handle=VPB_PORTHANDLE_NULL)
 Reset a port back to its idle state (on-hook, not ringing etc.) More...
 
int WINAPI vpb_close (VPBPortHandle handle=VPB_PORTHANDLE_NULL)
 Close a previously opened port using the handle returned by vpb_open(). More...
 

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
handleThe 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
variousexceptions may be thrown in the event of an error.

◆ 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
boardThe board number, starting from 0.
portThe port number on board, starting from 0.
flagsThe 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.

◆ 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
handleThe 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).