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

source code of kcontacts/src/contactgroup.h