1/****************************************************************************
2**
3** Copyright (C) 2015 The Qt Company Ltd.
4** Contact: http://www.qt.io/licensing/
5**
6** This file is part of the QtVersitOrganizer module of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL21$
9** Commercial License Usage
10** Licensees holding valid commercial Qt licenses may use this file in
11** accordance with the commercial license agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and The Qt Company. For licensing terms
14** and conditions see http://www.qt.io/terms-conditions. For further
15** information use the contact form at http://www.qt.io/contact-us.
16**
17** GNU Lesser General Public License Usage
18** Alternatively, this file may be used under the terms of the GNU Lesser
19** General Public License version 2.1 or version 3 as published by the Free
20** Software Foundation and appearing in the file LICENSE.LGPLv21 and
21** LICENSE.LGPLv3 included in the packaging of this file. Please review the
22** following information to ensure the GNU Lesser General Public License
23** requirements will be met: https://www.gnu.org/licenses/lgpl.html and
24** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
25**
26** As a special exception, The Qt Company gives you certain additional
27** rights. These rights are described in The Qt Company LGPL Exception
28** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
29**
30** $QT_END_LICENSE$
31**
32****************************************************************************/
33
34#include "qversitorganizerexporter.h"
35#include "qversitorganizerexporter_p.h"
36
37#include <QtOrganizer/qorganizer.h>
38
39#include <QtVersit/qversitproperty.h>
40
41QTORGANIZER_USE_NAMESPACE
42QTVERSIT_USE_NAMESPACE
43
44QT_BEGIN_NAMESPACE_VERSITORGANIZER
45
46/*!
47 \class QVersitOrganizerExporter
48 \brief The QVersitOrganizerExporter class converts \l {QOrganizerItem}{QOrganizerItems} into
49 \l {QVersitDocument}{QVersitDocuments}.
50
51 \ingroup versit
52 \inmodule QtVersit
53
54 This class is used to convert a list of \l {QOrganizerItem}{QOrganizerItems} (which may be stored
55 in a QOrganizerManager) into a QVersitDocument (which may be written to an I/O device using
56 QVersitReader. While multiple items are provided as input, a single QVersitDocument is produced
57 as output. Unless there is an error, there is a one-to-one mapping between organizer items
58 and sub-documents of the result.
59 */
60
61/*!
62 \class QVersitOrganizerExporterDetailHandler
63 \brief The QVersitOrganizerExporterDetailHandler class is an interface for specifying
64 custom export behaviour for certain organizer item details.
65
66 \ingroup versit-extension
67 \inmodule QtVersit
68
69 For general information on extending Qt Versit, see the document on
70 \l{Qt Versit Plugins}.
71
72 \sa QVersitOrganizerExporter
73 */
74
75/*!
76 \fn QVersitOrganizerExporterDetailHandler::~QVersitOrganizerExporterDetailHandler()
77 Frees any memory in use by this handler.
78 */
79
80/*!
81 \fn void QVersitOrganizerExporterDetailHandler::detailProcessed(const QOrganizerItem& item, const QOrganizerItemDetail& detail, const QVersitDocument& document, QSet<int>* processedFields, QList<QVersitProperty>* toBeRemoved, QList<QVersitProperty>* toBeAdded)
82
83 Process \a detail and provide a list of updated \l{QVersitProperty}{QVersitProperties} by
84 modifying the \a toBeRemoved and \a toBeAdded lists.
85
86 This function is called on every QOrganizerItemDetail encountered during an export, after the
87 detail has been processed by the QVersitOrganizerExporter. An implementation of this function can
88 be made to provide support for QOrganizerItemDetails not supported by QVersitOrganizerExporter.
89
90 The supplied \a item is the container for the \a detail. \a processedFields contains a list of
91 fields in the \a detail that were considered by the QVersitOrganizerExporter or another handler in
92 processing the detail. \a document holds the state of the document before the detail was
93 processed by the exporter.
94
95 \a toBeRemoved and \a toBeAdded are initially filled with a list of properties that the exporter
96 will remove from and add to the document. These lists can be modified (by removing, modifying or
97 adding properties) by the handler to control the changes that will actually be made to the
98 document. If a property is to be modified in the document, the old version will appear in the
99 \a toBeRemoved list and the new version will appear in the \a toBeAdded list. When the handler
100 uses a field from the detail, it should update the processedFields set to reflect this to inform
101 later handlers that the field has already been processed.
102
103 After the handler returns control back to the exporter, the properties in the \a toBeRemoved
104 list will be removed and the properties in the \a toBeAdded list will be appended to the document.
105 */
106
107/*!
108 \fn void QVersitOrganizerExporterDetailHandler::itemProcessed(const QOrganizerItem& item, QVersitDocument* document)
109 Perform any final processing on the \a document generated by the \a item. This can be
110 implemented by the handler to clear any internal state before moving onto the next item.
111
112 This function is called after all QOrganizerItemDetails have been handled by the
113 QVersitOrganizerExporter.
114*/
115
116/*!
117 \enum QVersitOrganizerExporter::Error
118 This enum specifies an error that occurred during the most recent call to exportItems()
119 \value NoError The most recent operation was successful
120 \value EmptyOrganizerError One of the organizer items was empty
121 \value UnknownComponentTypeError One of the components in the iCalendar file is not supported
122 \value UnderspecifiedOccurrenceError An event or todo exception was found which did not specify both its parent and a specifier for which instance to override
123 */
124
125/*! Constructs a new exporter */
126QVersitOrganizerExporter::QVersitOrganizerExporter()
127 : d(new QVersitOrganizerExporterPrivate)
128{
129}
130
131/*!
132 * Constructs a new exporter for the given \a profile. The profile strings should be one of those
133 * defined by QVersitOrganizerHandlerFactory, or a value otherwise agreed to by a \l{Qt Versit
134 * Plugins}{Versit plugin}.
135 *
136 * The profile determines which plugins will be loaded to supplement the exporter.
137 */
138QVersitOrganizerExporter::QVersitOrganizerExporter(const QString& profile)
139 : d(new QVersitOrganizerExporterPrivate(profile))
140{
141}
142
143/*! Frees the memory used by the exporter */
144QVersitOrganizerExporter::~QVersitOrganizerExporter()
145{
146 delete d;
147}
148
149/*!
150 * Converts \a items into a QVersitDocument, using the format given by \a versitType.
151 * Returns true on success. If any of the items could not be exported, false is returned and
152 * errorMap() will return a list describing the errors that occurred. The successfully exported
153 * components will still be available via document().
154 *
155 * \sa document(), errorMap()
156 */
157bool QVersitOrganizerExporter::exportItems(
158 const QList<QOrganizerItem>& items,
159 QVersitDocument::VersitType versitType)
160{
161 int itemIndex = 0;
162 d->mErrors.clear();
163 d->mResult.clear();
164 d->mResult.setType(versitType);
165 d->mResult.setComponentType(QStringLiteral("VCALENDAR"));
166 bool ok = true;
167 QList<QTVERSIT_PREPEND_NAMESPACE(QVersitDocument)> results;
168 foreach (const QOrganizerItem& item, items) {
169 QTVERSIT_PREPEND_NAMESPACE(QVersitDocument) document;
170 document.setType(versitType);
171 QVersitOrganizerExporter::Error error;
172 if (d->exportItem(item, document: &document, error: &error)) {
173 results.append(t: document);
174 } else {
175 d->mErrors.insert(akey: itemIndex, avalue: error);
176 ok = false;
177 }
178 itemIndex++;
179 }
180 d->mResult.setSubDocuments(results);
181
182 return ok;
183}
184
185/*!
186 *Returns the document exported in the most recent call to exportItems().
187 *
188 * \sa exportItems()
189 */
190QVersitDocument QVersitOrganizerExporter::document() const
191{
192 return d->mResult;
193}
194
195/*!
196 * \fn QVersitOrganizerExporter::errorMap() const
197 *
198 *Returns the map of errors encountered in the most recent call to exportItems(). The key is
199 * the index into the input list of organizer items and the value is the error that occurred on that
200 * item. If errors occur, export does not generate EmptyContactError or NoNameError errors but
201 * just succeeds in creating the empty, albeit invalid, vCard. QVersitContactExporter never fails.
202 *
203 * \sa exportItems()
204 */
205QMap<int, QVersitOrganizerExporter::Error> QVersitOrganizerExporter::errorMap() const
206{
207 return d->mErrors;
208}
209
210/*!
211 * Sets \a handler to be the handler for processing QOrganizerItemDetails, or 0 to have no handler.
212 *
213 * Does not take ownership of the handler. The client should ensure the handler remains valid for
214 * the lifetime of the exporter.
215 *
216 * Only one detail handler can be set. If another detail handler was previously set, it will no
217 * longer be associated with the exporter.
218 */
219void QVersitOrganizerExporter::setDetailHandler(QVersitOrganizerExporterDetailHandler* handler)
220{
221 d->mDetailHandler = handler;
222}
223
224QT_END_NAMESPACE_VERSITORGANIZER
225

source code of qtpim/src/versitorganizer/qversitorganizerexporter.cpp