# class Channel

An abstract communication channel. More...

Full name | `TelEngine::Channel`
Definition | `#include <yatephone.h>`
Inherits | TelEngine::CallEndpoint [public ], TelEngine::DebugEnabler [public ], TelEngine::MessageNotifier [public ]
Inherited by | ClientChannel
List of all Methods

Annotated List
Files
Globals
Hierarchy
Index

#### Public Methods

- 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)
- inline 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)
- inline const String& status () const
- inline const String& address () const
- inline bool isOutgoing () const
- inline bool isIncoming () const
- inline bool isAnswered () const
- const char* direction () const
- inline Driver* driver () const
- inline u_int64_t timeout () const
- inline void timeout (u_int64_t tout)
- inline u_int64_t maxcall () const
- inline void maxcall (u_int64_t tout)
- inline void setMaxcall (const Message& msg, int defTout = -1)
- void setMaxcall (const Message* msg, int defTout = -1)
- inline const String& targetid () const
- inline const String& billid () const
- const String& lastPeerId () const
- void initChan ()
- bool startRouter (Message* msg)
- void filterDebug (const String& item)
- inline const NamedList& parameters () const
- virtual void dispatched (const Message& msg, bool handled)

#### Public Static Methods

- static Mutex& paramMutex ()
- static unsigned int allocId ()

#### Protected Methods

- 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)
- virtual void statusParams (String& str)
- inline void setOutgoing (bool outgoing = true)
- bool dtmfSequence (Message& msg)
- bool dtmfEnqueue (Message* msg)
- bool dtmfInband (const char* tone)
- bool toneDetect (const char* sniffer = 0)
- inline NamedList& parameters ()

#### Protected Members

- String m_status
- String m_address
- String m_targetid
- String m_billid
- bool m_answered

## Detailed Description

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

String m_status

### m_status

[protected]

String m_address

### m_address

[protected]

String m_targetid

### m_targetid

[protected]

String m_billid

### m_billid

[protected]

bool m_answered

### m_answered

[protected]

~Channel ()

### ~Channel

[virtual]

Destructor

void* getObject (const String& name)

### getObject

[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.

Mutex& paramMutex ()

### paramMutex

[static]

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

Returns: A reference to the mutex

void complete (Message& msg, bool minimal = false)

### complete

[const virtual]

Put channel variables into a message

Parameters:

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

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

### message

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

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

### message

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

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

### message

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

bool msgProgress (Message& msg)

### msgProgress

[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

bool msgRinging (Message& msg)

### msgRinging

[virtual]

Notification on remote ringing

Parameters:

msg | Notification message

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

bool msgAnswered (Message& msg)

### msgAnswered

[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

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

### msgTone

[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

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

### msgText

[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

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

### msgDrop

[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

bool msgTransfer (Message& msg)

### msgTransfer

[virtual]

Notification on native transfer request

Parameters:

msg | Notification message

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

bool msgUpdate (Message& msg)

### msgUpdate

[virtual]

Notification on call parameters update request

Parameters:

msg | Notification message

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

bool msgMasquerade (Message& msg)

### msgMasquerade

[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

void msgStatus (Message& msg)

### msgStatus

[virtual]

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

Parameters:

msg | Status message

bool msgControl (Message& msg)

### msgControl

[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

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

### checkTimers

[virtual]

Timer check method, by default handles channel timeouts

Parameters:

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

bool callPrerouted (Message& msg, bool handled)

### callPrerouted

[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

bool callRouted (Message& msg)

### callRouted

[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

void callAccept (Message& msg)

### callAccept

[virtual]

Notification on success of incoming call

Parameters:

msg | Notification call.execute message just after being dispatched

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

### callRejected

[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

void callConnect (Message& msg)

### callConnect

[virtual]

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

Parameters:

msg | Notification call.execute message while being dispatched

bool setDebug (Message& msg)

### setDebug

[virtual]

Set the local debugging level

Parameters:

msg | Debug setting message

inline const String& status ()

### status

[const]

Get the current status of the channel

Returns: The current status as String

inline const String& address ()

### address

[const]

Get the current link address of the channel

Returns: The protocol dependent address as String

inline bool isOutgoing ()

### isOutgoing

[const]

Get the direction of the channel

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

inline bool isIncoming ()

### isIncoming

[const]

Get the direction of the channel

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

inline bool isAnswered ()

### isAnswered

[const]

Check if the call was answered or not

Returns: True if the call was answered

const char* direction ()

### direction

[const]

Get the direction of the channel as string

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

inline Driver* driver ()

### driver

[const]

Get the driver of this channel

Returns: Pointer to this channel's driver

inline u_int64_t timeout ()

### timeout

[const]

Get the time this channel will time out

Returns: Timeout time or zero if no timeout

inline void timeout (u_int64_t tout)

### timeout

Set the time this channel will time out

Parameters:

tout | New timeout time or zero to disable

inline u_int64_t maxcall ()

### maxcall

[const]

Get the time this channel will time out on outgoing calls

Returns: Timeout time or zero if no timeout

inline void maxcall (u_int64_t tout)

### maxcall

Set the time this channel will time out on outgoing calls

Parameters:

tout | New timeout time or zero to disable

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

### setMaxcall

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)

### setMaxcall

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

inline const String& targetid ()

### targetid

[const]

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.

inline const String& billid ()

### billid

[const]

Get the billing identifier.

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

const String& lastPeerId ()

### lastPeerId

[const]

Get the last connected peer id

Returns: The last connected peer id

void initChan ()

### initChan

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

bool startRouter (Message* msg)

### startRouter

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

unsigned int allocId ()

### allocId

[static]

Allocate an unique (per engine run) call ID

Returns: Unique call ID number

void filterDebug (const String& item)

### filterDebug

Enable or disable debugging according to driver's filter rules

Parameters:

item | Value of the item to match

inline const NamedList& parameters ()

### parameters

[const]

Get the disconnect parameters list

Returns: Constant reference to disconnect parameters

void dispatched (const Message& msg, bool handled)

### dispatched

[virtual]

Notification for dispatched messages

Parameters:

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

Reimplemented from MessageNotifier.

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

### Channel

[protected]

Constructor

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

### Channel

[protected]

Alternate constructor provided for convenience

void cleanup ()

### cleanup

[protected]

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

void dropChan ()

### dropChan

[protected]

Remove the channel from the parent driver list

void zeroRefs ()

### zeroRefs

[protected virtual]

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

Reimplemented from RefObject.

void connected (const char* reason)

### connected

[protected virtual]

Connect notification method.

Parameters:

reason | Text that describes connect reason.

Reimplemented from CallEndpoint.

void disconnected (bool final, const char* reason)

### disconnected

[protected virtual]

Disconnect notification method.

Parameters:

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

Reimplemented from CallEndpoint.

void setDisconnect (const NamedList* params)

### setDisconnect

[protected virtual]

Set disconnect parameters

Parameters:

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

Reimplemented from CallEndpoint.

void endDisconnect (const Message& msg, bool handled)

### endDisconnect

[protected virtual]

Notification after chan.disconnected handling

Parameters:

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

void setId (const char* newId)

### setId

[protected virtual]

Set a new ID for this channel

Parameters:

newId | New ID to set to this channel

Reimplemented from CallEndpoint.

Message* getDisconnect (const char* reason)

### getDisconnect

[protected virtual]

Create a properly populated chan.disconnect message

Parameters:

reason | Channel disconnect reason if available

Returns: A new allocated and parameter filled chan.disconnected message

void status (const char* newstat)

### status

[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

void statusParams (String& str)

### statusParams

[protected virtual]

Build the parameter reporting part of the status answer

Parameters:

str | String variable to fill up

inline void setOutgoing (bool outgoing = true)

### setOutgoing

[protected]

Set the current direction of the channel

Parameters:

outgoing | True if this is an outgoing call channel

bool dtmfSequence (Message& msg)

### dtmfSequence

[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)

bool dtmfEnqueue (Message* msg)

### dtmfEnqueue

[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)

### dtmfInband

[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 toneDetect (const char* sniffer = 0)

### toneDetect

[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

inline NamedList& parameters ()

### parameters

[protected]

Get the disconnect parameters list

Returns: Reference to disconnect parameters

Generated by: paulc on bussard on Fri Dec 21 16:28:34 2012, using kdoc 2.0a54.