1/*
2 This file is part of the kcal 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 KCAL_ATTENDEE_H
30#define KCAL_ATTENDEE_H
31
32#include <QtCore/QString>
33#include <QtCore/QStringList>
34
35#include "listbase.h"
36#include "person.h"
37#include "customproperties.h"
38
39namespace KCal {
40
41/**
42 @brief
43 Represents information related to an attendee of an Calendar Incidence,
44 typically a meeting or task (to-do).
45
46 Attendees are people with a name and (optional) email address who are
47 invited to participate in some way in a meeting or task. This class
48 also tracks that status of the invitation: accepted; tentatively accepted;
49 declined; delegated to another person; in-progress; completed.
50
51 Attendees may optionally be asked to @acronym RSVP ("Respond Please") to
52 the invitation.
53
54 Note that each attendee be can optionally associated with a @acronym UID
55 (unique identifier) derived from a Calendar Incidence, Email Message,
56 or any other thing you want.
57*/
58class KCAL_DEPRECATED_EXPORT Attendee : private Person
59{
60 public:
61 using Person::setEmail;
62 using Person::email;
63 using Person::setName;
64 using Person::name;
65 using Person::fullName;
66
67 /**
68 The different types of participant status.
69 The meaning is specific to the incidence type in context.
70 */
71 enum PartStat {
72 NeedsAction, /**< Event, to-do or journal needs action (default) */
73 Accepted, /**< Event, to-do or journal accepted */
74 Declined, /**< Event, to-do or journal declined */
75 Tentative, /**< Event or to-do tentatively accepted */
76 Delegated, /**< Event or to-do delegated */
77 Completed, /**< To-do completed */
78 InProcess, /**< To-do in process of being completed */
79 None
80 };
81
82 /**
83 The different types of participation roles.
84 */
85 enum Role {
86 ReqParticipant, /**< Participation is required (default) */
87 OptParticipant, /**< Participation is optional */
88 NonParticipant, /**< Non-Participant; copied for information purposes */
89 Chair /**< Chairperson */
90 };
91
92 /**
93 List of attendees.
94 */
95 typedef ListBase<Attendee> List;
96
97 /**
98 Constructs an attendee consisting of a Person name (@p name) and
99 email address (@p email); invitation status and #Role;
100 an optional @acronym RSVP flag and @acronym UID.
101
102 @param name is person name of the attendee.
103 @param email is person email address of the attendee.
104 @param rsvp if true, the attendee is requested to reply to invitations.
105 @param status is the #PartStat status of the attendee.
106 @param role is the #Role of the attendee.
107 @param uid is the @acronym UID of the attendee.
108 */
109 Attendee( const QString &name, const QString &email,
110 bool rsvp = false, PartStat status = None,
111 Role role = ReqParticipant, const QString &uid = QString() );
112
113 /**
114 Constructs an attendee by copying another attendee.
115
116 @param attendee is the attendee to be copied.
117 */
118 Attendee( const Attendee &attendee );
119
120 /**
121 Destroys the attendee.
122 */
123 ~Attendee();
124
125 /**
126 Sets the Role of the attendee to @p role.
127
128 @param role is the Role to use for the attendee.
129
130 @see role()
131 */
132 void setRole( Role role );
133
134 /**
135 Returns the Role of the attendee.
136
137 @see setRole()
138 */
139 Role role() const;
140
141 /**
142 Returns the attendee Role as a text string.
143
144 @see role(), roleName()
145 */
146 QString roleStr() const;
147
148 /**
149 Returns the specified #Role @p role as a text string.
150
151 @param role is a #Role value.
152
153 @see role(), roleStr()
154 */
155 static QString roleName( Role role );
156
157 /**
158 Returns a list of strings representing each #Role.
159 */
160 static QStringList roleList();
161
162 /**
163 Sets the @acronym UID of the attendee to @p uid.
164
165 @param uid is the @acronym UID to use for the attendee.
166
167 @see uid()
168 */
169 void setUid ( const QString &uid );
170
171 /**
172 Returns the @acronym UID of the attendee.
173
174 @see setUid()
175 */
176 QString uid() const;
177
178 /**
179 Sets the #PartStat of the attendee to @p status.
180
181 @param status is the #PartStat to use for the attendee.
182
183 @see status()
184 */
185 void setStatus( PartStat status );
186
187 /**
188 Returns the #PartStat of the attendee.
189
190 @see setStatus()
191 */
192 PartStat status() const;
193
194 /**
195 Returns the attendee #PartStat as a text string.
196
197 @see status(), statusName()
198 */
199 QString statusStr() const;
200
201 /**
202 Returns the specified #PartStat @p status as a text string.
203
204 @param status is a #PartStat value.
205
206 @see status(), statusStr()
207 */
208 static QString statusName( PartStat status );
209
210 /**
211 Returns a list of strings representing each #PartStat.
212 */
213 static QStringList statusList();
214
215 /**
216 Sets the @acronym RSVP flag of the attendee to @p rsvp.
217
218 @param rsvp if set (true), the attendee is requested to reply to
219 invitations.
220
221 @see RSVP()
222 */
223 void setRSVP( bool rsvp );
224
225 /**
226 Returns the attendee @acronym RSVP flag.
227
228 @see setRSVP()
229 */
230 bool RSVP() const;
231
232 /**
233 Compares this with @p attendee for equality.
234
235 @param attendee the attendee to compare.
236 */
237 //KDE5: make const
238 bool operator==( const Attendee &attendee ); //krazy:exclude=operators
239
240 /**
241 Sets the delegate.
242 @param delegate is a string containing a MAILTO URI of those delegated
243 to attend the meeting.
244 @see delegate(), setDelegator().
245 */
246 void setDelegate( const QString &delegate );
247
248 /**
249 Returns the delegate.
250 @see setDelegate().
251 */
252 QString delegate() const;
253
254 /**
255 Sets the delegator.
256 @param delegator is a string containing a MAILTO URI of those who
257 have delegated their meeting attendance.
258 @see delegator(), setDelegate().
259 */
260 void setDelegator( const QString &delegator );
261
262 /**
263 Returns the delegator.
264 @see setDelegator().
265 */
266 QString delegator() const;
267
268 /**
269 Adds a custom property. If the property already exists it will be overwritten.
270 @param xname is the name of the property.
271 @param xvalue is its value.
272 @since 4.4
273 */
274 void setCustomProperty( const QByteArray &xname, const QString &xvalue );
275
276 /**
277 Returns a reference to the CustomProperties object
278 @since 4.4
279 */
280 CustomProperties &customProperties();
281
282 /**
283 Returns a const reference to the CustomProperties object
284 @since 4.4
285 */
286 const CustomProperties &customProperties() const;
287
288 /**
289 Sets this attendee equal to @p attendee.
290
291 @param attendee is the attendee to copy.
292 */
293 Attendee &operator=( const Attendee &attendee );
294
295 private:
296 //@cond PRIVATE
297 class Private;
298 Private *const d;
299 //@endcond
300};
301
302}
303
304#endif
305