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
30class QString;
31
32namespace 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 */
46class 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
485Q_DECLARE_METATYPE( KABC::ContactGroup )
486
487#endif
488