1/*
2 kopeteprotocol.h - Kopete Protocol
3
4 Copyright (c) 2002 by Duncan Mac-Vicar Prett <duncan@kde.org>
5 Copyright (c) 2002-2003 by Martijn Klingens <klingens@kde.org>
6 Copyright (c) 2002-2005 by Olivier Goffart <ogoffart@kde.org>
7 Copyright (c) 2007 by Michaël Larouche <larouche@kde.org>
8
9 Kopete (c) 2002-2004 by the Kopete developers <kopete-devel@kde.org>
10
11 *************************************************************************
12 * *
13 * This library is free software; you can redistribute it and/or *
14 * modify it under the terms of the GNU Lesser General Public *
15 * License as published by the Free Software Foundation; either *
16 * version 2 of the License, or (at your option) any later version. *
17 * *
18 *************************************************************************
19*/
20
21#ifndef KOPETEPROTOCOL_H
22#define KOPETEPROTOCOL_H
23
24#include <QtCore/QFlags>
25
26#include "kopeteplugin.h"
27#include "kopeteonlinestatus.h"
28
29class KopeteEditAccountWidget;
30class AddContactPage;
31class KJob;
32
33#include "kopete_export.h"
34
35namespace Kopete
36{
37
38class Contact;
39class MetaContact;
40class Account;
41
42/*namespace UI
43{
44 class EditAccountWidget;
45 class AddContactPage;
46}*/
47
48
49/**
50 * @brief base class of every protocol.
51 *
52 * A protocol is just a particular case of Plugin
53 *
54 * Protocol is an abstract class, you need to reimplement createNewAccount,
55 * createAddContactPage, createEditAccountWidget
56 *
57 *
58 * @author Duncan Mac-Vicar Prett <duncan@kde.org>
59 * @author Martijn Klingens <klingens@kde.org>
60 * @author Olivier Goffart <ogoffart\@kde.org>
61 */
62class KOPETE_EXPORT Protocol : public Plugin
63{
64 Q_OBJECT
65
66public:
67
68 /**
69 * @todo Ideally, the destructor should be protected. but we need it public to allow QPtrList<Protocol>
70 */
71 virtual ~Protocol();
72
73 /**
74 * @brief Create an empty Account
75 *
76 * This method is called during the loading of the config file.
77 * @param accountId - the account ID to create the account with. This is usually
78 * the login name of the account
79 *
80 * you don't need to register the account to the AccountManager in this function.
81 * But if you want to use this function don't forget to call @ref AccountManager::registerAccount
82 *
83 * @return The new @ref Account object created by this function
84 */
85 virtual Account *createNewAccount( const QString &accountId ) = 0;
86
87 /**
88 * @brief Create a new AddContactPage widget to be shown in the Add Contact Wizard.
89 *
90 * @return A new AddContactPage to be shown in the Add Contact Wizard
91 */
92 virtual AddContactPage *createAddContactWidget( QWidget *parent, Account *account ) = 0;
93
94 /**
95 * @brief Create a new KopeteEditAccountWidget
96 *
97 * @return A new KopeteEditAccountWidget to be shown in the account part of the configurations.
98 *
99 * @param account is the KopeteAccount to edit. If it's 0L, then we create a new account
100 * @param parent The parent of the 'to be returned' widget
101 */
102 virtual KopeteEditAccountWidget * createEditAccountWidget( Account *account, QWidget *parent ) = 0;
103
104 /**
105 * @brief Available capabilities
106 *
107 * @ref capabilities() returns an ORed list of these, which
108 * the edit widget interperts to determine what buttons to show
109 */
110 enum Capability
111 {
112 BaseFgColor = 0x1, ///< Setting the bg color of the whole edit widget / message
113 BaseBgColor = 0x2, ///< Setting the fg color of the whole edit widget / message
114 RichFgColor = 0x4, ///< Setting the fg/bg color of text portions individually
115 RichBgColor = 0x8, ///< Setting the fg/bg color of text portions individually
116
117 BaseFont = 0x10, ///< Setting the font of the whole edit widget / message
118 RichFont = 0x20, ///< Setting the font of text portions individually
119
120 /// Setting the formatting of the whole edit widget / message
121 BaseUFormatting = 0x40,
122 BaseIFormatting = 0x80,
123 BaseBFormatting = 0x100,
124
125 /// Setting the formatting of text portions individually
126 RichUFormatting = 0x200,
127 RichIFormatting = 0x400,
128 RichBFormatting = 0x800,
129
130 Alignment = 0x1000, ///< Setting the alignment of text portions
131
132 /// Setting the formatting of the whole edit widget / message
133 BaseFormatting = BaseIFormatting | BaseUFormatting | BaseBFormatting,
134
135 /// Setting the formatting of text portions individually
136 RichFormatting = RichIFormatting | RichUFormatting | RichBFormatting,
137
138 RichColor = RichBgColor | RichFgColor,
139 BaseColor = BaseBgColor | BaseFgColor,
140
141 //Shortcut for All of the above - full HTML
142 FullRTF = RichFormatting | Alignment | RichFont | RichFgColor | RichBgColor ,
143
144
145 CanSendOffline = 0x10000 ///< If it's possible to send offline messages
146 };
147 Q_DECLARE_FLAGS(Capabilities, Capability)
148
149 /**
150 * @brief a bitmask of the capabilities of this protocol
151 * @sa @ref setCapabilities
152 */
153 Capabilities capabilities() const;
154
155 /**
156 * @brief true if account can add own contact into a contact list
157 */
158 bool canAddMyself() const;
159
160 /**
161 * @brief Returns the status used for contacts when accounts of this protocol are offline
162 */
163 Kopete::OnlineStatus accountOfflineStatus() const;
164
165
166protected:
167 /**
168 * @brief Constructor for Protocol
169 *
170 * @param instance The protocol's instance, every plugin needs to have a KComponentData of its own
171 * @param parent The protocol's parent object
172 * @param name The protocol's name
173 */
174 Protocol( const KComponentData &instance, QObject *parent, bool canAddMyself = false );
175
176 /**
177 * @brief Sets the capabilities of this protcol.
178 *
179 * The subclass contructor is a good place for calling it.
180 * @sa @ref capabilities()
181 */
182 void setCapabilities( Capabilities );
183
184public:
185
186 /**
187 * Reimplemented from Kopete::Plugin.
188 *
189 * This method disconnects all accounts and deletes them, after which it
190 * will emit readyForUnload.
191 *
192 * Note that this is an asynchronous operation that may take some time
193 * with active chats. It's no longer immediate as it used to be in
194 * Kopete 0.7.x and before. This also means that you can do a clean
195 * shutdown.
196 * @note The method is not private to allow subclasses to reimplement
197 * it even more, but if you need to do this please explain why
198 * on the list first. It might make more sense to add another
199 * virtual for protocols that's called instead, but for now I
200 * actually think protocols don't need their own implementation
201 * at all, so I left out the necessary hooks on purpose.
202 * - Martijn
203 */
204 virtual void aboutToUnload();
205
206private slots:
207 /**
208 * @internal
209 * The account changed online status. Used while unloading the protocol.
210 */
211 void slotAccountOnlineStatusChanged( Kopete::Contact *self );
212
213 /**
214 * @internal
215 * The account is destroyed. When it's the last account we emit the
216 * readyForUnload signal. Used while unloading the protocol.
217 */
218 void slotAccountDestroyed( );
219
220
221public:
222
223 /**
224 * @brief Deserialize the plugin data for a meta contact.
225 *
226 * This method splits up the data into the independent Kopete::Contact objects
227 * and calls @ref deserializeContact() for each contact.
228 *
229 * Note that you can still reimplement this method if you prefer, but you are
230 * strongly recommended to use this version of the method instead, unless you
231 * want to do _VERY_ special things with the data...
232 *
233 * @todo we probably should think to another way to save the contacltist.
234 */
235 virtual void deserialize( MetaContact *metaContact, const QMap<QString, QString> &serializedData );
236
237 /**
238 * @brief Deserialize the plugin data for a meta contact's contacts.
239 */
240 virtual void deserializeContactList( MetaContact *metaContact, const QList< QMap<QString, QString> > &dataList );
241
242 /**
243 * @brief Deserialize a single contact.
244 *
245 * This method is called by @ref deserialize() for each separate contact,
246 * so you don't need to add your own hooks for multiple contacts in a single
247 * meta contact yourself. @p serializedData and @p addressBookData will be
248 * the data the contact provided in Kopete::Contact::serialize.
249 *
250 * The default implementation does nothing.
251 *
252 * @return The contact created from the data
253 * @sa Contact::serialize
254 *
255 * @todo we probably should think to another way to save the contacltist.
256 */
257 virtual Contact *deserializeContact( MetaContact *metaContact,
258 const QMap<QString, QString> &serializedData,
259 const QMap<QString, QString> &addressBookData );
260
261 /**
262 * @brief Factory method to create a protocol Task
263 *
264 * Protocols Task are tasks needed for executing specific
265 * commands for the given protocol. This method creates the
266 * required task for the given task type.
267 *
268 * If a task type is not available in the protocol, just return
269 * a null pointer, like the default implementation.
270 *
271 * Example of a implementation of createProtocolTask()
272 * @code
273KJob* JabberProtocol::createProtocolTask(const QString &taskType)
274{
275 if( taskType == QLatin1String("DeleteContactTask") )
276 {
277 return new JabberDeleteContactTask();
278 }
279 if( taskType == QLatin1String("AddContactTask") )
280 {
281 return new JabberAddContactTask();
282 }
283
284 return 0;
285}
286 * @endcode
287 *
288 * @param taskType a task type as a string. Check each task for name.
289 */
290 virtual KJob *createProtocolTask(const QString &taskType);
291
292 /**
293 * Check whether a password is valid for this protocol. The default implementation
294 * validates every password
295 * @param password The password to check
296 */
297 virtual bool validatePassword( const QString & password ) const;
298
299public:
300 /**
301 * Serialize meta contact into the metacontact's plugin data
302 * Call serialize() for all contained contacts for this protocol.
303 * @internal
304 * it's public because for example, Contact::setMetaContact uses it.
305 * @todo we probably should think to another way to save the contacltist.
306 */
307 void serialize( Kopete::MetaContact *metaContact );
308
309
310private:
311 class Private;
312 Private * const d;
313};
314
315Q_DECLARE_OPERATORS_FOR_FLAGS(Protocol::Capabilities)
316
317} //END namespace kopete
318
319#endif
320
321