Yate
JGSession Class Referenceabstract

A basic Jingle session. More...

#include <yatejingle.h>

Inheritance diagram for JGSession:
RefObject Mutex GenObject Lockable JGSession0 JGSession1

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 , FlagRingNsRtp = 0x0002 , FlagNoOkInitiate = 0x0004 }
 

Public Member Functions

virtual ~JGSession ()
 
Version version () const
 
JGEngineengine () const
 
bool outgoing () const
 
const Stringsid () const
 
const JabberIDlocal () const
 
const JabberIDremote () const
 
State state () const
 
int flag (int mask) const
 
void setFlags (int value)
 
void * userData ()
 
void userData (void *userdata)
 
const Stringline () 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 XmlElementcreateRtpInfoXml (RtpInfo info)
 
virtual XmlElementcreateReason (int reason, const char *text=0, XmlElement *child=0)
 
virtual XmlElementcreateTransferReason (int reason)
 
virtual XmlElementcreateRtpSessionReason (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, XmlElement *extra=0)
 
bool sendDtmf (const char *dtmf, unsigned int msDuration=0, String *stanzaId=0)
 
bool hasFeature (XMPPNamespace::Type feature)
 
- Public Member Functions inherited from RefObject
 RefObject ()
 
virtual ~RefObject ()
 
virtual void * getObject (const String &name) const
 
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 StringtoString () const
 
virtual const StringtraceId () const
 
NamedCountergetObjCounter () const
 
NamedCountersetObjCounter (NamedCounter *counter)
 
- Public Member Functions inherited from Mutex
 Mutex (bool recursive=false, const char *name=0)
 
 Mutex (const Mutex &original)
 
 ~Mutex ()
 
Mutexoperator= (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 XmlElementbuildTransfer (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 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 NamedCountergetObjCounter (const String &name, bool create=true)
 
static ObjListgetObjCounters ()
 
- 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 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 JGEventgetEvent (u_int64_t time)
 
virtual void destroyed ()
 
bool sendStanza (XmlElement *stanza, String *stanzaId=0, bool confirmation=true, bool ping=false, unsigned int toutMs=0)
 
bool sendPing (u_int64_t msecNow)
 
virtual JGEventdecodeJingle (XmlElement *&xml, XmlElement *child)=0
 
virtual XmlElementcreateJingle (Action action, XmlElement *element1=0, XmlElement *element2=0, XmlElement *element3=0)=0
 
virtual XmlElementcreateDtmf (const char *dtmf, unsigned int msDuration=0)=0
 
virtual JGEventprocessJingleSetEvent (JGEvent *&ev)
 
virtual JGEventprocessJabberIqResponse (bool result, XmlElement *&xml)
 
virtual JGEventprocessFileTransfer (bool set, XmlElement *&xml, XmlElement *child)
 
void eventTerminated (JGEvent *event)
 
void changeState (State newState)
 
- Protected Member Functions inherited from RefObject
virtual void zeroRefs ()
 
bool resurrect ()
 

Protected Attributes

Version m_version
 
State m_state
 
int m_flags
 
u_int64_t m_timeToPing
 
JGEnginem_engine
 
bool m_outgoing
 
String m_sid
 
JabberID m_local
 
JabberID m_remote
 
XmlFragment m_queue
 
JGEventm_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

◆ Action

enum Action

Jingle action enumeration

◆ Reason

enum Reason

Jingle defined reasons and errors

◆ RtpInfo

enum RtpInfo

RTP session info (XEP 0167)

◆ SessionFlag

Session flags

◆ State

enum State

Session state enumeration

◆ Version

enum Version

Jingle session version

Constructor & Destructor Documentation

◆ ~JGSession()

virtual ~JGSession ( )
virtual

Destructor

◆ JGSession() [1/2]

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

Constructor. Create an outgoing session

Parameters
verThe session version
engineThe engine owning this session
callerThe caller's full JID
calledThe called party's full JID

References engine().

Referenced by changeState().

◆ JGSession() [2/2]

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

Constructor. Create an incoming session.

Parameters
verThe session version
engineThe engine owning this session
callerThe caller's full JID
calledThe called party's full JID
xmlA valid Jabber Jingle xml with action session initiate
idSession id

References engine().

Member Function Documentation

◆ accept()

virtual bool accept ( const ObjList & contents,
String * stanzaId = 0 )
inlinevirtual

Accept a Pending incoming session. This method is thread safe

Parameters
contentsThe list of accepted contents
stanzaIdOptional string to be filled with sent stanza id (used to track the response)
Returns
False if send failed

Reimplemented in JGSession0, and JGSession1.

◆ acceptIq()

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
typeIq type as enumeration
fromThe sender
toThe recipient
idThe session id of this is a request (set/get) or the stanza id
xmlThe received element
Returns
True if accepted (the element was enqueued), false if not

◆ buildSocksDstAddr()

void buildSocksDstAddr ( String & buf)

Build SOCKS SHA1 dst.addr used by file transfer

Parameters
bufDestination string

◆ buildTransfer()

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

Build a transfer element

Parameters
transferToThe JID to transfer to
transferFromThe transferror's JID
sidOptional session id used for attended transfer (empty for unattended transfer)
Returns
Valid XmlElement pointer

References String::empty(), and sid().

◆ changeState()

void changeState ( State newState)
protected

Changed session state

Parameters
newStateSession new state

References JGSession().

◆ confirmError()

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

Confirm (send error) a received element

Parameters
xmlThe element to confirm (will be consumed and zeroed)
errorThe error condition
textOptional text to add to the error element
typeError type
Returns
False if send failed or element is 0

◆ confirmResult()

bool confirmResult ( XmlElement * xml)

Confirm (send result) a received element

Parameters
xmlThe element to confirm
Returns
False if send failed or element is 0

◆ createDtmf()

virtual XmlElement * createDtmf ( const char * dtmf,
unsigned int msDuration = 0 )
protectedpure virtual

Create a dtmf XML element

Parameters
dtmfThe dtmf string
msDurationThe tone duration in miliseconds. Ignored if 0
Returns
Valid XmlElement pointer or 0

Implemented in JGSession0, and JGSession1.

◆ createJingle()

virtual XmlElement * createJingle ( Action action,
XmlElement * element1 = 0,
XmlElement * element2 = 0,
XmlElement * element3 = 0 )
protectedpure virtual

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

Parameters
actionThe action of the Jingle stanza
element1Optional child element
element2Optional child element
element3Optional child element
Returns
Valid XmlElement pointer

Implemented in JGSession0, and JGSession1.

◆ createReason()

virtual XmlElement * createReason ( int reason,
const char * text = 0,
XmlElement * child = 0 )
inlinevirtual

Create a termination reason element

Parameters
reasonThe reason code
textOptional reason text child
childOptional additional reason child
Returns
Valid XmlElement pointer or 0 if not supported

Reimplemented in JGSession1.

◆ createRtpInfoXml()

virtual XmlElement * createRtpInfoXml ( RtpInfo info)
inlinevirtual

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

Parameters
infoThe informational tag as enumeration
Returns
Valid XmlElement pointer or 0 if not supported

Reimplemented in JGSession1.

◆ createRtpSessionReason()

virtual XmlElement * createRtpSessionReason ( int reason)
inlinevirtual

Create a RTP session reason element

Parameters
reasonThe reason code
Returns
Valid XmlElement pointer or 0 if not supported

Reimplemented in JGSession1.

◆ createTransferReason()

virtual XmlElement * createTransferReason ( int reason)
inlinevirtual

Create a transfer reason element

Parameters
reasonThe reason code
Returns
Valid XmlElement pointer or 0 if not supported

Reimplemented in JGSession1.

◆ decodeJingle()

virtual JGEvent * decodeJingle ( XmlElement *& xml,
XmlElement * child )
protectedpure virtual

Decode a jingle element

Parameters
xmlThe element to decode
childThe element's first child
Returns
JGEvent pointer or 0

Implemented in JGSession0, and JGSession1.

◆ destroyed()

virtual void destroyed ( )
protectedvirtual

Release this session and its memory

Reimplemented from RefObject.

◆ engine()

JGEngine * engine ( ) const
inline

Retrieve the engine owning this session

Returns
The engine owning this session

Referenced by JGSession(), JGSession(), JGSession0::JGSession0(), JGSession0::JGSession0(), JGSession1::JGSession1(), and JGSession1::JGSession1().

◆ eventTerminated()

void eventTerminated ( JGEvent * event)
protected

Terminate notification from an event. Reset the last generated event

Parameters
eventTerminated (processed) event

◆ flag()

int flag ( int mask) const
inline

Retrieve session flags

Parameters
maskMask to retrieve
Returns
Session flags

◆ getAction()

Action getAction ( XmlElement * xml)

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

Parameters
xmlElement to check
Returns
The found action, ActCount if not found or unknown

◆ getEvent()

virtual JGEvent * getEvent ( u_int64_t time)
protectedvirtual

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

Parameters
timeCurrent time in miliseconds
Returns
JGEvent pointer or 0

◆ hangup()

virtual bool hangup ( XmlElement * reason = 0)
virtual

Close a Pending or Active session This method is thread safe

Parameters
reasonOptional termination reason
Returns
False if send failed

◆ hasFeature()

bool hasFeature ( XMPPNamespace::Type feature)

Check if the remote party supports a given feature

Parameters
featureThe requested feature
Returns
True if the remote party supports the given feature

◆ initiate()

virtual bool initiate ( const ObjList & contents,
XmlElement * extra,
const char * subject = 0 )
protectedpure virtual

Build and send the initial message on an outgoing session

Parameters
contentsThe session contents to be sent with session initiate element
extraOptional extra child to be added to the session initiate element
subjectOptional session subject
Returns
True on success

Implemented in JGSession0, and JGSession1.

◆ line() [1/2]

const String & line ( ) const
inline

Retrieve the client account used by this session

Returns
The client account used by this session

◆ line() [2/2]

void line ( const String & acc)
inline

Set the client account used by this session

Parameters
accThe client account used by this session

◆ local()

const JabberID & local ( ) const
inline

Get the local peer's JID

Returns
The local peer's JID

◆ lookupAction() [1/2]

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

Get the action associated with a given string

Parameters
strThe action name
verSession version to use
Returns
The name of an action

◆ lookupAction() [2/2]

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

Get the name of an action

Parameters
actThe action to find
verSession version to use
Returns
The name of an action

Referenced by JGEvent::actionName().

◆ lookupReason() [1/2]

static int lookupReason ( const char * value,
int def = ReasonOk )
inlinestatic

Get the termination code associated with a text

Parameters
valueThe termination text
defDefault value to return if not found
Returns
Termination code

References s_reasons.

◆ lookupReason() [2/2]

static const char * lookupReason ( int value,
const char * def = 0 )
inlinestatic

Get the termination code associated with a text

Parameters
valueThe termination code
defDefault value to return if not found
Returns
Termination text

References s_reasons.

◆ lookupState()

static const char * lookupState ( int state)
inlinestatic

Get the name of a session state

Parameters
stateThe state to find
Returns
The name of a session state

References s_states, and state().

◆ lookupVersion() [1/2]

static Version lookupVersion ( const char * value,
Version def = VersionUnknown )
inlinestatic

Get the session version associated with a text

Parameters
valueThe version text
defDefault value to return if not found
Returns
Session Version value

References s_versions.

◆ lookupVersion() [2/2]

static const char * lookupVersion ( int value,
const char * def = "unknown" )
inlinestatic

Get the session version name

Parameters
valueThe version value
defDefault value to return if not found
Returns
Session version name or the default value if not found

References s_versions.

◆ outgoing()

bool outgoing ( ) const
inline

Get the session direction

Returns
True if it is an outgoing session

◆ processFileTransfer()

virtual JGEvent * processFileTransfer ( bool set,
XmlElement *& xml,
XmlElement * child )
protectedvirtual

Decode a file transfer element

Parameters
setTrue if the xml is an iq 'set', false if type is 'get'
xmlThe element to decode
childThe element's first child
Returns
JGEvent pointer or 0

Reimplemented in JGSession1.

◆ processJabberIqResponse()

virtual JGEvent * processJabberIqResponse ( bool result,
XmlElement *& xml )
protectedvirtual

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

Parameters
resultTrue if the element is a result, false if it's an error response
xmlXml element to process
Returns
JGEvent pointer or 0

◆ processJingleSetEvent()

virtual JGEvent * processJingleSetEvent ( JGEvent *& ev)
protectedvirtual

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

Parameters
evThe event to process (will be consumed and zeroed)
Returns
JGEvent pointer or 0

◆ remote()

const JabberID & remote ( ) const
inline

Get the remote peer's JID

Returns
The remote peer's JID

◆ sendContent() [1/2]

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

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

Parameters
actionMust be a transport- or content- action
contentThe content to send
stanzaIdOptional string to be filled with sent stanza id (used to track the response)
Returns
False if send failed

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

◆ sendContent() [2/2]

virtual bool sendContent ( Action action,
const ObjList & contents,
String * stanzaId = 0 )
inlinevirtual

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

Parameters
actionMust be a transport- or content- action
contentsNon empty list with content(s) to send
stanzaIdOptional string to be filled with sent stanza id (used to track the response)
Returns
False if send failed

Reimplemented in JGSession0, and JGSession1.

Referenced by sendContent().

◆ sendDtmf()

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
dtmfThe dtmf string
msDurationThe tone duration in miliseconds. Ignored if 0
stanzaIdOptional string to be filled with sent stanza id (used to track the response)
Returns
False if send failed

◆ sendInfo()

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

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

Parameters
xmlThe XmlElement carried by the session info element
stanzaIdOptional string to be filled with sent stanza id (used to track the response)
extraOptional extra child for jingle element
Returns
False on failure

◆ sendPing()

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
msecNowThe current time
Returns
True if a ping was succesfully sent

◆ sendStanza()

bool sendStanza ( XmlElement * stanza,
String * stanzaId = 0,
bool confirmation = true,
bool ping = false,
unsigned int toutMs = 0 )
protected

Send a stanza to the remote peer

Parameters
stanzaThe stanza to send
stanzaIdOptional string to be filled with sent stanza id (used to track the response)
confirmationTrue if the stanza needs confirmation (add 'id' attribute)
pingTrue if the stanza is a ping one
toutMsOptional stanza timeout interval in milliseconds
Returns
True on success

◆ sendStreamHosts()

virtual bool sendStreamHosts ( const ObjList & hosts,
String * stanzaId = 0 )
inlinevirtual

Send a stanza with stream hosts This method is thread safe

Parameters
hostsThe list of hosts to send
stanzaIdOptional string to be filled with sent stanza id (used to track the response)
Returns
False if send failed

Reimplemented in JGSession1.

◆ sendStreamHostUsed()

virtual bool sendStreamHostUsed ( const char * jid,
const char * stanzaId )
inlinevirtual

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
jidThe stream host to send
stanzaIdThe id of the stanza to confirm
Returns
False if send failed

Reimplemented in JGSession1.

◆ setFlags()

void setFlags ( int value)
inline

Replace session flags

Parameters
valueThe new session flags

◆ sid()

const String & sid ( ) const
inline

Get the session id

Returns
The session id

Referenced by buildTransfer().

◆ state()

State state ( ) const
inline

Get the session state.

Returns
The session state as enumeration.

Referenced by lookupState().

◆ userData() [1/2]

void * userData ( )
inline

Get the arbitrary user data of this session

Returns
The arbitrary user data of this session

◆ userData() [2/2]

void userData ( void * userdata)
inline

Set the arbitrary user data of this session

Parameters
userdataThe new arbitrary user data's value

◆ version()

Version version ( ) const
inline

Get the session version

Returns
The session version

Member Data Documentation

◆ s_actions0

const TokenDict s_actions0[]
static

Action names for version Version0

◆ s_actions1

const TokenDict s_actions1[]
static

Action names for version Version1

◆ s_flagName

const TokenDict s_flagName[]
static

Session flag names

◆ s_reasons

const TokenDict s_reasons[]
static

Termination reasons and errors

Referenced by lookupReason(), and lookupReason().

◆ s_rtpInfo

const TokenDict s_rtpInfo[]
static

RTP session info (XEP 0167)

◆ s_states

const TokenDict s_states[]
static

Session state names

Referenced by lookupState().

◆ s_versions

const TokenDict s_versions[]
static

Session version names

Referenced by lookupVersion(), and lookupVersion().


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