JBStream Class Reference

A Jabber stream. More...

#include <yatejabber.h>

Inheritance diagram for JBStream:

Public Types
enum	State { Idle = 0, Connecting = 1, Started = 2, Securing = 3, Register = 4, Auth = 5, Running = 6, Destroy = 7 }
enum	Error { ErrorNone = 0, ErrorContext, ErrorPending, ErrorNoSocket }
enum	Flags { AutoRestart = 0x0001, AllowPlainAuth = 0x0002, NoVersion1 = 0x0004, UseTls = 0x0008, UseSasl = 0x0010, AllowUnsafeSetup = 0x0020, StreamSecured = 0x0100, StreamAuthenticated = 0x0200, NoRemoteVersion1 = 0x0400 }
Public Member Functions
virtual	~JBStream ()
int	type () const
State	state () const
bool	outgoing () const
const String &	name () const
const String &	id () const
JBEngine *	engine () const
const JabberID &	local () const
const JabberID &	remote () const
const SocketAddr &	addr () const
bool	flag (int mask) const
Mutex *	streamMutex ()
void	connect ()
bool	receive ()
virtual Error	sendStanza (XMLElement stanza, const char senderId=0)
JBEvent *	getEvent (u_int64_t time)
void	terminate (bool destroy, XMLElement recvStanza, XMPPError::Type error, const char reason, bool send, bool final=false, bool sendError=true)
void	removePending (const String &id, bool notify=false)
virtual const String &	toString () const
virtual void *	getObject (const String &name) const
Static Public Member Functions
static const char *	lookupState (int state)
Static Public Attributes
static TokenDict	s_flagName []
Protected Types
enum	WaitState { WaitIdle, WaitStart, WaitFeatures, WaitBindRsp, WaitSessionRsp, WaitTlsRsp, WaitChallenge, WaitResponse, WaitAborted }
Protected Member Functions
	JBStream (JBEngine *engine, int type, XMPPServerInfo &info, const JabberID &localJid, const JabberID &remoteJid)
	JBStream ()
virtual void	destroyed ()
virtual bool	checkDestination (XMLElement *xml, bool &respond)
virtual XMLElement *	getStreamStart ()
virtual XMLElement *	getAuthStart ()
virtual void	processRunning (XMLElement *xml)
virtual void	processRegister (XMLElement *xml)
virtual void	processAuth (XMLElement *xml)
virtual void	processSecuring (XMLElement *xml)
virtual void	processStarted (XMLElement *xml)
virtual void	streamRunning ()
JBEvent *	getIqEvent (XMLElement *xml, int iqType, XMPPError::Type &error)
bool	sendStreamStart ()
bool	sendStreamXML (XMLElement *e, State newState)
void	invalidStreamXML (XMLElement xml, XMPPError::Type error, const char reason)
void	errorStreamXML (XMLElement *xml)
void	dropXML (XMLElement *xml, bool unexpected=true)
void	changeState (State newState)
bool	getStreamFeatures (XMLElement *features)
bool	startTls ()
bool	startRegister ()
bool	startAuth ()
bool	sendAuthResponse (XMLElement *challenge=0)
void	buildSaslResponse (String &response, String realm=0, String nonce=0)
void	setClientAuthMechanism ()
void	buildDigestMD5Sasl (String &dest, bool authenticate=true)
void	setRecvCount (int value)
bool	startIdleTimer (u_int64_t time=Time::msecNow())
JBEvent *	lastEvent ()
Protected Attributes
String	m_name
String	m_password
JIDFeatureList	m_localFeatures
JIDFeatureList	m_remoteFeatures
int	m_flags
unsigned int	m_challengeCount
WaitState	m_waitState
JIDFeatureSasl::Mechanism	m_authMech
ObjList	m_events
bool	m_register
Friends
class	JBEngine
class	JBEvent

Detailed Description

A Jabber stream.

Base class for all Jabber streams. Basic stream data processing: send/receive XML elements, keep stream state, generate events

Member Enumeration Documentation

enum Error

Values returned by send() methods.

enum Flags

Stream behaviour options

enum State

Stream state enumeration.

enum WaitState [protected]

Internal wait states enumeration. Defines what kind of XML is expected

Constructor & Destructor Documentation

virtual ~JBStream ( ) [virtual]

Destructor. Gracefully close the stream and the socket

JBStream	(	JBEngine *	engine,
		int	type,
		XMPPServerInfo &	info,
		const JabberID &	localJid,
		const JabberID &	remoteJid
	)			`[protected]`

Constructor. Build an outgoing stream

Parameters:

	engine	The engine that owns this stream
	type	Stream type
	info	Structure containing data used to connect to remote server
	localJid	Local party's JID
	remoteJid	Remote party's JID

JBStream ( ) [inline, protected]

Default constructor

Member Function Documentation

const SocketAddr& addr ( ) const [inline]

Get the remote peer's address

Returns:: The remote peer's address

void buildDigestMD5Sasl	(	String &	dest,
		bool	authenticate = `true`
	)			`[protected]`

Build a Digest MD5 SASL (RFC 2831) to be sent with authentication responses

Parameters:

	dest	Destination string
	authenticate	True if building a Digest MD5 challenge response, false if building a Digest MD5 to check a 'success' response

void buildSaslResponse	(	String &	response,
		String *	realm = `0`,
		String *	nonce = `0`
	)			`[protected]`

Build SASL authentication response (Plain or Digest MD5 SASL). A valid mechanism must be previously set

Parameters:

	response	Destination string
	realm	Received realm or 0 to use local jid. If 0, nonce param is ignored
	nonce	Server nonce if available

void changeState ( State newState ) [protected]

Change stream's state. Raise a Running event when apropriate

Parameters:

newState

the new stream state

virtual bool checkDestination	(	XMLElement *	xml,
		bool &	respond
	)			`[protected, virtual]`

Check the 'to' attribute of a received element

Parameters:

	xml	The received element
	respond	Action to be taken when if not accepted. True to respond with an error, false to just drop it

Returns:: False to reject it. If the stream is not in Running state, it will be terminated

Reimplemented in JBClientStream.

void connect ( )

Connect the stream. Send stream start tag on success This method is thread safe

virtual void destroyed ( ) [protected, virtual]

Close the stream. Release memory

Reimplemented from RefObject.

void dropXML	(	XMLElement *	xml,
		bool	unexpected = `true`
	)			`[protected]`

Drop an unexpected or unhandled element

Parameters:

	xml	Received element
	unexpected	True if unexpected

JBEngine* engine ( ) const [inline]

Get the stream's owner

Returns:: Pointer to the engine owning this stream

void errorStreamXML ( XMLElement * xml ) [protected]

Terminate stream on receiving stanza errors while not running

Parameters:

xml

Received element

bool flag ( int mask ) const [inline]

Check if a given option (or option mask) is set

Parameters:

mask

The flag(s) to check

Returns:: True if set

virtual XMLElement* getAuthStart ( ) [protected, virtual]

Get the authentication element to be sent when authentication starts

Returns:: XMLElement pointer or 0 on failure

Reimplemented in JBComponentStream.

JBEvent* getEvent ( u_int64_t time )

Stream state and data processor. Increase restart counter. Restart stream if idle and auto restart. Extract an element from parser and construct an event. This method is thread safe

Parameters:

time

Current time

Returns:: JBEvent pointer or 0

JBEvent* getIqEvent	(	XMLElement *	xml,
		int	iqType,
		XMPPError::Type &	error
	)			`[protected]`

Create an iq event from a received iq stanza

Parameters:

	xml	Received element
	iqType	The iq type
	error	Error type if 0 is returned

Returns:: JBEvent pointer or 0

virtual void* getObject ( const String & name ) const [virtual]

Get an object from this stream

Parameters:

name

The name of the object to get

Reimplemented from GenObject.

Reimplemented in JBComponentStream, and JBClientStream.

bool getStreamFeatures ( XMLElement * features ) [protected]

Clear the remote feature list. Parse the received element to fill it up. Terminate the stream on error (such as invalid namespace). If false is returned, don't re-use the received element

Parameters:

features

Features element to parse

Returns:: False if the stream is terminated

virtual XMLElement* getStreamStart ( ) [protected, virtual]

Get the starting stream element to be sent after stream connected

Returns:: XMLElement pointer

Reimplemented in JBComponentStream.

const String& id ( ) const [inline]

Get the stream id

Returns:: The stream id

void invalidStreamXML	(	XMLElement *	xml,
		XMPPError::Type	error,
		const char *	reason
	)			`[protected]`

Terminate stream on receiving invalid elements

Parameters:

	xml	Received element
	error	Termination reason
	reason	Optional text to be added to the error stanza

JBEvent* lastEvent ( ) [inline, protected]

Get last event from queue

Returns:: JBEvent pointer or 0

References ObjList::get().

const JabberID& local ( ) const [inline]

Get the JID of the local side of this stream

Returns:: The JID of the local side of this stream

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

Get the name of a stream state

Parameters:

state

The requested state number

Returns:: The name of the requested state

const String& name ( ) const [inline]

Get the stream's name

Returns:: The stream's name

bool outgoing ( ) const [inline]

Get the stream direction

Returns:: True if the stream is an outgoing one

virtual void processAuth ( XMLElement * xml ) [protected, virtual]

Process a received element in Auth state. Descendants MUST consume the data

Parameters:

xml

Valid XMLElement pointer

Reimplemented in JBComponentStream.

virtual void processRegister ( XMLElement * xml ) [protected, virtual]

Process a received element in Register state. Descendants MUST consume the data

Parameters:

xml

Valid XMLElement pointer

virtual void processRunning ( XMLElement * xml ) [protected, virtual]

Process a received stanza in Running state

Parameters:

xml

Valid XMLElement pointer

Reimplemented in JBClientStream.

virtual void processSecuring ( XMLElement * xml ) [protected, virtual]

Process a received element in Securing state. Descendants MUST consume the data. Drop the received element

Parameters:

xml

Valid XMLElement pointer

virtual void processStarted ( XMLElement * xml ) [protected, virtual]

Process a received element in Started state. Descendants MUST consume the data

Parameters:

xml

Valid XMLElement pointer

Reimplemented in JBComponentStream.

bool receive ( )

Read data from socket and pass it to the parser. Terminate stream on socket or parser error. This method is thread safe

Returns:: True if data was received

const JabberID& remote ( ) const [inline]

Get the JID of the remote side of this stream

Returns:: The JID of the remote side of this stream

void removePending	(	const String &	id,
		bool	notify = `false`
	)			`[inline]`

Remove pending stanzas with a given id. This method is thread safe

Parameters:

	id	The id of stanzas to remove
	notify	True to raise an event for each removed stanza

bool sendAuthResponse ( XMLElement * challenge = 0 ) [protected]

Send authentication response. Terminate the stream on error

Parameters:

challenge

Received challenge. If non 0 a SASL response is built and sent. If 0, a non-SASL response is sent (using handshaking for component and XEP-0078 for client streams)

Returns:: False if the stream is terminated

virtual Error sendStanza	(	XMLElement *	stanza,
		const char *	senderId = `0`
	)			`[virtual]`

Send a stanza. This method is thread safe

Parameters:

	stanza	Element to send
	senderId	Optional sender's id. Used for notification events

Returns:: The result of posting the stanza

Reimplemented in JBClientStream.

bool sendStreamStart ( ) [protected]

Send declaration and stream start

Returns:: True on success

bool sendStreamXML	(	XMLElement *	e,
		State	newState
	)			`[protected]`

Send stream XML elements through the socket

Parameters:

	e	The element to send
	newState	The new stream state on success

Returns:: False if send failed (stream termination was initiated)

void setClientAuthMechanism ( ) [protected]

Parse remote's features and pick an authentication mechanism to be used when requesting authentication

void setRecvCount ( int value ) [protected]

Safely set receive count

Parameters:

value

The new value of the receive count

bool startAuth ( ) [protected]

Start client authentication. Send first request to authenticate with the server. Terminate the stream on error

Returns:: False if the stream is terminated

bool startIdleTimer ( u_int64_t time = Time::msecNow() ) [protected]

Start the idle timer if there are no pending stanzas

Parameters:

time

The current time in miliseconds

Returns:: True if started

bool startRegister ( ) [protected]

Start client registration Terminate the stream on error

Returns:: False if the stream is terminated

bool startTls ( ) [protected]

Start client TLS. Terminate the stream on error

Returns:: True if TLS was initiated. False on failure: stream termination was initiated

State state ( ) const [inline]

Get the stream state

Returns:: The stream state as enumeration.

Mutex* streamMutex ( ) [inline]

Get the stream mutex

Returns:: The stream mutex

virtual void streamRunning ( ) [inline, protected, virtual]

Notify descendants when stream state changed to Running

Reimplemented in JBClientStream.

void terminate	(	bool	destroy,
		XMLElement *	recvStanza,
		XMPPError::Type	error,
		const char *	reason,
		bool	send,
		bool	final = `false`,
		bool	sendError = `true`
	)

Terminate stream. Send stream end tag or error. Remove pending stanzas without id. Deref stream if destroying. This method is thread safe

Parameters:

	destroy	True to destroy. False to terminate
	recvStanza	Received stanza, if any
	error	Termination reason. Set it to NoError to send stream end tag
	reason	Optional text to be added to the error stanza
	send	True to send the stream end element
	final	True if called from destructor
	sendError	True to send the error element (ignored if error is NoError)