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
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
|
/****************************************************************************
**
** Copyright (C) 2015 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt PIM Module.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** 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. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page versitplugins.html
\title Qt Versit Plugins
While the \l {Qt Versit Overview}{QtVersit API} provides a convenient way to
import and export vCards,
it is common to encounter domain-specific vCard properties that the Versit
importer and exporter classes don't support. While it would be convenient if
the base Versit module could support everything, that is not possible because
there may be properties with the same name that have different semantics in
different domains.
\section1 Local Extension with Handlers
To remedy this, some hooks are provided to allow clients to alter the behaviour
of QVersitContactImporter and QVersitContactExporter. The basic mechanisms that
allow this are the QVersitContactImporterPropertyHandlerV2 and the
QVersitContactExporterDetailHandlerV2 interfaces. A client can supplement the
importer and exporter classes by implementing these interfaces and associating
them using QVersitContactImporter::setPropertyHandler() and
QVersitContactExporter::setDetailHandler().
\section1 Global Extension with Plugins
While these interfaces allow a single client to supplement the behaviour of
import and export, there are many cases where the entire deployment of the
Versit library will be operating under a known context. For example, the
library might be deployed on a device on a particular network where all of its
peers are known to support certain properties. In this situation, it's
desirable for all clients of the Versit library on that device to support those
properties through the Qt Versit API. It is possible to extend the library
globally by installing plugins that provide handlers automatically to all users
of the library on the system.
Writing a plugin involves these steps:
\list
\li Implement a handler class that inherits from QVersitContactHandler.
\li Implement a plugin class that inherits from QObject and QVersitContactHandlerFactory
and implements the createHandler() function to create the handler class.
\li Include the following two lines at the top of the factory declaration:
\code
Q_OBJECT
Q_INTERFACES(QtVersit::QVersitContactHandlerFactory)
\endcode
\li Export the plugin using the Q_EXPORT_PLUGIN2 macro.
\li Build the plugin using a suitable \tt{.pro} file.
\li Deploy the plugin in the \tt{plugins/versit} directory.
\endlist
Please see the relevant documentation in Qt for more details on writing a
plugin.
\section2 Example Plugin: Backup and Restore
A plugin is provided with the Qt Versit module that provides backup and restore
functionality to the exporter and importer.
These can be used by creating the exporter and importer under the "backup"
profile:
\code
QVersitContactExporter exporter(QVersitContactHandlerFactory::ProfileBackup);
\endcode
\code
QVersitContactImporter importer(QVersitContactHandlerFactory::ProfileBackup);
\endcode
When applied to the exporter, this handler encodes all writable details that the
exporter doesn't recognise. The format it uses to encode the detail is as
follows:
\list
\li All generated properties will have the name X-NOKIA-QCONTACTFIELD
\li All generated properties will have a single Versit group, and all properties
generated from a single detail will have the same group.
\li All generated properties will have at least the parameters DETAIL, which
holds the definition name of the QContactDetail from which it was generated, and
FIELD, which holds the name of the field within the detail from which it was
generated.
\li If the field is of type QString or QByteArray, the property's value is set
directly to the value of the field. (For a QByteArray value, the QVersitWriter
will base-64 encode it.)
\li If the field is of type bool, int, uint, QDate, QTime, QDateTime or QUrl a
the property's value is set to a string representation of the field. A
parameter DATATYPE is added to the property with value BOOL, INT, UINT, DATE,
TIME or DATETIME depending on the type.
\li If the field is of some other type, the field value is encoded to a
QByteArray via QDataStream (and the resulting byte array is base-64 encoded by
the QVersitWriter). In this case, the parameter DATATYPE=VARIANT is added to
the Versit property.
\endlist
For example, a detail with definition name "Pet" and fields "Name"="Rex" and
"Age"=(int)14 will be exported to the vCard properties:
\code
G0.X-NOKIA-QCONTACTFIELD;DETAIL=Pet;FIELD=Name:Rex
G0.X-NOKIA-QCONTACTFIELD;DETAIL=Pet;FIELD=Age;DATATYPE=INT:14
\endcode
And the next detail (say, "Pet" with a field "Name"="Molly" will generate:
\code
G1.X-NOKIA-QCONTACTFIELD;DETAIL=Pet;FIELD=Name:Molly
\endcode
When applied to the importer, this handler decodes the properties that were
generated by the exporter under the backup profile.
The code for this plugin can be perused in the
\tt{plugins/versit/backuphandler} directory.
*/
|
