# class JGSession | A basic Jingle session. More...
Contains pure virtuals
Full name | `TelEngine::JGSession`
Definition | `#include <libs/yjabber/yatejingle.h>`
Inherits | TelEngine::Mutex [public ], TelEngine::RefObject [public ]
Inherited by | JGSession0, JGSession1
List of all Methods
Annotated List
Files
Globals
Hierarchy
Index

#### 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 Methods

- virtual ~JGSession ()
- inline Version version () const
- inline JGEngine* engine () const
- inline bool outgoing () const
- inline const String& sid () const
- inline const JabberID& local () const
- inline const JabberID& remote () const
- inline State state () const
- inline int flag (int mask) const
- inline void setFlags (int value)
- inline void* userData ()
- inline void userData (void* userdata)
- inline const String& line () const
- inline 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)
- inline 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 Static Methods

- static XmlElement* buildTransfer (const String& transferTo, const String& transferFrom, const String& sid = String::empty())
- static inline Version lookupVersion (const char* value, Version def = VersionUnknown)
- static inline const char* lookupVersion (int value, const char* def = "unknown")
- static inline int lookupReason (const char* value, int def = ReasonOk)
- static inline 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)

#### Public Members

- 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 Methods

- 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)
- virtual JGEvent* getEvent (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 JGEvent* decodeJingle (XmlElement*& xml, XmlElement* child)
- virtual XmlElement* createJingle (Action action, XmlElement* element1 = 0, XmlElement* element2 = 0, XmlElement* element3 = 0)
- virtual XmlElement* createDtmf (const char* dtmf, unsigned int msDuration = 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 Members

- 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

## Detailed Description

This class is a base class for all specific jingle sessions

enum Version { Version0 = 0, Version1 = 1, VersionUnknown } | ### Version

Jingle session version

enum Reason { ReasonUnknown = 0, ReasonOk, ReasonBusy, ReasonDecline, ReasonCancel, ReasonExpired, ReasonConn, ReasonFailApp, ReasonFailTransport, ReasonGone, ReasonParams, ReasonMedia, ReasonTransport, ReasonApp, ReasonSecurity, ReasonTimeout, ReasonGeneral, ReasonAltSess, Transferred, CryptoRequired, InvalidCrypto, } | ### Reason

Jingle defined reasons and errors

enum RtpInfo { RtpActive, RtpHold, RtpMute, RtpRinging, } | ### RtpInfo

RTP session info (XEP 0167)

enum State { Idle = 0, Pending = 1, Active = 2, Ending = 3, Destroy = 4, } | ### State

Session state enumeration

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, } | ### Action

Jingle action enumeration

enum SessionFlag { FlagNoPing = 0x0001, FlagRingNsRtp = 0x0002, FlagNoOkInitiate = 0x0004, } | ### SessionFlag

Session flags

~JGSession () | ### ~JGSession

[virtual]

Destructor

inline Version version () | ### version

[const]

Get the session version

Returns: The session version

inline JGEngine* engine () | ### engine

[const]

Retrieve the engine owning this session

Returns: The engine owning this session

inline bool outgoing () | ### outgoing

[const]

Get the session direction

Returns: True if it is an outgoing session

inline const String& sid () | ### sid

[const]

Get the session id

Returns: The session id

inline const JabberID& local () | ### local

[const]

Get the local peer's JID

Returns: The local peer's JID

inline const JabberID& remote () | ### remote

[const]

Get the remote peer's JID

Returns: The remote peer's JID

inline State state () | ### state

[const]

Get the session state.

Returns: The session state as enumeration.

inline int flag (int mask) | ### flag

[const]

Retrieve session flags

Parameters:

mask | Mask to retrieve

Returns: Session flags

inline void setFlags (int value) | ### setFlags

Replace session flags

Parameters:

value | The new session flags

inline void* userData () | ### userData

Get the arbitrary user data of this session

Returns: The arbitrary user data of this session

inline void userData (void* userdata) | ### userData

Set the arbitrary user data of this session

Parameters:

userdata | The new arbitrary user data's value

inline const String& line () | ### line

[const]

Retrieve the client account used by this session

Returns: The client account used by this session

inline void line (const String& acc) | ### line

Set the client account used by this session

Parameters:

acc | The client account used by this session

Action getAction (XmlElement* xml) | ### getAction

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

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

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

bool confirmResult (XmlElement* xml) | ### confirmResult

Confirm (send result) a received element

Parameters:

xml | The element to confirm

Returns: False if send failed or element is 0

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

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 accept (const ObjList& contents, String* stanzaId = 0) | ### accept

[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

bool hangup (XmlElement* reason = 0) | ### hangup

[virtual]

Close a Pending or Active session This method is thread safe

Parameters:

reason | Optional termination reason

Returns: False if send failed

XmlElement* createRtpInfoXml (RtpInfo info) | ### createRtpInfoXml

[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

XmlElement* createReason (int reason, const char* text = 0, XmlElement* child = 0) | ### createReason

[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

XmlElement* createTransferReason (int reason) | ### createTransferReason

[virtual]

Create a transfer reason element

Parameters:

reason | The reason code

Returns: Valid XmlElement pointer or 0 if not supported

XmlElement* createRtpSessionReason (int reason) | ### createRtpSessionReason

[virtual]

Create a RTP session reason element

Parameters:

reason | The reason code

Returns: Valid XmlElement pointer or 0 if not supported

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

[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

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

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

bool sendStreamHosts (const ObjList& hosts, String* stanzaId = 0) | ### sendStreamHosts

[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

bool sendStreamHostUsed (const char* jid, const char* stanzaId) | ### sendStreamHostUsed

[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

void buildSocksDstAddr (String& buf) | ### buildSocksDstAddr

Build SOCKS SHA1 dst.addr used by file transfer

Parameters:

buf | Destination string

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

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)
extra | Optional extra child for jingle element

Returns: False on failure

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

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 hasFeature (XMPPNamespace::Type feature) | ### hasFeature

Check if the remote party supports a given feature

Parameters:

feature | The requested feature

Returns: True if the remote party supports the given feature

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

[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

inline Version lookupVersion (const char* value, Version def = VersionUnknown) | ### lookupVersion

[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

inline const char* lookupVersion (int value, const char* def = "unknown") | ### lookupVersion

[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

inline int lookupReason (const char* value, int def = ReasonOk) | ### lookupReason

[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

inline const char* lookupReason (int value, const char* def = 0) | ### lookupReason

[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

const char* lookupState (int state) | ### lookupState

[static]

Get the name of a session state

Parameters:

state | The state to find

Returns: The name of a session state

const char* lookupAction (int act, Version ver) | ### lookupAction

[static]

Get the name of an action

Parameters:

act | The action to find
ver | Session version to use

Returns: The name of an action

Action lookupAction (const char* str, Version ver) | ### lookupAction

[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 TokenDict s_versions[] | ### s_versions[]

static const TokenDict s_reasons[] | ### s_reasons[]

static const TokenDict s_rtpInfo[] | ### s_rtpInfo[]

static const TokenDict s_states[] | ### s_states[]

static const TokenDict s_actions0[] | ### s_actions0[]

static const TokenDict s_actions1[] | ### s_actions1[]

static const TokenDict s_flagName[] | ### s_flagName[]

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

[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) | ### JGSession

[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

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

[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

JGEvent* getEvent (u_int64_t time) | ### getEvent

[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

void destroyed () | ### destroyed

[protected virtual]

Release this session and its memory

Reimplemented from RefObject.

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

[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
toutMs | Optional stanza timeout interval in milliseconds

Returns: True on success

bool sendPing (u_int64_t msecNow) | ### sendPing

[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

JGEvent* decodeJingle (XmlElement*& xml, XmlElement* child) | ### decodeJingle

[protected pure virtual]

Decode a jingle element

Parameters:

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

Returns: JGEvent pointer or 0

XmlElement* createJingle (Action action, XmlElement* element1 = 0, XmlElement* element2 = 0, XmlElement* element3 = 0) | ### createJingle

[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

XmlElement* createDtmf (const char* dtmf, unsigned int msDuration = 0) | ### createDtmf

[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

JGEvent* processJingleSetEvent (JGEvent*& ev) | ### processJingleSetEvent

[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

JGEvent* processJabberIqResponse (bool result, XmlElement*& xml) | ### processJabberIqResponse

[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

JGEvent* processFileTransfer (bool set, XmlElement*& xml, XmlElement* child) | ### processFileTransfer

[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

void eventTerminated (JGEvent* event) | ### eventTerminated

[protected]

Terminate notification from an event. Reset the last generated event

Parameters:

event | Terminated (processed) event

void changeState (State newState) | ### changeState

[protected]

Changed session state

Parameters:

newState | Session new state

Version m_version | ### m_version

[protected]

State m_state | ### m_state

[protected]

int m_flags | ### m_flags

[protected]

u_int64_t m_timeToPing | ### m_timeToPing

[protected]

JGEngine* m_engine | ### m_engine

[protected]

bool m_outgoing | ### m_outgoing

[protected]

String m_sid | ### m_sid

[protected]

JabberID m_local | ### m_local

[protected]

JabberID m_remote | ### m_remote

[protected]

XmlFragment m_queue | ### m_queue

[protected]

JGEvent* m_lastEvent | ### m_lastEvent

[protected]

bool m_recvTerminate | ### m_recvTerminate

[protected]

void* m_private | ### m_private

[protected]

String m_localSid | ### m_localSid

[protected]

u_int32_t m_stanzaId | ### m_stanzaId

[protected]

ObjList m_sentStanza | ### m_sentStanza

[protected]

String m_line | ### m_line

[protected]

Generated by: paulc on bussard on Mon Feb 10 13:15:47 2014, using kdoc 2.0a54.