KCalendarCore

attendee.h
Go to the documentation of this file.
1 /*
2  This file is part of the kcalcore library.
3 
4  SPDX-FileCopyrightText: 2001-2003 Cornelius Schumacher <[email protected]>
5 
6  SPDX-License-Identifier: LGPL-2.0-or-later
7 */
8 /**
9  @file
10  This file is part of the API for handling calendar data and
11  defines the Attendee class.
12 
13  @author Cornelius Schumacher <[email protected]>
14 */
15 
16 #ifndef KCALCORE_ATTENDEE_H
17 #define KCALCORE_ATTENDEE_H
18 
19 #include <QMetaType>
20 #include <QSharedDataPointer>
21 
22 #include "customproperties.h"
23 #include "kcalendarcore_export.h"
24 
25 namespace KCalendarCore
26 {
27 /**
28  @brief
29  Represents information related to an attendee of an Calendar Incidence,
30  typically a meeting or task (to-do).
31 
32  Attendees are people with a name and (optional) email address who are
33  invited to participate in some way in a meeting or task. This class
34  also tracks that status of the invitation: accepted; tentatively accepted;
35  declined; delegated to another person; in-progress; completed.
36 
37  Attendees may optionally be asked to @acronym RSVP ("Respond Please") to
38  the invitation.
39 
40  Note that each attendee be can optionally associated with a @acronym UID
41  (unique identifier) derived from a Calendar Incidence, Email Message,
42  or any other thing you want.
43 */
44 class KCALENDARCORE_EXPORT Attendee
45 {
46  Q_GADGET
47  Q_PROPERTY(bool isNull READ isNull)
48  Q_PROPERTY(QString name READ name WRITE setName)
49  Q_PROPERTY(QString fullName READ fullName)
50  Q_PROPERTY(QString email READ email WRITE setEmail)
51  Q_PROPERTY(Role role READ role WRITE setRole)
52  Q_PROPERTY(QString uid READ uid WRITE setUid)
53  Q_PROPERTY(PartStat status READ status WRITE setStatus)
54  Q_PROPERTY(CuType cuType READ cuType WRITE setCuType)
55  Q_PROPERTY(bool rsvp READ RSVP WRITE setRSVP)
56  Q_PROPERTY(QString delegate READ delegate WRITE setDelegate)
57  Q_PROPERTY(QString delegator READ delegator WRITE setDelegator)
58 
59 public:
60  /**
61  The different types of participant status.
62  The meaning is specific to the incidence type in context.
63  */
64  enum PartStat {
65  NeedsAction, /**< Event, to-do or journal needs action (default) */
66  Accepted, /**< Event, to-do or journal accepted */
67  Declined, /**< Event, to-do or journal declined */
68  Tentative, /**< Event or to-do tentatively accepted */
69  Delegated, /**< Event or to-do delegated */
70  Completed, /**< To-do completed */
71  InProcess, /**< To-do in process of being completed */
72  None,
73  };
74  Q_ENUM(PartStat)
75 
76  /**
77  The different types of participation roles.
78  */
79  enum Role {
80  ReqParticipant, /**< Participation is required (default) */
81  OptParticipant, /**< Participation is optional */
82  NonParticipant, /**< Non-Participant; copied for information purposes */
83  Chair, /**< Chairperson */
84  };
85  Q_ENUM(Role)
86 
87  /**
88  * The different types of a participant.
89  *
90  * @since 4.14
91  */
92  enum CuType {
93  Individual, /**< An individual (default) */
94  Group, /**< A group of individuals */
95  Resource, /**< A physical resource */
96  Room, /**< A room resource */
97  Unknown, /**< Otherwise not known */
98  /**
99  * Parameters that have to set via the QString variant of @setCuType() and @cuType()
100  * x-name ; Experimental cuType
101  * iana-token ; Other IANA-registered
102  */
103  };
104  Q_ENUM(CuType)
105 
106  /**
107  List of attendees.
108  */
110 
111  /** Create a null Attendee. */
112  Attendee();
113 
114  /**
115  Constructs an attendee consisting of a person name (@p name) and
116  email address (@p email); invitation status and #Role;
117  an optional @acronym RSVP flag and @acronym UID.
118 
119  @param name is person name of the attendee.
120  @param email is person email address of the attendee.
121  @param rsvp if true, the attendee is requested to reply to invitations.
122  @param status is the #PartStat status of the attendee.
123  @param role is the #Role of the attendee.
124  @param uid is the @acronym UID of the attendee.
125  */
126  Attendee(const QString &name, const QString &email, bool rsvp = false, PartStat status = None, Role role = ReqParticipant, const QString &uid = QString());
127 
128  /**
129  Constructs an attendee by copying another attendee.
130 
131  @param attendee is the attendee to be copied.
132  */
133  Attendee(const Attendee &attendee);
134 
135  /**
136  Destroys the attendee.
137  */
138  ~Attendee();
139 
140  /**
141  * Returns @c true if this is a default-constructed Attendee instance.
142  */
143  bool isNull() const;
144 
145  /**
146  Returns the name of the attendee.
147  */
148  Q_REQUIRED_RESULT QString name() const;
149  /**
150  Sets the name of the attendee to @p name.
151  */
152  void setName(const QString &name);
153 
154  /**
155  Returns the full name and email address of this attendee
156  @return A QString containing the person's full name in the form
157  "FirstName LastName <mail@domain>".
158  */
159  Q_REQUIRED_RESULT QString fullName() const;
160 
161  /**
162  Returns the email address for this attendee.
163  */
164  Q_REQUIRED_RESULT QString email() const;
165  /**
166  Sets the email address for this attendee to @p email.
167  */
168  void setEmail(const QString &email);
169 
170  /**
171  Sets the Role of the attendee to @p role.
172 
173  @param role is the Role to use for the attendee.
174 
175  @see role()
176  */
177  void setRole(Role role);
178 
179  /**
180  Returns the Role of the attendee.
181 
182  @see setRole()
183  */
184  Q_REQUIRED_RESULT Role role() const;
185 
186  /**
187  Sets the @acronym UID of the attendee to @p uid.
188 
189  @param uid is the @acronym UID to use for the attendee.
190 
191  @see uid()
192  */
193  void setUid(const QString &uid);
194 
195  /**
196  Returns the @acronym UID of the attendee.
197 
198  @see setUid()
199  */
200  Q_REQUIRED_RESULT QString uid() const;
201 
202  /**
203  Sets the #PartStat of the attendee to @p status.
204 
205  @param status is the #PartStat to use for the attendee.
206 
207  @see status()
208  */
209  void setStatus(PartStat status);
210 
211  /**
212  Returns the #PartStat of the attendee.
213 
214  @see setStatus()
215  */
216  Q_REQUIRED_RESULT PartStat status() const;
217 
218  /**
219  Sets the #CuType of the attendee to @p cuType.
220 
221  @param cuType is the #CuType to use for the attendee.
222 
223  @see cuType()
224 
225  @since 4.14
226  */
227  void setCuType(CuType cuType);
228 
229  /**
230  Sets the #CuType of the attendee to @p cuType.
231 
232  @param cuType is the #CuType to use for the attendee.
233 
234  @see cuType()
235 
236  @since 4.14
237  */
238  void setCuType(const QString &cuType);
239 
240  /**
241  Returns the #CuType of the attendee.
242 
243  @see setCuType()
244 
245  @since 4.14
246  */
247  Q_REQUIRED_RESULT CuType cuType() const;
248 
249  /**
250  Returns the #CuType of the attendee.
251 
252  @see setCuType()
253 
254  @since 4.14
255  */
256  Q_REQUIRED_RESULT QString cuTypeStr() const;
257 
258  /**
259  Sets the @acronym RSVP flag of the attendee to @p rsvp.
260 
261  @param rsvp if set (true), the attendee is requested to reply to
262  invitations.
263 
264  @see RSVP()
265  */
266  void setRSVP(bool rsvp);
267 
268  /**
269  Returns the attendee @acronym RSVP flag.
270 
271  @see setRSVP()
272  */
273  Q_REQUIRED_RESULT bool RSVP() const;
274 
275  /**
276  Compares this with @p attendee for equality.
277 
278  @param attendee the attendee to compare.
279  */
280  bool operator==(const Attendee &attendee) const;
281 
282  /**
283  Compares this with @p attendee for inequality.
284 
285  @param attendee the attendee to compare.
286  */
287  bool operator!=(const Attendee &attendee) const;
288 
289  /**
290  Sets the delegate.
291  @param delegate is a string containing a MAILTO URI of those delegated
292  to attend the meeting.
293  @see delegate(), setDelegator().
294  */
295  void setDelegate(const QString &delegate);
296 
297  /**
298  Returns the delegate.
299  @see setDelegate().
300  */
301  Q_REQUIRED_RESULT QString delegate() const;
302 
303  /**
304  Sets the delegator.
305  @param delegator is a string containing a MAILTO URI of those who
306  have delegated their meeting attendance.
307  @see delegator(), setDelegate().
308  */
309  void setDelegator(const QString &delegator);
310 
311  /**
312  Returns the delegator.
313  @see setDelegator().
314  */
315  Q_REQUIRED_RESULT QString delegator() const;
316 
317  /**
318  Adds a custom property. If the property already exists it will be overwritten.
319  @param xname is the name of the property.
320  @param xvalue is its value.
321  */
322  void setCustomProperty(const QByteArray &xname, const QString &xvalue);
323 
324  /**
325  Returns a reference to the CustomProperties object
326  */
327  Q_REQUIRED_RESULT CustomProperties &customProperties();
328 
329  /**
330  Returns a const reference to the CustomProperties object
331  */
332  const CustomProperties &customProperties() const;
333 
334  /**
335  Sets this attendee equal to @p attendee.
336 
337  @param attendee is the attendee to copy.
338  */
339  Attendee &operator=(const Attendee &attendee);
340 
341 private:
342  //@cond PRIVATE
343  class Private;
344  QSharedDataPointer<Private> d;
345  //@endcond
346 
347  friend KCALENDARCORE_EXPORT QDataStream &operator<<(QDataStream &s, const KCalendarCore::Attendee &attendee);
348  friend KCALENDARCORE_EXPORT QDataStream &operator>>(QDataStream &s, KCalendarCore::Attendee &attendee);
349 };
350 
351 /**
352  Serializes an Attendee object into a data stream.
353  @param stream is a QDataStream.
354  @param attendee is a pointer to a Attendee object to be serialized.
355 */
356 KCALENDARCORE_EXPORT QDataStream &operator<<(QDataStream &stream, const KCalendarCore::Attendee &attendee);
357 
358 /**
359  Initializes an Attendee object from a data stream.
360  @param stream is a QDataStream.
361  @param attendee is a pointer to a Attendee object to be initialized.
362 */
363 KCALENDARCORE_EXPORT QDataStream &operator>>(QDataStream &stream, KCalendarCore::Attendee &attendee);
364 }
365 
366 //@cond PRIVATE
367 Q_DECLARE_TYPEINFO(KCalendarCore::Attendee, Q_MOVABLE_TYPE);
368 Q_DECLARE_METATYPE(KCalendarCore::Attendee)
369 //@endcond
370 
371 #endif
Represents information related to an attendee of an Calendar Incidence, typically a meeting or task (...
Definition: attendee.h:44
Namespace for all KCalendarCore types.
Definition: alarm.h:36
@ Completed
To-do completed.
Definition: attendee.h:70
@ Chair
Chairperson.
Definition: attendee.h:83
@ Tentative
Event or to-do tentatively accepted.
Definition: attendee.h:68
@ Resource
A physical resource.
Definition: attendee.h:95
@ OptParticipant
Participation is optional.
Definition: attendee.h:81
@ ReqParticipant
Participation is required (default)
Definition: attendee.h:80
Role
The different types of participation roles.
Definition: attendee.h:79
Q_SCRIPTABLE CaptureState status()
PartStat
The different types of participant status.
Definition: attendee.h:64
@ Unknown
Otherwise not known.
Definition: attendee.h:97
@ InProcess
To-do in process of being completed.
Definition: attendee.h:71
@ Group
A group of individuals.
Definition: attendee.h:94
@ NeedsAction
Event, to-do or journal needs action (default)
Definition: attendee.h:65
@ Declined
Event, to-do or journal declined.
Definition: attendee.h:67
@ Accepted
Event, to-do or journal accepted.
Definition: attendee.h:66
@ Room
A room resource.
Definition: attendee.h:96
@ NonParticipant
Non-Participant; copied for information purposes.
Definition: attendee.h:82
CuType
The different types of a participant.
Definition: attendee.h:92
@ Individual
An individual (default)
Definition: attendee.h:93
A class to manage custom calendar properties.
@ Delegated
Event or to-do delegated.
Definition: attendee.h:69
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Tue Oct 3 2023 03:58:12 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.