Kgapi

person.h
1/*
2 * SPDX-FileCopyrightText: 2021 Daniel Vrátil <dvratil@kde.org>
3 * SPDX-FileCopyrightText: 2022 Claudio Cambra <claudio.cambra@kde.org>
4 *
5 * SPDX-License-Identifier: LGPL-2.1-only
6 * SPDX-License-Identifier: LGPL-3.0-only
7 * SPDX-License-Identifier: LicenseRef-KDE-Accepted-LGPL
8 */
9
10#pragma once
11
12#include "object.h"
13#include "types.h"
14#include "kgapipeople_export.h"
15
16#include <QList>
17#include <QString>
18
19#include <QSharedPointer>
20
21#include <optional>
22
23class QJsonObject;
24class QJsonValue;
25
26namespace KContacts
27{
28class Addressee;
29}
30
31namespace KGAPI2::People
32{
33class Person;
34using PersonPtr = QSharedPointer<Person>;
35
36class Address;
37class AgeRangeType;
38class Biography;
39class Birthday;
40class BraggingRights;
41class CalendarUrl;
42class ClientData;
43class CoverPhoto;
44class EmailAddress;
45class Event;
46class ExternalId;
47class FileAs;
48class Gender;
49class ImClient;
50class Interest;
51class Location;
52class Membership;
53class MiscKeyword;
54class Name;
55class Nickname;
56class Occupation;
57class Organization;
58class PersonLocale;
59class PersonMetadata;
60class PhoneNumber;
61class Photo;
62class Relation;
63class RelationshipInterest;
64class RelationshipStatus;
65class Residence;
66class SipAddress;
67class Skill;
68class Tagline;
69class Url;
70class UserDefined;
71
72/**
73 * Information about a person merged from various data sources such as the
74 * authenticated user's contacts and profile data. Most fields can have multiple
75 * items. The items in a field have no guaranteed order, but each non-empty field
76 * is guaranteed to have exactly one field with `metadata.primary` set to true.
77 *
78 * @see https://developers.google.com/people/api/rest/v1/people#person
79 * @since 5.23.0
80 **/
81class KGAPIPEOPLE_EXPORT Person : public KGAPI2::Object
82{
83public:
84 enum class AgeRange {
85 AGE_RANGE_UNSPECIFIED, ///< Unspecified.
86 LESS_THAN_EIGHTEEN, ///< Younger than eighteen.
87 EIGHTEEN_TO_TWENTY, ///< Between eighteen and twenty.
88 TWENTY_ONE_OR_OLDER, ///< Twenty-one and older.
89 };
90
91 /** Construcuts a new Person **/
92 explicit Person();
93 /** Destructor. **/
95
96 static PersonPtr fromKContactsAddressee(const KContacts::Addressee &addressee);
97 KContacts::Addressee toKContactsAddressee() const;
98
99 bool operator==(const Person &) const;
100 bool operator!=(const Person &) const;
101
102 /** The person's nicknames. **/
103 [[nodiscard]] QList<Nickname> nicknames() const;
104 /** Sets value of the nicknames property. **/
105 void setNicknames(const QList<Nickname> &value);
106 /** Appends the given @c value to the list of nicknames. **/
107 void addNickname(const Nickname &value);
108 /** Removes the given @c value from the list of nicknames if it exists. **/
109 void removeNickname(const Nickname &value);
110 /** Clears the list of nicknames. **/
111 void clearNicknames();
112
113 /** The person's email addresses. For `people.connections.list` and `otherContacts.list` the number of email addresses is limited to 100. If a Person has
114 * more email addresses the entire set can be obtained by calling GetPeople. **/
115 [[nodiscard]] QList<EmailAddress> emailAddresses() const;
116 /** Sets value of the emailAddresses property. **/
117 void setEmailAddresses(const QList<EmailAddress> &value);
118 /** Appends the given @c value to the list of emailAddresses. **/
119 void addEmailAddress(const EmailAddress &value);
120 /** Removes the given @c value from the list of emailAddresses if it exists. **/
121 void removeEmailAddress(const EmailAddress &value);
122 /** Clears the list of emailAddresses. **/
123 void clearEmailAddresses();
124
125 /** The person's client data. **/
126 [[nodiscard]] QList<ClientData> clientData() const;
127 /** Sets value of the clientData property. **/
128 void setClientData(const QList<ClientData> &value);
129 /** Appends the given @c value to the list of clientData. **/
130 void addClientData(const ClientData &value);
131 /** Removes the given @c value from the list of clientData if it exists. **/
132 void removeClientData(const ClientData &value);
133 /** Clears the list of clientData. **/
134 void clearClientData();
135
136 /** **DEPRECATED**: No data will be returned The person's bragging rights. **/
137 [[nodiscard]] QList<BraggingRights> braggingRights() const;
138 /** Sets value of the braggingRights property. **/
139 void setBraggingRights(const QList<BraggingRights> &value);
140 /** Appends the given @c value to the list of braggingRights. **/
141 void addBraggingRights(const BraggingRights &value);
142 /** Removes the given @c value from the list of braggingRights if it exists. **/
143 void removeBraggingRights(const BraggingRights &value);
144 /** Clears the list of braggingRights. **/
145 void clearBraggingRights();
146
147 /** Output only. **DEPRECATED**: No data will be returned The person's relationship statuses. **/
148 [[nodiscard]] QList<RelationshipStatus> relationshipStatuses() const;
149
150 /** The person's birthdays. This field is a singleton for contact sources. **/
151 [[nodiscard]] QList<Birthday> birthdays() const;
152 /** Sets value of the birthdays property. **/
153 void setBirthdays(const QList<Birthday> &value);
154 /** Appends the given @c value to the list of birthdays. **/
155 void addBirthday(const Birthday &value);
156 /** Removes the given @c value from the list of birthdays if it exists. **/
157 void removeBirthday(const Birthday &value);
158 /** Clears the list of birthdays. **/
159 void clearBirthdays();
160
161 /** The person's relations. **/
162 [[nodiscard]] QList<Relation> relations() const;
163 /** Sets value of the relations property. **/
164 void setRelations(const QList<Relation> &value);
165 /** Appends the given @c value to the list of relations. **/
166 void addRelation(const Relation &value);
167 /** Removes the given @c value from the list of relations if it exists. **/
168 void removeRelation(const Relation &value);
169 /** Clears the list of relations. **/
170 void clearRelations();
171
172 /** The person's locale preferences. **/
173 [[nodiscard]] QList<PersonLocale> locales() const;
174 /** Sets value of the locales property. **/
175 void setLocales(const QList<PersonLocale> &value);
176 /** Appends the given @c value to the list of locales. **/
177 void addPersonLocale(const PersonLocale &value);
178 /** Removes the given @c value from the list of locales if it exists. **/
179 void removePersonLocale(const PersonLocale &value);
180 /** Clears the list of locales. **/
181 void clearLocales();
182
183 /** The person's locations. **/
184 [[nodiscard]] QList<Location> locations() const;
185 /** Sets value of the locations property. **/
186 void setLocations(const QList<Location> &value);
187 /** Appends the given @c value to the list of locations. **/
188 void addLocation(const Location &value);
189 /** Removes the given @c value from the list of locations if it exists. **/
190 void removeLocation(const Location &value);
191 /** Clears the list of locations. **/
192 void clearLocations();
193
194 /** The person's external IDs. **/
195 [[nodiscard]] QList<ExternalId> externalIds() const;
196 /** Sets value of the externalIds property. **/
197 void setExternalIds(const QList<ExternalId> &value);
198 /** Appends the given @c value to the list of externalIds. **/
199 void addExternalId(const ExternalId &value);
200 /** Removes the given @c value from the list of externalIds if it exists. **/
201 void removeExternalId(const ExternalId &value);
202 /** Clears the list of externalIds. **/
203 void clearExternalIds();
204
205 /** Output only. The person's age ranges. **/
206 [[nodiscard]] QList<AgeRangeType> ageRanges() const;
207
208 /** Output only. **DEPRECATED**: No data will be returned The person's taglines. **/
209 [[nodiscard]] QList<Tagline> taglines() const;
210
211 /** The person's user defined data. **/
212 [[nodiscard]] QList<UserDefined> userDefined() const;
213 /** Sets value of the userDefined property. **/
214 void setUserDefined(const QList<UserDefined> &value);
215 /** Appends the given @c value to the list of userDefined. **/
216 void addUserDefined(const UserDefined &value);
217 /** Removes the given @c value from the list of userDefined if it exists. **/
218 void removeUserDefined(const UserDefined &value);
219 /** Clears the list of userDefined. **/
220 void clearUserDefined();
221
222 /** The person's biographies. This field is a singleton for contact sources. **/
223 [[nodiscard]] QList<Biography> biographies() const;
224 /** Sets value of the biographies property. **/
225 void setBiographies(const QList<Biography> &value);
226 /** Appends the given @c value to the list of biographies. **/
227 void addBiography(const Biography &value);
228 /** Removes the given @c value from the list of biographies if it exists. **/
229 void removeBiography(const Biography &value);
230 /** Clears the list of biographies. **/
231 void clearBiographies();
232
233 /** The person's SIP addresses. **/
234 [[nodiscard]] QList<SipAddress> sipAddresses() const;
235 /** Sets value of the sipAddresses property. **/
236 void setSipAddresses(const QList<SipAddress> &value);
237 /** Appends the given @c value to the list of sipAddresses. **/
238 void addSipAddress(const SipAddress &value);
239 /** Removes the given @c value from the list of sipAddresses if it exists. **/
240 void removeSipAddress(const SipAddress &value);
241 /** Clears the list of sipAddresses. **/
242 void clearSipAddresses();
243
244 /** The person's group memberships. **/
245 [[nodiscard]] QList<Membership> memberships() const;
246 /** Sets value of the memberships property. **/
247 void setMemberships(const QList<Membership> &value);
248 /** Appends the given @c value to the list of memberships. **/
249 void addMembership(const Membership &value);
250 /** Removes the given @c value from the list of memberships if it exists. **/
251 void removeMembership(const Membership &value);
252 /** Clears the list of memberships. **/
253 void clearMemberships();
254
255 /** The person's skills. **/
256 [[nodiscard]] QList<Skill> skills() const;
257 /** Sets value of the skills property. **/
258 void setSkills(const QList<Skill> &value);
259 /** Appends the given @c value to the list of skills. **/
260 void addSkill(const Skill &value);
261 /** Removes the given @c value from the list of skills if it exists. **/
262 void removeSkill(const Skill &value);
263 /** Clears the list of skills. **/
264 void clearSkills();
265
266 /** **DEPRECATED**: (Please use `person.locations` instead) The person's residences. **/
267 [[nodiscard]] QList<Residence> residences() const;
268 /** Sets value of the residences property. **/
269 void setResidences(const QList<Residence> &value);
270 /** Appends the given @c value to the list of residences. **/
271 void addResidence(const Residence &value);
272 /** Removes the given @c value from the list of residences if it exists. **/
273 void removeResidence(const Residence &value);
274 /** Clears the list of residences. **/
275 void clearResidences();
276
277 /** The person's names. This field is a singleton for contact sources. **/
278 [[nodiscard]] QList<Name> names() const;
279 /** Sets value of the names property. **/
280 void setNames(const QList<Name> &value);
281 /** Appends the given @c value to the list of names. **/
282 void addName(const Name &value);
283 /** Removes the given @c value from the list of names if it exists. **/
284 void removeName(const Name &value);
285 /** Clears the list of names. **/
286 void clearNames();
287
288 /** The person's calendar URLs. **/
289 [[nodiscard]] QList<CalendarUrl> calendarUrls() const;
290 /** Sets value of the calendarUrls property. **/
291 void setCalendarUrls(const QList<CalendarUrl> &value);
292 /** Appends the given @c value to the list of calendarUrls. **/
293 void addCalendarUrl(const CalendarUrl &value);
294 /** Removes the given @c value from the list of calendarUrls if it exists. **/
295 void removeCalendarUrl(const CalendarUrl &value);
296 /** Clears the list of calendarUrls. **/
297 void clearCalendarUrls();
298
299 /** Output only. The person's cover photos. **/
300 [[nodiscard]] QList<CoverPhoto> coverPhotos() const;
301
302 /** The person's street addresses. **/
303 [[nodiscard]] QList<Address> addresses() const;
304 /** Sets value of the addresses property. **/
305 void setAddresses(const QList<Address> &value);
306 /** Appends the given @c value to the list of addresses. **/
307 void addAddress(const Address &value);
308 /** Removes the given @c value from the list of addresses if it exists. **/
309 void removeAddress(const Address &value);
310 /** Clears the list of addresses. **/
311 void clearAddresses();
312
313 /** The [HTTP entity tag](https://en.wikipedia.org/wiki/HTTP_ETag) of the resource. Used for web cache validation. **/
314 [[nodiscard]] QString etag() const;
315 /** Sets value of the etag property. **/
316 void setEtag(const QString &value);
317
318 /** The person's phone numbers. For `people.connections.list` and `otherContacts.list` the number of phone numbers is limited to 100. If a Person has more
319 * phone numbers the entire set can be obtained by calling GetPeople. **/
320 [[nodiscard]] QList<PhoneNumber> phoneNumbers() const;
321 /** Sets value of the phoneNumbers property. **/
322 void setPhoneNumbers(const QList<PhoneNumber> &value);
323 /** Appends the given @c value to the list of phoneNumbers. **/
324 void addPhoneNumber(const PhoneNumber &value);
325 /** Removes the given @c value from the list of phoneNumbers if it exists. **/
326 void removePhoneNumber(const PhoneNumber &value);
327 /** Clears the list of phoneNumbers. **/
328 void clearPhoneNumbers();
329
330 /** The person's instant messaging clients. **/
331 [[nodiscard]] QList<ImClient> imClients() const;
332 /** Sets value of the imClients property. **/
333 void setImClients(const QList<ImClient> &value);
334 /** Appends the given @c value to the list of imClients. **/
335 void addImClient(const ImClient &value);
336 /** Removes the given @c value from the list of imClients if it exists. **/
337 void removeImClient(const ImClient &value);
338 /** Clears the list of imClients. **/
339 void clearImClients();
340
341 /** The person's events. **/
342 [[nodiscard]] QList<Event> events() const;
343 /** Sets value of the events property. **/
344 void setEvents(const QList<Event> &value);
345 /** Appends the given @c value to the list of events. **/
346 void addEvent(const Event &value);
347 /** Removes the given @c value from the list of events if it exists. **/
348 void removeEvent(const Event &value);
349 /** Clears the list of events. **/
350 void clearEvents();
351
352 /** Output only. The person's photos. **/
353 [[nodiscard]] QList<Photo> photos() const;
354
355 /** The person's occupations. **/
356 [[nodiscard]] QList<Occupation> occupations() const;
357 /** Sets value of the occupations property. **/
358 void setOccupations(const QList<Occupation> &value);
359 /** Appends the given @c value to the list of occupations. **/
360 void addOccupation(const Occupation &value);
361 /** Removes the given @c value from the list of occupations if it exists. **/
362 void removeOccupation(const Occupation &value);
363 /** Clears the list of occupations. **/
364 void clearOccupations();
365
366 /** The person's miscellaneous keywords. **/
367 [[nodiscard]] QList<MiscKeyword> miscKeywords() const;
368 /** Sets value of the miscKeywords property. **/
369 void setMiscKeywords(const QList<MiscKeyword> &value);
370 /** Appends the given @c value to the list of miscKeywords. **/
371 void addMiscKeyword(const MiscKeyword &value);
372 /** Removes the given @c value from the list of miscKeywords if it exists. **/
373 void removeMiscKeyword(const MiscKeyword &value);
374 /** Clears the list of miscKeywords. **/
375 void clearMiscKeywords();
376
377 /** Output only. **DEPRECATED**: No data will be returned The person's relationship interests. **/
378 [[nodiscard]] QList<RelationshipInterest> relationshipInterests() const;
379
380 /** The resource name for the person, assigned by the server. An ASCII string with a max length of 27 characters, in the form of `people/{person_id}`. **/
381 [[nodiscard]] QString resourceName() const;
382 /** Sets value of the resourceName property. **/
383 void setResourceName(const QString &value);
384
385 /** The person's interests. **/
386 [[nodiscard]] QList<Interest> interests() const;
387 /** Sets value of the interests property. **/
388 void setInterests(const QList<Interest> &value);
389 /** Appends the given @c value to the list of interests. **/
390 void addInterest(const Interest &value);
391 /** Removes the given @c value from the list of interests if it exists. **/
392 void removeInterest(const Interest &value);
393 /** Clears the list of interests. **/
394 void clearInterests();
395
396 /** The person's past or current organizations. **/
397 [[nodiscard]] QList<Organization> organizations() const;
398 /** Sets value of the organizations property. **/
399 void setOrganizations(const QList<Organization> &value);
400 /** Appends the given @c value to the list of organizations. **/
401 void addOrganization(const Organization &value);
402 /** Removes the given @c value from the list of organizations if it exists. **/
403 void removeOrganization(const Organization &value);
404 /** Clears the list of organizations. **/
405 void clearOrganizations();
406
407 /** The person's associated URLs. **/
408 [[nodiscard]] QList<Url> urls() const;
409 /** Sets value of the urls property. **/
410 void setUrls(const QList<Url> &value);
411 /** Appends the given @c value to the list of urls. **/
412 void addUrl(const Url &value);
413 /** Removes the given @c value from the list of urls if it exists. **/
414 void removeUrl(const Url &value);
415 /** Clears the list of urls. **/
416 void clearUrls();
417
418 /** The person's genders. This field is a singleton for contact sources. **/
419 [[nodiscard]] QList<Gender> genders() const;
420 /** Sets value of the genders property. **/
421 void setGenders(const QList<Gender> &value);
422 /** Appends the given @c value to the list of genders. **/
423 void addGender(const Gender &value);
424 /** Removes the given @c value from the list of genders if it exists. **/
425 void removeGender(const Gender &value);
426 /** Clears the list of genders. **/
427 void clearGenders();
428
429 /** The person's file-ases. **/
430 [[nodiscard]] QList<FileAs> fileAses() const;
431 /** Sets value of the fileAses property. **/
432 void setFileAses(const QList<FileAs> &value);
433 /** Appends the given @c value to the list of fileAses. **/
434 void addFileAs(const FileAs &value);
435 /** Removes the given @c value from the list of fileAses if it exists. **/
436 void removeFileAs(const FileAs &value);
437 /** Clears the list of fileAses. **/
438 void clearFileAses();
439
440 /** Output only. **DEPRECATED** (Please use `person.ageRanges` instead) The person's age range. **/
441 [[nodiscard]] Person::AgeRange ageRange() const;
442
443 /** Output only. Metadata about the person. **/
444 [[nodiscard]] PersonMetadata metadata() const;
445
446 [[nodiscard]] static PersonPtr fromJSON(const QJsonObject &obj);
447 [[nodiscard]] QJsonValue toJSON() const;
448
449private:
450 class Private;
451 std::unique_ptr<Private> d;
452}; // Person
453
454} // namespace KGAPI2::People
Base class for all objects.
Definition object.h:31
A person's physical address.
Definition address.h:35
A person's short biography.
Definition biography.h:34
A person's birthday.
Definition birthday.h:37
DEPRECATED: No data will be returned A person's bragging rights.
A person's calendar URL.
Definition calendarurl.h:34
Arbitrary client data that is populated by clients.
Definition clientdata.h:35
A person's email address.
An event related to the person.
An identifier from an external entity related to the person.
Definition externalid.h:34
The name that should be used to sort the person in a list.
Definition fileas.h:34
A person's gender.
Definition gender.h:34
A person's instant messaging client.
Definition imclient.h:35
One of the person's interests.
Definition interest.h:34
A person's location.
A person's membership in a group.
Definition membership.h:36
A person's miscellaneous keyword.
Definition misckeyword.h:35
A person's name.
Definition name.h:38
A person's nickname.
Definition nickname.h:34
A person's occupation.
Definition occupation.h:34
A person's past or current organization.
A person's locale preference.
The metadata about a person.
Information about a person merged from various data sources such as the authenticated user's contacts...
Definition person.h:82
A person's phone number.
Definition phonenumber.h:38
A person's relation to another person.
Definition relation.h:34
DEPRECATED: Please use person.locations instead.
Definition residence.h:33
A person's SIP address.
Definition sipaddress.h:35
A skill that the person has.
Definition skill.h:34
A person's associated URLs.
Definition url.h:34
Arbitrary user data that is populated by the end users.
Definition userdefined.h:34
Organization
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Nov 29 2024 11:54:35 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.