#include <client.h>

Inheritance diagram for Client:

[legend]

Public Member Functions
	Client (const std::string &server)

	Client (const JID &jid, const std::string &password, int port=-1)

virtual	~Client ()

bool	bindResource (const std::string &resource)

bool	selectResource (const std::string &resource)

bool	hasResourceBind () const

bool	unbindResource (const std::string &resource)

const std::string &	resource () const

void	setStreamManagement (bool enable=true, bool resume=true)

void	ackStreamManagement ()

void	reqStreamManagement ()

int	priority () const

void	setUsername (const std::string &username)

void	setResource (const std::string &resource)

void	setPresence (const JID &to, Presence::PresenceType pres, int priority, const std::string &status=EmptyString)

void	setPresence (Presence::PresenceType pres, int priority, const std::string &status=EmptyString)

void	setPresence ()

void	setActive ()

void	setInactive ()

bool	hasClientStateIndication () const

Presence &	presence ()

GLOOX_DEPRECATED void	setForceNonSasl (bool force=true)

void	disableRoster ()

RosterManager *	rosterManager ()

void	disconnect ()

bool	login ()

Public Member Functions inherited from ClientBase
	ClientBase (const std::string &ns, const std::string &server, int port=-1)

	ClientBase (const std::string &ns, const std::string &password, const std::string &server, int port=-1)

virtual	~ClientBase ()

bool	connect (bool block=true)

virtual ConnectionError	recv (int timeout=-1)

virtual const std::string &	username () const

const JID &	jid ()

void	setSasl (bool sasl)

void	setTls (TLSPolicy tls)

void	setCompression (bool compression)

void	setPort (int port)

void	setServer (const std::string &server)

void	setPassword (const std::string &password)

const std::string &	server () const

bool	sasl () const

TLSPolicy	tls () const

bool	compression () const

int	port () const

virtual const std::string &	password () const

virtual Disco *	disco () const

const std::string	getID ()

void	send (Tag *tag)

void	send (IQ &iq, IqHandler *ih, int context, bool del=false)

void	send (const IQ &iq)

void	send (const Message &msg)

void	send (const Subscription &sub)

void	send (const Presence &pres)

bool	authed () const

ConnectionState	state () const

const std::string &	xmlLang () const

void	setXmlLang (const std::string &xmllang)

ConnectionBase *	connectionImpl () const

void	setConnectionImpl (ConnectionBase *cb)

TLSBase *	encryptionImpl () const

void	setEncryptionImpl (TLSBase *tb)

CompressionBase *	compressionImpl () const

void	setCompressionImpl (CompressionBase *cb)

void	whitespacePing ()

void	xmppPing (const JID &to, EventHandler *eh)

void	setAuthzid (const JID &authzid)

void	setAuthcid (const std::string &authcid)

void	setSASLMechanisms (int mechanisms)

void	registerStanzaExtension (StanzaExtension *ext)

bool	removeStanzaExtension (int ext)

void	registerConnectionListener (ConnectionListener *cl)

void	registerIqHandler (IqHandler *ih, int exttype)

void	removeIDHandler (IqHandler *ih)

void	registerMessageHandler (MessageHandler *mh)

void	removeMessageHandler (MessageHandler *mh)

void	registerMessageSession (MessageSession *session)

void	disposeMessageSession (MessageSession *session)

void	registerPresenceHandler (PresenceHandler *ph)

void	registerPresenceHandler (const JID &jid, PresenceHandler *ph)

void	registerSubscriptionHandler (SubscriptionHandler *sh)

void	registerTagHandler (TagHandler *th, const std::string &tag, const std::string &xmlns)

void	registerStatisticsHandler (StatisticsHandler *sh)

void	removeConnectionListener (ConnectionListener *cl)

void	removeIqHandler (IqHandler *ih, int exttype)

void	removePresenceHandler (PresenceHandler *ph)

void	removePresenceHandler (const JID &jid, PresenceHandler *ph)

void	removeSubscriptionHandler (SubscriptionHandler *sh)

void	removeTagHandler (TagHandler *th, const std::string &tag, const std::string &xmlns)

void	removeStatisticsHandler ()

void	setCACerts (const StringList &cacerts)

void	setClientCert (const std::string &clientKey, const std::string &clientCerts)

void	registerMessageSessionHandler (MessageSessionHandler *msh, int types=0)

LogSink &	logInstance ()

StreamError	streamError () const

const std::string &	streamErrorText (const std::string &lang="default") const

const std::string &	streamErrorCData () const

const Tag *	streamErrorAppCondition () const

AuthenticationError	authError () const

StatisticsStruct	getStatistics ()

void	registerMUCInvitationHandler (MUCInvitationHandler *mih)

void	removeMUCInvitationHandler ()

void	addPresenceExtension (StanzaExtension *se)

bool	removePresenceExtension (int type)

const StanzaExtensionList &	presenceExtensions () const

const TagList	sendQueue ()

virtual void	handleTag (Tag *tag)

virtual void	handleCompressedData (const std::string &data)

virtual void	handleDecompressedData (const std::string &data)

virtual void	handleReceivedData (const ConnectionBase *connection, const std::string &data)

virtual void	handleConnect (const ConnectionBase *connection)

virtual void	handleDisconnect (const ConnectionBase *connection, ConnectionError reason)

virtual void	handleEncryptedData (const TLSBase *base, const std::string &data)

virtual void	handleDecryptedData (const TLSBase *base, const std::string &data)

virtual void	handleHandshakeResult (const TLSBase *base, bool success, CertInfo &certinfo)

Public Member Functions inherited from TagHandler
virtual	~TagHandler ()

Public Member Functions inherited from ConnectionDataHandler
virtual	~ConnectionDataHandler ()

Public Member Functions inherited from CompressionDataHandler
virtual	~CompressionDataHandler ()

Public Member Functions inherited from TLSHandler
virtual	~TLSHandler ()

Public Member Functions inherited from IqHandler
virtual	~IqHandler ()

Protected Member Functions
void	nonSaslLogin ()

Protected Member Functions inherited from ClientBase
void	notifyOnResourceBindError (const Error *error)

void	notifyOnResourceBind (const std::string &resource)

void	notifyOnSessionCreateError (const Error *error)

bool	notifyOnTLSConnect (const CertInfo &info)

void	notifyOnConnect ()

void	notifyStreamEvent (StreamEvent event)

void	header ()

void	setAuthed (bool authed)

void	setAuthFailure (AuthenticationError e)

virtual bool	checkStreamVersion (const std::string &version)

void	startSASL (SaslMechanism type)

bool	processSASLSuccess (const std::string &payload)

void	processSASLChallenge (const std::string &challenge)

void	processSASLError (Tag *tag)

void	setNTLMDomain (const std::string &domain)

void	startTls ()

bool	hasTls ()

void	send (const std::string &xml)

void	checkQueue (int handled, bool resend)

int	stanzasSent () const

std::string	getRandom ()

Additional Inherited Members
Protected Types inherited from ClientBase
enum	SMContext { CtxSMInvalid , CtxSMFailed , CtxSMEnable , CtxSMResume , CtxSMEnabled , CtxSMResumed }

Protected Attributes inherited from ClientBase
JID	m_jid

JID	m_authzid

std::string	m_authcid

ConnectionBase *	m_connection

TLSBase *	m_encryption

CompressionBase *	m_compression

Disco *	m_disco

StanzaExtensionList	m_presenceExtensions

GLOOX_DEPRECATED std::string	m_selectedResource

std::string	m_clientCerts

std::string	m_clientKey

std::string	m_namespace

std::string	m_password

std::string	m_xmllang

std::string	m_server

std::string	m_sid

bool	m_compressionActive

bool	m_encryptionActive

bool	m_compress

bool	m_authed

bool	m_resourceBound

bool	m_block

bool	m_sasl

TLSPolicy	m_tls

int	m_port

int	m_availableSaslMechs

SMContext	m_smContext

int	m_smHandled

Detailed Description

This class implements a basic Jabber/XMPP Client.

It supports SASL Authentication as well as TLS (Encryption), which can be switched on/off separately. They are used automatically if the server supports them.

To use, create a new Client instance and feed it connection credentials, either in the Constructor or afterwards using the setters. You should then register packet handlers implementing the corresponding Interfaces (ConnectionListener, PresenceHandler, MessageHandler, IqHandler, SubscriptionHandler), and call connect() to establish the connection to the server.

Note: While the MessageHandler interface is still available (and will be in future versions) it is now recommended to use the new MessageSession for any serious messaging.

Simple usage example:

using namespace gloox;
 
void TestProg::doIt()
{
  Client* j = new Client( "user@server/resource", "password" );
  j->registerPresenceHandler( this );
  j->disco()->setVersion( "TestProg", "1.0" );
  j->disco()->setIdentity( "client", "bot" );
  j->connect();
}
 
virtual void TestProg::presenceHandler( Presence* presence )
{
  // handle incoming presence packets here
}

However, you can skip the presence handling stuff if you make use of the RosterManager.

By default, the library handles a few (incoming) IQ namespaces on the application's behalf. These include:

jabber:iq:roster: by default the server-side roster is fetched and handled. Use rosterManager() and RosterManager to interact with the Roster.
XEP-0092 (Software Version): If no version is specified, a name of "based on gloox" with gloox's current version is announced.
XEP-0030 (Service Discovery): All supported/available services are announced. No items are returned.
Note
As of gloox 0.9, by default a priority of 0 is sent along with the initial presence.

As of gloox 0.9, initial presence is automatically sent. Presence: available, Priority: 0. To disable sending of initial Presence use setPresence() with a value of Unavailable prior to connecting.

SASL Authentication

Besides the simple, IQ-based authentication (XEP-0078), gloox supports several SASL (Simple Authentication and Security Layer, RFC 2222) authentication mechanisms.

DIGEST-MD5: This mechanism is preferred over all other mechanisms if username and password are provided to the Client instance. It is secure even without TLS encryption.
PLAIN: This mechanism is used if DIGEST-MD5 is not available. It is not secure without encryption.
ANONYMOUS This mechanism is used if neither username nor password are set. The server generates random, temporary username and resource and may restrict available services.
EXTERNAL This mechanism is currently only available if client certificate and private key are provided. The server tries to figure out who the client is by external means – for instance, using the provided certificate or even the IP address. (The restriction to certificate/key availability is likely to be lifted in the future.)

Of course, all these mechanisms are not tried unless the server offers them.

Stream Management

To enable Stream Management (XEP-0198), call setStreamManagement() with the first parameter set to true at any time. This will tell the server to enable Stream Management, if the feature is available. Once switched on, Stream Management can not be disabled for a given active stream. However, setting the first parameter to false, it can be disabled inside gloox so that Stream Management will not be used for subsequent connections.

To enable the stream resumption feature, pass true as the second parameter to setStreamManagement(). Upon re-connect after an unexpected (i.e. neither user-triggered nor server-triggered) disconnect, gloox will try to resume the stream and re-send any non-acknowledged stanzas automatically. For stream resumption to work you have to re-connect using the very same Client instance.

After an unexpected disconnect you may check the send queue using sendQueue() . Stanzas in the queue have been sent but not yet acknowledged by the server. Depending on the circumstances of the disconnect, this does not mean that those stanzas have not been received by the recipient.

Author: Jakob Schröter js@ca.nosp@m.maya.nosp@m..net

Definition at line 116 of file client.h.

Constructor & Destructor Documentation

◆ Client() [1/2]

Client ( const std::string & server )

Constructs a new Client which can be used for account registration only. SASL and TLS are on by default. The port will be determined by looking up SRV records. Alternatively, you can set the port explicitly by calling setPort().

Parameters

server The server to connect to.

Definition at line 103 of file client.cpp.

◆ Client() [2/2]

Client	(	const JID &	jid,
		const std::string &	password,
		int	port = `-1`
	)

Constructs a new Client. SASL and TLS are on by default. This should be the default constructor for most use cases. The server address will be taken from the JID. The actual host will be resolved using SRV records. The domain part of the JID is used as a fallback in case no SRV record is found, or you can set the server address separately by calling setServer().

Parameters

jid	A full Jabber ID used for connecting to the server.
password	The password used for authentication.
port	The port to connect to. The default of -1 means to look up the port via DNS SRV.

Definition at line 115 of file client.cpp.

◆ ~Client()

~Client ( )

virtual

Virtual destructor.

Reimplemented in Client.

Definition at line 128 of file client.cpp.

Member Function Documentation

◆ ackStreamManagement()

void ackStreamManagement ( )

Use this function to send an unrequested 'ack' to the server to let it know the number of handled stanzas. You may use this function at any time. However, gloox will also reply to incoming 'ack requests' automatically. These automatic 'acks' are not announced anywhere in gloox. This function is a no-op if called in situations where sending an ack is not allowed by the protocol.

Note: This function is part of XEP-0198.

Since: 1.0.4

Definition at line 619 of file client.cpp.

◆ bindResource()

bool bindResource ( const std::string & resource )

inline

Use this function to bind an additional resource or to re-try to bind a resource in case previous binding failed and you were notified by means of ConnectionListener::onResourceBindError(). Use hasResourceBind() to find out if the server supports binding of multiple resources. bindResource() is a NOOP if it doesn't.

Note: ConnectionListener::onResourceBound() and ConnectionListener::onResourceBindError() will be called in case of success and failure, respectively.

Parameters

resource The resource identifier to bind. May be empty. In that case the server will assign a unique resource identifier.

Returns: Returns true if binding of multiple resources is supported, false otherwise. A return value of true does not indicate that the resource was successfully bound.

Note: It is not necessary to call this function to bind the initial, main, resource.

Since: 1.0

Definition at line 163 of file client.h.

◆ disableRoster()

void disableRoster ( )

Disables the automatic roster management. You have to keep track of incoming presence yourself if you want to have a roster.

Definition at line 699 of file client.cpp.

◆ disconnect()

void disconnect ( )

Disconnects from the server.

Definition at line 739 of file client.cpp.

◆ hasClientStateIndication()

bool hasClientStateIndication ( ) const

inline

Use this function to find out whether the server supports Client State Indication (XEP-0352).

Returns: True if the server supports XEP-0352, false if not. XEP Version: 0.2

Since: 1.0.19

Definition at line 321 of file client.h.

◆ hasResourceBind()

bool hasResourceBind ( ) const

inline

This function can be used to find out whether the server supports binding of multiple resources.

Returns: True if binding of multiple resources is supported by the server, false otherwise.

Definition at line 183 of file client.h.

◆ login()

bool login ( )

Initiates a login attempt (currently SASL External not supported). This is useful after registering a new account. Simply use setUsername() and setPassword(), and call login().

Returns: True if a login attempt could be started, false otherwise. A return value of true does not indicate that login was successful.

Definition at line 453 of file client.cpp.

◆ nonSaslLogin()

void nonSaslLogin ( )

protected

Initiates non-SASL login.

Definition at line 706 of file client.cpp.

◆ presence()

Presence& presence ( )

inline

Returns the current presence.

Returns: The current presence.

Definition at line 328 of file client.h.

◆ priority()

int priority ( ) const

inline

Returns the current priority.

Returns: The priority of the current resource.

Definition at line 239 of file client.h.

◆ reqStreamManagement()

void reqStreamManagement ( )

Use this function to request the number of handled stanzas from the server. You may use this function at any time. gloox does not send any such requests automatically.

Note: This function is part of XEP-0198.

Since: 1.0.4

Definition at line 629 of file client.cpp.

◆ resource()

const std::string& resource ( ) const

inline

Returns the current prepped main resource.

Returns: The resource used to connect.

Definition at line 200 of file client.h.

◆ rosterManager()

RosterManager* rosterManager ( )

inline

This function gives access to the RosterManager object.

Returns: A pointer to the RosterManager.

Definition at line 348 of file client.h.

◆ selectResource()

bool selectResource ( const std::string & resource )

Use this function to select a resource identifier that has been bound previously by means of bindResource(). It is not necessary to call this function if only one resource is bound. Use hasResourceBind() to find out if the server supports binding of multiple resources.

Parameters

resource A resource string that has been bound previously.

Note: If the resource string has not been bound previously, future sending of stanzas will fail.

Definition at line 523 of file client.cpp.

◆ setActive()

void setActive ( )

inline

Use this function to indicate a client state of 'active' to the Server. See XEP-0352 for more information. This function is a no-op if the server does not support Client State Indication (i.e. nothing is sent). Use hasClientStateIndication() to find out.

Since: 1.0.19

Definition at line 302 of file client.h.

◆ setForceNonSasl()

GLOOX_DEPRECATED void setForceNonSasl ( bool force = true )

inline

This is a temporary hack to enforce Non-SASL login. You should not need to use it.

Parameters

force Whether to force non-SASL auth. Default true.

Deprecated:: Please update the server to properly support SASL instead.

Definition at line 335 of file client.h.

◆ setInactive()

void setInactive ( )

inline

Use this function to indicate a client state of 'inactive' to the Server. See XEP-0352 for more information. This function is a no-op if the server does not support Client State Indication (i.e. nothing is sent). Use hasClientStateIndication() to find out.

Since: 1.0.19

Definition at line 312 of file client.h.

◆ setPresence() [1/3]

void setPresence ( )

inline

Use this function to broadcast the entity's presence to all subscribed entities. This is a NOOP if there's no active connection. To send directed presence, use setPresence( const JID&, Presence::PresenceType, int, const std::string& ). If used while a connection already is established a repective presence stanza will be sent out immediately. Use presence() to modify the Presence object.

Note: When login is finished, initial presence will be sent automatically. So you do not need to call this function after login.

Since: 1.0

Definition at line 293 of file client.h.

◆ setPresence() [2/3]

void setPresence	(	const JID &	to,
		Presence::PresenceType	pres,
		int	priority,
		const std::string &	status = `EmptyString`
	)

Sends directed presence to the given JID. This is a NOOP if there's no active connection. To broadcast presence use setPresence( Presence::PresenceType, int, const std::string& ).

Parameters

to	The JID to send directed Presence to.
pres	The presence to send.
priority	The priority to include. Legal values: -128 <= priority <= 127
status	The optional status message to include.

Note: This function does not include any presence extensions (as added by means of addPresenceExtension()) to the stanza.

Definition at line 684 of file client.cpp.

◆ setPresence() [3/3]

void setPresence	(	Presence::PresenceType	pres,
		int	priority,
		const std::string &	status = `EmptyString`
	)

Use this function to set the entity's presence, that is, to broadcast presence to all subscribed entities. To send directed presence, use setPresence( const JID&, Presence::PresenceType, int, const std::string& ). If used prior to establishing a connection, the set values will be sent with the initial presence stanza. If used while a connection already is established, a presence stanza will be sent out immediately.

Parameters

pres	The Presence value to set.
priority	An optional priority value. Legal values: -128 <= priority <= 127
status	An optional message describing the presence state.

Since: 0.9

Definition at line 674 of file client.cpp.

◆ setResource()

void setResource ( const std::string & resource )

inline

Sets the main resource to use to connect to the XMPP server.

Parameters

resource The resource to use to log into the server.

Definition at line 251 of file client.h.

◆ setStreamManagement()

void setStreamManagement	(	bool	enable = `true`,
		bool	resume = `true`
	)

This function enables Stream Management (XEP-0198) if the server supports it. Optionally, stream resumption can be disabled.

Note: You can use this function at any time. However, gloox will make sure Stream Management requests are sent only when allowed by the specification.

Parameters

enable	Enable or disable Stream Management. Note: once enabled on a connection, Stream Management can not be disabled for that connection.
resume	Tells the server whether to enable stream resumption. Defaults to true.

Note: This function is part of XEP-0198.

Since: 1.0.4

Definition at line 570 of file client.cpp.

◆ setUsername()

void setUsername ( const std::string & username )

Sets the username to use to connect to the XMPP server.

Parameters

username The username to authenticate with.

Definition at line 143 of file client.cpp.

◆ unbindResource()

bool unbindResource ( const std::string & resource )

inline

Use this function to unbind a resource identifier that has been bound previously by means of bindResource(). Use hasResourceBind() to find out if the server supports binding of multiple resources. unbindResource() is a NOOP if it doesn't.

Parameters

resource A resource string that has been bound previously.

Note: Servers are encouraged to terminate the connection should the only bound resource be unbound.

Definition at line 193 of file client.h.

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

Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

SASL Authentication

Stream Management

Constructor & Destructor Documentation

◆ Client() [1/2]

◆ Client() [2/2]

◆ ~Client()

Member Function Documentation

◆ ackStreamManagement()

◆ bindResource()

◆ disableRoster()

◆ disconnect()

◆ hasClientStateIndication()

◆ hasResourceBind()

◆ login()

◆ nonSaslLogin()

◆ presence()

◆ priority()

◆ reqStreamManagement()

◆ resource()

◆ rosterManager()

◆ selectResource()

◆ setActive()

◆ setForceNonSasl()

◆ setInactive()

◆ setPresence() [1/3]

◆ setPresence() [2/3]

◆ setPresence() [3/3]

◆ setResource()

◆ setStreamManagement()

◆ setUsername()

◆ unbindResource()