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 | |
38 | namespace 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 | */ |
57 | class KCALCORE_EXPORT Attendee : private Person |
58 | { |
59 | public: |
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 | |
321 | private: |
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 | */ |
338 | KCALCORE_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 | */ |
346 | KCALCORE_EXPORT QDataStream &operator>>(QDataStream &stream, |
347 | KCalCore::Attendee::Ptr &attendee); |
348 | } |
349 | |
350 | //@cond PRIVATE |
351 | Q_DECLARE_TYPEINFO(KCalCore::Attendee::Ptr, Q_MOVABLE_TYPE); |
352 | Q_DECLARE_METATYPE(KCalCore::Attendee::Ptr) |
353 | //@endcond |
354 | |
355 | #endif |
356 | |