JGSession Class Reference

A basic Jingle session. More...

#include <yatejingle.h>

Inheritance diagram for JGSession:

Public Types
enum	Version { Version0 = 0, Version1 = 1, VersionUnknown }
enum	Reason { ReasonBusy, ReasonDecline, ReasonConn, ReasonMedia, ReasonTransport, ReasonNoError, ReasonOk, ReasonNoApp, ReasonAltSess, ReasonUnknown, ReasonTransfer, ReasonNone }
enum	State { Idle = 0, Pending = 1, Active = 2, Ending = 3, Destroy = 4 }
enum	Action { ActAccept, ActInitiate, ActTerminate, ActInfo, ActTransportInfo, ActTransportAccept, ActTransportReject, ActTransportReplace, ActContentAccept, ActContentAdd, ActContentModify, ActContentReject, ActContentRemove, ActContentInfo, ActTransfer, ActRinging, ActTrying, ActReceived, ActHold, ActActive, ActMute, ActDtmf, ActStreamHost, ActCount }
Public Member Functions
virtual	~JGSession ()
Version	version () const
bool	outgoing () const
const String &	sid () const
const JabberID &	local () const
const JabberID &	remote () const
State	state () const
const JBStream *	stream () const
void *	userData ()
void	userData (void *userdata)
virtual XMLElement *	checkJingle (XMLElement *xml)
Action	getAction (XMLElement *xml)
bool	acceptEvent (JBEvent *event, const String &sid=String::empty())
bool	confirm (XMLElement xml, XMPPError::Type error=XMPPError::NoError, const char text=0, XMPPError::ErrorType type=XMPPError::TypeModify)
virtual bool	accept (const ObjList &contents, String *stanzaId=0)
virtual bool	hangup (int reason, const char *msg=0)
virtual XMLElement *	createHoldXml ()
virtual XMLElement *	createActiveXml ()
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	sendMessage (const char *msg)
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 TokenDict	s_versions []
static TokenDict	s_reasons []
static TokenDict	s_states []
static TokenDict	s_actions0 []
static TokenDict	s_actions1 []
Protected Member Functions
	JGSession (Version ver, JGEngine engine, JBStream stream, const String &callerJID, const String &calledJID, const char *msg=0)
	JGSession (Version ver, JGEngine engine, JBEvent event, 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 ()
void	enqueue (JBEvent *event)
bool	sendStanza (XMLElement stanza, String stanzaId=0, bool confirmation=true, bool ping=false)
bool	sendPing (u_int64_t msecNow)
virtual JGEvent *	decodeJingle (JBEvent *jbev)=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 void	processJingleSetLastEvent (JBEvent &ev)
virtual bool	processJabberIqResponse (JBEvent &ev)
virtual void	processJabberIqEvent (JBEvent &ev)
void	eventTerminated (JGEvent *event)
void	changeState (State newState)
Protected Attributes
Version	m_version
State	m_state
u_int64_t	m_timeToPing
JGEngine *	m_engine
JBStream *	m_stream
bool	m_outgoing
String	m_sid
JabberID	m_localJID
JabberID	m_remoteJID
ObjList	m_events
JGEvent *	m_lastEvent
bool	m_recvTerminate
void *	m_private
String	m_localSid
u_int32_t	m_stanzaId
ObjList	m_sentStanza
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 termination reasons

enum State

Session state enumeration

enum Version

Jingle session version

Constructor & Destructor Documentation

virtual ~JGSession ( ) [virtual]

Destructor

JGSession	(	Version	ver,
		JGEngine *	engine,
		JBStream *	stream,
		const String &	callerJID,
		const String &	calledJID,
		const char *	msg = `0`
	)			`[protected]`

Constructor. Create an outgoing session

Parameters:

	ver	The session version
	engine	The engine that owns this session
	stream	The stream this session is bound to
	callerJID	The caller's full JID
	calledJID	The called party's full JID
	msg	Optional message to be sent before session initiate

JGSession	(	Version	ver,
		JGEngine *	engine,
		JBEvent *	event,
		const String &	id
	)			`[protected]`

Constructor. Create an incoming session.

Parameters:

	ver	The session version
	engine	The engine that owns this session
	event	A valid Jabber Jingle event 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 JGSession0, and JGSession1.

bool acceptEvent	(	JBEvent *	event,
		const String &	sid = `String::empty()`
	)

Ask this session to accept an event

Parameters:

	event	The event to accept
	sid	The session id if this is a request

Returns:: True if accepted (the event 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

virtual XMLElement* checkJingle ( XMLElement * xml ) [inline, virtual]

Check if a given XML element is valid jingle one

Parameters:

xml

Element to check

Returns:: The given element if it's a valid jingle element, 0 otherwise

Reimplemented in JGSession0, and JGSession1.

bool confirm	(	XMLElement *	xml,
		XMPPError::Type	error = `XMPPError::NoError`,
		const char *	text = `0`,
		XMPPError::ErrorType	type = `XMPPError::TypeModify`
	)

Confirm a received element. If the error is NoError a result stanza will be sent. Otherwise, an error stanza will be created and sent and the received element is consumed (attached to the sent error stanza)

Parameters:

	xml	The element to confirm
	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

virtual XMLElement* createActiveXml ( ) [inline, virtual]

Create an 'active' child to be added to a session-info element

Returns:: Valid XMLElement pointer or 0

Reimplemented in JGSession1.

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 JGSession0, and JGSession1.

virtual XMLElement* createHoldXml ( ) [inline, virtual]

Create a 'hold' child to be added to a session-info element

Returns:: Valid XMLElement pointer or 0

Reimplemented in JGSession1.

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 JGSession0, and JGSession1.

virtual JGEvent* decodeJingle ( JBEvent * jbev ) [protected, pure virtual]

Decode a valid jingle set event. Set the event's data on success

Parameters:

jbev

The event to decode

Returns:: JGEvent pointer or 0

Implemented in JGSession0, and JGSession1.

virtual void destroyed ( ) [protected, virtual]

Release this session and its memory

Reimplemented from RefObject.

void enqueue ( JBEvent * event ) [protected]

Enqueue a Jabber engine event. This method is thread safe

Parameters:

event

The event event to process

void eventTerminated ( JGEvent * event ) [protected]

Terminate notification from an event. Reset the last generated event

Parameters:

event

Terminated (processed) event

Action getAction ( XMLElement * xml ) [inline]

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

References XMLElement::getAttribute().

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	(	int	reason,
		const char *	msg = `0`
	)			`[virtual]`

Close a Pending or Active session This method is thread safe

Parameters:

	reason	Termination reason
	msg	Optional termination message

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 JGSession0, and JGSession1.

const JabberID& local ( ) const [inline]

Get the local peer's JID

Returns:: The local peer's JID

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

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

bool outgoing ( ) const [inline]

Get the session direction

Returns:: True if it is an outgoing session

virtual void processJabberIqEvent ( JBEvent & ev ) [protected, virtual]

Method called in getEvent() to process a generic jabber iq event

Parameters:

ev

The event to process

Reimplemented in JGSession1.

virtual bool processJabberIqResponse ( JBEvent & ev ) [protected, virtual]

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

Parameters:

ev

The event to process

Returns:: False to stop further processing

virtual void processJingleSetLastEvent ( JBEvent & ev ) [protected, virtual]

Method called in getEvent() to process a last event set from a jingle set jabber event

Parameters:

ev

The event to process

const JabberID& remote ( ) const [inline]

Get the remote peer's JID

Returns:: The remote peer's JID

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

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 JGSession0, and JGSession1.

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 sendMessage ( const char * msg ) [inline]

Send a message to the remote peer. This method is thread safe

Parameters:

msg

The message to send

Returns:: False on socket error

References JBMessage::createMessage().

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.

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.

const JBStream* stream ( ) const [inline]

Get the stream this session is bound to

Returns:: The stream this session is bound to

void userData ( void * userdata ) [inline]

Set the arbitrary user data of this session

Parameters:

userdata

The new arbitrary user data's value

void* userData ( ) [inline]

Get the arbitrary user data of this session

Returns:: The arbitrary user data of this session

Version version ( ) const [inline]

Get the session version

Returns:: The session version

Member Data Documentation

TokenDict s_actions0[] [static]

Action names for version Version0

TokenDict s_actions1[] [static]

Action names for version Version1

TokenDict s_reasons[] [static]

Termination reasons

TokenDict s_states[] [static]

Session state names

TokenDict s_versions[] [static]

Session version names

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

yatejingle.h

JGSession Class Reference

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