2
/***************************************************************************
3
jabberclient.h - Generic Jabber Client Class
5
begin : Sat May 25 2005
6
copyright : (C) 2005 by Till Gerken <till@tantalo.net>
7
(C) 2006 by Michaël Larouche <larouche@kde.org>
9
Copyright 2006 by Tommi Rantala <tommi.rantala@cs.helsinki.fi>
11
Kopete (C) 2001-2006 Kopete developers
12
<kopete-devel@kde.org>.
13
***************************************************************************/
15
/***************************************************************************
17
* This program is free software; you can redistribute it and/or modify *
18
* it under the terms of the GNU General Public License as published by *
19
* the Free Software Foundation; either version 2 of the License, or *
20
* (at your option) any later version. *
22
***************************************************************************/
24
#ifndef JABBERCLIENT_H
25
#define JABBERCLIENT_H
29
// include these because of namespace reasons
36
#include <kopete_export.h>
40
namespace XMPP { class PrivacyManager; }
43
* This class provides an interface to the Iris subsystem. The goal is to
44
* abstract the Iris layer and manage it via a single, simple to use class.
45
* By default, @ref JabberClient will attempt to establish a connection
46
* using XMPP 1.0. This means that apart from the JID and password, no
47
* further details are necessary to connect. The server and port will be
48
* determined using a SRV lookup. If TLS is possible (meaning, the TLS
49
* plugin is available and the server supports TLS) it will automatically
50
* be used. Otherwise, a non-encrypted connection will be established.
51
* If XMPP 1.0 is not possible, the connection will fall back to the old
52
* protocol. By default, this connection is not encrypted. You can, however,
53
* use @ref setUseSSL to immediately attempt an SSL connection. This is
54
* most useful if you want to establish an SSL connection to a non-standard
55
* port, in which case you will also have to use @ref setOverrideHost. In case
56
* XMPP 1.0 does not work, an automatic attempt to connect to the standard port
57
* 5223 with SSL can be made with @ref setProbeSSL. If the attempt is not
58
* sucessful, the connection will fall back to an unencrypted attempt
60
* @brief Provides a Jabber client
63
class JABBER_EXPORT JabberClient : public QObject
70
* Error codes indicating problems during operation.
75
InvalidPassword, /** Password used to connect to the server was incorrect. */
76
AlreadyConnected, /** A new connection was attempted while the previous one hasn't been closed. */
77
NoTLS, /** Use of TLS has been forced (see @ref forceTLS) but TLS is not available, either server- or client-side. */
78
InvalidPasswordForMUC = 401, /** A password is require to enter on this Multi-User Chat */
79
NicknameConflict = 409, /** There is already someone with that nick connected to the Multi-User Chat */
80
BannedFromThisMUC = 403, /** You can't join this Multi-User Chat because you were bannished */
81
MaxUsersReachedForThisMuc = 503 /** You can't join this Multi-User Chat because it is full */
88
* Connect to a Jabber server.
89
* @param jid JID to connect to.
90
* @param password Password to authenticate with.
91
* @param auth True if authentication should be done, false if not.
93
ErrorCode connect ( const XMPP::Jid &jid, const QString &password, bool auth = true );
96
* Disconnect from Jabber server.
101
* Disconnect from Jabber server with reason
102
* @param reason The reason for disconnecting
104
void disconnect (XMPP::Status &reason);
107
* Returns if this instance is connected to a server.
109
bool isConnected () const;
112
* Returns the JID associated with this instance.
114
XMPP::Jid jid () const;
117
* Set flag to ignore TLS warnings. If TLS
118
* warnings are not ignored, the class will emit
119
* @ref tlsWarning and wait for the user to
120
* call @ref continueAfterTLSWarning or
121
* @ref disconnect. Default is false.
123
void setIgnoreTLSWarnings ( bool flag );
125
* Return if TLS warnings are being ignored.
127
bool ignoreTLSWarnings ();
130
* Continue after a @ref tlsWarning signal.
132
void continueAfterTLSWarning ();
135
* Set the port on which the S5B server should listen.
136
* This is only taken into account if @ref setFileTransfersEnabled
138
* @return True if port could be bound, false if not.
140
bool setS5BServerPort ( int port );
142
* Returns the port the S5B server listens on.
144
int s5bServerPort () const;
147
* Force the use of TLS. If TLS connections are forced,
148
* unencrypted connections will not be established.
151
void setForceTLS ( bool flag );
153
* Returns if TLS connections are forced.
155
bool forceTLS () const;
158
* Force direct SSL connection, also for the
159
* handshake. This is only useful if you know
160
* the server supports it or you want to use
161
* a non-standard port, in which case @ref setOverrideHost
162
* will be useful. Default is false.
164
void setUseSSL ( bool flag );
166
* Returns if an SSL connection attempt should be made.
168
bool useSSL () const;
171
* Use only the old protocol (pre-XMPP 1.0). This should only
172
* be used with servers not supporting XMPP 1.0 or with servers
173
* that have a broken login procedure. Default is false. If
174
* a connection attempt is not possible, Iris will automatically
175
* fall back to the old protocol.
177
void setUseXMPP09 ( bool flag );
179
* Returns if the old protocol should be used.
181
bool useXMPP09 () const;
184
* Probe port 5223 if an SSL connection is possible. If
185
* a connection is not possible, an unencrypted connection
186
* will be attempted at port 5222. This is only meaningful
187
* if @ref useXMPP09 is true. Default is false.
189
void setProbeSSL ( bool flag );
191
* Returns if SSL support will be probed.
193
bool probeSSL () const;
196
* Override the name and port of the server to connect to.
197
* This only has an effect if the old protocol (@ref useXMPP09)
198
* has been enabled. Default is false.
200
void setOverrideHost ( bool flag, const QString &server = "", int port = 5222 );
202
* Returns if the server name and port are overridden.
204
bool overrideHost () const;
207
* Allow the transmission of a plain text password. If digested
208
* passwords are supported by the server, they will still be preferred.
211
void setAllowPlainTextPassword ( bool flag );
213
* Returns if plain text passwords are allowed.
215
bool allowPlainTextPassword () const;
218
* Enable file transfers. Default is false.
219
* @param flag Whether to enable file transfers.
220
* @param localAddress Local address to receive file transfers at. Will be determined automatically if not specified.
222
void setFileTransfersEnabled ( bool flag, const QString &localAddress = QString() );
225
* Returns the address of the local interface.
227
QString localAddress () const;
230
* Returns if file transfers are enabled.
232
bool fileTransfersEnabled () const;
237
void setClientName ( const QString &clientName );
239
* Return client name.
241
QString clientName () const;
244
* Set client version.
246
void setClientVersion ( const QString &clientVersion );
248
* Return client version.
250
QString clientVersion () const;
253
* Set operating system name.
255
void setOSName ( const QString &osName );
257
* Return operating system name.
259
QString osName () const;
262
* Set the caps(JEP-0115: Entity capabilities) node name.
263
* @param node Node name.
265
void setCapsNode( const QString &capsNode );
267
* Return the caps node name for this client.
268
* @return the caps node name.
270
QString capsNode() const;
273
* Set the caps(JEP-0115: Entity capabilities) node version.
274
* @param capsVersion the node version.
276
void setCapsVersion( const QString &capsVersion );
278
* Return the caps version for this client.
279
* @return the caps version.
281
QString capsVersion() const;
284
* Return the caps extension list for this client.
285
* @return A string containing all extensions separated by space.
287
QString capsExt() const;
290
* Set the disco Identity information for this client.
291
* Create a Disco identity like this:
293
* DiscoItem::Identity identity;
294
* identity.category = "client";
295
* identity.type = "pc";
296
* identity.name = "Kopete";
299
* @param identity DiscoItem::Identity for the client.
301
void setDiscoIdentity(DiscoItem::Identity identity);
303
* Get the disco Identity information for this client.
304
* @return the DiscoItem::Identity for this client.
306
DiscoItem::Identity discoIdentity() const;
309
* Set timezone information. Default is UTC.
311
void setTimeZone ( const QString &timeZoneName, int timeZoneOffset );
313
* Return timezone name.
315
QString timeZoneName () const;
317
* Return timezone offset.
319
int timeZoneOffset () const;
322
* This method can be used to implement a penalty
323
* system when a lot of queries need to be sent to the
324
* server. Using the time returned by this method,
325
* the caller can determine a delay until the next
326
* operation in the queue can be carried out.
327
* @brief Return current penalty time in seconds.
329
int getPenaltyTime ();
332
* Return the XMPP client instance.
334
XMPP::Client *client () const;
337
* Return client stream instance.
339
XMPP::ClientStream *clientStream () const;
342
* Return client connector instance.
344
XMPP::AdvancedConnector *clientConnector () const;
347
* Get the root task for this connection.
348
* You need this instance for every task
351
XMPP::Task *rootTask () const;
354
* Returns the file transfer manager
355
* instance that deals with current file
358
XMPP::FileTransferManager *fileTransferManager () const;
361
* Returns the privacy lists manager
363
PrivacyManager *privacyManager () const;
367
* @param host Node to join the room at.
368
* @param room Name of room to join.
369
* @param nick Nick name you want to join with.
371
void joinGroupChat ( const QString &host, const QString &room, const QString &nick );
374
* Join a groupchat that require a password.
375
* @param host Node to join the room at.
376
* @param room Name of room to join.
377
* @param nick Nick name you want to join with.
378
* @param password The password to join the room.
380
void joinGroupChat ( const QString &host, const QString &room, const QString &nick, const QString &password );
384
* @param host Node to leave room at.
385
* @param room Name of room to leave.
387
void leaveGroupChat ( const QString &host, const QString &room );
390
* change the status of a groupchat
392
void setGroupChatStatus(const QString &host, const QString &room, const XMPP::Status &);
394
* change the nick in a groupchat
396
void changeGroupChatNick(const QString &host, const QString &room, const QString &nick, const XMPP::Status &status =XMPP::Status());
401
void sendMessage ( const XMPP::Message &message );
404
* Send raw packet to the server.
406
void send ( const QString &packet );
409
* Request the roster from the Jabber server.
411
void requestRoster ();
415
* Connected successfully.
420
* Client stream authenticated. This
421
* signal is emitted when the socket
422
* connection has been successfully
423
* established, before sending the login
426
void csAuthenticated ();
429
* Client stream error.
431
void csError ( int error );
434
* Client stream was disconnected.
436
void csDisconnected ();
439
* TLS problem encountered.
441
void tlsWarning ( QCA::TLS::IdentityResult, QCA::Validity );
444
* A new file transfer needs to be handled.
445
* The file transfer can be dealt with by
446
* querying the file transfer manager from
449
void incomingFileTransfer ();
452
* Fatal error has been encountered,
453
* further operations are not possible.
455
void error ( JabberClient::ErrorCode code );
458
* Roster has been transmitted and processed.
460
void rosterRequestFinished ( bool success );
463
* A new contact appeared on the roster.
465
void newContact ( const XMPP::RosterItem &item );
468
* A contact has been removed from the roster.
470
void contactDeleted ( const XMPP::RosterItem &item );
473
* A roster item has changed.
475
void contactUpdated ( const XMPP::RosterItem &item );
478
* New resource is available for a contact.
480
void resourceAvailable ( const XMPP::Jid &jid, const XMPP::Resource &resource );
483
* An existing resource has been removed.
485
void resourceUnavailable ( const XMPP::Jid &jid, const XMPP::Resource &resource );
488
* A new message has been received.
490
void messageReceived ( const XMPP::Message &message );
493
* Group chat has been joined.
495
void groupChatJoined ( const XMPP::Jid &jid );
498
* Group chat has been left.
500
void groupChatLeft ( const XMPP::Jid &jid );
503
* A presence to a groupchat has been signalled.
505
void groupChatPresence ( const XMPP::Jid &jid, const XMPP::Status &status );
508
* An error was encountered joining or processing a groupchat.
510
void groupChatError ( const XMPP::Jid &jid, int error, const QString &reason );
513
* New subscription request.
515
void subscription ( const XMPP::Jid &jid, const QString &type );
518
* Dispatches a debug message. Debug messages
519
* include incoming and outgoing XML packets
520
* as well as internal status messages.
522
void debugMessage ( const QString &message );
523
void incomingXML (const QString &msg);
524
void outgoingXML (const QString &msg);
531
* Delete all member classes and reset the class to a predefined state.
536
* Return current instance of the S5B server.
538
XMPP::S5BServer *s5bServer ();
540
* Add an address that the S5B server should handle.
542
void addS5BServerAddress ( const QString &address );
544
* Remove an address that the S5B server currently handles.
546
void removeS5BServerAddress ( const QString &address );
549
/* S5B server object has been destroyed. */
550
void slotS5BServerGone ();
552
/* update the penalty timer */
553
void slotUpdatePenaltyTime ();
555
/* Login if the connection was OK. */
556
void slotCSNeedAuthParams (bool user, bool pass, bool realm);
558
/* Called from Psi: tells us when we're logged in OK. */
559
void slotCSAuthenticated ();
561
/* Called from Psi: tells us when we've been disconnected from the server. */
562
void slotCSDisconnected ();
564
/* Called from Psi: alerts us to a protocol warning. */
565
void slotCSWarning (int);
567
/* Called from Psi: alerts us to a protocol error. */
568
void slotCSError (int);
570
/* Called from Psi: tells us when we're connected. */
571
void slotCSConnected ();
573
/* Called from Psi: report certificate status */
574
void slotTLSHandshaken ();
576
/* Called from Psi: roster request finished */
577
void slotRosterRequestFinished ( bool success, int statusCode, const QString &statusString );
579
/* Called from Psi: incoming file transfer */
580
void slotIncomingFileTransfer ();
582
/* A new item appeared in our roster */
583
void slotNewContact (const RosterItem &);
585
/* An item has been deleted from our roster. */
586
void slotContactDeleted (const RosterItem &);
588
/* Update a contact's details. */
589
void slotContactUpdated (const RosterItem &);
591
/* Someone on our contact list had (another) resource come online. */
592
void slotResourceAvailable (const Jid &, const Resource &);
594
/* Someone on our contact list had a resource go offline. */
595
void slotResourceUnavailable (const Jid &, const Resource &);
597
/* Incoming message. */
598
void slotReceivedMessage (const Message &);
600
/* Called from Psi: debug messages from the backend. */
601
void slotPsiDebug (const QString & msg);
602
void slotIncomingXML (const QString &msg);
603
void slotOutgoingXML (const QString &msg);
605
/* Slots for handling groupchats. */
606
void slotGroupChatJoined (const Jid & jid);
607
void slotGroupChatLeft (const Jid & jid);
608
void slotGroupChatPresence (const Jid & jid, const Status & status);
609
void slotGroupChatError (const Jid & jid, int error, const QString & reason);
611
/* Incoming subscription request. */
612
void slotSubscription (const Jid & jid, const QString & type);
614
/* the session task is finished */
615
void slotSessionStarted();
added
removed
protocols/jabber/jabberclient.h
