1 /*  This file is part of the KDE project
2     SPDX-FileCopyrightText: 2011 Christian Mollekopf <chrigi_1@fastmail.fm>
3 
4     SPDX-License-Identifier: LGPL-2.0-or-later
5 */
6 
7 #pragma once
8 
9 #include "akonadi-notes_export.h"
10 
11 #include <QMap>
12 #include <QUrl>
13 
14 #include <memory>
15 
16 class QDateTime;
17 class QString;
18 
19 template<typename T> class QSharedPointer;
20 
21 namespace KMime
22 {
23 class Message;
24 typedef QSharedPointer<Message> MessagePtr;
25 }
26 namespace Akonadi
27 {
28 namespace NoteUtils
29 {
30 /**
31  * @return mimetype for notes
32  * @since 4.8
33  */
34 AKONADI_NOTES_EXPORT QString noteMimeType();
35 
36 /**
37  * @return icon for notes
38  * @since 4.8
39  */
40 AKONADI_NOTES_EXPORT QString noteIconName();
41 
42 class AttachmentPrivate;
43 
44 /**
45  * An attachment for a note
46  * @since 4.9
47  */
48 class AKONADI_NOTES_EXPORT Attachment
49 {
50 public:
51     /**
52      * Create an attachment referencing a url only
53      */
54     Attachment();
55     Attachment(const QUrl &url, const QString &mimetype);
56     /**
57      * Create an attachment with the content stored inline
58      */
59     Attachment(const QByteArray &data, const QString &mimetype);
60     Attachment(const Attachment &other);
61     ~Attachment();
62 
63     bool operator==(const Attachment &a) const;
64     void operator=(const Attachment &a);
65 
66     /**
67      * Returns the url for url-only attachments
68      */
69     QUrl url() const;
70 
71     /**
72      * Returns the date for inline attachments
73      */
74     QByteArray data() const;
75 
76     /**
77      * Sets the unique identifier of the attachment
78      *
79      * It can be used to refer to attachment from the note itself
80      *
81      * @since 5.15
82      */
83     void setContentID(const QString &contentID);
84 
85     /**
86      * Returns the unique identifier for inline attachment
87      *
88      * @since 5.15
89      */
90     QString contentID() const;
91 
92     /**
93      * Set this to true if inline data provided via ctor
94      * is already base64 encoded. Default value is false.
95      *
96      * @since 5.15
97      */
98     void setDataBase64Encoded(bool encoded);
99 
100     /**
101      * Returns true if data is already base64-encoded
102      *
103      * @since 5.15
104      */
105     bool dataBase64Encoded() const;
106 
107     /**
108      * Returns the mimetype
109      */
110     QString mimetype() const;
111 
112     /**
113      * Sets the label to be presented to the user
114      */
115     void setLabel(const QString &label);
116 
117     /**
118      * Returns the label of the attachment
119      */
120     QString label() const;
121 
122 private:
123     //@cond PRIVATE
124     std::unique_ptr<AttachmentPrivate> const d_ptr;
125     Q_DECLARE_PRIVATE(Attachment)
126     //@endcond
127 };
128 
129 class NoteMessageWrapperPrivate;
130 
131 /**
132  * A convenience wrapper around KMime::MessagePtr for notes
133  *
134  * This is the format used by the Akonotes Resource
135  *
136  * A note has the following properties:
137  * uid: globally unique identifier (generated if empty)
138  * creationDate: timestamp when the note was created (generated if empty)
139  * lastModified: lastModified (generated if empty)
140  * classification: one of private, confidential, public. This is only meant as an indication to the user.
141  * title: title of the note
142  * text: textual content
143  * from: author (generated if empty)
144  * attachments: inline or url only
145  * custom: key value pair for custom values
146  *
147  * Reading a note from an Akonotes akonadi item:
148  * @code
149  * if ( item.hasPayload<KMime::MessagePtr>() ) {
150  *   NoteUtils::NoteMessageWrapper note(item.payload<KMime::MessagePtr>());
151  *   qCDebug(AKONADINOTES_LOG) << note.text();
152  *   textIsRich = messageWrapper.textFormat() == Qt::RichText;
153  * }
154  * @endcode
155  *
156  * Setting the note as payload of an akonadi Item
157  * @code
158  * item.setMimeType(NoteUtils::noteMimeType());
159  * NoteUtils::NoteMessageWrapper note;
160  * note.setTitle( "title" );
161  * note.setText( "text" );
162  * note.setFrom( QString::fromLatin1( "MyApplication@kde4" ) );
163  * item.setPayload( note.message() );
164  * @endcode
165  *
166  * @author Christian Mollekopf <chrigi_1@fastmail.fm>
167  * @since 4.8
168  */
169 class AKONADI_NOTES_EXPORT NoteMessageWrapper
170 {
171 public:
172     NoteMessageWrapper();
173     explicit NoteMessageWrapper(const KMime::MessagePtr &msg);
174     ~NoteMessageWrapper();
175 
176     /**
177      * Set the uid of the note
178      * @param uid should be globally unique
179      */
180     void setUid(const QString &uid);
181 
182     /**
183      * Returns the uid of the note
184      */
185     QString uid() const;
186 
187     enum Classification { Public, Private, Confidential };
188 
189     /**
190      * Set the classification of the note
191      */
192     void setClassification(Classification);
193 
194     /**
195      * Returns the classification of the note
196      */
197     Classification classification() const;
198 
199     /**
200      * Set the title of the note
201      */
202     void setTitle(const QString &title);
203 
204     /**
205      * Returns the title of the note
206      */
207     QString title() const;
208 
209     /**
210      * Set the text of the note
211      *
212      * @param format only Qt::PlainText and Qt::RichText is supported
213      */
214     void setText(const QString &text, Qt::TextFormat format = Qt::PlainText);
215 
216     /**
217      * Returns the text of the note
218      */
219     QString text() const;
220 
221     /**
222      * @return Qt::PlainText or Qt::RichText
223      */
224     Qt::TextFormat textFormat() const;
225 
226     /**
227      * @return plaintext version of the text (if richtext)
228      */
229     QString toPlainText() const;
230 
231     /**
232      * Set the creation date of the note (stored in the mime header)
233      */
234     void setCreationDate(const QDateTime &creationDate);
235 
236     /**
237      * Returns the creation date of the note
238      */
239     QDateTime creationDate() const;
240 
241     /**
242      * Set the lastModified-date of the note
243      */
244     void setLastModifiedDate(const QDateTime &lastModifiedDate);
245 
246     /**
247      * Returns the lastModified-date of the note
248      */
249     QDateTime lastModifiedDate() const;
250 
251     /**
252      * Set the origin (creator) of the note (stored in the mime header)
253      * This is usually the application creating the note.
254      * @param from must be an address in the style of foo@kde.org.
255      */
256     void setFrom(const QString &from);
257 
258     /**
259      * Returns the origin (creator) of the note
260      */
261     QString from() const;
262 
263     /**
264      * Returns a reference to the list of attachments of the note
265      */
266     QVector<Attachment> &attachments();
267 
268     /**
269      * Returns a reference to the custom-value map
270      * @return key-value map containing all custom values
271      */
272     QMap<QString, QString> &custom();
273 
274     /**
275      * Assemble a KMime message with the given values
276      *
277      * The message can then i.e. be stored inside an akonadi item
278      */
279     KMime::MessagePtr message() const;
280 
281 private:
282     //@cond PRIVATE
283     Q_DISABLE_COPY(NoteMessageWrapper)
284     std::unique_ptr<NoteMessageWrapperPrivate> const d_ptr;
285     Q_DECLARE_PRIVATE(NoteMessageWrapper)
286     //@endcond
287 };
288 
289 }
290 }
291 
292 Q_DECLARE_TYPEINFO(Akonadi::NoteUtils::Attachment, Q_MOVABLE_TYPE);
293