Client Class Reference

This class implements a basic Jabber Client. More...

#include <client.h>

Inherits ClientBase.

Inheritance diagram for Client:

[legend]List of all members.

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
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 ()
Presence &	presence ()
GLOOX_DEPRECATED void	setForceNonSasl (bool force=true)
void	disableRoster ()
RosterManager *	rosterManager ()
void	disconnect ()
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( 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.

Author:

Jakob Schroeter <js@camaya.net>

Definition at line 98 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 116 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 127 of file client.cpp.

~Client (   )  [virtual]

Virtual destructor. Definition at line 139 of file client.cpp.

---

Member Function Documentation

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

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

void disconnect (   )

Disconnects from the server. Definition at line 566 of file client.cpp.

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

void nonSaslLogin (   )  [protected]

Initiates non-SASL login. Definition at line 533 of file client.cpp.

Presence& presence (   )  [inline]

Returns the current presence. Returns: The current presence. Definition at line 248 of file client.h.

int priority (   )  const [inline]

Returns the current priority. Returns: The priority of the current resource. Definition at line 188 of file client.h.

const std::string& resource (   )  const [inline]

Returns the current prepped main resource. Returns: The resource used to connect. Definition at line 182 of file client.h.

RosterManager* rosterManager (   )  [inline]

This function gives access to the RosterManager object. Returns: A pointer to the RosterManager. Definition at line 268 of file client.h.

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. selectResource() is a NOOP if it doesn't. 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 425 of file client.cpp.

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

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

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

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

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

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

---

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

• client.h
• client.cpp

---