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

~Channel()

virtual ~Channel ( )

virtual

Destructor

Channel() [1/2]

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

protected

Constructor

Channel() [2/2]

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

protected

Alternate constructor provided for convenience

Member Function Documentation

address()

const String & address ( ) const

inline

Get the current link address of the channel

Returns

The protocol dependent address as String

allocId()

static unsigned int allocId ( )

static

Allocate an unique (per engine run) call ID

Returns

Unique call ID number

billid()

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.

callAccept()

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.

callConnect()

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

callPrerouted()

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

callRejected()

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.

callRouted()

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.

checkTimers()

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

cleanup()

void cleanup ( )

protected

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

complete()

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

connected()

virtual void connected ( const char *  reason )

protectedvirtual

Connect notification method.

Parameters

reason

Text that describes connect reason.

Reimplemented from CallEndpoint.

Reimplemented in ClientChannel.

copyChanParams()

void copyChanParams ( NamedList &  list ) const

inline

Copy channel parameters

Parameters

list	Destination list

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

direction()

const char * direction

(

)

const

Get the direction of the channel as string

Returns

"incoming" or "outgoing" according to the direction

disconnected()

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.

dispatched()

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 * driver ( ) const

inline

Get the driver of this channel

Returns

Pointer to this channel's driver

dropChan()

void dropChan ( )

protected

Remove the channel from the parent driver list

dtmfEnqueue()

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

dtmfInband()

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

dtmfSequence()

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)

endDisconnect()

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

filterDebug()

void filterDebug

(

const String &

item

)

Enable or disable debugging according to driver's filter rules

Parameters

item	Value of the item to match

getDisconnect()

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

getObject()

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.

getStatus() [1/2]

const String & getStatus ( ) const

inlineprotected

Retrieve Channel status This method is not thread safe

Returns

Channel status

Referenced by Channel::putStatus().

getStatus() [2/2]

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

initChan()

void initChan

(

)

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

isAnswered()

bool isAnswered ( ) const

inline

Check if the call was answered or not

Returns

True if the call was answered

isIncoming()

bool isIncoming ( ) const

inline

Get the direction of the channel

Returns

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

isOutgoing()

bool isOutgoing ( ) const

inline

Get the direction of the channel

Returns

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

maxcall() [1/2]

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

maxcall() [2/2]

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

maxPDD() [1/2]

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

maxPDD() [2/2]

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() [1/3]

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() [2/3]

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().

message() [3/3]

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

msgAnswered()

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.

msgControl()

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

msgDrop()

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.

msgMasquerade()

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

msgProgress()

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.

msgRinging()

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.

msgStatus()

virtual void msgStatus ( Message &  msg )

virtual

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

Parameters

msg	Status message

msgText()

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

msgTone()

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

msgTransfer()

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

msgUpdate()

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

parameters() [1/2]

NamedList & parameters ( )

inlineprotected

Get the disconnect parameters list

Returns

Reference to disconnect parameters

parameters() [2/2]

const NamedList & parameters ( ) const

inline

Get the disconnect parameters list

Returns

Constant reference to disconnect parameters

paramMutex()

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().

putStatus()

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().

setChanParams()

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(), and Channel::paramMutex().

setDebug()

virtual bool setDebug ( Message &  msg )

virtual

Set the local debugging level

Parameters

msg	Debug setting message

setDisconnect()

virtual void setDisconnect ( const NamedList *  params )

protectedvirtual

Set disconnect parameters

Parameters

params

Pointer to disconnect cause parameters, NULL to reset them

Reimplemented from CallEndpoint.

setId()

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.

setMaxcall() [1/2]

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

References Channel::setMaxcall().

Referenced by Channel::setMaxcall().

setMaxcall() [2/2]

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

setMaxPDD()

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

setOutgoing()

void setOutgoing ( bool  outgoing = true )

inlineprotected

Set the current direction of the channel

Parameters

outgoing

True if this is an outgoing call channel

startRouter()

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

status()

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

statusParams()

virtual void statusParams ( String &  str )

protectedvirtual

Build the parameter reporting part of the status answer

Parameters

str	String variable to fill up

targetid()

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.

timeout() [1/2]

u_int64_t timeout ( ) const

inline

Get the time this channel will time out

Returns

Timeout time or zero if no timeout

timeout() [2/2]

void timeout ( u_int64_t  tout )

inline

Set the time this channel will time out

Parameters

tout	New timeout time or zero to disable

toneDetect()

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

zeroRefs()

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