1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
|
/****************************************************************************
**
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** No Commercial Usage
** This file contains pre-release code and may not be distributed.
** You may use this file in accordance with the terms and conditions
** contained in the Technology Preview License Agreement accompanying
** this package.
**
** GNU Free Documentation License
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of this
** file.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page versit.html
\title Versit
\brief An API to import and export to the vCard and iCalendar formats.
\ingroup mobility
\tableofcontents
\section1 Namespace
The QtMobility APIs are placed into the \i{QtMobility} namespace. This is done
to facilitate the future migration of QtMobility APIs into Qt. See the
\l {Quickstart guide} for an example on how the
namespace impacts on application development.
\section1 Overview
The Versit API provides a library to convert \l{QContact}{QContacts} to and from
\l{http://en.wikipedia.org/wiki/Vcard}{vCard} files, and to convert
\l{QOrganizerItem}{QOrganizerItems} to and from
\l{http://en.wikipedia.org/wiki/ICalendar}{iCalendar} files.
Because vCard and iCalendar share the same structure, they are represented in
abstract form with a common class, namely QVersitDocument. vCard and iCalendar
files can be parsed into QVersitDocument form using QVersitReader.
QVersitDocument objects can be written to an I/O device using QVersitWriter.
A QVersitDocument object can represent either a vCard or an iCalendar.
\l{QVersitDocument}{QVersitDocuments} representing vCards can be converted to
\l{QContact}{QContacts} using QVersitContactImporter.
\l{QVersitDocument}{QVersitDocuments} representing iCalendars can be converted
to \l{QOrganizerItem}{QOrganizerItems} using QVersitOrganizerImporter.
\l{QContact}{QContacts} and \l{QOrganizerItem}{QOrganizerItems} can be converted
to \l{QVersitDocument}{QVersitDocuments} using QVersitContactExporter and
QVersitOrganizerExporter, respectively.
Currently \l{QVersitReader} and \l{QVersitWriter} support
reading and writing vCard 2.1, vCard 3.0 and iCalendar 2.0 format documents.
Please note that the QtMobility Organizer API is still under development, so
the Qt Versit API classes related to importing and exporting organizer items
is subject to change.
Versit \reg is a trademark of the Internet Mail Consortium.
\section1 Usage
The following example goes through the process of reading a vCard and importing
it to QContact format, then exporting and writing it back out.
First, let's create some data to read. In this case, we create a QBuffer as a demonstration, but
any QIODevice will work.
\snippet ../../doc/src/snippets/qtversitdocsample/qtversitdocsample.cpp Complete example - create
QVersitReader can be used to parse a vCard or iCalendar from an I/O device to
produce a list of QVersitDocuments.
\snippet ../../doc/src/snippets/qtversitdocsample/qtversitdocsample.cpp Complete example - read
QVersitDocuments aren't very useful to the QtContacts API. They need to be imported using the
QVersitContactImporter. If the QVersitDocuments were iCalendar objects, they could be imported
using QVersitOrganizerImporter.
\snippet ../../doc/src/snippets/qtversitdocsample/qtversitdocsample.cpp Complete example - import
Conversely, QVersitContactExporter can be used to convert from QContacts to QVersitDocuments.
(QVersitOrganizerExporter can be used for QOrganizerItem):
\snippet ../../doc/src/snippets/qtversitdocsample/qtversitdocsample.cpp Complete example - export
To complete the exporting process, QVersitWriter can be used to write to an I/O device.
\snippet ../../doc/src/snippets/qtversitdocsample/qtversitdocsample.cpp Complete example - write
\section1 Classes
The main classes for a client interested in importing or exporting vCard and
iCalendar documents are:
\list
\o \l{QVersitProperty}
\o \l{QVersitDocument}
\o \l{QVersitReader}
\o \l{QVersitWriter}
\o \l{QVersitContactImporter}
\o \l{QVersitContactExporter}
\o \l{QVersitOrganizerImporter}
\o \l{QVersitOrganizerExporter}
\endlist
It is also possible to extend the behaviour of the importer and exporter classes
by writing handlers and plugins. For more details, please see the document on
\l{Versit Plugins}.
\annotatedlist versit-extension
\section1 Supported Features
Please see the \l{vcardsupport}{Supported vCard Features} document for a list of vCard
features that the Versit module
supports.
*/
|
