MGCPEngine Class Reference

An MGCP engine. More...

#include <yatemgcp.h>

Inheritance diagram for MGCPEngine:

Public Member Functions
	MGCPEngine (bool gateway, const char *name=0, const NamedList *params=0)
virtual	~MGCPEngine ()
bool	gateway () const
const SocketAddr &	address () const
unsigned int	maxRecvPacket () const
bool	allowUnkCmd () const
unsigned int	retransInterval () const
unsigned int	retransCount () const
u_int64_t	extraTime () const
bool	parseParamToLower () const
bool	provisional () const
bool	ackRequest () const
void	ackRequest (bool request)
virtual void	initialize (const NamedList &params)
bool	knownCommand (const String &cmd)
void	addCommand (const char *cmd)
void	attach (MGCPEndpoint *ep)
void	detach (MGCPEndpoint *ep, bool del=false, bool delTrans=false)
MGCPEndpoint *	findEp (MGCPEndpoint *ep)
MGCPEndpoint *	findEp (const String &epId)
MGCPTransaction *	findTrans (unsigned int id, bool outgoing)
unsigned int	getNextId ()
MGCPTransaction *	sendCommand (MGCPMessage *cmd, const SocketAddr &address, bool engineProcess=true)
bool	receive (unsigned char *buffer, SocketAddr &addr)
bool	process (u_int64_t time=Time())
bool	processTransaction (MGCPTransaction *tr, u_int64_t time=Time())
void	runReceive (SocketAddr &addr)
void	runReceive ()
void	runProcess ()
MGCPEvent *	getEvent (u_int64_t time=Time())
virtual bool	processEvent (MGCPEvent *event)
virtual bool	processEvent (MGCPTransaction *trans, MGCPMessage *msg)
void	returnEvent (MGCPEvent *event)
void	cleanup (bool gracefully=true, const char *text="Shutdown")
virtual void	timeout (MGCPTransaction *tr)
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 Mutex
	Mutex (bool recursive=false, const char *name=0)
	Mutex (const Mutex &original)
	~Mutex ()
Mutex &	operator= (const Mutex &original)
virtual bool	lock (long maxwait=-1)
virtual bool	unlock ()
virtual bool	locked () const
const char *	owner () const
bool	recursive () const
Public Member Functions inherited from Lockable
virtual	~Lockable ()
virtual bool	check (long maxwait=-1)
virtual bool	unlockAll ()

Static Public Member Functions
static int	defaultPort (bool gateway)
Static Public Member Functions inherited from Mutex
static int	count ()
static int	locks ()
static bool	efficientTimedLock ()
Static Public Member Functions inherited from Lockable
static void	wait (unsigned long maxwait)
static unsigned long	wait ()
static void	startUsingNow ()
static void	enableSafety (bool safe=true)
static bool	safety ()

Static Public Attributes
static TokenDict	mgcp_commands []
static TokenDict	mgcp_responses []
static TokenDict	mgcp_reasons []

Protected Member Functions
bool	sendData (const String &msg, const SocketAddr &address)
void	appendTrans (MGCPTransaction *trans)
void	removeTrans (MGCPTransaction *trans, bool del)
Protected Member Functions inherited from DebugEnabler
void	debugName (const char *name)

Protected Attributes
ObjList	m_endpoints
ObjList	m_transactions
ListIterator	m_iterator

Friends
class	MGCPPrivateThread
class	MGCPTransaction

Detailed Description

An MGCP engine.

The engine may keep gateway endpoints or call agents Keep the transaction list and manage it (create/delete/modify/timeout...) Keep a list with the endpoints it services Generate transaction numbers (IDs) Parse received messages, validate and send them to the appropriate transaction Send MGCP messages to remote addresses

Constructor & Destructor Documentation

MGCPEngine()

MGCPEngine	(	bool	gateway,
		const char *	name = 0,
		const NamedList *	params = 0 )

Constructor. Construct the engine and, optionally, initialize it

Parameters

gateway	Engine's mode: true if this engine is an MGCP Gateway, false if it's a collection of Call Agents
name	Optional debug name for this engine
params	Optional parameters used to initialize this engine

References gateway().

~MGCPEngine()

virtual ~MGCPEngine ( )

virtual

Destructor. Clear all lists

Member Function Documentation

ackRequest() [1/2]

bool ackRequest ( ) const

inline

Get the remote ACK request flag

Returns

True if remote will be requested to send an ACK

ackRequest() [2/2]

void ackRequest ( bool request )

inline

Set the remote ACK request flag

Parameters

request

False to not request from remote to send an ACK

addCommand()

void addCommand

(

const char *

cmd

)

Add a command to the list of known commands

Parameters

cmd	The command name to add

address()

const SocketAddr & address ( ) const

inline

Get the IP address used by this engine to receive data

Returns

The IP address used by this engine to receive data

Referenced by sendCommand(), and sendData().

allowUnkCmd()

bool allowUnkCmd ( ) const

inline

Check if this engine is allowed to send/accept unknown commands

Returns

True if this engine is allowed to send/accept unknown commands

appendTrans()

void appendTrans ( MGCPTransaction * trans )

protected

Append a transaction to the list

Parameters

trans

The transaction to append

attach()

void attach

(

MGCPEndpoint *

ep

)

Append an endpoint to this engine if not already done

Parameters

ep	The endpoint to append

cleanup()

void cleanup	(	bool	gracefully = true,
		const char *	text = "Shutdown" )

Terminate all transactions. Cancel all private threads if any and wait for them to terminate

Parameters

gracefully	If true, all incoming transaction will be responded and private threads will be gently cancelled. If false, all transactions will be deleted and threads will be cancelled the hard way
text	Optional text to be sent with the response code of the incoming transactions on gracefully cleanup

defaultPort()

static int defaultPort ( bool gateway )

inlinestatic

Get the default port defined by the protocol

Parameters

gateway

True to get the default Gateway port, false to get the default port for the Call Agent

Returns

The default port defined by the protocol

References gateway().

detach()

void detach	(	MGCPEndpoint *	ep,
		bool	del = false,
		bool	delTrans = false )

Remove an endpoint from this engine and, optionally, remove all its transactions

Parameters

ep	The endpoint to remove
del	True to delete it, false to just remove it from the list
delTrans	True to remove all its transactions. Forced to true if the endpoint is deleted

extraTime()

u_int64_t extraTime ( ) const

inline

Get the time to live after the transaction terminated gracefully

Returns

The time to live after the transaction terminated gracefully

findEp() [1/2]

MGCPEndpoint * findEp

(

const String &

epId

)

Find an endpoint by its id

Parameters

epId	The endpoint's id to find

Returns

MGCPEndpoint pointer or 0 if not found

findEp() [2/2]

MGCPEndpoint * findEp

(

MGCPEndpoint *

ep

)

Find an endpoint by its pointer

Parameters

ep	The endpoint to find

Returns

MGCPEndpoint pointer or 0 if not found

findTrans()

MGCPTransaction * findTrans	(	unsigned int	id,
		bool	outgoing )

Find a transaction by its id

Parameters

id	The id of the transaction to find
outgoing	The transaction direction. True for outgoing, false for incoming

Returns

MGCPTransaction pointer or 0 if not found

gateway()

bool gateway ( ) const

inline

Check if this engine is an MGCP Gateway or a collection of Call Agents

Returns

True if this engine is an MGCP Gateway, false if it's a collection of Call Agents

Referenced by defaultPort(), and MGCPEngine().

getEvent()

MGCPEvent * getEvent

(

u_int64_t

time = Time()

)

Try to get an event from a transaction

Parameters

time	Current time in microseconds

Returns

MGCPEvent pointer or 0 if none

getNextId()

unsigned int getNextId

(

)

Generate a new id for an outgoing transaction

Returns

An id for an outgoing transaction

initialize()

virtual void initialize ( const NamedList & params )

virtual

Initialize this engine

Parameters

params

Engine's parameters

knownCommand()

bool knownCommand ( const String & cmd )

inline

Check if a command is known by this engine

Parameters

cmd	The command name to check

Returns

True if the given command is known by this engine

References Mutex::lock().

maxRecvPacket()

unsigned int maxRecvPacket ( ) const

inline

Get the maximum length or received packets. This is the size of the buffer used by this engine to read data from the socket

Returns

The maximum length or received packets

parseParamToLower()

bool parseParamToLower ( ) const

inline

Check if the parser should convert received messages' parameters to lower case

Returns

True if the parser should convert received messages' parameters to lower case

process()

bool process

(

u_int64_t

time = Time()

)

Try to get an event from a transaction. If the event contains an unknown command and this engine is not allowed to process such commands, calls the returnEvent() method, otherwise, calls the processEvent() method

Parameters

time	Current time in microseconds

Returns

True if an event was processed

processEvent() [1/2]

virtual bool processEvent ( MGCPEvent * event )

virtual

Process an event generated by a transaction. Descendants must override this method if they want to process events. By default it calls the version of processEvent that accepts separate parameters of event

Parameters

event

The event to process

Returns

True if the event was processed. If the event carry a received command and it's not processed the transaction will receive an 'unknown command' response

processEvent() [2/2]

virtual bool processEvent ( MGCPTransaction * trans, MGCPMessage * msg )

virtual

Process an event generated by a transaction. Descendants must override this method if they want to process events

Parameters

trans	Pointer to the transaction that generated the event
msg	MGCP message of the event, may be NULL

Returns

True if the event was processed. If the event carry a received command and it's not processed the transaction will receive an 'unknown command' response

processTransaction()

bool processTransaction	(	MGCPTransaction *	tr,
		u_int64_t	time = Time() )

Try to get an event from a given transaction. If the event contains an unknown command and this engine is not allowed to process such commands, calls the returnEvent() method, otherwise, calls the processEvent() method

Parameters

tr	Transaction to process
time	Current time in microseconds

Returns

True if an event was processed

provisional()

bool provisional ( ) const

inline

Check if incoming transactions would send provisional responses

Returns

True if incoming transactions would send provisional responses

receive()

bool receive	(	unsigned char *	buffer,
		SocketAddr &	addr )

Read data from the socket. Parse and process the received message

Parameters

buffer	Buffer used for read operation. The buffer must be large enough to keep the maximum packet length returned by maxRecvPacket()
addr	The sender's address if received any data

Returns

True if received any data (a message was successfully parsed)

removeTrans()

void removeTrans ( MGCPTransaction * trans, bool del )

protected

Remove a transaction from the list

Parameters

trans	The transaction to remove
del	True to delete it, false to just remove it from list

retransCount()

unsigned int retransCount ( ) const

inline

Get the maximum number of retransmissions for a message

Returns

The maximum number of retransmissions for a message

retransInterval()

unsigned int retransInterval ( ) const

inline

Get the message retransmission interval

Returns

The message retransmission interval

returnEvent()

void returnEvent

(

MGCPEvent *

event

)

Returns an unprocessed event to this engine to be deleted. Incoming transactions will be responded. Unknown commands will receive a 504 Unknown Command response, the others will receive a 507 Unsupported Functionality one

Parameters

event

The event to return

runProcess()

void runProcess

(

)

Repeatedly calls process() until the calling thread terminates

runReceive() [1/2]

void runReceive

(

)

Repeatedly calls receive() until the calling thread terminates

runReceive() [2/2]

void runReceive

(

SocketAddr &

addr

)

Repeatedly calls receive() until the calling thread terminates

Parameters

addr	The sender's address if received any data

sendCommand()

MGCPTransaction * sendCommand	(	MGCPMessage *	cmd,
		const SocketAddr &	address,
		bool	engineProcess = true )

Send a command message. Create a transaction for it. The method will fail if the message is not a valid one or isn't a valid command

Parameters

cmd	The message containig the command
address	The destination IP address
engineProcess	Use engine private processor thread for the new transaction. If false the caller is responsable with transaction processing

Returns

MGCPTransaction pointer or 0 if failed to create a transaction

References address().

sendData()

bool sendData ( const String & msg, const SocketAddr & address )

protected

Send a string buffer through the socket

Parameters

msg	The buffer to send
address	The destination IP address

Returns

False if the operation failed

References address().

timeout()

virtual void timeout ( MGCPTransaction * tr )

inlinevirtual

Handle a transaction that has timed out

Parameters

tr	The transaction that has timed out

Member Data Documentation

m_endpoints

ObjList m_endpoints

protected

The list of endpoints attached to this engine

m_iterator

ListIterator m_iterator

protected

The transaction list iterator used to get events

m_transactions

ObjList m_transactions

protected

The transaction list

mgcp_commands

TokenDict mgcp_commands[]

static

The list of commands defined in RFC 3435

mgcp_reasons

TokenDict mgcp_reasons[]

static

The list of known reason codes defined in RFC 3435 2.5. Reason codes are used by the gateway when deleting a connection to inform the Call Agent about the reason for deleting the connection. They may also be used in a RestartInProgress command to inform the Call Agent of the reason for the RestartInProgress

mgcp_responses

TokenDict mgcp_responses[]

static

The list of known responses defined in RFC 3435 2.4

---

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

• yatemgcp.h