1/*
2 This file is part of the kcalcore library.
3
4 Copyright (c) 2002 Michael Brade <brade@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 Attachment class.
25
26 @author Michael Brade \<brade@kde.org\>
27*/
28
29#ifndef KCALCORE_ATTACHMENT_H
30#define KCALCORE_ATTACHMENT_H
31
32#include "kcalcore_export.h"
33
34#include <QtCore/QHash>
35#include <QtCore/QString>
36#include <QtCore/QSharedPointer>
37#include <QMetaType>
38
39namespace KCalCore {
40
41/**
42 @brief
43 Represents information related to an attachment for a Calendar Incidence.
44
45 This is not an email message attachment.
46
47 Calendar Incidence attachments consist of:
48 - A <a href="http://en.wikipedia.org/wiki/Uniform_Resource_Identifier">
49 Uniform Resource Identifier (URI)</a>
50 or a
51 <a href="http://en.wikipedia.org/wiki/Base64#MIME">base64 encoded</a>
52 binary blob.
53 - A <a href="http://en.wikipedia.org/wiki/MIME">
54 Multipurpose Internet Mail Extensions (MIME)</a> type.
55
56 This class is used to associate files (local or remote) or other resources
57 with a Calendar Incidence.
58*/
59class KCALCORE_EXPORT Attachment
60{
61public:
62 /**
63 A shared pointer to an Attachment object.
64 */
65 typedef QSharedPointer<Attachment> Ptr;
66
67 /**
68 List of attachments.
69 */
70 typedef QVector<Ptr> List;
71
72 /**
73 Constructs an attachment consisting of a @p uri and a @p mime type.
74
75 @param uri is the @acronym URI referred to by this attachment.
76 @param mime is the (optional) @acronym MIME type of the @p uri
77 */
78 explicit Attachment(const QString &uri, const QString &mime = QString());
79
80 /**
81 Constructs an attachment consisting of a binary blob of data
82 and a @p mime type.
83
84 @param base64 is the binary data in base64 format for the attachment.
85 @param mime is the (optional) @acronym MIME type of the attachment
86 */
87 explicit Attachment(const QByteArray &base64,
88 const QString &mime = QString());
89
90 /**
91 Constructs an attachment by copying another attachment.
92
93 @param attachment is the attachment to be copied.
94 */
95 Attachment(const Attachment &attachment);
96
97 /**
98 Destroys the attachment.
99 */
100 ~Attachment();
101
102 /**
103 Sets the @acronym URI for this attachment to @p uri.
104
105 @param uri is the @acronym URI to use for the attachment.
106
107 @see uri(), isUri()
108 */
109 void setUri(const QString &uri);
110
111 /**
112 Returns the @acronym URI of the attachment.
113
114 @see setUri(), isUri()
115 */
116 QString uri() const;
117
118 /**
119 Returns true if the attachment has a @acronym URI; false otherwise.
120
121 @see uri(), setUri(I), isBinary()
122 */
123 bool isUri() const;
124
125 /**
126 Returns true if the attachment has a binary blob; false otherwise.
127
128 @see isUri()
129 */
130 bool isBinary() const;
131
132 /**
133 Sets the base64 encoded binary blob data of the attachment.
134
135 @param base64 contains the base64 encoded binary data.
136
137 @see data(), decodedData()
138 */
139 void setData(const QByteArray &base64);
140
141 /**
142 Returns a pointer to a QByteArray containing the base64 encoded
143 binary data of the attachment.
144
145 @see setData(), setDecodedData()
146 */
147 QByteArray data() const;
148
149 /**
150 Sets the decoded attachment data.
151
152 @param data is the decoded base64 binary data.
153
154 @see decodedData(), data()
155 */
156 void setDecodedData(const QByteArray &data);
157
158 /**
159 Returns a QByteArray containing the decoded base64 binary data of the
160 attachment.
161
162 @see setDecodedData(), setData()
163 */
164 QByteArray decodedData() const;
165
166 /**
167 Returns the size of the attachment, in bytes.
168 If the attachment is binary (i.e, there is no @acronym URI associated
169 with the attachment) then a value of 0 is returned.
170 */
171 uint size() const;
172
173 /**
174 Sets the @acronym MIME-type of the attachment to @p mime.
175
176 @param mime is the string to use for the attachment @acronym MIME-type.
177
178 @see mimeType()
179 */
180 void setMimeType(const QString &mime);
181
182 /**
183 Returns the @acronym MIME-type of the attachment.
184
185 @see setMimeType()
186 */
187 QString mimeType() const;
188
189 /**
190 Sets the attachment "show in-line" option, which is derived from
191 the Calendar Incidence @b X-CONTENT-DISPOSITION parameter.
192
193 @param showinline is the flag to set (true) or unset (false)
194 for the attachment "show in-line" option.
195
196 @see showInline()
197 */
198 void setShowInline(bool showinline);
199
200 /**
201 Returns the attachment "show in-line" flag.
202
203 @see setShowInline()
204 */
205 bool showInline() const;
206
207 /**
208 Sets the attachment label to @p label, which is derived from
209 the Calendar Incidence @b X-LABEL parameter.
210
211 @param label is the string to use for the attachment label.
212
213 @see label()
214 */
215 void setLabel(const QString &label);
216
217 /**
218 Returns the attachment label string.
219 */
220 QString label() const;
221
222 /**
223 Sets the attachment "local" option, which is derived from the
224 Calendar Incidence @b X-KONTACT-TYPE parameter.
225
226 @param local is the flag to set (true) or unset (false) for the
227 attachment "local" option.
228
229 @see local()
230 */
231 void setLocal(bool local);
232
233 /**
234 Returns the attachment "local" flag.
235 */
236 bool isLocal() const;
237
238 /**
239 Assignment operator.
240 @param attachment is the attachment to assign.
241 */
242 Attachment &operator=(const Attachment &attachment);
243
244 /**
245 Compare this with @p attachment for equality.
246 @param attachment is the attachment to compare.
247 @return true if the attachments are equal; false otherwise.
248 */
249 bool operator==(const Attachment &attachment) const;
250
251 /**
252 Compare this with @p attachment for inequality.
253 @param attachment is the attachment to compare.
254 @return true if the attachments are /not/ equal; false otherwise.
255 */
256 bool operator!=(const Attachment &attachment) const;
257
258private:
259 //@cond PRIVATE
260 class Private;
261 Private *const d;
262 //@endcond
263
264 friend KCALCORE_EXPORT QDataStream &operator<<(QDataStream &s, const KCalCore::Attachment::Ptr &);
265 friend KCALCORE_EXPORT QDataStream &operator>>(QDataStream &s, const KCalCore::Attachment::Ptr &);
266};
267
268/**
269 * Attachment serializer.
270 *
271 * @since 4.12
272 */
273KCALCORE_EXPORT QDataStream &operator<<(QDataStream &out, const KCalCore::Attachment::Ptr &);
274
275/**
276 * Attachment deserializer.
277 *
278 * @since 4.12
279 */
280KCALCORE_EXPORT QDataStream &operator>>(QDataStream &in, const KCalCore::Attachment::Ptr &);
281
282}
283
284//@cond PRIVATE
285Q_DECLARE_TYPEINFO(KCalCore::Attachment::Ptr, Q_MOVABLE_TYPE);
286Q_DECLARE_METATYPE(KCalCore::Attachment::Ptr)
287//@endcond
288
289//@cond PRIVATE
290inline uint qHash(const QSharedPointer<KCalCore::Attachment> &key)
291{
292 return qHash<KCalCore::Attachment>(key.data());
293}
294//@endcond
295
296#endif
297