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 | |
39 | namespace 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 | */ |
59 | class KCALCORE_EXPORT Attachment |
60 | { |
61 | public: |
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 | |
258 | private: |
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 | */ |
273 | KCALCORE_EXPORT QDataStream &operator<<(QDataStream &out, const KCalCore::Attachment::Ptr &); |
274 | |
275 | /** |
276 | * Attachment deserializer. |
277 | * |
278 | * @since 4.12 |
279 | */ |
280 | KCALCORE_EXPORT QDataStream &operator>>(QDataStream &in, const KCalCore::Attachment::Ptr &); |
281 | |
282 | } |
283 | |
284 | //@cond PRIVATE |
285 | Q_DECLARE_TYPEINFO(KCalCore::Attachment::Ptr, Q_MOVABLE_TYPE); |
286 | Q_DECLARE_METATYPE(KCalCore::Attachment::Ptr) |
287 | //@endcond |
288 | |
289 | //@cond PRIVATE |
290 | inline uint qHash(const QSharedPointer<KCalCore::Attachment> &key) |
291 | { |
292 | return qHash<KCalCore::Attachment>(key.data()); |
293 | } |
294 | //@endcond |
295 | |
296 | #endif |
297 | |