← Back to branch summary

~chris.gagnon/+junk/qtpim-coverage

« back to all changes in this revision

Viewing changes to src/versit/qversitwriter.cpp

  • Committer: chris.gagnon
  • Date: 2013-12-10 23:09:37 UTC
  • Revision ID: chris.gagnon@canonical.com-20131210230937-2akf1ft1edcttk87
first post

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/versit/qversitwriter.cpp
 
1
/****************************************************************************
 
2
**
 
3
** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
 
4
** Contact: http://www.qt-project.org/legal
 
5
**
 
6
** This file is part of the QtVersit module of the Qt Toolkit.
 
7
**
 
8
** $QT_BEGIN_LICENSE:LGPL$
 
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 Digia.  For licensing terms and
 
14
** conditions see http://qt.digia.com/licensing.  For further information
 
15
** use the contact form at http://qt.digia.com/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 as published by the Free Software
 
20
** Foundation and appearing in the file LICENSE.LGPL included in the
 
21
** packaging of this file.  Please review the following information to
 
22
** ensure the GNU Lesser General Public License version 2.1 requirements
 
23
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
 
24
**
 
25
** In addition, as a special exception, Digia gives you certain additional
 
26
** rights.  These rights are described in the Digia Qt LGPL Exception
 
27
** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
 
28
**
 
29
** GNU General Public License Usage
 
30
** Alternatively, this file may be used under the terms of the GNU
 
31
** General Public License version 3.0 as published by the Free Software
 
32
** Foundation and appearing in the file LICENSE.GPL included in the
 
33
** packaging of this file.  Please review the following information to
 
34
** ensure the GNU General Public License version 3.0 requirements will be
 
35
** met: http://www.gnu.org/copyleft/gpl.html.
 
36
**
 
37
**
 
38
** $QT_END_LICENSE$
 
39
**
 
40
****************************************************************************/
 
41
 
 
42
#include <qversitwriter.h>
 
43
#include "qversitwriter_p.h"
 
44
#include "qversitutils_p.h"
 
45
 
 
46
#include <QStringList>
 
47
#include <QTextCodec>
 
48
#include <QBuffer>
 
49
 
 
50
QT_BEGIN_NAMESPACE_VERSIT
 
51
 
 
52
/*!
 
53
  \class QVersitWriter
 
54
  \brief The QVersitWriter class writes Versit documents such as vCards to a device.
 
55
  \ingroup versit
 
56
  \inmodule QtVersit
 
57
 
 
58
  QVersitWriter converts a QVersitDocument into its textual representation.
 
59
  QVersitWriter supports writing to an abstract I/O device
 
60
  which can be for example a file or a memory buffer.
 
61
  The writing can be done asynchronously and the waitForFinished()
 
62
  function can be used to implement a blocking write.
 
63
 
 
64
  The serialization of the document is done in accordance with the type of the QVersitDocument
 
65
  being written.  The value of each QVersitProperty is encoded according to the type of object:
 
66
  \list
 
67
  \li \l{QString}{QStrings} are serialized verbatim, unless the default codec of the writer cannot
 
68
  encode the string: in this case, UTF-8 is used to encode it (and the CHARSET parameter added to
 
69
  the property, as per the vCard 2.1 specification).  If the document type is vCard 2.1,
 
70
  quoted-printable encoding may also be performed.
 
71
  \li \l{QByteArray}{QByteArrays} are assumed to be binary data and are serialized as base-64 encoded
 
72
  values.
 
73
  \li \l{QVersitDocument}{QVersitDocuments} are serialized as a nested document (eg. as per the
 
74
  AGENT property in vCard).
 
75
  \endlist
 
76
 
 
77
  \sa QVersitDocument, QVersitProperty
 
78
 */
 
79
 
 
80
 
 
81
/*!
 
82
 * \enum QVersitWriter::Error
 
83
 * This enum specifies an error that occurred during the most recent operation:
 
84
 * \value NoError The most recent operation was successful
 
85
 * \value UnspecifiedError The most recent operation failed for an undocumented reason
 
86
 * \value IOError The most recent operation failed because of a problem with the device
 
87
 * \value OutOfMemoryError The most recent operation failed due to running out of memory
 
88
 * \value NotReadyError The most recent operation failed because there is an operation in progress
 
89
 */
 
90
 
 
91
/*!
 
92
 * \enum QVersitWriter::State
 
93
 * Enumerates the various states that a reader may be in at any given time
 
94
 * \value InactiveState Write operation not yet started
 
95
 * \value ActiveState Write operation started, not yet finished
 
96
 * \value CanceledState Write operation is finished due to cancelation
 
97
 * \value FinishedState Write operation successfully completed
 
98
 */
 
99
 
 
100
/*!
 
101
 * \fn QVersitWriter::stateChanged(QVersitWriter::State state)
 
102
 * The signal is emitted by the writer when its state has changed (eg. when it has finished
 
103
 * writing to the device).
 
104
 * \a state is the new state of the writer.
 
105
 */
 
106
 
 
107
/*! Constructs a new writer. */
 
108
QVersitWriter::QVersitWriter() : d(new QVersitWriterPrivate)
 
109
{
 
110
    d->init(this);
 
111
}
 
112
 
 
113
/*! Constructs a new writer that writes to \a outputDevice. */
 
114
QVersitWriter::QVersitWriter(QIODevice *outputDevice) : d(new QVersitWriterPrivate)
 
115
{
 
116
    d->init(this);
 
117
    d->mIoDevice = outputDevice;
 
118
}
 
119
 
 
120
/*! Constructs a new writer that appends to \a outputBytes. */
 
121
QVersitWriter::QVersitWriter(QByteArray *outputBytes) : d(new QVersitWriterPrivate)
 
122
{
 
123
    d->init(this);
 
124
    d->mOutputBytes.reset(new QBuffer);
 
125
    d->mOutputBytes->setBuffer(outputBytes);
 
126
    d->mOutputBytes->open(QIODevice::WriteOnly);
 
127
    d->mIoDevice = d->mOutputBytes.data();
 
128
}
 
129
 
 
130
/*!
 
131
 * Frees the memory used by the writer.
 
132
 * Waits until a pending asynchronous writing has been completed.
 
133
 */
 
134
QVersitWriter::~QVersitWriter()
 
135
{
 
136
    d->wait();
 
137
    delete d;
 
138
}
 
139
 
 
140
/*!
 
141
 * Sets the device used for writing to \a device.
 
142
 * Does not take ownership of the device.
 
143
 */
 
144
void QVersitWriter::setDevice(QIODevice* device)
 
145
{
 
146
    d->mOutputBytes.reset(0);
 
147
    d->mIoDevice = device;
 
148
}
 
149
 
 
150
/*!
 
151
 * Returns the device used for writing, or 0 if no device has been set.
 
152
 */
 
153
QIODevice* QVersitWriter::device() const
 
154
{
 
155
    if (d->mOutputBytes.isNull())
 
156
        return d->mIoDevice;
 
157
    else
 
158
        return 0;
 
159
}
 
160
 
 
161
/*!
 
162
 * Sets the default codec for the writer to use for writing the entire output.
 
163
 *
 
164
 * If \a codec is NULL, the writer uses the codec according to the specification prescribed default.
 
165
 * (for vCard 2.1, ASCII; for vCard 3.0, UTF-8).
 
166
 */
 
167
void QVersitWriter::setDefaultCodec(QTextCodec *codec)
 
168
{
 
169
    d->mDefaultCodec = codec;
 
170
}
 
171
 
 
172
/*!
 
173
 * Returns the document's codec.
 
174
 */
 
175
QTextCodec* QVersitWriter::defaultCodec() const
 
176
{
 
177
    return d->mDefaultCodec;
 
178
}
 
179
 
 
180
/*!
 
181
 * Returns the state of the writer.
 
182
 */
 
183
QVersitWriter::State QVersitWriter::state() const
 
184
{
 
185
    return d->state();
 
186
}
 
187
 
 
188
/*!
 
189
 * Returns the error encountered by the last operation.
 
190
 */
 
191
QVersitWriter::Error QVersitWriter::error() const
 
192
{
 
193
    return d->error();
 
194
}
 
195
 
 
196
/*!
 
197
 * Starts writing \a input to device() asynchronously.  The serialization format is determined based
 
198
 * on the contents of the input documents.
 
199
 *
 
200
 * Returns false if the output device has not been set or opened or if there is another asynchronous
 
201
 * write operation already pending.  Signal \l stateChanged() is emitted with parameter
 
202
 * FinishedState when the writing has finished.
 
203
 *
 
204
 * The device must be already open.  The client is responsible for closing it when finished.
 
205
 */
 
206
bool QVersitWriter::startWriting(const QList<QVersitDocument>& input)
 
207
{
 
208
    return startWriting(input, QVersitDocument::InvalidType);
 
209
}
 
210
 
 
211
/*!
 
212
 * Starts writing \a input to device() asynchronously using the serialization format specified by \a
 
213
 * type.  If \a type is QVersitDocument::InvalidType, the format will be determined based on the
 
214
 * contents of the input documents.
 
215
 *
 
216
 * Returns false if the output device has not been set or opened or if there is another asynchronous
 
217
 * write operation already pending.  Signal \l stateChanged() is emitted with parameter
 
218
 * FinishedState when the writing has finished.
 
219
 *
 
220
 * The device must be already open.  The client is responsible for closing it when finished.
 
221
 */
 
222
bool QVersitWriter::startWriting(const QList<QVersitDocument>& input, QVersitDocument::VersitType type)
 
223
{
 
224
    d->mInput = input;
 
225
    if (d->state() == ActiveState || d->isRunning()) {
 
226
        d->setError(QVersitWriter::NotReadyError);
 
227
        return false;
 
228
    } else if (!d->mIoDevice || !d->mIoDevice->isWritable()) {
 
229
        d->setError(QVersitWriter::IOError);
 
230
        return false;
 
231
    } else {
 
232
        d->setState(ActiveState);
 
233
        d->setError(NoError);
 
234
        d->setDocumentType(type);
 
235
        d->start();
 
236
        return true;
 
237
    }
 
238
}
 
239
 
 
240
/*!
 
241
 * Starts writing \a input to device() asynchronously.  The serialization format is determined based
 
242
 * on the contents of the input documents.
 
243
 *
 
244
 * Returns false if the output device has not been set or opened or if there is another asynchronous
 
245
 * write operation already pending.  Signal \l stateChanged() is emitted with parameter
 
246
 * FinishedState when the writing has finished.
 
247
 *
 
248
 * The device must be already open.  The client is responsible for closing it when finished.
 
249
 */
 
250
bool QVersitWriter::startWriting(const QVersitDocument& input)
 
251
{
 
252
    return startWriting(QList<QVersitDocument>() << input, QVersitDocument::InvalidType);
 
253
}
 
254
 
 
255
/*!
 
256
 * Starts writing \a input to device() asynchronously using the serialization format specified by \a
 
257
 * type.  If \a type is QVersitDocument::InvalidType, the format will be determined based on the
 
258
 * contents of the input documents.
 
259
 *
 
260
 * Returns false if the output device has not been set or opened or if there is another asynchronous
 
261
 * write operation already pending.  Signal \l stateChanged() is emitted with parameter
 
262
 * FinishedState when the writing has finished.
 
263
 *
 
264
 * The device must be already open.  The client is responsible for closing it when finished.
 
265
 */
 
266
bool QVersitWriter::startWriting(const QVersitDocument& input, QVersitDocument::VersitType type)
 
267
{
 
268
    return startWriting(QList<QVersitDocument>() << input, type);
 
269
}
 
270
 
 
271
/*!
 
272
 * Attempts to asynchronously cancel the write request.
 
273
 */
 
274
void QVersitWriter::cancel()
 
275
{
 
276
    d->setCanceling(true);
 
277
}
 
278
 
 
279
/*!
 
280
 * If the state is ActiveState, blocks until the writer has finished writing or \a msec milliseconds
 
281
 * has elapsed, returning true if it successfully finishes or is cancelled by the user.
 
282
 * If \a msec is negative or zero, the function blocks until the writer has finished, regardless of
 
283
 * how long it takes.
 
284
 * If the state is FinishedState, returns true immediately.
 
285
 * Otherwise, returns false immediately.
 
286
 */
 
287
bool QVersitWriter::waitForFinished(int msec)
 
288
{
 
289
    State state = d->state();
 
290
    if (state != InactiveState) {
 
291
        if (msec <= 0)
 
292
            return d->wait(ULONG_MAX);
 
293
        else
 
294
            return d->wait(msec);
 
295
    } else {
 
296
        return false;
 
297
    }
 
298
}
 
299
 
 
300
#include "moc_qversitwriter.cpp"
 
301
QT_END_NAMESPACE_VERSIT