KCalendarCore

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

KDE's Doxygen guidelines are available online.