1 | /* |
2 | This file is part of libkabc. |
3 | Copyright (c) 2008 Tobias Koenig <tokoe@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_CONTACTGROUP_H |
22 | #define KABC_CONTACTGROUP_H |
23 | |
24 | #include <QtCore/QList> |
25 | #include <QtCore/QSharedDataPointer> |
26 | #include <QtCore/QMetaType> |
27 | |
28 | #include "kabc_export.h" |
29 | |
30 | class QString; |
31 | |
32 | namespace KABC { |
33 | |
34 | /** |
35 | * @short This class represents a group of contacts. |
36 | * |
37 | * It can contain two types of contacts, either a reference |
38 | * or data. |
39 | * The reference entry is just an unique identifier which |
40 | * identifies the real contact in the system. |
41 | * The data entry contains a name and an email address. |
42 | * |
43 | * @author Tobias Koenig <tokoe@kde.org> |
44 | * @since 4.3 |
45 | */ |
46 | class KABC_EXPORT ContactGroup |
47 | { |
48 | public: |
49 | |
50 | /** |
51 | * This class represents a contact reference |
52 | */ |
53 | class KABC_EXPORT ContactReference |
54 | { |
55 | public: |
56 | /** |
57 | * A list of contact references. |
58 | */ |
59 | typedef QList<ContactReference> List; |
60 | |
61 | /** |
62 | * Creates an empty contact reference. |
63 | */ |
64 | ContactReference(); |
65 | |
66 | /** |
67 | * Creates a contact reference from an @p other reference. |
68 | */ |
69 | ContactReference( const ContactReference &other ); |
70 | |
71 | /** |
72 | * Creates a contact reference for the given contact @p uid. |
73 | */ |
74 | ContactReference( const QString &uid ); |
75 | |
76 | /** |
77 | * Destroys the contact reference. |
78 | */ |
79 | ~ContactReference(); |
80 | |
81 | /** |
82 | * Sets the contact uid of the contact reference. |
83 | * @param uid identifier of the contact to reference |
84 | * @note That is the Akonadi Item ID of the contact that |
85 | * is referenced here. |
86 | */ |
87 | void setUid( const QString &uid ); |
88 | |
89 | /** |
90 | * Returns the contact uid of the contact reference. |
91 | * |
92 | * @note That is the Akonadi Item ID of the contact that |
93 | * is referenced here. |
94 | */ |
95 | QString uid() const; |
96 | |
97 | /** |
98 | * Sets the contact gid of the contact reference. |
99 | * @param gid globally unique identifier of the contact to reference |
100 | * @since 4.12 |
101 | */ |
102 | void setGid( const QString &gid ); |
103 | |
104 | /** |
105 | * Returns the contact GID of the contact reference. |
106 | * @since 4.12 |
107 | */ |
108 | QString gid() const; |
109 | |
110 | /** |
111 | * Sets the preferred email address. |
112 | */ |
113 | void setPreferredEmail( const QString &email ); |
114 | |
115 | /** |
116 | * Returns the preferred email address, or an empty string |
117 | * if no preferred email address is set. |
118 | */ |
119 | QString preferredEmail() const; |
120 | |
121 | /** |
122 | * Inserts a custom entry. |
123 | * If an entry with the same @p key already exists, it is |
124 | * overwritten. |
125 | * |
126 | * @param key The unique key. |
127 | * @param value The value. |
128 | */ |
129 | void insertCustom( const QString &key, const QString &value ); |
130 | |
131 | /** |
132 | * Removes the custom entry with the given @p key. |
133 | */ |
134 | void removeCustom( const QString &key ); |
135 | |
136 | /** |
137 | * Returns the value for the given @p key, or an empty string |
138 | * if the entry for that key does not exists. |
139 | */ |
140 | QString custom( const QString &key ) const; |
141 | |
142 | /** |
143 | * @internal |
144 | */ |
145 | ContactReference &operator=( const ContactReference & ); |
146 | |
147 | /** |
148 | * @internal |
149 | */ |
150 | bool operator==( const ContactReference & ) const; |
151 | |
152 | private: |
153 | class ContactReferencePrivate; |
154 | QSharedDataPointer<ContactReferencePrivate> d; |
155 | }; |
156 | |
157 | /** |
158 | * This class represents a contact group reference |
159 | */ |
160 | class KABC_EXPORT ContactGroupReference |
161 | { |
162 | public: |
163 | /** |
164 | * A list of contact group references. |
165 | */ |
166 | typedef QList<ContactGroupReference> List; |
167 | |
168 | /** |
169 | * Creates an empty contact group reference. |
170 | */ |
171 | ContactGroupReference(); |
172 | |
173 | /** |
174 | * Creates a contact group reference from an @p other reference. |
175 | */ |
176 | ContactGroupReference( const ContactGroupReference &other ); |
177 | |
178 | /** |
179 | * Creates a contact group reference for the given contact group @p uid. |
180 | */ |
181 | ContactGroupReference( const QString &uid ); |
182 | |
183 | /** |
184 | * Destroys the contact group reference. |
185 | */ |
186 | ~ContactGroupReference(); |
187 | |
188 | /** |
189 | * Sets the contact group uid of the contact group reference. |
190 | */ |
191 | void setUid( const QString &uid ); |
192 | |
193 | /** |
194 | * Returns the contact group uid of the contact group reference. |
195 | */ |
196 | QString uid() const; |
197 | |
198 | /** |
199 | * Inserts a custom entry. |
200 | * If an entry with the same @p key already exists, it is |
201 | * overwritten. |
202 | * |
203 | * @param key The unique key. |
204 | * @param value The value. |
205 | */ |
206 | void insertCustom( const QString &key, const QString &value ); |
207 | |
208 | /** |
209 | * Removes the custom entry with the given @p key. |
210 | */ |
211 | void removeCustom( const QString &key ); |
212 | |
213 | /** |
214 | * Returns the value for the given @p key, or an empty string |
215 | * if the entry for that key does not exists. |
216 | */ |
217 | QString custom( const QString &key ) const; |
218 | |
219 | /** |
220 | * @internal |
221 | */ |
222 | ContactGroupReference &operator=( const ContactGroupReference & ); |
223 | |
224 | /** |
225 | * @internal |
226 | */ |
227 | bool operator==( const ContactGroupReference & ) const; |
228 | |
229 | private: |
230 | class ContactGroupReferencePrivate; |
231 | QSharedDataPointer<ContactGroupReferencePrivate> d; |
232 | }; |
233 | |
234 | /** |
235 | * This class represents a contact data object |
236 | */ |
237 | class KABC_EXPORT Data |
238 | { |
239 | public: |
240 | /** |
241 | * A list of contact data. |
242 | */ |
243 | typedef QList<Data> List; |
244 | |
245 | /** |
246 | * Creates an empty contact data object. |
247 | */ |
248 | Data(); |
249 | |
250 | /** |
251 | * Creates a contact data object from an @p other data object. |
252 | */ |
253 | Data( const Data &other ); |
254 | |
255 | /** |
256 | * Creates a contact data object with the given @p name and @p email address. |
257 | */ |
258 | Data( const QString &name, const QString &email ); |
259 | |
260 | /** |
261 | * Destroys the contact data object. |
262 | */ |
263 | ~Data(); |
264 | |
265 | /** |
266 | * Sets the @p name of the contact data object. |
267 | */ |
268 | void setName( const QString &name ); |
269 | |
270 | /** |
271 | * Returns the name of the contact data object. |
272 | */ |
273 | QString name() const; |
274 | |
275 | /** |
276 | * Sets the @p email address of the contact data object. |
277 | */ |
278 | void setEmail( const QString &email ); |
279 | |
280 | /** |
281 | * Returns the email address of the contact data object. |
282 | */ |
283 | QString email() const; |
284 | |
285 | /** |
286 | * Inserts a custom entry. |
287 | * If an entry with the same @p key already exists, it is |
288 | * overwritten. |
289 | * |
290 | * @param key The unique key. |
291 | * @param value The value. |
292 | */ |
293 | void insertCustom( const QString &key, const QString &value ); |
294 | |
295 | /** |
296 | * Removes the custom entry with the given @p key. |
297 | */ |
298 | void removeCustom( const QString &key ); |
299 | |
300 | /** |
301 | * Returns the value for the given @p key, or an empty string |
302 | * if the entry for that key does not exists. |
303 | */ |
304 | QString custom( const QString &key ) const; |
305 | |
306 | /** |
307 | * @internal |
308 | */ |
309 | Data &operator=( const Data & ); |
310 | |
311 | /** |
312 | * @internal |
313 | */ |
314 | bool operator==( const Data & ) const; |
315 | |
316 | private: |
317 | class DataPrivate; |
318 | QSharedDataPointer<DataPrivate> d; |
319 | }; |
320 | |
321 | /** |
322 | * A list of contact groups. |
323 | */ |
324 | typedef QList<ContactGroup> List; |
325 | |
326 | /** |
327 | * Creates an empty contact group. |
328 | */ |
329 | ContactGroup(); |
330 | |
331 | /** |
332 | * Creates a contact group from an @p other group. |
333 | */ |
334 | ContactGroup( const ContactGroup &other ); |
335 | |
336 | /** |
337 | * Creates a contact group with the given name. |
338 | */ |
339 | ContactGroup( const QString &name ); |
340 | |
341 | /** |
342 | * Destroys the contact group. |
343 | */ |
344 | ~ContactGroup(); |
345 | |
346 | /** |
347 | * Sets the unique @p id of the contact group. |
348 | */ |
349 | void setId( const QString &id ); |
350 | |
351 | /** |
352 | * Returns the unique id of the contact group. |
353 | */ |
354 | QString id() const; |
355 | |
356 | /** |
357 | * Sets the i18n'd @p name of the contact group. |
358 | */ |
359 | void setName( const QString &name ); |
360 | |
361 | /** |
362 | * Returns the i18n'd name of the contact group. |
363 | */ |
364 | QString name() const; |
365 | |
366 | /** |
367 | * Returns the number of contacts in this group. |
368 | * That includes the contact references and contact data. |
369 | */ |
370 | unsigned int count() const; |
371 | |
372 | /** |
373 | * Returns the number of contact references in this group. |
374 | */ |
375 | unsigned int contactReferenceCount() const; |
376 | |
377 | /** |
378 | * Returns the number of group references in this group. |
379 | */ |
380 | unsigned int contactGroupReferenceCount() const; |
381 | |
382 | /** |
383 | * Returns the number of contact data objects in this group. |
384 | */ |
385 | unsigned int dataCount() const; |
386 | |
387 | /** |
388 | * Returns the contact reference at the given @p index. |
389 | */ |
390 | ContactReference &contactReference( unsigned int index ); |
391 | |
392 | /** |
393 | * Returns the contact reference at the given @p index. |
394 | */ |
395 | const ContactReference &contactReference( unsigned int index ) const; |
396 | |
397 | /** |
398 | * Returns the contact group reference at the given @p index. |
399 | */ |
400 | ContactGroupReference &contactGroupReference( unsigned int index ); |
401 | |
402 | /** |
403 | * Returns the contact group reference at the given @p index. |
404 | */ |
405 | const ContactGroupReference &contactGroupReference( unsigned int index ) const; |
406 | |
407 | /** |
408 | * Returns the contact data object at the given @p index. |
409 | */ |
410 | Data &data( unsigned int index ); |
411 | |
412 | /** |
413 | * Returns the contact data object at the given @p index. |
414 | */ |
415 | const Data &data( unsigned int index ) const; |
416 | |
417 | /** |
418 | * Appends a new contact @p reference to the contact group. |
419 | */ |
420 | void append( const ContactReference &reference ); |
421 | |
422 | /** |
423 | * Appends a new contact group @p reference to the contact group. |
424 | */ |
425 | void append( const ContactGroupReference &reference ); |
426 | |
427 | /** |
428 | * Appends a new contact @p data object to the contact group. |
429 | */ |
430 | void append( const Data &data ); |
431 | |
432 | /** |
433 | * Removes the given contact @p reference from the contact group. |
434 | */ |
435 | void remove( const ContactReference &reference ); |
436 | |
437 | /** |
438 | * Removes the given contact group @p reference from the contact group. |
439 | */ |
440 | void remove( const ContactGroupReference &reference ); |
441 | |
442 | /** |
443 | * Removes the given contact @p data object from the contact group. |
444 | */ |
445 | void remove( const Data &data ); |
446 | |
447 | /** |
448 | * Removes all contact references from the contact group. |
449 | */ |
450 | void removeAllContactReferences(); |
451 | |
452 | /** |
453 | * Removes all contact group references from the contact group. |
454 | */ |
455 | void removeAllContactGroupReferences(); |
456 | |
457 | /** |
458 | * Removes all contact data from the contact group. |
459 | */ |
460 | void removeAllContactData(); |
461 | |
462 | /** |
463 | * @internal |
464 | */ |
465 | ContactGroup &operator=( const ContactGroup & ); |
466 | |
467 | /** |
468 | * @internal |
469 | */ |
470 | bool operator==( const ContactGroup & ) const; |
471 | |
472 | /** |
473 | * Returns the MIME type used for Contact Groups |
474 | */ |
475 | static QString mimeType(); |
476 | |
477 | private: |
478 | class Private; |
479 | QSharedDataPointer<Private> d; |
480 | }; |
481 | |
482 | } |
483 | |
484 | #define KABC_CONTACTGROUP_METATYPE_DEFINED |
485 | Q_DECLARE_METATYPE( KABC::ContactGroup ) |
486 | |
487 | #endif |
488 | |