1/*
2 ktnefwriter.cpp
3
4 Copyright (C) 2002 Bo Thorsen <bo@sonofthor.dk>
5
6 This file is part of KTNEF, the KDE TNEF support library/program.
7
8 This library is free software; you can redistribute it and/or
9 modify it under the terms of the GNU Library General Public
10 License as published by the Free Software Foundation; either
11 version 2 of the License, or (at your option) any later version.
12
13 This library is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 Library General Public License for more details.
17
18 You should have received a copy of the GNU Library General Public License
19 along with this library; see the file COPYING.LIB. If not, write to
20 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
21 Boston, MA 02110-1301, USA.
22 */
23/**
24 * @file
25 * This file is part of the API for handling TNEF data and
26 * defines the KTNEFWriter class.
27 *
28 * @author Bo Thorsen
29 */
30
31#ifndef KTNEFWRITER_H
32#define KTNEFWRITER_H
33
34class QString;
35class QVariant;
36class QIODevice;
37class QDataStream;
38class QDateTime;
39class QStringList;
40
41#include "ktnef_export.h"
42#include <qglobal.h>
43
44namespace KTnef {
45
46/**
47 * @brief
48 * Manages the writing of @acronym TNEF attachments.
49 */
50class KTNEF_EXPORT KTNEFWriter
51{
52 public:
53 /**
54 * The different types of messages.
55 */
56 enum MessageType {
57 Appointment, /**< Appointment */
58 MeetingCancelled,/**< The meeting is cancelled */
59 MeetingRequest, /**< Meeting request */
60 MeetingNo, /**< Negative response to a meeting request */
61 MeetingYes, /**< Affirmative response to a meeting request */
62 MeetingTent /**< Tentative affirmative to a meeting request */
63 };
64
65 /**
66 * The different types of message statuses.
67 */
68 enum Method {
69 PublishNew, /**< Publish new */
70 Obsolete, /**< Replace the message */
71 RequestNew, /**< Request a new message */
72 RequestUpdate, /**< Request an update */
73 Unknown /**< Unknown */
74 };
75
76 /**
77 * The different types of meeting roles.
78 */
79 enum Role {
80 ReqParticipant, /**< Required participant */
81 OptParticipant, /**< Optional participant */
82 NonParticipant, /**< Non-participant */
83 Chair /**< Meeting chairperson */
84 };
85
86 /**
87 * The different types of participant statuses.
88 */
89 enum PartStat {
90 NeedsAction, /**< No information about the task/invitation received */
91 Accepted, /**< Accepted the task/invitation */
92 Declined, /**< Declined the task/invitation */
93 Tentative, /**< Tentatively accepted the task/invitation */
94 Delegated, /**< Delegated the task to another */
95 Completed, /**< Completed the task */
96 InProcess /**< Work on the task is in-progress */
97 };
98
99 /**
100 * The different priorities.
101 */
102 enum Priority {
103 High = 2, /**< High priority task */
104 Normal = 3, /**< Normal priority task */
105 Low = 1 /**< Low priority task */
106 };
107
108 /**
109 * The different alarm actions.
110 */
111 enum AlarmAction {
112 Display /**< Display the alarm */
113 };
114
115 /**
116 * Constructs a @acronym TNEF writer object.
117 */
118 KTNEFWriter();
119
120 /**
121 * Destroys the @acronym TNEF writer object.
122 */
123 ~KTNEFWriter();
124
125 /**
126 * Adds a @acronym TNEF property.
127 *
128 * @param tag is the @acronym TNEF tag
129 * @param type is the property type
130 * @param value is the property value
131 */
132 void addProperty( int tag, int type, const QVariant &value );
133
134 /**
135 * Writes a @acronym TNEF property to the #QDataStream specified by @p stream.
136 *
137 * A @acronym TNEF property has a 1 byte type (LVL_MESSAGE or LVL_ATTACHMENT),
138 * a 4 byte type/tag, a 4 byte length, the data and finally the checksum.
139 *
140 * The checksum is a 16 byte int with all bytes in the data added.
141 *
142 * @param stream is the #QDataStream to write
143 * @param bytes is a pointer to an int type that will contain
144 * the number of bytes written to the @p stream
145 * @param tag is the @acronym TNEF tag
146 *
147 * @return false if an invalid @acronym TNEF tag was specified by @p tag or
148 * if there are no properties to write; else true.
149 */
150 bool writeProperty( QDataStream &stream, int &bytes, int tag ) const;
151
152 /**
153 * Writes the attachment to the #QIODevice specified by @p file.
154 *
155 * @param file is the #QIODevice to write.
156 * @return true if the write was successful; otherwise false.
157 */
158 bool writeFile( QIODevice &file ) const;
159
160 /**
161 * Writes the attachment to the #QDataStream specified by @p stream.
162 *
163 * @param stream is the #QDataStream to write.
164 * @return true if the write was successful; otherwise false.
165 */
166 bool writeFile( QDataStream &stream ) const;
167
168 /**
169 * Sets the sender's @p name and @p email address.
170 *
171 * @param name is the sender's name.
172 * @param email is the sender's email address.
173 */
174 void setSender( const QString &name, const QString &email );
175
176 /**
177 * Sets the #MessageType to @p methodType.
178 *
179 * @param methodType is the #MessageType.
180 */
181 void setMessageType( MessageType methodType );
182
183 /**
184 * Sets the #Method to @p method.
185 *
186 * @param method is the #Method.
187 */
188 void setMethod( Method method );
189
190 /**
191 * Clears the attendees list.
192 */
193 void clearAttendees();
194
195 /**
196 * Adds a meeting participant (attendee).
197 *
198 * @param name is the name of the attendee
199 * @param role is the #Role of the attendee
200 * @param partstat is the status #PartStat of the attendee
201 * @param rsvp is true if the attendee will attend the meeting; else false
202 * @param email is the email address of the attendee
203 */
204 void addAttendee( const QString &name, Role role, PartStat partstat,
205 bool rsvp, const QString &email );
206
207 /**
208 * Sets the name of the organizer to @p organizer.
209 * The organizer is any string identifier; it could be the name
210 * of a person, or the application that sent the invitation, for example.
211 *
212 * @param organizer is the organizer identifier.
213 */
214 void setOrganizer( const QString &organizer );
215
216 /**
217 * Sets the Starting Date and Time to @p dtStart.
218 *
219 * @param dtStart is the starting date/time.
220 */
221 void setDtStart( const QDateTime &dtStart );
222
223 /**
224 * Sets the Ending Date and Time to @p dtEnd.
225 *
226 * @param dtEnd is the ending date/time.
227 */
228 void setDtEnd( const QDateTime &dtEnd );
229
230 /**
231 * Sets the Location to @p location.
232 *
233 * @param location is the location.
234 */
235 void setLocation( const QString &location );
236
237 /**
238 * Sets the @acronym UID to @p uid.
239 *
240 * @param uid is the @acronym UID.
241 */
242 void setUID( const QString &uid );
243
244 /**
245 * Sets the timestamp to @p dtStamp.
246 *
247 * @param dtStamp is the timestamp.
248 */
249 void setDtStamp( const QDateTime &dtStamp );
250
251 /**
252 * Sets the category list to @p categories.
253 *
254 * @param categories is the list categories.
255 */
256 void setCategories( const QStringList &categories );
257
258 /**
259 * Sets the description to @p description.
260 *
261 * @param description is the description.
262 */
263 void setDescription( const QString &description );
264
265 /**
266 * Sets the summary to @p summary.
267 *
268 * @param summary is the summary.
269 */
270 void setSummary( const QString &summary );
271
272 /**
273 * Sets the priority to @p priority.
274 *
275 * @param priority is the #Priority.
276 */
277 void setPriority( Priority priority );
278
279 /**
280 * Sets the alarm.
281 *
282 * @param description is the alarm description
283 * @param action is the alaram #AlarmAction
284 * @param wakeBefore is the alarm Date/Time
285 */
286 void setAlarm( const QString &description, AlarmAction action,
287 const QDateTime &wakeBefore );
288
289 private:
290 //@cond PRIVATE
291 class PrivateData;
292 PrivateData *const d;
293 //@endcond
294
295 Q_DISABLE_COPY( KTNEFWriter )
296};
297
298}
299
300#endif // KTNEFWRITER_H
301