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 | |
29 | namespace 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 | */ |
37 | class 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 | */ |
64 | class 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 | |