A basic Jingle session. More...

#include <yatejingle.h>

Inheritance diagram for JGSession:

Public Types
enum	Version { Version0 = 0, Version1 = 1, VersionUnknown }
enum	Reason { ReasonUnknown = 0, ReasonOk, ReasonBusy, ReasonDecline, ReasonCancel, ReasonExpired, ReasonConn, ReasonFailApp, ReasonFailTransport, ReasonGone, ReasonParams, ReasonMedia, ReasonTransport, ReasonApp, ReasonSecurity, ReasonTimeout, ReasonGeneral, ReasonAltSess, Transferred, CryptoRequired, InvalidCrypto }
enum	RtpInfo { RtpActive, RtpHold, RtpMute, RtpRinging }
enum	State { Idle = 0, Pending = 1, Active = 2, Ending = 3, Destroy = 4 }
enum	Action { ActAccept, ActInitiate, ActTerminate, ActReject, ActInfo, ActTransportInfo, ActTransportAccept, ActTransportReject, ActTransportReplace, ActCandidates, ActContentAccept, ActContentAdd, ActContentModify, ActContentReject, ActContentRemove, ActContentInfo, ActDescriptionInfo, ActTransfer, ActRinging, ActTrying, ActReceived, ActHold, ActActive, ActMute, ActDtmf, ActStreamHost, ActCount }
enum	SessionFlag { FlagNoPing = 0x0001 }
Public Member Functions
virtual	~JGSession ()
Version	version () const
JGEngine *	engine () const
bool	outgoing () const
const String &	sid () const
const JabberID &	local () const
const JabberID &	remote () const
State	state () const
int	flag (int mask) const
void	setFlags (int value)
void *	userData ()
void	userData (void *userdata)
const String &	line () const
void	line (const String &acc)
Action	getAction (XmlElement *xml)
bool	acceptIq (XMPPUtils::IqType type, const JabberID &from, const JabberID &to, const String &id, XmlElement *xml)
bool	confirmResult (XmlElement *xml)
bool	confirmError (XmlElement &xml, XMPPError::Type error, const char text=0, XMPPError::ErrorType type=XMPPError::TypeModify)
virtual bool	accept (const ObjList &contents, String *stanzaId=0)
virtual bool	hangup (XmlElement *reason=0)
virtual XmlElement *	createRtpInfoXml (RtpInfo info)
virtual XmlElement *	createReason (int reason, const char text=0, XmlElement child=0)
virtual XmlElement *	createTransferReason (int reason)
virtual XmlElement *	createRtpSessionReason (int reason)
virtual bool	sendContent (Action action, const ObjList &contents, String *stanzaId=0)
bool	sendContent (Action action, const JGSessionContent content, String stanzaId=0)
virtual bool	sendStreamHosts (const ObjList &hosts, String *stanzaId=0)
virtual bool	sendStreamHostUsed (const char jid, const char stanzaId)
void	buildSocksDstAddr (String &buf)
bool	sendInfo (XmlElement xml, String stanzaId=0)
bool	sendDtmf (const char dtmf, unsigned int msDuration=0, String stanzaId=0)
bool	hasFeature (XMPPNamespace::Type feature)
Static Public Member Functions
static XmlElement *	buildTransfer (const String &transferTo, const String &transferFrom, const String &sid=String::empty())
static Version	lookupVersion (const char *value, Version def=VersionUnknown)
static const char *	lookupVersion (int value, const char *def="unknown")
static int	lookupReason (const char *value, int def=ReasonOk)
static const char *	lookupReason (int value, const char *def=0)
static const char *	lookupState (int state)
static const char *	lookupAction (int act, Version ver)
static Action	lookupAction (const char *str, Version ver)
Static Public Attributes
static const TokenDict	s_versions []
static const TokenDict	s_reasons []
static const TokenDict	s_rtpInfo []
static const TokenDict	s_states []
static const TokenDict	s_actions0 []
static const TokenDict	s_actions1 []
static const TokenDict	s_flagName []
Protected Member Functions
	JGSession (Version ver, JGEngine *engine, const JabberID &caller, const JabberID &called)
	JGSession (Version ver, JGEngine engine, const JabberID &caller, const JabberID &called, XmlElement xml, const String &id)
virtual bool	initiate (const ObjList &contents, XmlElement extra, const char subject=0)=0
virtual JGEvent *	getEvent (u_int64_t time)
virtual void	destroyed ()
bool	sendStanza (XmlElement stanza, String stanzaId=0, bool confirmation=true, bool ping=false)
bool	sendPing (u_int64_t msecNow)
virtual JGEvent *	decodeJingle (XmlElement &xml, XmlElement child)=0
virtual XmlElement *	createJingle (Action action, XmlElement element1=0, XmlElement element2=0, XmlElement *element3=0)=0
virtual XmlElement *	createDtmf (const char *dtmf, unsigned int msDuration=0)=0
virtual JGEvent *	processJingleSetEvent (JGEvent *&ev)
virtual JGEvent *	processJabberIqResponse (bool result, XmlElement *&xml)
virtual JGEvent *	processFileTransfer (bool set, XmlElement &xml, XmlElement child)
void	eventTerminated (JGEvent *event)
void	changeState (State newState)
Protected Attributes
Version	m_version
State	m_state
int	m_flags
u_int64_t	m_timeToPing
JGEngine *	m_engine
bool	m_outgoing
String	m_sid
JabberID	m_local
JabberID	m_remote
XmlFragment	m_queue
JGEvent *	m_lastEvent
bool	m_recvTerminate
void *	m_private
String	m_localSid
u_int32_t	m_stanzaId
ObjList	m_sentStanza
String	m_line
Friends
class	JGEvent
class	JGEngine

Detailed Description

A basic Jingle session.

This class is a base class for all specific jingle sessions

Member Enumeration Documentation

enum Action

Jingle action enumeration

enum Reason

Jingle defined reasons and errors

enum RtpInfo

RTP session info (XEP 0167)

enum SessionFlag

Session flags

enum State

Session state enumeration

enum Version

Jingle session version

Constructor & Destructor Documentation

virtual ~JGSession ( ) [virtual]

Destructor

JGSession	(	Version	ver,
		JGEngine *	engine,
		const JabberID &	caller,
		const JabberID &	called
	)		`[protected]`

Constructor. Create an outgoing session

Parameters:

ver	The session version
engine	The engine owning this session
caller	The caller's full JID
called	The called party's full JID

JGSession	(	Version	ver,
		JGEngine *	engine,
		const JabberID &	caller,
		const JabberID &	called,
		XmlElement *	xml,
		const String &	id
	)		`[protected]`

Constructor. Create an incoming session.

Parameters:

ver	The session version
engine	The engine owning this session
caller	The caller's full JID
called	The called party's full JID
xml	A valid Jabber Jingle xml with action session initiate
id	Session id

Member Function Documentation

virtual bool accept	(	const ObjList &	contents,
		String *	stanzaId = `0`
	)		`[inline, virtual]`

Accept a Pending incoming session. This method is thread safe

Parameters:

contents	The list of accepted contents
stanzaId	Optional string to be filled with sent stanza id (used to track the response)

Returns:: False if send failed

Reimplemented in JGSession1, and JGSession0.

bool acceptIq	(	XMPPUtils::IqType	type,
		const JabberID &	from,
		const JabberID &	to,
		const String &	id,
		XmlElement *	xml
	)

Ask this session to accept an incoming xml 'iq' element

Parameters:

type	Iq type as enumeration
from	The sender
to	The recipient
id	The session id of this is a request (set/get) or the stanza id
xml	The received element

Returns:: True if accepted (the element was enqueued), false if not

void buildSocksDstAddr ( String & buf )

Build SOCKS SHA1 dst.addr used by file transfer

Parameters:

buf	Destination string

static XmlElement* buildTransfer	(	const String &	transferTo,
		const String &	transferFrom,
		const String &	sid = `String::empty()`
	)		`[static]`

Build a transfer element

Parameters:

transferTo	The JID to transfer to
transferFrom	The transferror's JID
sid	Optional session id used for attended transfer (empty for unattended transfer)

Returns:: Valid XmlElement pointer

void changeState ( State newState ) [protected]

Changed session state

Parameters:

newState Session new state

bool confirmError	(	XmlElement *&	xml,
		XMPPError::Type	error,
		const char *	text = `0`,
		XMPPError::ErrorType	type = `XMPPError::TypeModify`
	)

Confirm (send error) a received element

Parameters:

xml	The element to confirm (will be consumed and zeroed)
error	The error condition
text	Optional text to add to the error element
type	Error type

Returns:: False if send failed or element is 0

bool confirmResult ( XmlElement * xml )

Confirm (send result) a received element

Parameters:

xml	The element to confirm

Returns:: False if send failed or element is 0

virtual XmlElement* createDtmf	(	const char *	dtmf,
		unsigned int	msDuration = `0`
	)		`[protected, pure virtual]`

Create a dtmf XML element

Parameters:

dtmf	The dtmf string
msDuration	The tone duration in miliseconds. Ignored if 0

Returns:: Valid XmlElement pointer or 0

Implemented in JGSession1, and JGSession0.

virtual XmlElement* createJingle	(	Action	action,
		XmlElement *	element1 = `0`,
		XmlElement *	element2 = `0`,
		XmlElement *	element3 = `0`
	)		`[protected, pure virtual]`

Create an 'iq' of type 'set' with a 'jingle' child

Parameters:

action	The action of the Jingle stanza
element1	Optional child element
element2	Optional child element
element3	Optional child element

Returns:: Valid XmlElement pointer

Implemented in JGSession1.

virtual XmlElement* createReason	(	int	reason,
		const char *	text = `0`,
		XmlElement *	child = `0`
	)		`[inline, virtual]`

Create a termination reason element

Parameters:

reason	The reason code
text	Optional reason text child
child	Optional additional reason child

Returns:: Valid XmlElement pointer or 0 if not supported

Reimplemented in JGSession1.

virtual XmlElement* createRtpInfoXml ( RtpInfo info ) [inline, virtual]

Create a RTP info child to be added to a session-info element

Parameters:

info	The informational tag as enumeration

Returns:: Valid XmlElement pointer or 0 if not supported

Reimplemented in JGSession1.

virtual XmlElement* createRtpSessionReason ( int reason ) [inline, virtual]

Create a RTP session reason element

Parameters:

reason The reason code

Returns:: Valid XmlElement pointer or 0 if not supported

Reimplemented in JGSession1.

virtual XmlElement* createTransferReason ( int reason ) [inline, virtual]

Create a transfer reason element

Parameters:

reason The reason code

Returns:: Valid XmlElement pointer or 0 if not supported

Reimplemented in JGSession1.

virtual JGEvent* decodeJingle	(	XmlElement *&	xml,
		XmlElement *	child
	)		`[protected, pure virtual]`

Decode a jingle element

Parameters:

xml	The element to decode
child	The element's first child

Returns:: JGEvent pointer or 0

Implemented in JGSession1, and JGSession0.

virtual void destroyed ( ) [protected, virtual]

Release this session and its memory

Reimplemented from RefObject.

JGEngine* engine ( ) const [inline]

Retrieve the engine owning this session

Returns:: The engine owning this session

void eventTerminated ( JGEvent * event ) [protected]

Terminate notification from an event. Reset the last generated event

Parameters:

event Terminated (processed) event

int flag ( int mask ) const [inline]

Retrieve session flags

Parameters:

mask	Mask to retrieve

Returns:: Session flags

Action getAction ( XmlElement * xml )

Get an action (jingle element type) from a jingle element

Parameters:

xml	Element to check

Returns:: The found action, ActCount if not found or unknown

virtual JGEvent* getEvent ( u_int64_t time ) [protected, virtual]

Get a Jingle event from the queue. This method is thread safe

Parameters:

time	Current time in miliseconds

Returns:: JGEvent pointer or 0

virtual bool hangup ( XmlElement * reason = 0 ) [virtual]

Close a Pending or Active session This method is thread safe

Parameters:

reason Optional termination reason

Returns:: False if send failed

bool hasFeature ( XMPPNamespace::Type feature )

Check if the remote party supports a given feature

Parameters:

feature The requested feature

Returns:: True if the remote party supports the given feature

virtual bool initiate	(	const ObjList &	contents,
		XmlElement *	extra,
		const char *	subject = `0`
	)		`[protected, pure virtual]`

Build and send the initial message on an outgoing session

Parameters:

contents	The session contents to be sent with session initiate element
extra	Optional extra child to be added to the session initiate element
subject	Optional session subject

Returns:: True on success

Implemented in JGSession1, and JGSession0.

const String& line ( ) const [inline]

Retrieve the client account used by this session

Returns:: The client account used by this session

void line ( const String & acc ) [inline]

Set the client account used by this session

Parameters:

acc	The client account used by this session

const JabberID& local ( ) const [inline]

Get the local peer's JID

Returns:: The local peer's JID

static const char* lookupAction	(	int	act,
		Version	ver
	)		`[static]`

Get the name of an action

Parameters:

act	The action to find
ver	Session version to use

Returns:: The name of an action

Referenced by JGEvent::actionName().

static Action lookupAction	(	const char *	str,
		Version	ver
	)		`[static]`

Get the action associated with a given string

Parameters:

str	The action name
ver	Session version to use

Returns:: The name of an action

static int lookupReason	(	const char *	value,
		int	def = `ReasonOk`
	)		`[inline, static]`

Get the termination code associated with a text

Parameters:

value	The termination text
def	Default value to return if not found

Returns:: Termination code

References TelEngine::lookup().

static const char* lookupReason	(	int	value,
		const char *	def = `0`
	)		`[inline, static]`

Get the termination code associated with a text

Parameters:

value	The termination code
def	Default value to return if not found

Returns:: Termination text

References TelEngine::lookup().

static const char* lookupState ( int state ) [inline, static]

Get the name of a session state

Parameters:

state The state to find

Returns:: The name of a session state

References TelEngine::lookup().

static Version lookupVersion	(	const char *	value,
		Version	def = `VersionUnknown`
	)		`[inline, static]`

Get the session version associated with a text

Parameters:

value	The version text
def	Default value to return if not found

Returns:: Session Version value

References TelEngine::lookup().

static const char* lookupVersion	(	int	value,
		const char *	def = `"unknown"`
	)		`[inline, static]`

Get the session version name

Parameters:

value	The version value
def	Default value to return if not found

Returns:: Session version name or the default value if not found

References TelEngine::lookup().

bool outgoing ( ) const [inline]

Get the session direction

Returns:: True if it is an outgoing session

virtual JGEvent* processFileTransfer	(	bool	set,
		XmlElement *&	xml,
		XmlElement *	child
	)		`[protected, virtual]`

Decode a file transfer element

Parameters:

set	True if the xml is an iq 'set', false if type is 'get'
xml	The element to decode
child	The element's first child

Returns:: JGEvent pointer or 0

Reimplemented in JGSession1.

virtual JGEvent* processJabberIqResponse	(	bool	result,
		XmlElement *&	xml
	)		`[protected, virtual]`

Method called in getEvent() to process a jabber event carrying a response

Parameters:

result	True if the element is a result, false if it's an error response
xml	Xml element to process

Returns:: JGEvent pointer or 0

virtual JGEvent* processJingleSetEvent ( JGEvent *& ev ) [protected, virtual]

Method called in getEvent() to process a last event decoded from a received jingle element

Parameters:

ev	The event to process (will be consumed and zeroed)

Returns:: JGEvent pointer or 0

const JabberID& remote ( ) const [inline]

Get the remote peer's JID

Returns:: The remote peer's JID

virtual bool sendContent	(	Action	action,
		const ObjList &	contents,
		String *	stanzaId = `0`
	)		`[inline, virtual]`

Send a stanza with session content(s) This method is thread safe

Parameters:

action	Must be a transport- or content- action
contents	Non empty list with content(s) to send
stanzaId	Optional string to be filled with sent stanza id (used to track the response)

Returns:: False if send failed

Reimplemented in JGSession1.

bool sendContent	(	Action	action,
		const JGSessionContent *	content,
		String *	stanzaId = `0`
	)		`[inline]`

Send a stanza with a session content This method is thread safe

Parameters:

action	Must be a transport- or content- action
content	The content to send
stanzaId	Optional string to be filled with sent stanza id (used to track the response)

Returns:: False if send failed

References ObjList::append(), and ObjList::setDelete().

bool sendDtmf	(	const char *	dtmf,
		unsigned int	msDuration = `0`,
		String *	stanzaId = `0`
	)

Send a dtmf string to remote peer. If the string's length is greater then 1, each character is added as a 'dtmf' child of the jingle element

Parameters:

dtmf	The dtmf string
msDuration	The tone duration in miliseconds. Ignored if 0
stanzaId	Optional string to be filled with sent stanza id (used to track the response)

Returns:: False if send failed

bool sendInfo	(	XmlElement *	xml,
		String *	stanzaId = `0`
	)

Send a session info element to the remote peer. This method is thread safe

Parameters:

xml	The XmlElement carried by the session info element
stanzaId	Optional string to be filled with sent stanza id (used to track the response)

Returns:: False on failure

bool sendPing ( u_int64_t msecNow ) [protected]

Send a ping (empty session info) stanza to the remote peer if it's time to do it

Parameters:

msecNow The current time

Returns:: True if a ping was succesfully sent

bool sendStanza	(	XmlElement *	stanza,
		String *	stanzaId = `0`,
		bool	confirmation = `true`,
		bool	ping = `false`
	)		`[protected]`

Send a stanza to the remote peer

Parameters:

stanza	The stanza to send
stanzaId	Optional string to be filled with sent stanza id (used to track the response)
confirmation	True if the stanza needs confirmation (add 'id' attribute)
ping	True if the stanza is a ping one

Returns:: True on success

virtual bool sendStreamHosts	(	const ObjList &	hosts,
		String *	stanzaId = `0`
	)		`[inline, virtual]`

Send a stanza with stream hosts This method is thread safe

Parameters:

hosts	The list of hosts to send
stanzaId	Optional string to be filled with sent stanza id (used to track the response)

Returns:: False if send failed

Reimplemented in JGSession1.

virtual bool sendStreamHostUsed	(	const char *	jid,
		const char *	stanzaId
	)		`[inline, virtual]`

Send a stanza with a stream host used. If the jid is empty, send an item-not-found error response This method is thread safe

Parameters:

jid	The stream host to send
stanzaId	The id of the stanza to confirm

Returns:: False if send failed

Reimplemented in JGSession1.

void setFlags ( int value ) [inline]

Replace session flags

Parameters:

value The new session flags

const String& sid ( ) const [inline]

Get the session id

Returns:: The session id

State state ( ) const [inline]

Get the session state.

Returns:: The session state as enumeration.

void* userData ( ) [inline]

Get the arbitrary user data of this session

Returns:: The arbitrary user data of this session

void userData ( void * userdata ) [inline]

Set the arbitrary user data of this session

Parameters:

userdata The new arbitrary user data's value

Version version ( ) const [inline]

Get the session version

Returns:: The session version

Member Data Documentation

const TokenDict s_actions0[] [static]

Action names for version Version0

const TokenDict s_actions1[] [static]

Action names for version Version1

const TokenDict s_flagName[] [static]

Session flag names

const TokenDict s_reasons[] [static]

Termination reasons and errors

const TokenDict s_rtpInfo[] [static]

RTP session info (XEP 0167)

const TokenDict s_states[] [static]

Session state names

const TokenDict s_versions[] [static]

Session version names

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

yatejingle.h

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation