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