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

Connection Class Reference

Encapsulates a CAPI connection with all its states and methods. More...

#include <connection.h>

List of all members.

Public Types

enum  service_t { VOICE, FAXG3, OTHER }
 Type for describing the service of incoming and outgoing calls. More...
enum  disconnect_mode_t { ALL, PHYSICAL_ONLY, LOGICAL_ONLY }
 Tells disconnectCall() method how to disconnect. More...
enum  connection_state_t { DOWN, WAITING, UP, OTHER_STATE }
 Represents the current connection state in an easy way. More...

Public Member Functions

 Connection (Capi *capi, _cdword controller, string call_from, bool clir, string call_to, service_t service, string faxStationID, string faxHeadline) throw (CapiExternalError, CapiMsgError)
 Constructor. Create an object to initiate an outgoing call.
 ~Connection ()
 . Destructor. Deletes the connection object.
void registerCallInterface (CallInterface *call_if)
 Register the instance implementing the CallInterface.
void changeProtocol (service_t desired_service, string faxStationID, string faxHeadline) throw (CapiMsgError, CapiExternalError, CapiWrongState)
 Change the used B protcols (e.g. switch from speech to faxG3).
void start_file_transmission (string filename) throw (CapiError,CapiWrongState,CapiExternalError,CapiMsgError)
 called to start sending of a file
void stop_file_transmission ()
 called to stop sending of the current file, will block until file is really finished
void start_file_reception (string filename) throw (CapiWrongState, CapiExternalError)
 called to activate receive mode
void stop_file_reception ()
 called to stop receive mode
void disconnectCall (disconnect_mode_t disconnect_mode=ALL) throw (CapiMsgError)
 Terminate this connection.
void connectWaiting (service_t desired_service, string faxStationID="", string faxHeadline="") throw (CapiWrongState,CapiExternalError,CapiMsgError)
 Accept a waiting incoming call.
void rejectWaiting (_cword reject) throw (CapiWrongState, CapiMsgError, CapiExternalError)
 Reject a waiting incoming call.
void acceptWaiting () throw (CapiMsgError, CapiWrongState)
 disable timeout for a pending call (i.e. send ALERT)
void enableDTMF () throw (CapiWrongState, CapiMsgError)
 Enable indication for DTMF signals.
void disableDTMF () throw (CapiWrongState, CapiMsgError)
 Disable indication for DTMF signals.
string getDTMF ()
 read the saved DTMF characters
void clearDTMF ()
 Delete the saved DTMF characters.
string getCalledPartyNumber ()
 Return number of the called party (the source of the call).
string getCallingPartyNumber ()
 Return number of calling party (the destination of the call).
service_t getService ()
 Return currently used service mode.
_cword getCause ()
 Return disconnection cause given by the CAPI.
_cword getCauseB3 ()
 Return disconnection cause given by the CAPI.
connection_state_t getState ()
 Return the connection state.
fax_info_tgetFaxInfo ()
 Return fax information.
void errorMessage (string message)
 Output error message.
void debugMessage (string message, unsigned short level)
 Output debug message.

Protected Types

enum  plci_state_t {
  P0, P01, P1, P2,
  P3, P4, P5, P6,
  PACT
}
 State for the physical connection as defined in the CAPI spec. More...
enum  ncci_state_t {
  N0, N01, N1, N2,
  N3, N4, N5, NACT
}
 State for logical connection as defined in the CAPI spec. More...

Protected Member Functions

 Connection (_cmsg &message, Capi *capi, unsigned short DDILength=0, unsigned short DDIBaseLength=0, std::vector< std::string > DDIStopNumbers=std::vector< std::string >())
 Constructor. Create an object for an incoming call.
void connect_active_ind (_cmsg &message) throw (CapiWrongState, CapiMsgError)
 Called when we get CONNECT_ACTIVE_IND from CAPI.
void connect_b3_ind (_cmsg &message) throw (CapiWrongState, CapiMsgError)
 called when we get CONNECT_B3_IND from CAPI
void connect_b3_active_ind (_cmsg &message) throw (CapiError,CapiWrongState,CapiExternalError)
 called when we get CONNECT_B3_ACTIVE_IND from CAPI
void data_b3_ind (_cmsg &message) throw (CapiError,CapiWrongState,CapiMsgError)
 called when we get DATA_B3_IND from CAPI
void facility_ind_DTMF (_cmsg &message) throw (CapiError,CapiWrongState)
 called when we get FACILITY_IND from CAPI with facility selector saying it's DTMF
void info_ind_alerting (_cmsg &message) throw (CapiError,CapiWrongState)
 called when we get INFO_IND from CAPI with Info number saying it's ALERTING
bool info_ind_called_party_nr (_cmsg &message) throw (CapiError,CapiWrongState)
 called when we get INFO_IND from CAPI with Info number saying it's ALERTING
void disconnect_b3_ind (_cmsg &message) throw (CapiError,CapiWrongState)
 called when we get DISCONNECT_B3_IND from CAPI
void disconnect_ind (_cmsg &message) throw (CapiError,CapiWrongState,CapiMsgError)
 called when we get DISCONNECT_IND from CAPI
void connect_conf (_cmsg &message) throw (CapiWrongState, CapiMsgError)
 called when we get CONNECT_CONF from CAPI
void connect_b3_conf (_cmsg &message) throw (CapiWrongState, CapiMsgError)
 called when we get CONNECT_B3_CONF from CAPI
void select_b_protocol_conf (_cmsg &message) throw (CapiError,CapiWrongState,CapiMsgError)
 called when we get SELECT_B_PROTOCOL_CONF from CAPI
void alert_conf (_cmsg &message) throw (CapiError,CapiWrongState,CapiMsgError)
 called when we get ALERT_CONF from CAPI
void data_b3_conf (_cmsg &message) throw (CapiError,CapiWrongState, CapiMsgError, CapiExternalError)
 called when we get DATA_B3_CONF from CAPI
void facility_conf_DTMF (_cmsg &message) throw (CapiError,CapiWrongState,CapiMsgError)
 called when we get FACILITY_CONF from CAPI with facility selector saying it's DTMF
void disconnect_b3_conf (_cmsg &message) throw (CapiError,CapiWrongState,CapiMsgError)
 called when we get DISCONNECT_B3_CONF from CAPI
void disconnect_conf (_cmsg &message) throw (CapiError,CapiWrongState,CapiMsgError)
 called when we get DISCONNECT_CONF from CAPI
string prefix ()
 return a prefix containing this pointer and date for log messages
string getNumber (_cstruct capi_input, bool isCallingNr)
 format the CallingPartyNr or CalledPartyNr to readable string
void send_block () throw (CapiError,CapiWrongState,CapiExternalError,CapiMsgError)
 called to send next block (2048 bytes) of file
void buildBconfiguration (_cdword controller, service_t service, string faxStationID, string faxHeadline, _cword &B1proto, _cword &B2proto, _cword &B3proto, _cstruct &B1config, _cstruct &B2config, _cstruct &B3config) throw (CapiExternalError)
 called to build the B Configuration info elements out of given service
void convertToCP437 (string &text)
 convert a String from ISO8859-1 to CP437 (IBM PC-DOS charset)

Protected Attributes

enum Connection::plci_state_t plci_state
 State for the physical connection as defined in the CAPI spec.
enum Connection::ncci_state_t ncci_state
 State for logical connection as defined in the CAPI spec.
_cdword plci
 CAPI id for call.
_cdword ncci
 id for logical connection
service_t service
 as described in Connection::service_t, set to the last known service (either got from ISDN or set explicitly)
_cword connect_ind_msg_nr
 this is needed as connect_resp is given in another function as connect_ind
_cword disconnect_cause
 the disconnect cause as given by the CAPI in DISCONNECT_IND
_cword disconnect_cause_b3
 the disconnect cause as given by the CAPI in DISCONNECT_B3_IND
string call_from
 CallingPartyNumber, formatted as string with leading '0' or '+' prefix.
string call_to
 CalledPartyNumber, formatted as string.
string received_dtmf
 accumulates the received DTMF data, see readDTMF()
bool keepPhysicalConnection
 set to true to disable auto-physical disconnect after logical disconnect for one time
bool our_call
 set to true if we initiated the call (needed to know as some messages must be sent if we initiated the call)
CallInterfacecall_if
 pointer to the object implementing CallInterface
Capicapi
 pointer to the Capi object
pthread_mutex_t send_mutex
 to realize critical sections in transmission code
pthread_mutex_t receive_mutex
 to realize critical sections in reception code
ofstream * file_for_reception
 NULL if no file is received, pointer to the file otherwise.
ifstream * file_to_send
 NULL if no file is sent, pointer to the file otherwise.
ostream & debug
 debug stream
ostream & error
 stream for error messages
unsigned short debug_level
 debug level
char send_buffer [7][2048]
 ring buffer for sending
unsigned short buffer_start
 holds the index for the first buffer currently used
unsigned short buffers_used
 holds the number of currently used buffers
fax_info_tfax_info
 holds some data about fax connections
unsigned short DDILength
 the length of DDI extension numbers. 0 means DDI disabled
unsigned short DDIBaseLength
 the length of the base number for a PtP interface
vector< string > DDIStopNumbers
 list of complete DDI extensions shorter than DDILength


Detailed Description

Encapsulates a CAPI connection with all its states and methods.

This class encapsulates one ISDN connection (physical and logical). It has two groups of methods: methods which are supposed to be called from the application (declared public) which serve to access the connection, send data, clear it etc. Also there are many message handlers implemented (declared as private) which are called by Capi::readMessage() and do the most message handling stuff.

Only one logical connection per physical connection is supported.

To communicate with the application by callback functions, the application must implement the CallInterface. The methods of this class are called if different events occur like call completion or a finished data transfer.

There are two ways how Connection objects are created:

Author:
Gernot Hillier


Member Enumeration Documentation

enum Connection::connection_state_t
 

Represents the current connection state in an easy way.

Enumeration values:
DOWN  this means the connection is completely down, i.e. physical and logical down
WAITING  this means an incoming connection is waiting for our decision (accept or reject)
UP  this means the connection is completely up, i.e. physical and logical up
OTHER_STATE  connection is in some other state (e.g. physical up, logical down, ...)

enum Connection::disconnect_mode_t
 

Tells disconnectCall() method how to disconnect.

Enumeration values:
ALL  do the necessary steps to finish the call nicely (first logical, then physical)
PHYSICAL_ONLY  quick'n'dirty disconnect (physical only, logical will auto-disconnect with protocol error)
LOGICAL_ONLY  only disconnect logical connection, physical will stay up

enum Connection::ncci_state_t [protected]
 

State for logical connection as defined in the CAPI spec.

For complete diagrams and state definition see CAPI 2.0 spec, chapter 7.2

Enumeration values:
N0  default state, no connection.
N01  CONNECT_B3_REQ sent, waiting for CONNECT_B3_CONF.
N1  CONNECT_B3_IND received, CONNECT_B3_RESP not sent yet.
N2  CONNECT_B3_CONF received / CONNECT_B3_RESP sent, waiting for CONNECT_B3_ACTIVE_IND.
N3  RESET_B3_REQ sent, waiting for RESET_B3_IND.
N4  DISCONNECT_B3_REQ sent, waiting for DISCONNECT_B3_IND.
N5  DISCONNECT_B3_IND received.
NACT  active logical connection

enum Connection::plci_state_t [protected]
 

State for the physical connection as defined in the CAPI spec.

For complete diagrams and state definition see CAPI 2.0 spec, chapter 7.2

Enumeration values:
P0  default state. no connection.
P01  CONNECT_REQ sent, waiting for CONNECT_CONF.
P1  CONNECT_CONF received, waiting for CONNECT_ACTIVE_IND.
P2  CONNECT_IND received, no CONNECT_RESP given yet.
P3  only needed for handsets
P4  CONNECT_RESP sent, waiting for CONNECT_ACTIVE_IND.
P5  DISCONNECT_REQ sent, waiting for DISCONNECT_IND.
P6  DISCONNECT_IND received, DISCONNECT_RESP not sent yet.
PACT  active physical connection

enum Connection::service_t
 

Type for describing the service of incoming and outgoing calls.

Several similar services are grouped together so the application doesn't have to distinct between speech calls originating from the analog or digital network, between devices providing a High Layer compatibility and devices which only provide bearer capabilities and so on.

For outgoing calls, the most specific value will be used.

For exact details concerning the different services see the parameter CIP in the CAPI spec.

Enumeration values:
VOICE  connections for speech services originated from the analog or digital network (CIP values 1,4,16)
FAXG3  connections for fax Group2/3 services originating from the digital network (as analog networks don't provide service indicator) (CIP value 17)
OTHER  all other service types not included in the above values


Constructor & Destructor Documentation

Connection::Connection Capi capi,
_cdword  controller,
string  call_from,
bool  clir,
string  call_to,
service_t  service,
string  faxStationID,
string  faxHeadline
throw (CapiExternalError, CapiMsgError)
 

Constructor. Create an object to initiate an outgoing call.

This constructor is used when the application creates a Connection object manually to initiate an outgoing connection.

It constructs the necessary information elements (B channel protocol settings, Number elements) and calls Capi::connect_req to initiate a call.

Parameters:
capi pointer to the Capi Object
controller number of the controller which should initiate the call
call_from our number
clir set to TRUE to hide our number (so that the called party can't see it)
call_to the number which we want to call
service service to use (currently only VOICE and FAXG3 are supported), see service_t
faxStationID fax station ID, only used with service faxG3
faxHeadline fax headline (written on each fax page), only used with service faxG3, encoded in ISO8859-1
Exceptions:
CapiExternalError thrown when parameters are missing or wrong
CapiMsgError thrown by Capi::connect_req, see there

Connection::~Connection  ) 
 

. Destructor. Deletes the connection object.

Can block if file transmission is still in progress and/or if connection is not cleared already.

Please call as soon as you don't need the object any more as this will also free some CAPI resources associated to the call.

Please disconnect before deleting a Connection object! The auto-disconnect here is only supported to prevent fatal errors and won't work very nicely!!

Connection::Connection _cmsg &  message,
Capi capi,
unsigned short  DDILength = 0,
unsigned short  DDIBaseLength = 0,
std::vector< std::string >  DDIStopNumbers = std::vector< std::string >()
[protected]
 

Constructor. Create an object for an incoming call.

This one is used by Capi when an incoming connection triggers the automatic creation of a Connection object, i.e. when we receive a CONNECT_IND message.

It only extracts some data (numbers, services, etc.) from the message and saves it in private attributes. The answer to CONNECT_IND (i.e. CONNECT_RESP) is given later by the Connection object.

Parameters:
message the received CONNECT_IND message
capi pointer to the Capi Object
DDILength set the length of DDI extension numbers (0=default means disable DDI)
DDIBaseLength the length of the base number of the PtP interface
DDIStopNumbers a vector of strings listing complete DDI extension numbers which are shorter than DDILength


Member Function Documentation

void Connection::acceptWaiting  )  throw (CapiMsgError, CapiWrongState)
 

disable timeout for a pending call (i.e. send ALERT)

Normally, a call is indicated from ISDN and timeouts after 4 (or 8) seconds if no answer is received. If you want to accept the call, not immediately, but some secods later, you must call acceptWaiting(). This tells ISDN that we will accept it some times later (i.e. send ALERT_REQ)

Exceptions:
CapiWrongState Thrown if call is not in necessary state (waiting for acception or rejection)
CapiMsgError Thrown by Capi::calert_req(). See there.

void Connection::alert_conf _cmsg &  message  )  throw (CapiError,CapiWrongState,CapiMsgError) [protected]
 

called when we get ALERT_CONF from CAPI

Parameters:
message the received ALERT_CONF message
Exceptions:
CapiWrongState Thrown when the message is received unexpected (i.e. in a wrong plci_state)
CapiError Thrown when an invalid message is received
CapiMsgError Thrown if the info InfoElement indicates an error

void Connection::buildBconfiguration _cdword  controller,
service_t  service,
string  faxStationID,
string  faxHeadline,
_cword &  B1proto,
_cword &  B2proto,
_cword &  B3proto,
_cstruct &  B1config,
_cstruct &  B2config,
_cstruct &  B3config
throw (CapiExternalError) [protected]
 

called to build the B Configuration info elements out of given service

This is a convenience function to do the quite annoying enconding stuff for the 6 B configuration parameters.

It also checks if the requested controller really has this abilities and throws an exception otherwise.

Parameters:
controller number of controller to use - necessary to check available services
service value indicating service to be used as described in service_t
faxStationID my fax station ID
faxHeadline the fax headline, encoded in ISO8859-1
B1proto return value: B1protocol value for CAPI, see CAPI spec
B2proto return value: B2protocol value for CAPI, see CAPI spec
B3proto return value: B3protocol value for CAPI, see CAPI spec
B1config return value: B1configuration element for CAPI, see CAPI spec
B2config return value: B2configuration element for CAPI, see CAPI spec
B3config return value: B3configuration element for CAPI, see CAPI spec
Exceptions:
CapiExternalError thrown when the ISDN controller doesn't support the wanted service

void Connection::changeProtocol service_t  desired_service,
string  faxStationID,
string  faxHeadline
throw (CapiMsgError, CapiExternalError, CapiWrongState)
 

Change the used B protcols (e.g. switch from speech to faxG3).

You have to disconnect the logical connection before calling this method. So to change from speech to fax do:

  • disconnect(LOGICAL_ONLY);
  • wait for CallInterface::CallDisconnectedLogical() to be called
  • changeProtocol(FAXG3,"stationID","headline")
  • wait for CallInterface::callConnected() to be called

Does nothing if the requested service is already active. Otherwise the necessary information elements are built and Capi::select_b_protocol_req is called.

Parameters:
desired_service service to switch to
faxStationID Only needed when switching to FaxG3. The fax station ID to use.
faxHeadline Only needed when switching to FaxG3. The fax headline to use, encoded in ISO8859-1
Exceptions:
CapiExternalError Thrown by Connection::buildBconfiguration. See there.
CapiMsgError Thrown by Connection::select_b_protocol_req. See there.
CapiWrongState Connection is in wrong state. Either it was finished by the partner or you didn't disconnect the logical connection before calling changeProtocol

void Connection::clearDTMF  ) 
 

Delete the saved DTMF characters.

void Connection::connect_active_ind _cmsg &  message  )  throw (CapiWrongState, CapiMsgError) [protected]
 

Called when we get CONNECT_ACTIVE_IND from CAPI.

This method will also send a response to Capi and initiate a B3 connection if necessary.

Parameters:
message the received CONNECT_ACTIVE_IND message
Exceptions:
CapiWrongState Thrown when the message is received unexpected (i.e. in a wrong plci_state)
CapiMsgError Thrown by Capi::connect_b3_req

void Connection::connect_b3_active_ind _cmsg &  message  )  throw (CapiError,CapiWrongState,CapiExternalError) [protected]
 

called when we get CONNECT_B3_ACTIVE_IND from CAPI

This method will also send a response to Capi and call CallInterface::callConnected().

Parameters:
message the received CONNECT_B3_ACTIVE_IND message
Exceptions:
CapiWrongState Thrown when the message is received unexpected (i.e. in a wrong ncci_state)
CapiExternalError Thrown if no CallInterface is registered
CapiError Thrown if invalid message was received

void Connection::connect_b3_conf _cmsg &  message  )  throw (CapiWrongState, CapiMsgError) [protected]
 

called when we get CONNECT_B3_CONF from CAPI

Parameters:
message the received CONNECT_B3_CONF message
Exceptions:
CapiWrongState Thrown when the message is received unexpected (i.e. in a wrong ncci_state)
CapiMsgError Thrown if the info InfoElement indicates an error

void Connection::connect_b3_ind _cmsg &  message  )  throw (CapiWrongState, CapiMsgError) [protected]
 

called when we get CONNECT_B3_IND from CAPI

This method will also send a response to Capi.

Parameters:
message the received CONNECT_B3_IND message
Exceptions:
CapiWrongState Thrown when the message is received unexpected (i.e. in a wrong ncci_state)
CapiMsgError Thrown by Capi::connect_b3_resp()

void Connection::connect_conf _cmsg &  message  )  throw (CapiWrongState, CapiMsgError) [protected]
 

called when we get CONNECT_CONF from CAPI

Parameters:
message the received CONNECT_CONF message
Exceptions:
CapiWrongState Thrown when the message is received unexpected (i.e. in a wrong plci_state)
CapiMsgError Thrown if the info InfoElement indicates an error

void Connection::connectWaiting service_t  desired_service,
string  faxStationID = "",
string  faxHeadline = ""
throw (CapiWrongState,CapiExternalError,CapiMsgError)
 

Accept a waiting incoming call.

Will update the saved service to the desired_service. Calls Capi::connect_resp().

Parameters:
desired_service to determine with which service we should connect (e.g. VOICE or FAXG3)
faxStationID my fax station ID - only needed in FAXG3 mode
faxHeadline my fax headline - only needed in FAXG3 mode, encoded in ISO8859-1
Exceptions:
CapiWrongState Thrown if call is not in necessary state (waiting for acception or rejection)
CapiExternalError Thrown by buildBconfiguration and if method is called with an outgoing call
CapiMsgError Thrown by Capi::connect_resp(). See there.

void Connection::convertToCP437 string &  text  )  [protected]
 

convert a String from ISO8859-1 to CP437 (IBM PC-DOS charset)

Unfortunately, some CAPI drivers expect the fax headline to be given in the IBM PC-DOS charset. This method can convert the string from the normal ISO8859-1 representation to this charset.

Parameters:
text the string to convert
Exceptions:
CapiExternalError thrown when the iconv* functions report an error (other than conversion not supported)

void Connection::data_b3_conf _cmsg &  message  )  throw (CapiError,CapiWrongState, CapiMsgError, CapiExternalError) [protected]
 

called when we get DATA_B3_CONF from CAPI

This will trigger new send_block().

Parameters:
message the received DATA_B3_CONF message
Exceptions:
CapiWrongState Thrown when the message is received unexpected (i.e. in a wrong plci_state)
CapiMsgError Thrown if the info InfoElement indicates an error
CapiError Thrown when an invalid message is received and by Connection::send_block()
CapiExternalError Thrown by Connection::send_block()

void Connection::data_b3_ind _cmsg &  message  )  throw (CapiError,CapiWrongState,CapiMsgError) [protected]
 

called when we get DATA_B3_IND from CAPI

This method will also save the received data, send a response to Capi and call CallInterface::dataIn().

Parameters:
message the received DATA_B3_IND message
Exceptions:
CapiError Thrown when an invalid message is received
CapiWrongState Thrown when the message is received unexpected (i.e. in a wrong ncci_state)
CapiMsgError Thrown by Capi::data_b3_resp()

void Connection::debugMessage string  message,
unsigned short  level
 

Output debug message.

This is intended for external use if some other part of the application wants to make a log entry. For internal use in this class just output to the stream "debug".

Parameters:
message the message to print
level the debug level of the given message (see capisuite.conf for explanation)

void Connection::disableDTMF  )  throw (CapiWrongState, CapiMsgError)
 

Disable indication for DTMF signals.

Exceptions:
CapiWrongState Thrown if Connection isn't up completely (physical & logical)
CapiMsgError Thrown by Capi::facility_req(). See there.

void Connection::disconnect_b3_conf _cmsg &  message  )  throw (CapiError,CapiWrongState,CapiMsgError) [protected]
 

called when we get DISCONNECT_B3_CONF from CAPI

Parameters:
message the received DISCONNECT_B3_CONF message
Exceptions:
CapiWrongState Thrown when the message is received unexpected (i.e. in a wrong plci_state)
CapiMsgError Thrown if the info InfoElement indicates an error
CapiError Thrown when an invalid message is received

void Connection::disconnect_b3_ind _cmsg &  message  )  throw (CapiError,CapiWrongState) [protected]
 

called when we get DISCONNECT_B3_IND from CAPI

This method will also send a response to Capi and stop_file_transmission and stop_file_reception(). It will call CallInterface::callDisconnectedLogical() and initiate termination of physical connection.

Parameters:
message the received DISCONNECT_B3_IND message
Exceptions:
CapiError Thrown when an invalid message is received
CapiWrongState Thrown when the message is received unexpected (i.e. in a wrong ncci_state)

void Connection::disconnect_conf _cmsg &  message  )  throw (CapiError,CapiWrongState,CapiMsgError) [protected]
 

called when we get DISCONNECT_CONF from CAPI

Parameters:
message the received DISCONNECT_CONF message
Exceptions:
CapiWrongState Thrown when the message is received unexpected (i.e. in a wrong plci_state)
CapiMsgError Thrown if the info InfoElement indicates an error
CapiError Thrown when an invalid message is received

void Connection::disconnect_ind _cmsg &  message  )  throw (CapiError,CapiWrongState,CapiMsgError) [protected]
 

called when we get DISCONNECT_IND from CAPI

This method will also send a response to Capi and call CallInterface::callDisconnectedPhysical().

Parameters:
message the received DISCONNECT_IND message
Exceptions:
CapiError Thrown when an invalid message is received
CapiWrongState Thrown when the message is received unexpected (i.e. in a wrong ncci_state or plci_state)
CapiMsgError Thrown by Capi::disconnect_resp()

void Connection::disconnectCall disconnect_mode_t  disconnect_mode = ALL  )  throw (CapiMsgError)
 

Terminate this connection.

According to the current state and the given mode, the needed steps to disconnect will be executed.

If you don't specify a mode, the connection will be completely cleared (first logical, then physical).

It doesn't throw any error if you call it for an already cleared connection, so it's safe to call it more than one time.

To reject a waiting call you haven't accepted earlier, use rejectWaiting(), not disconnectCall().

Attention: Connection objects will not be deleted after the disconnection. You must delete the Connection object explicitly. The reason for this behavior is to allow you to get connection related information (like disconnect cause, ...) after the connection has cleared. See also CallInterface::callDisconnectedPhysical().

Parameters:
disconnect_mode see description of disconnect_mode_t
Exceptions:
CapiMsgError Thrown by Capi::disconnect_b3_req() or Capi::disconnect_req(). See there.

void Connection::enableDTMF  )  throw (CapiWrongState, CapiMsgError)
 

Enable indication for DTMF signals.

Normally you get no indication when the CAPI recognizes a DTMF signal. With enableDTMF() you enable these indications. DTMF signals will be saved locally and signalled by CallInterface::gotDTMF(). You can read the saved DTMF signales with getDTMF().

Exceptions:
CapiWrongState Thrown if Connection isn't up completely (physical & logical)
CapiMsgError Thrown by Capi::facility_req(). See there.

void Connection::errorMessage string  message  ) 
 

Output error message.

This is intended for external use if some other part of the application wants to make a error-log entry. For internal use in this class just output to the stream "error".

Parameters:
message the message to print

void Connection::facility_conf_DTMF _cmsg &  message  )  throw (CapiError,CapiWrongState,CapiMsgError) [protected]
 

called when we get FACILITY_CONF from CAPI with facility selector saying it's DTMF

Parameters:
message the received FACILITY_CONF message
Exceptions:
CapiWrongState Thrown when the message is received unexpected (i.e. in a wrong plci_state)
CapiError Thrown when an invalid message is received
CapiMsgError Thrown if the info InfoElement indicates an error

void Connection::facility_ind_DTMF _cmsg &  message  )  throw (CapiError,CapiWrongState) [protected]
 

called when we get FACILITY_IND from CAPI with facility selector saying it's DTMF

This method will save the received DTMF to received_dtmf, send a response to Capi and call CallInterface::gotDTMF().

Parameters:
message the received FACILITY_IND message
Exceptions:
CapiError Thrown when an invalid message is received
CapiWrongState Thrown when the message is received unexpected (i.e. in a wrong ncci_state)

string Connection::getCalledPartyNumber  ) 
 

Return number of the called party (the source of the call).

Returns:
CalledPartyNumber

string Connection::getCallingPartyNumber  ) 
 

Return number of calling party (the destination of the call).

Returns:
callingPartyNumber

_cword Connection::getCause  ) 
 

Return disconnection cause given by the CAPI.

0x33xx=see CAPI spec 0x34xx=ISDN cause, for coding of xx see ETS 300102-1.

Returns:
Returns the disconnection cause, 0=no cause available

_cword Connection::getCauseB3  ) 
 

Return disconnection cause given by the CAPI.

0x33xx=see CAPI spec 0x34xx=ISDN cause, for coding of xx see ETS 300102-1.

Returns:
Returns the disconnection cause of Layer3, 0=no cause available or normal clearing

string Connection::getDTMF  ) 
 

read the saved DTMF characters

DTMF characters will only be saved if you called enableDTMF() before.

 

Returns:
string containing received DTMF coded as characters ('0'..'9','A'..'D','*','#','X'=fax CNG,'Y'=fax CED)

Connection::fax_info_t * Connection::getFaxInfo  ) 
 

Return fax information.

Returns:
several informations about a fax transfer as specified in Connection::fax_info_t, NULL when not available

string Connection::getNumber _cstruct  capi_input,
bool  isCallingNr
[protected]
 

format the CallingPartyNr or CalledPartyNr to readable string

Parameters:
capi_input the CallingPartyNumber resp. CalledPartyNumber struct
isCallingNr true = CallingPartyNr / false = CalledPartyNr
Returns:
the number formatted as string

Connection::service_t Connection::getService  ) 
 

Return currently used service mode.

Returns:
service as described in Connection::service_t

Connection::connection_state_t Connection::getState  ) 
 

Return the connection state.

Returns:
current connection state as specified in Connection::connection_state_t

void Connection::info_ind_alerting _cmsg &  message  )  throw (CapiError,CapiWrongState) [protected]
 

called when we get INFO_IND from CAPI with Info number saying it's ALERTING

This method will call CallInterface::alerting().

Parameters:
message the received INFO_IND message
Exceptions:
CapiError Thrown when an invalid message is received
CapiWrongState Thrown when the message is received unexpected (i.e. in a wrong plci_state)

bool Connection::info_ind_called_party_nr _cmsg &  message  )  throw (CapiError,CapiWrongState) [protected]
 

called when we get INFO_IND from CAPI with Info number saying it's ALERTING

This method will understand additional Called Party Number Info Elements to get the DDI (necessary for getting the whole number in PtP configuration as the DDI is signalled after* CONNECT_IND.

Parameters:
message the received INFO_IND message
Returns:
true if the CalledPartyNumber is complete (DDI length fulfilled or stop_number found)
Exceptions:
CapiError Thrown when an invalid message is received
CapiWrongState Thrown when the message is received unexpected (i.e. in a wrong plci_state)

string Connection::prefix  )  [protected]
 

return a prefix containing this pointer and date for log messages

Returns:
constructed prefix as stringstream

void Connection::registerCallInterface CallInterface call_if  ) 
 

Register the instance implementing the CallInterface.

Parameters:
call_if - pointer to the instance to use

void Connection::rejectWaiting _cword  reject  )  throw (CapiWrongState, CapiMsgError, CapiExternalError)
 

Reject a waiting incoming call.

Only use for waiting calls - to disconnect an already connected call use disconnectCall().

Parameters:
reject reject cause, see CAPI spec ch 5.6 for details
Exceptions:
CapiWrongState Thrown if call is not in necessary state (waiting for acception or rejection)
CapiExternalError Thrown if function called with wrong parameters
CapiMsgError Thrown by Capi::connect_resp(). See there.

void Connection::select_b_protocol_conf _cmsg &  message  )  throw (CapiError,CapiWrongState,CapiMsgError) [protected]
 

called when we get SELECT_B_PROTOCOL_CONF from CAPI

Parameters:
message the received SELECT_B_PROTOCOL_CONF message
Exceptions:
CapiWrongState Thrown when the message is received unexpected (i.e. in a wrong plci_state)
CapiError Thrown when an invalid message is received
CapiMsgError Thrown if the info InfoElement indicates an error

void Connection::send_block  )  throw (CapiError,CapiWrongState,CapiExternalError,CapiMsgError) [protected]
 

called to send next block (2048 bytes) of file

The transmission will be controlled automatically by Connection, so you don't need to call this method directly. send_block() will automatically send as much packets as the configured window size (conf_send_buffers) permits.

Will call CallInterface::transmissionComplete() if the file was transferred completely.

Exceptions:
CapiWrongState Thrown when the the connection is not up completely (physical & logical)
CapiExternalError Thrown when no CallInterface is registered
CapiError Thrown on some internal errors
CapiMsgError Thrown by Capi::data_b3_req().

void Connection::start_file_reception string  filename  )  throw (CapiWrongState, CapiExternalError)
 

called to activate receive mode

This method doen't do anything active, it will only set the receive mode for this connection If you don't call this, all received data is discarded. If called, the data B3 stream received is written to this file w/o changes. So it's in the native format given by CAPI (i.e. inserved A-Law for speech, SFF for FaxG3).

Parameters:
filename name of the file to which to save the incoming data
Exceptions:
CapiWrongState Thrown if Connection isn't up completely (physical & logical)
CapiExternalError Thrown if file reception is already in progress or the file couldn't be opened

void Connection::start_file_transmission string  filename  )  throw (CapiError,CapiWrongState,CapiExternalError,CapiMsgError)
 

called to start sending of a file

The transmission will be controlled automatically by Connection - no further user interaction is necessary if the whole file should be sent.

The file has to be in the correct format expected by CAPI, i.e. bit-reversed A-Law, 8 khz, mono (".la" for sox) for speech, SFF for faxG3

Parameters:
filename the name of the file which should be sent
Exceptions:
CapiWrongState Thrown if Connection isn't up completely (physical & logical)
CapiExternalError Thrown if file transmission is already in progress or the file couldn't be opened
CapiMsgError Thrown by send_block(). See there.
CapiError Thrown by send_block(). See there.

void Connection::stop_file_reception  ) 
 

called to stop receive mode

This closes the reception file and tells us to ignore further incoming B3 data.

void Connection::stop_file_transmission  ) 
 

called to stop sending of the current file, will block until file is really finished

If you stop the file transmission manually, CallInterface::transferCompleted won't be called.


Member Data Documentation

unsigned short Connection::buffer_start [protected]
 

holds the index for the first buffer currently used

unsigned short Connection::buffers_used [protected]
 

holds the number of currently used buffers

string Connection::call_from [protected]
 

CallingPartyNumber, formatted as string with leading '0' or '+' prefix.

CallInterface* Connection::call_if [protected]
 

pointer to the object implementing CallInterface

string Connection::call_to [protected]
 

CalledPartyNumber, formatted as string.

Capi* Connection::capi [protected]
 

pointer to the Capi object

_cword Connection::connect_ind_msg_nr [protected]
 

this is needed as connect_resp is given in another function as connect_ind

unsigned short Connection::DDIBaseLength [protected]
 

the length of the base number for a PtP interface

unsigned short Connection::DDILength [protected]
 

the length of DDI extension numbers. 0 means DDI disabled

vector<string> Connection::DDIStopNumbers [protected]
 

list of complete DDI extensions shorter than DDILength

ostream& Connection::debug [protected]
 

debug stream

unsigned short Connection::debug_level [protected]
 

debug level

_cword Connection::disconnect_cause [protected]
 

the disconnect cause as given by the CAPI in DISCONNECT_IND

_cword Connection::disconnect_cause_b3 [protected]
 

the disconnect cause as given by the CAPI in DISCONNECT_B3_IND

ostream & Connection::error [protected]
 

stream for error messages

fax_info_t* Connection::fax_info [protected]
 

holds some data about fax connections

ofstream* Connection::file_for_reception [protected]
 

NULL if no file is received, pointer to the file otherwise.

ifstream* Connection::file_to_send [protected]
 

NULL if no file is sent, pointer to the file otherwise.

bool Connection::keepPhysicalConnection [protected]
 

set to true to disable auto-physical disconnect after logical disconnect for one time

_cdword Connection::ncci [protected]
 

id for logical connection

enum Connection::ncci_state_t Connection::ncci_state [protected]
 

State for logical connection as defined in the CAPI spec.

For complete diagrams and state definition see CAPI 2.0 spec, chapter 7.2

bool Connection::our_call [protected]
 

set to true if we initiated the call (needed to know as some messages must be sent if we initiated the call)

_cdword Connection::plci [protected]
 

CAPI id for call.

enum Connection::plci_state_t Connection::plci_state [protected]
 

State for the physical connection as defined in the CAPI spec.

For complete diagrams and state definition see CAPI 2.0 spec, chapter 7.2

pthread_mutex_t Connection::receive_mutex [protected]
 

to realize critical sections in reception code

string Connection::received_dtmf [protected]
 

accumulates the received DTMF data, see readDTMF()

char Connection::send_buffer[7][2048] [protected]
 

ring buffer for sending

7 buffers a 2048 byte mark the maximal window size handled by CAPI

is empty: buffer_used==0 / is full: buffers_used==7 to forget item: buffers_used--; buffer_start++; to remember item: send_buffer[ (buffer_start+buffers_used)8 ]=item; buffers_used++

pthread_mutex_t Connection::send_mutex [protected]
 

to realize critical sections in transmission code

service_t Connection::service [protected]
 

as described in Connection::service_t, set to the last known service (either got from ISDN or set explicitly)


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