← Back to branch summary

~chris.gagnon/+junk/qtpim-coverage

« back to all changes in this revision

Viewing changes to src/versit/doc/src/versitplugins.qdoc

  • 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/doc/src/versitplugins.qdoc
 
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 documentation of the Qt PIM Module.
 
7
**
 
8
** $QT_BEGIN_LICENSE:FDL$
 
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 Free Documentation License Usage
 
18
** Alternatively, this file may be used under the terms of the GNU Free
 
19
** Documentation License version 1.3 as published by the Free Software
 
20
** Foundation and appearing in the file included in the packaging of
 
21
** this file.  Please review the following information to ensure
 
22
** the GNU Free Documentation License version 1.3 requirements
 
23
** will be met: http://www.gnu.org/copyleft/fdl.html.
 
24
** $QT_END_LICENSE$
 
25
**
 
26
****************************************************************************/
 
27
 
 
28
/*!
 
29
\page versitplugins.html
 
30
 
 
31
\title Qt Versit Plugins
 
32
 
 
33
While the \l {Qt Versit Overview}{QtVersit API} provides a convenient way to
 
34
import and export vCards,
 
35
it is common to encounter domain-specific vCard properties that the Versit
 
36
importer and exporter classes don't support.  While it would be convenient if
 
37
the base Versit module could support everything, that is not possible because
 
38
there may be properties with the same name that have different semantics in
 
39
different domains.
 
40
 
 
41
\section1 Local Extension with Handlers
 
42
 
 
43
To remedy this, some hooks are provided to allow clients to alter the behaviour
 
44
of QVersitContactImporter and QVersitContactExporter.  The basic mechanisms that
 
45
allow this are the QVersitContactImporterPropertyHandlerV2 and the
 
46
QVersitContactExporterDetailHandlerV2 interfaces.  A client can supplement the
 
47
importer and exporter classes by implementing these interfaces and associating
 
48
them using QVersitContactImporter::setPropertyHandler() and
 
49
QVersitContactExporter::setDetailHandler().
 
50
 
 
51
\section1 Global Extension with Plugins
 
52
 
 
53
While these interfaces allow a single client to supplement the behaviour of
 
54
import and export, there are many cases where the entire deployment of the
 
55
Versit library will be operating under a known context.  For example, the
 
56
library might be deployed on a device on a particular network where all of its
 
57
peers are known to support certain properties.  In this situation, it's
 
58
desirable for all clients of the Versit library on that device to support those
 
59
properties through the Qt Versit API.  It is possible to extend the library
 
60
globally by installing plugins that provide handlers automatically to all users
 
61
of the library on the system.
 
62
 
 
63
Writing a plugin involves these steps:
 
64
\list
 
65
\li Implement a handler class that inherits from QVersitContactHandler.
 
66
\li Implement a plugin class that inherits from QObject and QVersitContactHandlerFactory
 
67
   and implements the createHandler() function to create the handler class.
 
68
\li Include the following two lines at the top of the factory declaration:
 
69
\code
 
70
Q_OBJECT
 
71
Q_INTERFACES(QtVersit::QVersitContactHandlerFactory)
 
72
\endcode
 
73
\li Export the plugin using the Q_EXPORT_PLUGIN2 macro.
 
74
\li Build the plugin using a suitable \tt{.pro} file.
 
75
\li Deploy the plugin in the \tt{plugins/versit} directory.
 
76
\endlist
 
77
 
 
78
Please see the relevant documentation in Qt for more details on writing a
 
79
plugin.
 
80
 
 
81
\section2 Example Plugin: Backup and Restore
 
82
 
 
83
A plugin is provided with the Qt Versit module that provides backup and restore
 
84
functionality to the exporter and importer.
 
85
 
 
86
These can be used by creating the exporter and importer under the "backup"
 
87
profile:
 
88
\code
 
89
QVersitContactExporter exporter(QVersitContactHandlerFactory::ProfileBackup);
 
90
\endcode
 
91
\code
 
92
QVersitContactImporter importer(QVersitContactHandlerFactory::ProfileBackup);
 
93
\endcode
 
94
 
 
95
When applied to the exporter, this handler encodes all writable details that the
 
96
exporter doesn't recognise.  The format it uses to encode the detail is as
 
97
follows:
 
98
\list
 
99
\li All generated properties will have the name X-NOKIA-QCONTACTFIELD
 
100
\li All generated properties will have a single Versit group, and all properties
 
101
 generated from a single detail will have the same group.
 
102
\li All generated properties will have at least the parameters DETAIL, which
 
103
 holds the definition name of the QContactDetail from which it was generated, and
 
104
 FIELD, which holds the name of the field within the detail from which it was
 
105
 generated.
 
106
\li If the field is of type QString or QByteArray, the property's value is set
 
107
 directly to the value of the field.  (For a QByteArray value, the QVersitWriter
 
108
 will base-64 encode it.)
 
109
\li If the field is of type bool, int, uint, QDate, QTime, QDateTime or QUrl a
 
110
 the property's value is set to a string representation of the field.  A
 
111
 parameter DATATYPE is added to the property with value BOOL, INT, UINT, DATE,
 
112
 TIME or DATETIME depending on the type.
 
113
\li If the field is of some other type, the field value is encoded to a
 
114
 QByteArray via QDataStream (and the resulting byte array is base-64 encoded by
 
115
 the QVersitWriter).  In this case, the parameter DATATYPE=VARIANT is added to
 
116
 the Versit property.
 
117
\endlist
 
118
 
 
119
For example, a detail with definition name "Pet" and fields "Name"="Rex" and
 
120
"Age"=(int)14 will be exported to the vCard properties:
 
121
\code
 
122
G0.X-NOKIA-QCONTACTFIELD;DETAIL=Pet;FIELD=Name:Rex
 
123
G0.X-NOKIA-QCONTACTFIELD;DETAIL=Pet;FIELD=Age;DATATYPE=INT:14
 
124
\endcode
 
125
 
 
126
And the next detail (say, "Pet" with a field "Name"="Molly" will generate:
 
127
\code
 
128
G1.X-NOKIA-QCONTACTFIELD;DETAIL=Pet;FIELD=Name:Molly
 
129
\endcode
 
130
 
 
131
When applied to the importer, this handler decodes the properties that were
 
132
generated by the exporter under the backup profile.
 
133
 
 
134
The code for this plugin can be perused in the
 
135
\tt{plugins/versit/backuphandler} directory.
 
136
 
 
137
*/