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

source code of kcontacts/src/contactgroup.h