Main Page | Modules | Class Hierarchy | Alphabetical List | Class List | File List | Class Members | File Members

Capi Class Reference

Main Class for communication with CAPI. More...

#include <capi.h>

List of all members.

Public Member Functions

 Capi (ostream &debug, unsigned short debug_level, ostream &error, unsigned short DDILength=0, unsigned short DDIBaseLength=0, vector< string > DDIStopNumbers=vector< string >(), unsigned maxLogicalConnection=2, unsigned maxBDataBlocks=7, unsigned maxBDataLen=2048) throw (CapiError, CapiMsgError)
 Constructor. Registers our App at CAPI and start the communication thread.
 ~Capi ()
 Destructor. Unregister App at CAPI.
void registerApplicationInterface (ApplicationInterface *application_in)
 Register the instance implementing the ApplicationInterface.
void setListenFaxG3 (_cdword Controller=0) throw (CapiMsgError,CapiError)
 Tell capi that we want to _additionally_ listen to Fax G3 calls.
void setListenTelephony (_cdword Controller=0) throw (CapiMsgError,CapiError)
 Tell capi that we want to _additionally_ listen to Telephony calls.
string getInfo (bool verbose=false)
 Static Returns some info about the installed Controllers.

Private Member Functions

void unregisterConnection (_cdword plci)
 erase Connection object in connections map
void readProfile () throw (CapiMsgError)
 Get informations about CAPI driver and installed controllers.
void listen_req (_cdword Controller, _cdword InfoMask=0x03FF, _cdword CIPMask=0x1FFF03FF) throw (CapiMsgError)
 Send LISTEN_REQ to CAPI.
void alert_req (_cdword plci) throw (CapiMsgError)
 Send ALERT_REQ to CAPI.
void connect_req (Connection *conn, _cdword Controller, _cword CIPvalue, _cstruct calledPartyNumber, _cstruct callingPartyNumber, _cword B1protocol, _cword B2protocol, _cword B3protocol, _cstruct B1configuration, _cstruct B2configuration, _cstruct B3configuration) throw (CapiMsgError)
 Send CONNECT_REQ to CAPI.
void select_b_protocol_req (_cdword plci, _cword B1protocol, _cword B2protocol, _cword B3protocol, _cstruct B1configuration, _cstruct B2configuration, _cstruct B3configuration) throw (CapiMsgError)
 send SELECT_B_PROTOCOL_REQ to CAPI
void connect_b3_req (_cdword plci) throw (CapiMsgError)
 send CONNECT_B3_REQ to CAPI
void data_b3_req (_cdword ncci, void *Data, _cword DataLength, _cword DataHandle, _cword Flags) throw (CapiMsgError)
 send DATA_B3_REQ to CAPI
void disconnect_b3_req (_cdword ncci, _cstruct ncpi=NULL) throw (CapiMsgError)
 send DISCONNECT_B3_REQ to CAPI
void disconnect_req (_cdword plci, _cstruct Keypadfacility=NULL, _cstruct Useruserdata=NULL, _cstruct Facilitydataarray=NULL) throw (CapiMsgError)
 send DISCONNECT_REQ to CAPI
void facility_req (_cdword address, _cword FacilitySelector, _cstruct FacilityRequestParameter) throw (CapiMsgError)
 send FACILITY_REQ to CAPI
void connect_resp (_cword messageNumber, _cdword plci, _cword reject, _cword B1protocol, _cword B2protocol, _cword B3protocol, _cstruct B1configuration, _cstruct B2configuration, _cstruct B3configuration) throw (CapiMsgError)
 send CONNECT_RESP to CAPI
void connect_active_resp (_cword messageNumber, _cdword plci) throw (CapiMsgError)
 send CONNECT_ACTIVE_RESP to CAPI
void connect_b3_resp (_cword messageNumber, _cdword ncci, _cword reject, _cstruct ncpi) throw (CapiMsgError)
 send CONNECT_B3_RESP to CAPI
void connect_b3_active_resp (_cword messageNumber, _cdword ncci) throw (CapiMsgError)
 send CONNECT_B3_ACTIVE_RESP to CAPI
void data_b3_resp (_cword messageNumber, _cdword ncci, _cword dataHandle) throw (CapiMsgError)
 send DATA_B3_RESP to CAPI
void facility_resp (_cword messageNumber, _cdword address, _cword facilitySelector, _cstruct facilityResponseParameter=NULL) throw (CapiMsgError)
 send FACILITY_RESP to CAPI
void info_resp (_cword messageNumber, _cdword address) throw (CapiMsgError)
 send INFO_RESP to CAPI
void disconnect_resp (_cword messageNumber, _cdword plci) throw (CapiMsgError)
 send DISCONNECT_RESP to CAPI
void disconnect_b3_resp (_cword messageNumber, _cdword ncci) throw (CapiMsgError)
 send DISCONNECT_B3_RESP to CAPI
void readMessage (void) throw (CapiMsgError, CapiError, CapiWrongState, CapiExternalError)
 read Message from CAPI and process it accordingly
unsigned short getApplId (void)
 getApplId returns the application id we got from CAPI
virtual void run (void)
 Thread body - endless loop, will be blocked until message is received and then call readMessage().
string prefix ()
 return a prefix containing this pointer and date for log messages

Static Private Member Functions

string describeParamInfo (unsigned int info)
 textual description for Parameter Info

Private Attributes

short numControllers
 number of installed controllers, set by readProfile() method
string capiManufacturer
 manufacturer of the general CAPI driver
string capiVersion
 version of the general CAPI driver
unsigned short DDILength
 length of extension number (DDI) when ISDN PtP mode is used (0=PtMP)
unsigned short DDIBaseLength
 base number length for the ISDN interface if PtP mode is used
vector< string > DDIStopNumbers
 list of DDIs shorten than DDILength we'll accept
vector< CardProfileTprofiles
map< _cdword, Connection * > connections
 objects, referenced by PLCI (or 0xFACE & messageNum when Connection is in plci_state Connection::P01
_cword messageNumber
 sequencial message number, must be increased for every sent message
_cdword usedInfoMask
 InfoMask currently used (in last listen_req).
_cdword usedCIPMask
 CIPMask currently used (in last listen_req).
unsigned applId
 containing the ID we got from CAPI after successful registration
ApplicationInterfaceapplication
 pointer to the application object implementing ApplicationInterface
ostream & debug
 stream to write debug info to
ostream & error
 stream for error messages
unsigned short debug_level
 debug level
pthread_t thread_handle
 handle for the created message reading thread

Friends

void * capi_exec_handler (void *)
 Thread exec handler for Capi class.


Detailed Description

Main Class for communication with CAPI.

This class is the main encapsulation to use the CAPI ISDN interface.

There are only a small subset of methods which are of use for the application layer. These are for general purposes like enabling listening to calls and getting some nice formatted info strings.

The biggest amount are shadow methods for nearly all CAPI messages, which do the dumb stuff like increasing message numbers, testing for errors, building message structures and so on. Not each parameter of these is described in every detail here. For more details please have a look in the CAPI 2.0 specification, available from http://www.capi.org

There's also a big message handling routine (readMessage()) which calls special handlers for incoming messages of the CAPI.

A Capi object creates a new thread (with body run()) which waits for incoming messages in an endless loop and hands them to readMessage().

This class only does the general things - for handling single connections see Connection. Connection objects will be automatically created by this class for incoming connections and can be created manually to initiate an outgoing connection.

The application is supposed to create one single object of this class.

To communicate with the application via callback functions, the application must provide an implementation of the ApplicationInterface. The methods of this interface are called when some special events are received.

Author:
Gernot Hillier


Constructor & Destructor Documentation

Capi::Capi ostream &  debug,
unsigned short  debug_level,
ostream &  error,
unsigned short  DDILength = 0,
unsigned short  DDIBaseLength = 0,
vector< string >  DDIStopNumbers = vector< string >(),
unsigned  maxLogicalConnection = 2,
unsigned  maxBDataBlocks = 7,
unsigned  maxBDataLen = 2048
throw (CapiError, CapiMsgError)
 

Constructor. Registers our App at CAPI and start the communication thread.

Parameters:
debug reference to a ostream object where debug info should be written to
debug_level verbosity level for debug messages
error reference to a ostream object where errors should be written to
DDILength if ISDN interface is in PtP mode, the length of the DDI must be set here. 0 means disabled (PtMP)
DDIBaseLength the base number length w/o extension (and w/o 0) if DDI is used
DDIStopNumbers list of DDIs shorter than DDILength we will accept
maxLogicalConnection max. number of logical connections we will handle
maxBDataBlocks max. number of unconfirmed B3-datablocks, 7 is the maximum supported by CAPI
maxBDataLen max. B3-Datablocksize, 2048 is the maximum supported by CAPI
Exceptions:
CapiError Thrown if no ISDN controller is reported by CAPI
CapiMsgError Thrown if registration at CAPI wasn't successful.

Capi::~Capi  ) 
 

Destructor. Unregister App at CAPI.

Exceptions:
CapiMsgError Thrown if deregistration at CAPI failed.


Member Function Documentation

void Capi::alert_req _cdword  plci  )  throw (CapiMsgError) [private]
 

Send ALERT_REQ to CAPI.

Parameters:
plci reference to physical connection
Exceptions:
CapiMsgError Thrown when CAPI_PUT_MESSAGE returned an error.

void Capi::connect_active_resp _cword  messageNumber,
_cdword  plci
throw (CapiMsgError) [private]
 

send CONNECT_ACTIVE_RESP to CAPI

Parameters:
messageNumber number of the referred INDICATION message
plci reference to physical connection
Exceptions:
CapiMsgError Thrown when CAPI_PUT_MESSAGE returned an error.

void Capi::connect_b3_active_resp _cword  messageNumber,
_cdword  ncci
throw (CapiMsgError) [private]
 

send CONNECT_B3_ACTIVE_RESP to CAPI

Parameters:
messageNumber number of the referred INDICATION message
ncci reference to physical connection
Exceptions:
CapiMsgError Thrown when CAPI_PUT_MESSAGE returned an error.

void Capi::connect_b3_req _cdword  plci  )  throw (CapiMsgError) [private]
 

send CONNECT_B3_REQ to CAPI

Parameters:
plci reference to physical connection
Exceptions:
CapiMsgError Thrown when CAPI_PUT_MESSAGE returned an error.

void Capi::connect_b3_resp _cword  messageNumber,
_cdword  ncci,
_cword  reject,
_cstruct  ncpi
throw (CapiMsgError) [private]
 

send CONNECT_B3_RESP to CAPI

Parameters:
messageNumber number of the referred INDICATION message
ncci reference to physical connection
reject tell CAPI if we want to accept (0) or reject (2) the incoming call
ncpi protocol specific info
Exceptions:
CapiMsgError Thrown when CAPI_PUT_MESSAGE returned an error.

void Capi::connect_req Connection conn,
_cdword  Controller,
_cword  CIPvalue,
_cstruct  calledPartyNumber,
_cstruct  callingPartyNumber,
_cword  B1protocol,
_cword  B2protocol,
_cword  B3protocol,
_cstruct  B1configuration,
_cstruct  B2configuration,
_cstruct  B3configuration
throw (CapiMsgError) [private]
 

Send CONNECT_REQ to CAPI.

To be able to see which CONNECT_CONF corresponds to this CONNECT_REQ, the Connection object will be saved in the connections map under a pseudo PLCI (0xFACE & messageNumber). This will be corrected at the moment the CONNECT_CONF is received.

Parameters:
conn reference to the Connection object which calls connect_req()
Controller Nr. of controller to use for connection establishment
CIPvalue CIP (service indicator) to use for the connection
calledPartyNumber The number of the party which is called (i.e. the destination of the call)
callingPartyNumber The number of the party which calls (i.e. the source of the call)
B1protocol see CAPI spec for details
B2protocol see CAPI spec for details
B3protocol see CAPI spec for details
B1configuration see CAPI spec for details
B2configuration see CAPI spec for details
B3configuration see CAPI spec for details
Exceptions:
CapiMsgError Thrown when CAPI_PUT_MESSAGE returned an error.

void Capi::connect_resp _cword  messageNumber,
_cdword  plci,
_cword  reject,
_cword  B1protocol,
_cword  B2protocol,
_cword  B3protocol,
_cstruct  B1configuration,
_cstruct  B2configuration,
_cstruct  B3configuration
throw (CapiMsgError) [private]
 

send CONNECT_RESP to CAPI

Parameters:
messageNumber number of the referred INDICATION message
plci reference to physical connection
reject tell CAPI if we want to accept (0) or reject (!=0, for details see CAPI spec) the incoming call
B1protocol see CAPI spec for details
B2protocol see CAPI spec for details
B3protocol see CAPI spec for details
B1configuration see CAPI spec for details
B2configuration see CAPI spec for details
B3configuration see CAPI spec for details
Exceptions:
CapiMsgError Thrown when CAPI_PUT_MESSAGE returned an error.

void Capi::data_b3_req _cdword  ncci,
void *  Data,
_cword  DataLength,
_cword  DataHandle,
_cword  Flags
throw (CapiMsgError) [private]
 

send DATA_B3_REQ to CAPI

Parameters:
ncci reference to physical connection
Data pointer to transmission data
DataLength length of transmission data
DataHandle some word value which will be referred to in DATA_B3_CONF (to see which data packet was sent successful)
Flags see CAPI 2.0 spec
Exceptions:
CapiMsgError Thrown when CAPI_PUT_MESSAGE returned an error.

void Capi::data_b3_resp _cword  messageNumber,
_cdword  ncci,
_cword  dataHandle
throw (CapiMsgError) [private]
 

send DATA_B3_RESP to CAPI

Parameters:
messageNumber number of the referred INDICATION message
ncci reference to physical connection
dataHandle Data Handle given by the referred DATA_B3_IND
Exceptions:
CapiMsgError Thrown when CAPI_PUT_MESSAGE returned an error.

string Capi::describeParamInfo unsigned int  info  )  [static, private]
 

textual description for Parameter Info

This method returns an error string for the given info parameter. The strings were taken out of the CAPI 2.0 spec

Parameters:
info errorcode as given by CAPI
Returns:
textual description of error

void Capi::disconnect_b3_req _cdword  ncci,
_cstruct  ncpi = NULL
throw (CapiMsgError) [private]
 

send DISCONNECT_B3_REQ to CAPI

Parameters:
ncci reference to physical connection
ncpi protocol specific info
Exceptions:
CapiMsgError Thrown when CAPI_PUT_MESSAGE returned an error.

void Capi::disconnect_b3_resp _cword  messageNumber,
_cdword  ncci
throw (CapiMsgError) [private]
 

send DISCONNECT_B3_RESP to CAPI

Parameters:
messageNumber number of the referred INDICATION message
ncci reference to physical connection
Exceptions:
CapiMsgError Thrown when CAPI_PUT_MESSAGE returned an error.

void Capi::disconnect_req _cdword  plci,
_cstruct  Keypadfacility = NULL,
_cstruct  Useruserdata = NULL,
_cstruct  Facilitydataarray = NULL
throw (CapiMsgError) [private]
 

send DISCONNECT_REQ to CAPI

Parameters:
plci reference to physical connection
Keypadfacility see CAPI spec
Useruserdata see CAPI spec
Facilitydataarray see CAPI spec
Exceptions:
CapiMsgError Thrown when CAPI_PUT_MESSAGE returned an error.

void Capi::disconnect_resp _cword  messageNumber,
_cdword  plci
throw (CapiMsgError) [private]
 

send DISCONNECT_RESP to CAPI

Parameters:
messageNumber number of the referred INDICATION message
plci reference to physical connection
Exceptions:
CapiMsgError Thrown when CAPI_PUT_MESSAGE returned an error.

void Capi::facility_req _cdword  address,
_cword  FacilitySelector,
_cstruct  FacilityRequestParameter
throw (CapiMsgError) [private]
 

send FACILITY_REQ to CAPI

Parameters:
address Nr. of connection (Controller/PLCI/NCCI)
FacilitySelector see CAPI spec (1=DTMF)
FacilityRequestParameter see CAPI spec (too long to describe it here...)
Exceptions:
CapiMsgError Thrown when CAPI_PUT_MESSAGE returned an error.

void Capi::facility_resp _cword  messageNumber,
_cdword  address,
_cword  facilitySelector,
_cstruct  facilityResponseParameter = NULL
throw (CapiMsgError) [private]
 

send FACILITY_RESP to CAPI

Parameters:
messageNumber number of the referred INDICATION message
address Nr. of connection (Controller/PLCI/NCCI)
facilitySelector see CAPI spec (1=DTMF)
facilityResponseParameter see CAPI spec
Exceptions:
CapiMsgError Thrown when CAPI_PUT_MESSAGE returned an error.

unsigned short Capi::getApplId void   )  [inline, private]
 

getApplId returns the application id we got from CAPI

Returns:
Application ID from CAPI

string Capi::getInfo bool  verbose = false  ) 
 

Static Returns some info about the installed Controllers.

The returned string has the following format (UPPERCASE words replaced):

"NUM controllers found. CAPI_MANUFACTURER, version VERSION_OF_CAPI/SUBVERSION_OF_CAPI Controller X: CONTROLLER_MANUFACTURER (NUM B channels, SERVICE1, SERVICE2, ..., driver version DRIVER_VERSION/DRIVER_SUBVERSION Controller X+1: CONTROLLER_MANUFACTURER (NUM B channels, SERVICE1, SERVICE2, ..., driver version DRIVER_VERSION/DRIVER_SUBVERSION ..."

If verbose is set to false, only the first line is returned.

The following services are checked currently and printed as SERVICEX if found: DTMF, SuppServ, transparent, FaxG3, FaxG3ext

The method uses values stored by readProfile which must have been called before (constructor does it).

Parameters:
verbose controls verbosity of output (see above).
Returns:
string containing details (see above).

void Capi::info_resp _cword  messageNumber,
_cdword  address
throw (CapiMsgError) [private]
 

send INFO_RESP to CAPI

Parameters:
messageNumber number of the referred INDICATION message
address Nr. of connection (Controller/PLCI)
Exceptions:
CapiMsgError Thrown when CAPI_PUT_MESSAGE returned an error.

void Capi::listen_req _cdword  Controller,
_cdword  InfoMask = 0x03FF,
_cdword  CIPMask = 0x1FFF03FF
throw (CapiMsgError) [private]
 

Send LISTEN_REQ to CAPI.

Parameters:
Controller Nr. of Controller
InfoMask see CAPI 2.0 spec, ch 5.37, default = 0x03FF -> all available info elements
CIPMask see CAPI 2.0 spec, ch 5.37, default = 0x1FFF03FF -> all available services
Exceptions:
CapiMsgError Thrown when CAPI_PUT_MESSAGE returned an error.

string Capi::prefix  )  [private]
 

return a prefix containing this pointer and date for log messages

Returns:
constructed prefix as string

void Capi::readMessage void   )  throw (CapiMsgError, CapiError, CapiWrongState, CapiExternalError) [private]
 

read Message from CAPI and process it accordingly

This method handles all incoming messages. It is called by run() and will call special handler methods of Connection mainly. Prints messages for debug purposes.

Exceptions:
CapiMsgError directly raised when CAPI_GET_MESSAGE or LISTEN_REQ fails, may also be raised by all called *_ind, *_conf handlers
CapiError directly raised when general error occurs (unknown call references, unknown message, ... received)
CapiWrongState may be raised by all called *_ind(), *_conf() handlers
CapiExternalError may be raised by some called *_ind(), *_conf() handlers

void Capi::readProfile  )  throw (CapiMsgError) [private]
 

Get informations about CAPI driver and installed controllers.

Fills the members profiles, capiVersion, capiManufacturer, numControllers

Exceptions:
CapiMsgError Thrown when requesting information fails

void Capi::registerApplicationInterface ApplicationInterface application_in  ) 
 

Register the instance implementing the ApplicationInterface.

Parameters:
application_in pointer to a class implementing (derived from) ApplicationInterface

void Capi::run void   )  [private, virtual]
 

Thread body - endless loop, will be blocked until message is received and then call readMessage().

void Capi::select_b_protocol_req _cdword  plci,
_cword  B1protocol,
_cword  B2protocol,
_cword  B3protocol,
_cstruct  B1configuration,
_cstruct  B2configuration,
_cstruct  B3configuration
throw (CapiMsgError) [private]
 

send SELECT_B_PROTOCOL_REQ to CAPI

Parameters:
plci reference to physical connection
B1protocol see CAPI spec for details
B2protocol see CAPI spec for details
B3protocol see CAPI spec for details
B1configuration see CAPI spec for details
B2configuration see CAPI spec for details
B3configuration see CAPI spec for details
Exceptions:
CapiMsgError Thrown when CAPI_PUT_MESSAGE returned an error.

void Capi::setListenFaxG3 _cdword  Controller = 0  )  throw (CapiMsgError,CapiError)
 

Tell capi that we want to _additionally_ listen to Fax G3 calls.

This method enables listening to fax calls from the analog network (coded as Bearer Capability 3.1kHz audio and from ISDN coded as fax group 3. The previously set listen mask is not cleared, so that the application can call this method after another listen request w/o loosing the other services.

It will also check if this controller is able to handle this service and throw an error otherwise.

Parameters:
Controller Nr. of Controller (0 = all available controllers)
Exceptions:
CapiMsgError Thrown by listen_req, see there for details
CapiError Thrown if the given controller can't handle fax group 3

void Capi::setListenTelephony _cdword  Controller = 0  )  throw (CapiMsgError,CapiError)
 

Tell capi that we want to _additionally_ listen to Telephony calls.

This method enables listening to speech calls from the analog network (coded as Bearer Capability 3.1kHz audio) and from ISDN (coded as Bearer Capability Speech or High Layer Compatibility telephony). The previously set listen mask is not cleared, so that the application can call this method after another listen request w/o loosing the other services.

It will also check if this controller is able to handle this service and throw an error otherwise.

Parameters:
Controller Nr. of Controller (0 = all available controllers)
Exceptions:
CapiMsgError Thrown by listen_req, see there for details
CapiError Thrown if the given controller can't handle fax group 3

void Capi::unregisterConnection _cdword  plci  )  [private]
 

erase Connection object in connections map

This method is used by Connection::~Connection()


Friends And Related Function Documentation

void* capi_exec_handler void *   )  [friend]
 

Thread exec handler for Capi class.

This is a handler which will call this->run() for the use in pthread_create().


Member Data Documentation

ApplicationInterface* Capi::application [private]
 

pointer to the application object implementing ApplicationInterface

unsigned Capi::applId [private]
 

containing the ID we got from CAPI after successful registration

string Capi::capiManufacturer [private]
 

manufacturer of the general CAPI driver

string Capi::capiVersion [private]
 

version of the general CAPI driver

map<_cdword,Connection*> Capi::connections [private]
 

objects, referenced by PLCI (or 0xFACE & messageNum when Connection is in plci_state Connection::P01

containing pointers to the currently active Connection

unsigned short Capi::DDIBaseLength [private]
 

base number length for the ISDN interface if PtP mode is used

unsigned short Capi::DDILength [private]
 

length of extension number (DDI) when ISDN PtP mode is used (0=PtMP)

vector<string> Capi::DDIStopNumbers [private]
 

list of DDIs shorten than DDILength we'll accept

ostream& Capi::debug [private]
 

stream to write debug info to

unsigned short Capi::debug_level [private]
 

debug level

ostream & Capi::error [private]
 

stream for error messages

_cword Capi::messageNumber [private]
 

sequencial message number, must be increased for every sent message

short Capi::numControllers [private]
 

number of installed controllers, set by readProfile() method

vector<CardProfileT> Capi::profiles [private]
 

vector containing profiles for all found cards (ATTENTION: starts with index 0, while CAPI numbers controllers starting by 1 (sigh)

pthread_t Capi::thread_handle [private]
 

handle for the created message reading thread

_cdword Capi::usedCIPMask [private]
 

CIPMask currently used (in last listen_req).

_cdword Capi::usedInfoMask [private]
 

InfoMask currently used (in last listen_req).


The documentation for this class was generated from the following files:
Generated on Sun Nov 28 14:37:44 2004 for CapiSuite by doxygen 1.3.8