#include <client.h>

Inheritance diagram for Client:

Collaboration diagram for Client:

Public Member Functions
	Client (const std::string &server)
	Client (const JID &jid, const std::string &password, int port=-1)
	Client (const std::string &username, const std::string &password, const std::string &server, const std::string &resource, int port=-1)
virtual	~Client ()
void	bindResource ()
const std::string &	resource () const
int	priority () const
void	setUsername (const std::string &username)
void	setResource (const std::string &resource)
void	setPresence (Presence presence, int priority=0, const std::string &msg="")
Presence	presence () const
const std::string &	status () const
void	addPresenceExtension (StanzaExtension *se)
void	removePresenceExtensions ()
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)
ConnectionError	recv (int timeout=-1)
virtual const std::string &	username () const
const JID &	jid ()
void	setSasl (bool sasl)
GLOOX_DEPRECATED void	setTls (bool tls)
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
bool	tls () const
bool	compression () const
int	port () const
virtual const std::string &	password () const
virtual Disco *	disco () const
const std::string	getID ()
virtual void	send (Tag *tag)
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)
void	setAuthzid (const JID &authzid)
void	setSASLMechanisms (int mechanisms)
void	registerConnectionListener (ConnectionListener *cl)
void	registerIqHandler (IqHandler *ih, const std::string &xmlns)
void	trackID (IqHandler *ih, const std::string &id, int context)
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 (const std::string &xmlns)
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 ()
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 ()

Protected Member Functions
void	nonSaslLogin ()

Detailed Description

This class implements a basic Jabber 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( Stanza *stanza )
{
  // 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 PresenceUnavailable 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.

Author: Jakob Schroeter js@ca.nosp@m.maya.nosp@m..net

Definition at line 97 of file client.h.

Constructor & Destructor Documentation

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 45 of file client.cpp.

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 56 of file client.cpp.

Client	(	const std::string &	username,
		const std::string &	password,
		const std::string &	server,
		const std::string &	resource,
		int	port = `-1`
	)

Constructs a new Client. SASL and TLS are on by default. The actual host will be resolved using SRV records. The server value is used as a fallback in case no SRV record is found.

Parameters

username	The username/local part of the JID.
resource	The resource part of the JID.
password	The password to use for authentication.
server	The Jabber ID'S server part and the host name to connect to. If those are different for your setup, use the second constructor instead.
port	The port to connect to. The default of -1 means to look up the port via DNS SRV.

Definition at line 68 of file client.cpp.

~Client ( )

virtual

Virtual destructor.

Definition at line 83 of file client.cpp.

Member Function Documentation

void addPresenceExtension ( StanzaExtension * se )

Use this function to add a StanzaExtension which will be sent with eacha nd every Presence Stanza that is sent out. Use cases include signed presence (GPGSigned , XEP-0027), VCard avatar notifications (VCardUpdate , XEP-0153), and others (see StanzaExtension for derived classes.

Parameters

se	The StanzaExtension to add. Client will become the owner of the given StanzaExtension.

Note: Currently there is no way to selectively remove an extension. Use removePresenceExtensions() to remove all extensions.

Definition at line 466 of file client.cpp.

void bindResource ( )

Use this function to re-try to bind a resource only in case you were notified about an error by means of ConnectionListener::onResourceBindError(). You may (or should) use setResource() before.

Definition at line 345 of file client.cpp.

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 496 of file client.cpp.

void disconnect ( )

Disconnects from the server.

Definition at line 563 of file client.cpp.

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 318 of file client.cpp.

void nonSaslLogin ( )

protected

Initiates non-SASL login.

Definition at line 503 of file client.cpp.

Presence presence ( ) const

inline

Returns the current presence.

Returns: The current presence.

Definition at line 192 of file client.h.

int priority ( ) const

inline

Returns the current priority.

Returns: The priority of the current resource.

Definition at line 161 of file client.h.

void removePresenceExtensions ( )

Use this function to remove all extensions added using addPresenceExtension().

Definition at line 471 of file client.cpp.

const std::string& resource ( ) const

inline

Returns the current prepped resource.

Returns: The resource used to connect.

Definition at line 155 of file client.h.

RosterManager* rosterManager ( )

inline

This function gives access to the RosterManager object.

Returns: A pointer to the RosterManager.

Definition at line 236 of file client.h.

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 223 of file client.h.

void setPresence	(	Presence	presence,
		int	priority = `0`,
		const std::string &	msg = `""`
	)

Use this function to set the entity's presence. 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 repective presence stanza will be sent out immediately.

Parameters

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

Since: 0.9

Definition at line 481 of file client.cpp.

void setResource ( const std::string & resource )

inline

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

Parameters

resource The resource to use to log into the server.

Definition at line 173 of file client.h.

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 96 of file client.cpp.

const std::string& status ( ) const

inline

Returns the current status message.

Returns: The current status message.

Definition at line 198 of file client.h.

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

Public Member Functions

Protected Member Functions

Detailed Description

SASL Authentication

Constructor & Destructor Documentation

Member Function Documentation