1/*
2 This file is part of libkabc.
3 Copyright (c) 2001 Cornelius Schumacher <schumacher@kde.org>
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Library General Public
7 License as published by the Free Software Foundation; either
8 version 2 of the License, or (at your option) any later version.
9
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Library General Public License for more details.
14
15 You should have received a copy of the GNU Library General Public License
16 along with this library; see the file COPYING.LIB. If not, write to
17 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
19*/
20
21#ifndef KABC_RESOURCE_H
22#define KABC_RESOURCE_H
23
24#include "addressbook.h"
25#include "distributionlist.h"
26#include "plugin.h"
27#include "kresources/resource.h"
28
29namespace KABC {
30
31/**
32 * @short Helper class for handling coordinated save of address books.
33 *
34 * This class is used as helper class for saving address book.
35 * @see requestSaveTicket(), save().
36 */
37class KABC_DEPRECATED_EXPORT Ticket
38{
39 friend class Resource;
40
41 public:
42 /**
43 Destroys the Ticket instance.
44 */
45 ~Ticket();
46
47 /**
48 Returns the resource for which this ticket has been created.
49
50 @see Resource::createTicket()
51 */
52 Resource *resource();
53
54 private:
55 Ticket( Resource *resource );
56
57 class Private;
58 Private *const d;
59};
60
61/**
62 * @internal
63 */
64class KABC_DEPRECATED_EXPORT Resource : public KRES::Resource
65{
66 Q_OBJECT
67
68 public:
69
70 /**
71 @short Resource Iterator
72
73 This class provides an iterator for resource entries.
74 */
75 class ConstIterator;
76 class KABC_DEPRECATED_EXPORT Iterator
77 {
78 friend class KABC::Resource::ConstIterator;
79 friend class KABC::Resource;
80 public:
81 /**
82 * Default constructor
83 */
84 Iterator();
85 /**
86 * Copy constructor
87 */
88 Iterator( const Iterator & );
89 virtual ~Iterator();
90
91 /**
92 * Assignment operator. Assignes the given iterator to
93 * @c *this.
94 *
95 * @return this iterator, @c *this
96 */
97 virtual Iterator &operator=( const Iterator & );
98 /**
99 * Constant Dereference operator.
100 * @note For invalid iterators, the result is undefined.
101 *
102 * @return the @c const Addressee object the iterator points to.
103 */
104 virtual const Addressee &operator*() const;
105 /**
106 * Dereference operator.
107 * @note For invalid iterators, the result is undefined.
108 *
109 * @return the Addressee object the iterator points to.
110 */
111 virtual Addressee &operator*();
112 /**
113 * Preincrement operator. Advances the iterator by one.
114 *
115 * @return this iterator, @c *this
116 */
117 virtual Iterator &operator++();
118 /**
119 * Postincrement operator. Advances the iterator by one.
120 * @note This function does not copy the iterator object.
121 *
122 * @return this iterator, @c *this
123 */
124 virtual Iterator &operator++( int );
125 /**
126 * Predecrement operator. Decreases the iterator by one.
127 *
128 * @return this iterator, @c *this
129 */
130 virtual Iterator &operator--();
131 /**
132 * Postdecrement operator. Decreases the iterator by one.
133 * @note This function does not copy the iterator object.
134 *
135 * @return this iterator, @c *this
136 */
137 virtual Iterator &operator--( int );
138 /**
139 * Equality operator. Compares this iterator to @p it
140 *
141 * @param it the iterator to compare this iterator to
142 * @return @c true if both iterators are equal,
143 * @c false otherwise
144 */
145 virtual bool operator==( const Iterator &it ) const;
146 /**
147 * Inequality operator. Compares this iterator to @p it
148 *
149 * @param it the iterator to compare this iterator to
150 * @return @c true if the iterators are not equal,
151 * @c false otherwise
152 */
153 virtual bool operator!=( const Iterator &it ) const;
154
155 private:
156 class Private;
157 Private *const d;
158 };
159
160 /**
161 @short Resource Const Iterator
162
163 This class provides a const iterator for resource entries.
164 */
165 class KABC_DEPRECATED_EXPORT ConstIterator
166 {
167 friend class KABC::Resource;
168
169 public:
170 /**
171 * Default constructor
172 */
173 ConstIterator();
174 /**
175 * Copy constructor
176 */
177 ConstIterator( const ConstIterator & );
178#ifndef QT_STRICT_ITERATORS
179 /**
180 * Copy constructor. Constructs a ConstIterator from
181 * an non-@c const Iterator
182 */
183 ConstIterator( const Iterator & );
184#endif
185 virtual ~ConstIterator();
186
187 /**
188 * Assignment operator. Assignes the given iterator to
189 * @c *this.
190 *
191 * @return this iterator, @c *this
192 */
193 virtual ConstIterator &operator=( const ConstIterator & );
194 /**
195 * Constant Dereference operator.
196 * @note For invalid iterators, the result is undefined.
197 * @note Unlike in Iterator, there is no non-constant
198 * dereference operator.
199 *
200 * @return the @c const Addressee object the iterator points to.
201 */
202 virtual const Addressee &operator*() const;
203 /**
204 * Preincrement operator. Advances the iterator by one.
205 *
206 * @return this iterator, @c *this
207 */
208 virtual ConstIterator &operator++();
209 /**
210 * Postincrement operator. Advances the iterator by one.
211 * @note This function does not copy the iterator object.
212 *
213 * @return this iterator, @c *this
214 */
215 virtual ConstIterator &operator++( int );
216 /**
217 * Predecrement operator. Decreases the iterator by one.
218 *
219 * @return this iterator, @c *this
220 */
221 virtual ConstIterator &operator--();
222 /**
223 * Postdecrement operator. Decreases the iterator by one.
224 * @note This function does not copy the iterator object.
225 *
226 * @return this iterator, @c *this
227 */
228 virtual ConstIterator &operator--( int );
229 /**
230 * Equality operator. Compares this iterator to @p it
231 *
232 * @param it the iterator to compare this iterator to
233 * @return @c true if both iterators are equal,
234 * @c false otherwise
235 */
236 virtual bool operator==( const ConstIterator &it ) const;
237 /**
238 * Inequality operator. Compares this iterator to @p it
239 *
240 * @param it the iterator to compare this iterator to
241 * @return @c true if the iterators are not equal,
242 * @c false otherwise
243 */
244 virtual bool operator!=( const ConstIterator &it ) const;
245
246 private:
247 class Private;
248 Private *const d;
249 };
250
251 /**
252 * Typedef for STL style iterator
253 */
254 typedef Iterator iterator;
255
256 /**
257 * Typedef for STL style iterator
258 */
259 typedef ConstIterator const_iterator;
260
261 /**
262 Default constructor.
263 */
264 Resource();
265
266 /**
267 Constructor.
268
269 @param group The configuration group where the derived classes can
270 read out their settings.
271 */
272 Resource( const KConfigGroup &group );
273
274 /**
275 Destructor.
276 */
277 virtual ~Resource();
278
279 /**
280 Returns an iterator pointing to the first addressee in the resource.
281 This iterator equals end() if the resource is empty.
282 */
283 virtual ConstIterator begin() const;
284 ConstIterator constBegin() const { return begin(); }
285
286 /**
287 This is an overloaded member function, provided for convenience. It
288 behaves essentially like the above function.
289 */
290 virtual Iterator begin();
291
292 /**
293 Returns an iterator pointing to the last addressee in the resource.
294 This iterator equals begin() if the resource is empty.
295 */
296 virtual ConstIterator end() const;
297 ConstIterator constEnd() const { return end(); }
298
299 /**
300 This is an overloaded member function, provided for convenience. It
301 behaves essentially like the above function.
302 */
303 virtual Iterator end();
304
305 /**
306 Returns a pointer to the addressbook.
307 */
308 AddressBook *addressBook();
309
310 /**
311 Writes the resource specific config to file.
312
313 @param group The config section to write into
314 */
315 virtual void writeConfig( KConfigGroup &group );
316
317 /**
318 Request a ticket, you have to pass through save() to
319 allow locking. The resource has to create its locks
320 in this function.
321 */
322 virtual Ticket *requestSaveTicket() = 0;
323
324 /**
325 Releases the ticket previousely requested with requestSaveTicket().
326 The resource has to remove its locks in this function.
327 This function is also responsible for deleting the ticket.
328
329 @param ticket the save ticket acquired with requestSaveTicket()
330 */
331 virtual void releaseSaveTicket( Ticket *ticket ) = 0;
332
333 /**
334 Loads all addressees synchronously.
335
336 @returns Whether the loading was successfully.
337 */
338 virtual bool load() = 0;
339
340 /**
341 Loads all addressees asyncronously. You have to make sure that either
342 the loadingFinished() or loadingError() signal is emitted from within
343 this function.
344
345 The default implementation simply calls the synchronous load.
346
347 @return Whether the synchronous part of loading was successfully.
348 */
349 virtual bool asyncLoad();
350
351 /**
352 Insert an addressee into the resource.
353
354 @param addr The addressee to add
355 */
356 virtual void insertAddressee( const Addressee &addr );
357
358 /**
359 Removes an addressee from resource.
360
361 @param addr The addressee to remove
362 */
363 virtual void removeAddressee( const Addressee &addr );
364
365 /**
366 Saves all addressees synchronously.
367
368 @param ticket You have to release the ticket later with
369 releaseSaveTicket() explicitly.
370 @return Whether the saving was successfully.
371 */
372 virtual bool save( Ticket *ticket ) = 0;
373
374 /**
375 Saves all addressees asynchronously. You have to make sure that either
376 the savingFinished() or savingError() signal is emitted from within
377 this function.
378
379 The default implementation simply calls the synchronous save.
380
381 @param ticket You have to release the ticket later with
382 releaseSaveTicket() explicitly.
383 @return Whether the saving was successfully.
384 */
385 virtual bool asyncSave( Ticket *ticket );
386
387 /**
388 Searches an addressee with the specified unique identifier.
389
390 @param uid The unique identifier you are looking for.
391 @return The addressee with the specified unique identifier or an
392 empty addressee.
393 */
394 virtual Addressee findByUid( const QString &uid );
395
396 /**
397 Searches all addressees which match the specified name.
398
399 @param name The name you are looking for.
400 @return A list of all matching addressees.
401 */
402 virtual Addressee::List findByName( const QString &name );
403
404 /**
405 Searches all addressees which match the specified email address.
406
407 @param email The email address you are looking for.
408 @return A list of all matching addressees.
409 */
410 virtual Addressee::List findByEmail( const QString &email );
411
412 /**
413 Searches all addressees which belongs to the specified category.
414
415 @param category The category you are looking for.
416 @return A list of all matching addressees.
417 */
418 virtual Addressee::List findByCategory( const QString &category );
419
420 /**
421 Removes all addressees and distribution lists from the resource.
422 */
423 virtual void clear();
424
425 /**
426 Adds a distribution @p list into this resource.
427
428 @param list The list to insert.
429 */
430 virtual void insertDistributionList( DistributionList *list );
431
432 /**
433 Removes a distribution @p list from this resource.
434
435 @param list The list to remove.
436 */
437 virtual void removeDistributionList( DistributionList *list );
438
439 /**
440 Returns a distribution list for the given @p identifier or @c 0
441
442 @param identifier The ID of the list for look for.
443 */
444 virtual DistributionList *findDistributionListByIdentifier( const QString &identifier );
445
446 /**
447 Returns a distribution list with the given @p name or @c 0
448
449 @param name The localized name of the list for look for.
450 @param caseSensitivity Whether to do string matching case sensitive or
451 case insensitive. Default is @c Qt::CaseSensitive
452 */
453 virtual DistributionList *findDistributionListByName(
454 const QString &name,
455 Qt::CaseSensitivity caseSensitivity = Qt::CaseSensitive );
456
457 /**
458 Returns a list of all distribution lists of this resource.
459 */
460 virtual QList<DistributionList*> allDistributionLists();
461
462 /**
463 Returns a list of names of all distribution lists of this resource.
464
465 Convenience function, equal to iterate over the list returned
466 by allDistributionLists()
467 */
468 virtual QStringList allDistributionListNames() const;
469
470 /**
471 @internal
472
473 Sets the address book of the resource.
474
475 @param addr The address book to use
476 */
477 void setAddressBook( AddressBook *addr );
478
479 Q_SIGNALS:
480 /**
481 This signal is emitted when the resource has finished the loading of all
482 addressees from the backend to the internal cache.
483
484 @param resource The pointer to the resource which emitted this signal.
485 */
486 void loadingFinished( Resource *resource );
487
488 /**
489 This signal is emitted when an error occurred during loading the
490 addressees from the backend to the internal cache.
491
492 @param resource The pointer to the resource which emitted this signal.
493 @param msg A translated error message.
494 */
495 void loadingError( Resource *resource, const QString &msg );
496
497 /**
498 This signal is emitted when the resource has finished the saving of all
499 addressees from the internal cache to the backend.
500
501 @param resource The pointer to the resource which emitted this signal.
502 */
503 void savingFinished( Resource *resource );
504
505 /**
506 This signal is emitted when an error occurred during saving the
507 addressees from the internal cache to the backend.
508
509 @param resource The pointer to the resource which emitted this signal.
510 @param msg A translated error message.
511 */
512 void savingError( Resource *resource, const QString &msg );
513
514 protected:
515 /**
516 Factory method, just creates and returns a new Ticket for the given resource.
517
518 Needed by subclasses since the constructor of Ticket is private and only
519 this base class is a friend, effectively limiting "new Ticket(this)" to
520 resource implementations.
521 */
522 Ticket *createTicket( Resource * );
523
524 /**
525 A mapping from KABC UIDs to the respective addressee.
526 */
527 Addressee::Map mAddrMap;
528
529 /**
530 A mapping from unique identifiers to the respective distribution list.
531 */
532 DistributionListMap mDistListMap;
533
534 private:
535 class Private;
536 Private *const d;
537};
538
539}
540
541#endif
542