gloox  1.0.9
Public Member Functions | Protected Member Functions | List of all members
Client Class Reference

#include <client.h>

Inheritance diagram for Client:
Inheritance graph
[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 ()
Presencepresence ()
GLOOX_DEPRECATED void setForceNonSasl (bool force=true)
void disableRoster ()
RosterManagerrosterManager ()
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 JIDjid ()
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 Discodisco () 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)
ConnectionBaseconnectionImpl () const
void setConnectionImpl (ConnectionBase *cb)
TLSBaseencryptionImpl () const
void setEncryptionImpl (TLSBase *tb)
CompressionBasecompressionImpl () 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)
LogSinklogInstance ()
StreamError streamError () const
const std::string & streamErrorText (const std::string &lang="default") const
const std::string & streamErrorCData () const
const TagstreamErrorAppCondition () const
AuthenticationError authError () const
StatisticsStruct getStatistics ()
void registerMUCInvitationHandler (MUCInvitationHandler *mih)
void removeMUCInvitationHandler ()
void addPresenceExtension (StanzaExtension *se)
bool removePresenceExtension (int type)
const StanzaExtensionListpresenceExtensions () 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 ()
virtual bool handleIq (const IQ &iq)=0
virtual void handleIqID (const IQ &iq, int context)=0

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)
virtual void disconnect (ConnectionError reason)
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
ConnectionBasem_connection
TLSBasem_encryption
CompressionBasem_compression
Discom_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_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->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:

SASL Authentication

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

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 Schroeter js@ca.nosp@m.maya.nosp@m..net

Definition at line 116 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
serverThe server to connect to.

Definition at line 103 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
jidA full Jabber ID used for connecting to the server.
passwordThe password used for authentication.
portThe 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 ( )
virtual

Virtual destructor.

Reimplemented in Client.

Definition at line 128 of file client.cpp.

Member Function Documentation

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

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
resourceThe 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.

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

void disconnect ( )

Disconnects from the server.

Definition at line 732 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 183 of file client.h.

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

void nonSaslLogin ( )
protected

Initiates non-SASL login.

Definition at line 699 of file client.cpp.

Presence& presence ( )
inline

Returns the current presence.

Returns
The current presence.

Definition at line 299 of file client.h.

int priority ( ) const
inline

Returns the current priority.

Returns
The priority of the current resource.

Definition at line 239 of file client.h.

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

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 ( )
inline

This function gives access to the RosterManager object.

Returns
A pointer to the RosterManager.

Definition at line 319 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.

Parameters
resourceA 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 520 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
forceWhether to force non-SASL auth. Default true.
Deprecated:
Please update the server to properly support SASL instead.

Definition at line 306 of file client.h.

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
toThe JID to send directed Presence to.
presThe presence to send.
priorityThe priority to include. Legal values: -128 <= priority <= 127
statusThe 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 677 of file client.cpp.

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
presThe Presence value to set.
priorityAn optional priority value. Legal values: -128 <= priority <= 127
statusAn optional message describing the presence state.
Since
0.9

Definition at line 668 of file client.cpp.

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.

void setResource ( const std::string &  resource)
inline

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

Parameters
resourceThe resource to use to log into the server.

Definition at line 251 of file client.h.

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
enableEnable or disable Stream Management. Note: once enabled on a connection, Stream Management can not be disabled for that connection.
resumeTells 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 567 of file client.cpp.

void setUsername ( const std::string &  username)

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

Parameters
usernameThe username to authenticate with.

Definition at line 143 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
resourceA 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: