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