Yate: Channel Class Reference

Yate

- Main Page
- Namespaces
- Classes
- Files

- Class List
- Class Hierarchy
- Class Members

Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes | Friends | List of all members
Channel Class Reference

An abstract communication channel. More...

`#include <yatephone.h>`

Inheritance diagram for Channel:

## Public Member Functions
virtual | ~Channel ()
virtual void * | getObject (const String &name) const
virtual void | complete (Message &msg, bool minimal=false) const
Message * | message (const char *name, bool minimal=false, bool data=false)
Message * | message (const char *name, const NamedList *original, const char *params=0, bool minimal=false, bool data=false)
Message * | message (const char *name, const NamedList &original, const char *params=0, bool minimal=false, bool data=false)
virtual bool | msgProgress (Message &msg)
virtual bool | msgRinging (Message &msg)
virtual bool | msgAnswered (Message &msg)
virtual bool | msgTone (Message &msg, const char *tone)
virtual bool | msgText (Message &msg, const char *text)
virtual bool | msgDrop (Message &msg, const char *reason)
virtual bool | msgTransfer (Message &msg)
virtual bool | msgUpdate (Message &msg)
virtual bool | msgMasquerade (Message &msg)
virtual void | msgStatus (Message &msg)
virtual bool | msgControl (Message &msg)
virtual void | checkTimers (Message &msg, const Time &tmr)
virtual bool | callPrerouted (Message &msg, bool handled)
virtual bool | callRouted (Message &msg)
virtual void | callAccept (Message &msg)
virtual void | callRejected (const char *error, const char *reason=0, const Message *msg=0)
virtual void | callConnect (Message &msg)
virtual bool | setDebug (Message &msg)
String & | getStatus (String &buf, bool append=true) const
void | putStatus (NamedList &list, const char *param="status", bool append=true) const
const String & | address () const
bool | isOutgoing () const
bool | isIncoming () const
bool | isAnswered () const
const char * | direction () const
Driver * | driver () const
u_int64_t | timeout () const
void | timeout (u_int64_t tout)
u_int64_t | maxcall () const
void | maxcall (u_int64_t tout)
void | setMaxcall (const Message &msg, int defTout=-1)
void | setMaxcall (const Message *msg, int defTout=-1)
u_int64_t | maxPDD () const
void | maxPDD (u_int64_t tout)
void | setMaxPDD (const Message &msg)
const String & | targetid () const
const String & | billid () const
void | initChan ()
bool | startRouter (Message *msg)
void | filterDebug (const String &item)
const NamedList & | parameters () const
void | setChanParams (const NamedList &list, bool in=false)
void | copyChanParams (NamedList &list) const
virtual void | dispatched (const Message &msg, bool handled)
Public Member Functions inherited from CallEndpoint
virtual void | destroyed ()
virtual const String & | toString () const
const String & | id () const
CallEndpoint * | getPeer () const
bool | getPeerId (String &id) const
String | getPeerId () const
bool | getLastPeerId (String &id) const
void | setLastPeerId ()
Mutex * | mutex () const
bool | connect (CallEndpoint *peer, const char *reason=0, bool notify=true)
bool | disconnect (const char *reason=0, bool notify=true, const NamedList *params=0)
bool | disconnect (const char *reason, const NamedList &params)
DataEndpoint * | getEndpoint (const String &type=CallEndpoint::audioType()) const
DataEndpoint * | setEndpoint (const String &type=CallEndpoint::audioType())
void | clearEndpoint (const String &type=String::empty())
void | setSource (DataSource *source=0, const String &type=CallEndpoint::audioType())
DataSource * | getSource (const String &type=CallEndpoint::audioType()) const
void | setConsumer (DataConsumer *consumer=0, const String &type=CallEndpoint::audioType())
DataConsumer * | getConsumer (const String &type=CallEndpoint::audioType()) const
bool | clearData (DataNode *node, const String &type=CallEndpoint::audioType())
Public Member Functions inherited from RefObject
| RefObject ()
virtual | ~RefObject ()
virtual bool | alive () const
bool | ref ()
bool | deref ()
int | refcount () const
virtual void | destruct ()
Public Member Functions inherited from GenObject
| GenObject ()
virtual | ~GenObject ()
virtual const String & | traceId () const
NamedCounter * | getObjCounter () const
NamedCounter * | setObjCounter (NamedCounter *counter)
Public Member Functions inherited from DebugEnabler
| DebugEnabler (int level=TelEngine::debugLevel(), bool enabled=true)
int | debugLevel () const
int | debugLevel (int level)
bool | debugEnabled () const
void | debugEnabled (bool enable)
const char * | debugName () const
bool | debugAt (int level) const
bool | debugChained () const
void | debugChain (const DebugEnabler *chain=0)
void | debugCopy (const DebugEnabler *original=0)
Public Member Functions inherited from MessageNotifier
virtual | ~MessageNotifier ()

## Static Public Member Functions
static Mutex & | paramMutex ()
static unsigned int | allocId ()
Static Public Member Functions inherited from CallEndpoint
static Mutex & | commonMutex ()
static const String & | audioType ()
Static Public Member Functions inherited from RefObject
static bool | alive (const RefObject *obj)
static bool | efficientIncDec ()
Static Public Member Functions inherited from GenObject
static void * | getObject (const String &name, const GenObject *obj)
static bool | getObjCounting ()
static void | setObjCounting (bool enable)
static NamedCounter * | getObjCounter (const String &name, bool create=true)
static ObjList & | getObjCounters ()

## Protected Member Functions
| Channel (Driver *driver, const char *id=0, bool outgoing=false)
| Channel (Driver &driver, const char *id=0, bool outgoing=false)
void | cleanup ()
void | dropChan ()
virtual void | zeroRefs ()
virtual void | connected (const char *reason)
virtual void | disconnected (bool final, const char *reason)
virtual void | setDisconnect (const NamedList *params)
virtual void | endDisconnect (const Message &msg, bool handled)
virtual void | setId (const char *newId)
virtual Message * | getDisconnect (const char *reason)
void | status (const char *newstat)
const String & | getStatus () const
virtual void | statusParams (String &str)
void | setOutgoing (bool outgoing=true)
bool | dtmfSequence (Message &msg)
bool | dtmfEnqueue (Message *msg)
bool | dtmfInband (const char *tone)
bool | toneDetect (const char *sniffer=0)
NamedList & | parameters ()
Protected Member Functions inherited from CallEndpoint
| CallEndpoint (const char *id=0)
void | setPeer (CallEndpoint *peer, const char *reason=0, bool notify=true, const NamedList *params=0)
void | setEndpoint (DataEndpoint *endPoint)
Protected Member Functions inherited from RefObject
bool | resurrect ()
Protected Member Functions inherited from DebugEnabler
void | debugName (const char *name)

## Protected Attributes
String | m_status
String | m_address
String | m_targetid
String | m_billid
bool | m_answered
Protected Attributes inherited from CallEndpoint
ObjList | m_data
Mutex * | m_mutex

## Friends
class | Driver
class | Router

## Detailed Description

An abstract communication channel.

A class that holds common channel related features (a.k.a. call leg)

## Constructor & Destructor Documentation

virtual ~Channel | ( |  | ) |
| virtual

Destructor

Channel | ( | Driver * | driver,
|  | const char * | id = `0`,
|  | bool | outgoing = `false`
| ) |  |
| protected

Constructor

Channel | ( | Driver & | driver,
|  | const char * | id = `0`,
|  | bool | outgoing = `false`
| ) |  |
| protected

Alternate constructor provided for convenience

## Member Function Documentation

const String& address | ( |  | ) | const
| inline

Get the current link address of the channel

Returns
  The protocol dependent address as String

static unsigned int allocId | ( |  | ) |
| static

Allocate an unique (per engine run) call ID

Returns
  Unique call ID number

const String& billid | ( |  | ) | const
| inline

Get the billing identifier.

Returns
  An identifier of the call or account that will be billed for calls made by this channel.

virtual void callAccept | ( | Message & | msg | ) |
| virtual

Notification on success of incoming call

Parameters

  msg | Notification call.execute message just after being dispatched

Reimplemented in ClientChannel.

virtual void callConnect | ( | Message & | msg | ) |
| virtual

Common processing after connecting the outgoing call, should be called from Driver's msgExecute()

Parameters

  msg | Notification call.execute message while being dispatched

virtual bool callPrerouted | ( | Message & | msg,
|  | bool | handled
| ) |  |
| virtual

Notification on progress of prerouting incoming call

Parameters

  msg | Notification call.preroute message just after being dispatched
  handled | True if a handler claimed having handled prerouting

Returns
  True to continue with the call, false to abort the route

virtual void callRejected | ( | const char * | error,
|  | const char * | reason = `0`,
|  | const Message * | msg = `0`
| ) |  |
| virtual

Notification on failure of incoming call

Parameters

  error | Standard error keyword
  reason | Textual failure reason
  msg | Pointer to message causing the rejection, if any

Reimplemented in ClientChannel.

virtual bool callRouted | ( | Message & | msg | ) |
| virtual

Notification on progress of routing incoming call

Parameters

  msg | Notification call.route message just after being dispatched

Returns
  True to continue with the call, false to abort the route

Reimplemented in ClientChannel.

virtual void checkTimers | ( | Message & | msg,
|  | const Time & | tmr
| ) |  |
| virtual

Timer check method, by default handles channel timeouts

Parameters

  msg | Timer message
  tmr | Current time against which timers are compared

void cleanup | ( |  | ) |
| protected

Perform destruction time cleanup. You can call this method earlier if destruction is to be postponed.

virtual void complete | ( | Message & | msg,
|  | bool | minimal = `false`
| ) |  | const
| virtual

Put channel variables into a message

Parameters

  msg | Message to fill in
  minimal | True to fill in only a minimum of parameters

virtual void connected | ( | const char * | reason | ) |
| protectedvirtual

Connect notification method.

Parameters

  reason | Text that describes connect reason.

Reimplemented from CallEndpoint.

Reimplemented in ClientChannel.

void copyChanParams | ( | NamedList & | list | ) | const
| inline

Copy channel parameters

Parameters

  list | Destination list

References NamedList::copyParams(), and Channel::paramMutex().

const char* direction | ( |  | ) | const

Get the direction of the channel as string

Returns
  "incoming" or "outgoing" according to the direction

virtual void disconnected | ( | bool | final,
|  | const char * | reason
| ) |  |
| protectedvirtual

Disconnect notification method.

Parameters

  final | True if this disconnect was called from the destructor.
  reason | Text that describes disconnect reason.

Reimplemented from CallEndpoint.

Reimplemented in ClientChannel.

virtual void dispatched | ( | const Message & | msg,
|  | bool | handled
| ) |  |
| virtual

Notification for dispatched messages

Parameters

  msg | Message that was dispatched
  handled | Result of handling the message

Implements MessageNotifier.

Driver* driver | ( |  | ) | const
| inline

Get the driver of this channel

Returns
  Pointer to this channel's driver

void dropChan | ( |  | ) |
| protected

Remove the channel from the parent driver list

bool dtmfEnqueue | ( | Message * | msg | ) |
| protected

Add sequence number to chan.dtmf and enqueue it, delete if duplicate

Parameters

  msg | chan.dtmf message to sequence and enqueue

Returns
  True if the message was enqueued, false if was a duplicate

bool dtmfInband | ( | const char * | tone | ) |
| protected

Attempt to install an override data source to send DTMF inband. Needs a tone generator module capable to override with "tone/dtmfstr/xyz"

Parameters

  tone | Pointer to the tone sequence to send

Returns
  True on success

bool dtmfSequence | ( | Message & | msg | ) |
| protected

Add sequence number to chan.dtmf message, check for duplicates

Parameters

  msg | chan.dtmf message to apply sequence number

Returns
  True if the message is a duplicate (same tone, different method)

virtual void endDisconnect | ( | const Message & | msg,
|  | bool | handled
| ) |  |
| protectedvirtual

Notification after chan.disconnected handling

Parameters

  msg | The chan.disconnected message
  handled | True if the message was handled

void filterDebug | ( | const String & | item | ) |

Enable or disable debugging according to driver's filter rules

Parameters

  item | Value of the item to match

virtual Message* getDisconnect | ( | const char * | reason | ) |
| protectedvirtual

Create a properly populated chan.disconnect message

Parameters

  reason | Channel disconnect reason if available

Returns
  A new allocated and parameter filled chan.disconnected message

virtual void* getObject | ( | const String & | name | ) | const
| virtual

Get a pointer to a derived class given that class name

Parameters

  name | Name of the class we are asking for

Returns
  Pointer to the requested class or NULL if this object doesn't implement it

Reimplemented from CallEndpoint.

String& getStatus | ( | String & | buf,
|  | bool | append = `true`
| ) |  | const
| inline

Get the current status of the channel This method is thread safe

Parameters

  buf | Destination buffer
  append | True to append to destination buffer, false to set (replace contents)

Returns
  Destination buffer reference

const String& getStatus | ( |  | ) | const
| inlineprotected

Retrieve Channel status This method is not thread safe

Returns
  Channel status

Referenced by Channel::putStatus().

void initChan | ( |  | ) |

Add the channel to the parent driver list This method must be called exactly once after the object is fully constructed

bool isAnswered | ( |  | ) | const
| inline

Check if the call was answered or not

Returns
  True if the call was answered

bool isIncoming | ( |  | ) | const
| inline

Get the direction of the channel

Returns
  True if the channel is an incoming call (generated remotely)

bool isOutgoing | ( |  | ) | const
| inline

Get the direction of the channel

Returns
  True if the channel is an outgoing call (generated locally)

u_int64_t maxcall | ( |  | ) | const
| inline

Get the time this channel will time out on outgoing calls

Returns
  Timeout time or zero if no timeout

void maxcall | ( | u_int64_t | tout | ) |
| inline

Set the time this channel will time out on outgoing calls

Parameters

  tout | New timeout time or zero to disable

u_int64_t maxPDD | ( |  | ) | const
| inline

Get the time this channel will time out while waiting for some progress on outgoing calls

Returns
  Timeout time or zero if no timeout

void maxPDD | ( | u_int64_t | tout | ) |
| inline

Set the time this channel will time out while waiting for some progress on outgoing calls

Parameters

  tout | New timeout time or zero to disable

Message* message | ( | const char * | name,
|  | bool | minimal = `false`,
|  | bool | data = `false`
| ) |  |

Create a filled notification message

Parameters

  name | Name of the message to create
  minimal | Set to true to fill in only a minimum of parameters
  data | Set the channel as message data

Returns
  A new allocated and parameter filled message

Referenced by Channel::message().

Message* message | ( | const char * | name,
|  | const NamedList * | original,
|  | const char * | params = `0`,
|  | bool | minimal = `false`,
|  | bool | data = `false`
| ) |  |

Create a filled notification message, copy some parameters from another message

Parameters

  name | Name of the message to create
  original | Parameters to copy from, can be NULL
  params | Comma separated list of parameters to copy, if NULL will be taken from the "copyparams" parameter of original
  minimal | Set to true to fill in only a minimum of parameters
  data | Set the channel as message data

Returns
  A new allocated and parameter filled message

Message* message | ( | const char * | name,
|  | const NamedList & | original,
|  | const char * | params = `0`,
|  | bool | minimal = `false`,
|  | bool | data = `false`
| ) |  |
| inline

Create a filled notification message, copy some parameters from another message

Parameters

  name | Name of the message to create
  original | Parameters to copy from
  params | Comma separated list of parameters to copy, if NULL will be taken from the "copyparams" parameter of original
  minimal | Set to true to fill in only a minimum of parameters
  data | Set the channel as message data

Returns
  A new allocated and parameter filled message

References Channel::message().

virtual bool msgAnswered | ( | Message & | msg | ) |
| virtual

Notification on remote answered. Note that the answered flag will be set

Parameters

  msg | Notification message

Returns
  True to stop processing the message, false to let it flow

Reimplemented in ClientChannel.

virtual bool msgControl | ( | Message & | msg | ) |
| virtual

Control message handler that is invoked only for messages to this channel

Parameters

  msg | Control message

Returns
  True to stop processing the message, false to let it flow

virtual bool msgDrop | ( | Message & | msg,
|  | const char * | reason
| ) |  |
| virtual

Notification on current call drop request

Parameters

  msg | Notification message
  reason | Pointer to drop reason text or NULL if none provided

Returns
  True if initiated call drop, false if failed

Reimplemented in ClientChannel.

virtual bool msgMasquerade | ( | Message & | msg | ) |
| virtual

Notification on message masquerade as channel request

Parameters

  msg | Message already modified to masquerade as this channel

Returns
  True to stop processing the message, false to masquerade it

virtual bool msgProgress | ( | Message & | msg | ) |
| virtual

Notification on remote call making some progress, not enabled by default

Parameters

  msg | Notification message

Returns
  True to stop processing the message, false to let it flow

Reimplemented in ClientChannel.

virtual bool msgRinging | ( | Message & | msg | ) |
| virtual

Notification on remote ringing

Parameters

  msg | Notification message

Returns
  True to stop processing the message, false to let it flow

Reimplemented in ClientChannel.

virtual void msgStatus | ( | Message & | msg | ) |
| virtual

Status message handler that is invoked only for messages to this channel

Parameters

  msg | Status message

virtual bool msgText | ( | Message & | msg,
|  | const char * | text
| ) |  |
| virtual

Notification on remote text messaging (sms)

Parameters

  msg | Notification message
  text | Pointer to the received text

Returns
  True to stop processing the message, false to let it flow

virtual bool msgTone | ( | Message & | msg,
|  | const char * | tone
| ) |  |
| virtual

Notification on remote tone(s)

Parameters

  msg | Notification message
  tone | Pointer to the received tone(s)

Returns
  True to stop processing the message, false to let it flow

virtual bool msgTransfer | ( | Message & | msg | ) |
| virtual

Notification on native transfer request

Parameters

  msg | Notification message

Returns
  True to stop processing the message, false to let it flow

virtual bool msgUpdate | ( | Message & | msg | ) |
| virtual

Notification on call parameters update request

Parameters

  msg | Notification message

Returns
  True to stop processing the message, false to let it flow

const NamedList& parameters | ( |  | ) | const
| inline

Get the disconnect parameters list

Returns
  Constant reference to disconnect parameters

NamedList& parameters | ( |  | ) |
| inlineprotected

Get the disconnect parameters list

Returns
  Reference to disconnect parameters

static Mutex& paramMutex | ( |  | ) |
| static

Get the big mutex that serializes access to all disconnect parameter lists

Returns
  A reference to the mutex

Referenced by Channel::copyChanParams(), and Channel::setChanParams().

void putStatus | ( | NamedList & | list,
|  | const char * | param = `"status"`,
|  | bool | append = `true`
| ) |  | const
| inline

Get the current status of the channel. Add it in list parameters This method is thread safe

Parameters

  list | Destination list
  param | Parameter name
  append | True to append parameter to list, false to replace

References NamedList::addParam(), Channel::getStatus(), and NamedList::setParam().

void setChanParams | ( | const NamedList & | list,
|  | bool | in = `false`
| ) |  |
| inline

Set channel parameters

Parameters

  list | List of parameters
  in | True if set for incoming channel (called for (pre)routed/rejected,accepted)

References NamedList::copySubParams(), Channel::paramMutex(), and TelEngine::YSTRING().

virtual bool setDebug | ( | Message & | msg | ) |
| virtual

Set the local debugging level

Parameters

  msg | Debug setting message

virtual void setDisconnect | ( | const NamedList * | params | ) |
| protectedvirtual

Set disconnect parameters

Parameters

  params | Pointer to disconnect cause parameters, NULL to reset them

Reimplemented from CallEndpoint.

virtual void setId | ( | const char * | newId | ) |
| protectedvirtual

Set a new ID for this channel

Parameters

  newId | New ID to set to this channel

Reimplemented from CallEndpoint.

void setMaxcall | ( | const Message & | msg,
|  | int | defTout = `-1`
| ) |  |
| inline

Set the time this channel will time out on outgoing calls

Parameters

  msg | Reference of message possibly holding "maxcall" parameter
  defTout | Default timeout to apply, negative to not alter

void setMaxcall | ( | const Message * | msg,
|  | int | defTout = `-1`
| ) |  |

Set the time this channel will time out on outgoing calls

Parameters

  msg | Pointer to message possibly holding "maxcall" parameter
  defTout | Default timeout to apply, negative to not alter

void setMaxPDD | ( | const Message & | msg | ) |

Set the time this channel will time out while waiting for some progress on outgoing calls

Parameters

  msg | Reference of message possibly holding "maxpdd" parameter

void setOutgoing | ( | bool | outgoing = `true` | ) |
| inlineprotected

Set the current direction of the channel

Parameters

  outgoing | True if this is an outgoing call channel

bool startRouter | ( | Message * | msg | ) |

Start a routing thread for this channel, dereference dynamic channels

Parameters

  msg | Pointer to message to route, typically a "call.route", will be destroyed after routing fails or completes

Returns
  True if routing thread started successfully, false if failed

void status | ( | const char * | newstat | ) |
| protected

Set the current status of the channel. Note that a value of "answered" will set the answered flag

Parameters

  newstat | The new status as String

virtual void statusParams | ( | String & | str | ) |
| protectedvirtual

Build the parameter reporting part of the status answer

Parameters

  str | String variable to fill up

const String& targetid | ( |  | ) | const
| inline

Get the connected channel identifier.

Returns
  A String holding the unique channel id of the target or an empty string if this channel is not connected to a target.

u_int64_t timeout | ( |  | ) | const
| inline

Get the time this channel will time out

Returns
  Timeout time or zero if no timeout

void timeout | ( | u_int64_t | tout | ) |
| inline

Set the time this channel will time out

Parameters

  tout | New timeout time or zero to disable

bool toneDetect | ( | const char * | sniffer = `0` | ) |
| protected

Attempt to install a data sniffer to detect inband tones Needs a tone detector module capable of attaching sniffer consumers.

Parameters

  sniffer | Name of the sniffer to install, default will detect all tones

Returns
  True on success

virtual void zeroRefs | ( |  | ) |
| protectedvirtual

This method is overriden to safely remove the channel from the parent driver list before actually destroying the channel.

Reimplemented from RefObject.

The documentation for this class was generated from the following file:

- yatephone.h