#include <clientbase.h>
Public Member Functions | |
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) |
It manages connection establishing, authentication, filter registration and invocation.
Definition at line 60 of file clientbase.h.
ClientBase | ( | const std::string & | ns, | |
const std::string & | server, | |||
int | port = -1 | |||
) |
Constructs a new ClientBase. You should not need to use this class directly. Use Client or Component instead.
ns | The namespace which qualifies the stream. Either jabber:client or jabber:component:* | |
server | The server to connect to. | |
port | The port to connect to. The default of -1 means to look up the port via DNS SRV or to use a default port of 5222 as defined in XMPP Core. |
Definition at line 62 of file clientbase.cpp.
ClientBase | ( | const std::string & | ns, | |
const std::string & | password, | |||
const std::string & | server, | |||
int | port = -1 | |||
) |
Constructs a new ClientBase. You should not need to use this class directly. Use Client or Component instead.
ns | The namespace which qualifies the stream. Either jabber:client or jabber:component:* | |
password | The password to use for further authentication. | |
server | The server to connect to. | |
port | The port to connect to. The default of -1 means to look up the port via DNS SRV or to use a default port of 5222 as defined in XMPP: Core. |
Definition at line 77 of file clientbase.cpp.
~ClientBase | ( | ) | [virtual] |
Virtual destrcuctor.
Definition at line 128 of file clientbase.cpp.
bool connect | ( | bool | block = true |
) |
Initiates the connection to a server. This function blocks as long as a connection is established. You can have the connection block 'til the end of the connection, or you can have it return immediately. If you choose the latter, its your responsibility to call recv() every now and then to actually receive data from the socket and to feed the parser.
block | True for blocking, false for non-blocking connect. Defaults to true. |
Definition at line 153 of file clientbase.cpp.
ConnectionError recv | ( | int | timeout = -1 |
) |
Use this periodically to receive data from the socket and to feed the parser. You need to use this only if you chose to connect in non-blocking mode.
timeout | The timeout in microseconds to use for select. Default of -1 means blocking until data was available. |
Definition at line 145 of file clientbase.cpp.
virtual const std::string& username | ( | ) | const [inline, virtual] |
Reimplement this function to provide a username for connection purposes.
Definition at line 121 of file clientbase.h.
const JID& jid | ( | ) | [inline] |
Returns the current Jabber ID. If an authentication ID has been set (using setAuthzid()) this authzid is returned.
Definition at line 130 of file clientbase.h.
void setSasl | ( | bool | sasl | ) | [inline] |
Switches usage of SASL on/off. Default: on. SASL should only be disabled if there are problems with using it.
sasl | Whether to switch SASL usage on or off. |
Definition at line 137 of file clientbase.h.
GLOOX_DEPRECATED void setTls | ( | bool | tls | ) | [inline] |
Switches usage of TLS on/off (if available). Default: on if available. TLS should only be disabled if there are problems with using it.
tls | Whether to switch TLS usage on or off. |
Definition at line 144 of file clientbase.h.
void setTls | ( | TLSPolicy | tls | ) | [inline] |
Switches usage of TLS on/off (if available). Default: on if available. TLS should only be disabled if there are problems with using it.
tls | Whether to switch TLS usage on or off. |
Definition at line 151 of file clientbase.h.
void setCompression | ( | bool | compression | ) | [inline] |
Switches usage of Stream Compression on/off (if available). Default: on if available. Stream Compression should only be disabled if there are problems with using it.
compression | Whether to switch Stream Compression usage on or off. |
Definition at line 158 of file clientbase.h.
void setPort | ( | int | port | ) | [inline] |
Sets the port to connect to. This is not necessary if either the default port (5222) is used or SRV records exist which will be resolved.
port | The port to connect to. |
Definition at line 165 of file clientbase.h.
void setServer | ( | const std::string & | server | ) |
Sets the XMPP server to connect to.
server | The server to connect to. Either IP or fully qualified domain name. |
This function also sets the server of the Connection(Base) in use.
Definition at line 393 of file clientbase.cpp.
void setPassword | ( | const std::string & | password | ) | [inline] |
Sets the password to use to connect to the XMPP server.
password | The password to use for authentication. |
Definition at line 180 of file clientbase.h.
const std::string& server | ( | ) | const [inline] |
Returns the current prepped server.
Definition at line 186 of file clientbase.h.
bool sasl | ( | ) | const [inline] |
Returns whether SASL is currently enabled (not necessarily used).
Definition at line 192 of file clientbase.h.
bool tls | ( | ) | const [inline] |
Returns whether TLS is currently enabled (not necessarily used).
Definition at line 198 of file clientbase.h.
bool compression | ( | ) | const [inline] |
Returns whether Stream Compression is currently enabled (not necessarily used).
Definition at line 204 of file clientbase.h.
int port | ( | ) | const [inline] |
Returns the port. The default of -1 means that the actual port will be looked up using SRV records, or the XMPP default port of 5222 will be used.
Definition at line 211 of file clientbase.h.
virtual const std::string& password | ( | ) | const [inline, virtual] |
Returns the current password.
Definition at line 217 of file clientbase.h.
virtual Disco* disco | ( | ) | const [inline, virtual] |
This function gives access to the Disco
object.
Definition at line 223 of file clientbase.h.
const std::string getID | ( | ) |
Creates a string which is unique in the current instance and can be used as an ID for queries.
Definition at line 681 of file clientbase.cpp.
void send | ( | Tag * | tag | ) | [virtual] |
Sends a given Tag over an established connection. The ClientBase object becomes the owner of this Tag and will delete it after sending it. You should not rely on the existance of the Tag after it's been sent. If you still need it after sending it, use Tag::clone() to create a deep copy.
tag | The Tag to send. |
Definition at line 600 of file clientbase.cpp.
bool authed | ( | ) | const [inline] |
Returns whether authentication has taken place and was successful.
Definition at line 245 of file clientbase.h.
ConnectionState state | ( | ) | const |
Returns the current connection status.
Definition at line 657 of file clientbase.cpp.
const std::string& xmlLang | ( | ) | const [inline] |
Retrieves the value of the xml:lang attribute of the initial stream. Default is 'en', i.e. if not changed by a call to setXmlLang().
Definition at line 257 of file clientbase.h.
void setXmlLang | ( | const std::string & | xmllang | ) | [inline] |
Sets the value for the xml:lang attribute of the initial stream.
xmllang | The language identifier for the stream. It must conform to section 2.12 of the XML specification and RFC 3066. Default is 'en'. |
Definition at line 265 of file clientbase.h.
ConnectionBase* connectionImpl | ( | ) | const [inline] |
This function returns the concrete connection implementation currently in use.
Definition at line 272 of file clientbase.h.
void setConnectionImpl | ( | ConnectionBase * | cb | ) |
Use this function if you have a class implementing a UDP, SCTP (or whatever) connection. This should be called before calling connect(). If there already is a connection implementation set (either manually or automatically), it gets deleted.
cb | The connection to use. |
Definition at line 719 of file clientbase.cpp.
TLSBase* encryptionImpl | ( | ) | const [inline] |
This function returns the concrete encryption implementation currently in use.
Definition at line 288 of file clientbase.h.
void setEncryptionImpl | ( | TLSBase * | tb | ) |
Use this function if you have a class supporting hardware encryption (or whatever). This should be called before calling connect(). If there already is a encryption implementation set (either manually or automatically), it gets deleted.
tb | The encryption implementation to use. |
Definition at line 728 of file clientbase.cpp.
CompressionBase* compressionImpl | ( | ) | const [inline] |
This function returns the concrete compression implementation currently in use.
Definition at line 304 of file clientbase.h.
void setCompressionImpl | ( | CompressionBase * | cb | ) |
Use this function if you have a class supporting some fancy compression algorithm. This should be called before calling connect(). If there already is a compression implementation set (either manually or automatically), it gets deleted.
cb | The compression implementation to use. |
Definition at line 737 of file clientbase.cpp.
void whitespacePing | ( | ) |
void xmppPing | ( | const JID & | to | ) |
Sends a XMPP Ping (XEP-0199) to the given JID. There is currently no way to know whether the remote entity answered (other than registering an IQ handler for the urn:xmpp:ping namespace).
Definition at line 667 of file clientbase.cpp.
void setAuthzid | ( | const JID & | authzid | ) | [inline] |
Use this function to set an authorization ID (authzid). Provided the server supports it and the user has sufficient rights, they could then authenticate as bob@example.net but act as alice@example.net.
Definition at line 336 of file clientbase.h.
void setSASLMechanisms | ( | int | mechanisms | ) | [inline] |
Use this function to limit SASL mechanisms gloox can use. By default, all supported mechanisms are allowed. To exclude one (or more) mechanisms, remove it from SaslMechAll like so:
int mymechs = SaslMechAll ^ SaslMechDigestMd5;
mechanisms | Bitwise ORed SaslMechanism. |
Definition at line 348 of file clientbase.h.
void registerConnectionListener | ( | ConnectionListener * | cl | ) |
Registers cl
as object that receives connection notifications.
cl | The object to receive connection notifications. |
Definition at line 1011 of file clientbase.cpp.
void registerIqHandler | ( | IqHandler * | ih, | |
const std::string & | xmlns | |||
) |
Registers ih
as object that receives Iq stanza notifications for namespace xmlns
. Only one handler per namespace is possible.
ih | The object to receive Iq stanza notifications. | |
xmlns | The namespace the object handles. |
Definition at line 904 of file clientbase.cpp.
void trackID | ( | IqHandler * | ih, | |
const std::string & | id, | |||
int | context | |||
) |
Use this function to be notified of incoming IQ stanzas with the given value of the id attribute. Since IDs are supposed to be unique, this notification works only once.
ih | The IqHandler to receive notifications. | |
id | The id to track. | |
context | A value that allows for restoring context. |
Definition at line 880 of file clientbase.cpp.
void removeIDHandler | ( | IqHandler * | ih | ) |
Removes the given IqHandler from the list of handlers of pending operations, added using trackID(). Necessary, for example, when closing a GUI element that has an operation pending.
ih | The IqHandler to remove. |
Definition at line 891 of file clientbase.cpp.
void registerMessageHandler | ( | MessageHandler * | mh | ) |
Registers mh
as object that receives Message stanza notifications.
mh | The object to receive Message stanza notifications. |
Definition at line 936 of file clientbase.cpp.
void removeMessageHandler | ( | MessageHandler * | mh | ) |
Removes the given object from the list of message handlers.
mh | The object to remove from the list. |
Definition at line 942 of file clientbase.cpp.
void registerMessageSession | ( | MessageSession * | session | ) |
Registers the given MessageSession to receive Messages incoming from the session's target JID.
session | The MessageSession to register. |
Definition at line 916 of file clientbase.cpp.
void disposeMessageSession | ( | MessageSession * | session | ) |
Removes the given MessageSession from the list of MessageSessions and deletes it.
session | The MessageSession to be deleted. |
Definition at line 922 of file clientbase.cpp.
void registerPresenceHandler | ( | PresenceHandler * | ph | ) |
Registers ph
as object that receives Presence stanza notifications.
ph | The object to receive Presence stanza notifications. |
Definition at line 841 of file clientbase.cpp.
void registerPresenceHandler | ( | const JID & | jid, | |
PresenceHandler * | ph | |||
) |
Registers a new PresenceHandler for the given JID. Presences received for this particular JID will not be forwarded to the generic PresenceHandler (and therefore the Roster). This functionality is primarily intended for the MUC implementation.
jid | The JID to 'watch'. | |
ph | The PresenceHandler to inform about presence changes from jid . |
Definition at line 853 of file clientbase.cpp.
void registerSubscriptionHandler | ( | SubscriptionHandler * | sh | ) |
Registers sh
as object that receives Subscription stanza notifications.
sh | The object to receive Subscription stanza notifications. |
Definition at line 948 of file clientbase.cpp.
void registerTagHandler | ( | TagHandler * | th, | |
const std::string & | tag, | |||
const std::string & | xmlns | |||
) |
Registers th
as object that receives incoming packts with a given root tag qualified by the given namespace.
th | The object to receive Subscription packet notifications. | |
tag | The element's name. | |
xmlns | The element's namespace. |
Definition at line 960 of file clientbase.cpp.
void registerStatisticsHandler | ( | StatisticsHandler * | sh | ) |
Registers sh
as object that receives up-to-date connection statistics each time a Stanza is received or sent. Alternatively, you can use getStatistics() manually. Only one StatisticsHandler per ClientBase at a time is possible.
sh | The StatisticsHandler to register. |
Definition at line 985 of file clientbase.cpp.
void removeConnectionListener | ( | ConnectionListener * | cl | ) |
Removes the given object from the list of connection listeners.
cl | The object to remove from the list. |
Definition at line 1017 of file clientbase.cpp.
void removeIqHandler | ( | const std::string & | xmlns | ) |
Removes the handler for the given namespace from the list of Iq handlers.
xmlns | The namespace to remove from the list. |
Definition at line 910 of file clientbase.cpp.
void removePresenceHandler | ( | PresenceHandler * | ph | ) |
Removes the given object from the list of presence handlers.
ph | The object to remove from the list. |
Definition at line 847 of file clientbase.cpp.
void removePresenceHandler | ( | const JID & | jid, | |
PresenceHandler * | ph | |||
) |
Removes the given object from the list of presence handlers for the given JID.
jid | The JID to remove the PresenceHandler(s) for. | |
ph | The PresenceHandler to remove from the list. If ph is 0, all handlers for the given JID will be removed. |
Definition at line 864 of file clientbase.cpp.
void removeSubscriptionHandler | ( | SubscriptionHandler * | sh | ) |
Removes the given object from the list of subscription handlers.
sh | The object to remove from the list. |
Definition at line 954 of file clientbase.cpp.
void removeTagHandler | ( | TagHandler * | th, | |
const std::string & | tag, | |||
const std::string & | xmlns | |||
) |
Removes the given object from the list of tag handlers for the given element and namespace.
th | The object to remove from the list. | |
tag | The element to remove the handler for. | |
xmlns | The namespace qualifying the element. |
Definition at line 972 of file clientbase.cpp.
void removeStatisticsHandler | ( | ) |
Removes the current StatisticsHandler.
Definition at line 991 of file clientbase.cpp.
void setCACerts | ( | const StringList & | cacerts | ) | [inline] |
Use this function to set a number of trusted root CA certificates which shall be used to verify a servers certificate.
cacerts | A list of absolute paths to CA root certificate files in PEM format. |
Definition at line 504 of file clientbase.h.
void setClientCert | ( | const std::string & | clientKey, | |
const std::string & | clientCerts | |||
) |
Use this function to set the user's certificate and private key. The certificate will be presented to the server upon request and can be used for SASL EXTERNAL authentication. The user's certificate file should be a bundle of more than one certificate in PEM format. The first one in the file should be the user's certificate, each cert following that one should have signed the previous one.
clientKey | The absolute path to the user's private key in PEM format. | |
clientCerts | A path to a certificate bundle in PEM format. |
Definition at line 400 of file clientbase.cpp.
void registerMessageSessionHandler | ( | MessageSessionHandler * | msh, | |
int | types = 0 | |||
) |
Use this function to register a MessageSessionHandler with the Client. Optionally the MessageSessionHandler can receive only MessageSessions with a given message type. There can be only one handler per message type.
A MessageSession will be created for every incoming message stanza if there is no MessageHandler registered for the originating JID.
msh | The MessageSessionHandler that will receive the newly created MessageSession. | |
types | ORed StanzaSubType's that describe the desired message types the handler shall receive. Only StanzaMessage* types are valid. A value of 0 means any type (default). |
Definition at line 826 of file clientbase.cpp.
LogSink & logInstance | ( | ) |
Returns the LogSink instance for this ClientBase and all related objects.
Definition at line 714 of file clientbase.cpp.
StreamError streamError | ( | ) | const [inline] |
Use this function to retrieve the type of the stream error after it occurs and you received a ConnectionError of type ConnStreamError from the ConnectionListener.
Definition at line 543 of file clientbase.h.
const std::string streamErrorText | ( | const std::string & | lang = "default" |
) | const |
Returns the text of a stream error for the given language if available. If the requested language is not available, the default text (without a xml:lang attribute) will be returned.
lang | The language identifier for the desired language. It must conform to section 2.12 of the XML specification and RFC 3066. If empty, the default body will be returned, if any. |
Definition at line 820 of file clientbase.cpp.
const std::string& streamErrorCData | ( | ) | const [inline] |
In case the defined-condition element of an stream error contains XML character data you can use this function to retrieve it. RFC 3920 only defines one condition (see-other-host)where this is possible.
Definition at line 562 of file clientbase.h.
const Tag* streamErrorAppCondition | ( | ) | const [inline] |
This function can be used to retrieve the application-specific error condition of a stream error.
Definition at line 569 of file clientbase.h.
AuthenticationError authError | ( | ) | const [inline] |
Use this function to retrieve the type of the authentication error after it occurs and you received a ConnectionError of type ConnAuthenticationFailed from the ConnectionListener.
Definition at line 576 of file clientbase.h.
StatisticsStruct getStatistics | ( | ) |
Returns a StatisticsStruct containing byte and stanza counts for the current active connection.
Definition at line 647 of file clientbase.cpp.
void registerMUCInvitationHandler | ( | MUCInvitationHandler * | mih | ) |
Registers a MUCInvitationHandler with the ClientBase.
mih | The MUCInvitationHandler to register. |
Definition at line 996 of file clientbase.cpp.
void removeMUCInvitationHandler | ( | ) |
Removes the currently registered MUCInvitationHandler.
Definition at line 1005 of file clientbase.cpp.
void handleTag | ( | Tag * | tag | ) | [virtual] |
This function is called when a registered XML element arrives. As with every handler in gloox, the Tag is going to be deleted after this function returned. If you need a copy afterwards, create it using Tag::clone().
tag | The complete Tag. |
Implements TagHandler.
Definition at line 184 of file clientbase.cpp.
void handleCompressedData | ( | const std::string & | data | ) | [virtual] |
This function is called when compression is finished.
data | The compressed data. |
Implements CompressionDataHandler.
Definition at line 251 of file clientbase.cpp.
void handleDecompressedData | ( | const std::string & | data | ) | [virtual] |
This function is called when decompression is finished.
data | The decompressed data. |
Implements CompressionDataHandler.
Definition at line 261 of file clientbase.cpp.
void handleReceivedData | ( | const ConnectionBase * | connection, | |
const std::string & | data | |||
) | [virtual] |
This function is called for received from the underlying transport.
connection | The connection that received the data. | |
data | The data received. |
Implements ConnectionDataHandler.
Definition at line 309 of file clientbase.cpp.
void handleConnect | ( | const ConnectionBase * | connection | ) | [virtual] |
This function is called when e.g. the raw TCP connection was established.
connection | The connection. |
Implements ConnectionDataHandler.
Definition at line 321 of file clientbase.cpp.
void handleDisconnect | ( | const ConnectionBase * | connection, | |
ConnectionError | reason | |||
) | [virtual] |
This connection is called when e.g. the raw TCP connection was closed.
connection | The connection. | |
reason | The reason for the disconnect. |
Implements ConnectionDataHandler.
Definition at line 330 of file clientbase.cpp.
void handleEncryptedData | ( | const TLSBase * | base, | |
const std::string & | data | |||
) | [virtual] |
Reimplement this function to receive encrypted data from a TLSBase implementation.
base | The encryption implementation which called this function. | |
data | The encrypted data (e.g. to send over the wire). |
Implements TLSHandler.
Definition at line 269 of file clientbase.cpp.
void handleDecryptedData | ( | const TLSBase * | base, | |
const std::string & | data | |||
) | [virtual] |
Reimplement this function to receive decrypted data from a TLSBase implementation.
base | The encryption implementation which called this function. | |
data | The decrypted data (e.g. to parse). |
Implements TLSHandler.
Definition at line 277 of file clientbase.cpp.
Reimplement this function to receive the result of a TLS handshake.
base | The encryption implementation which called this function. | |
success | Whether or not the handshake was successful. | |
certinfo | Information about the server's certificate. |
Implements TLSHandler.
Definition at line 287 of file clientbase.cpp.