/usr/share/qt5/doc/qtversit/versitplugins.html is in qtpim5-doc-html 5.0~git20140515~29475884-0ubuntu24~7.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 | <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- versitplugins.qdoc -->
<title>Qt Versit Plugins | Qt 5.0</title>
<link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
<script type="text/javascript">
document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
// loading style sheet breaks anchors that were jumped to before
// so force jumping to anchor again
setTimeout(function() {
var anchor = location.hash;
// need to jump to different anchor first (e.g. none)
location.hash = "#";
setTimeout(function() {
location.hash = anchor;
}, 0);
}, 0);
</script>
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<table><tr>
<td >Qt 5.0</td><td >Qt Versit Plugins</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right">Qt 5.0.0 Reference Documentation</td>
</tr></table>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#local-extension-with-handlers">Local Extension with Handlers</a></li>
<li class="level1"><a href="#global-extension-with-plugins">Global Extension with Plugins</a></li>
<li class="level2"><a href="#example-plugin-backup-and-restore">Example Plugin: Backup and Restore</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Qt Versit Plugins</h1>
<span class="subtitle"></span>
<!-- $$$versitplugins.html-description -->
<div class="descr"> <a name="details"></a>
<p>While the <a href="versit.html">QtVersit API</a> 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.</p>
<a name="local-extension-with-handlers"></a>
<h2 id="local-extension-with-handlers">Local Extension with Handlers</h2>
<p>To remedy this, some hooks are provided to allow clients to alter the behaviour of <a href="qversitcontactimporter.html">QVersitContactImporter</a> and <a href="qversitcontactexporter.html">QVersitContactExporter</a>. The basic mechanisms that allow this are the <a href="qversitcontactimporterpropertyhandlerv2.html">QVersitContactImporterPropertyHandlerV2</a> and the <a href="qversitcontactexporterdetailhandlerv2.html">QVersitContactExporterDetailHandlerV2</a> interfaces. A client can supplement the importer and exporter classes by implementing these interfaces and associating them using <a href="qversitcontactimporter.html#setPropertyHandler">QVersitContactImporter::setPropertyHandler</a>() and <a href="qversitcontactexporter.html#setDetailHandler">QVersitContactExporter::setDetailHandler</a>().</p>
<a name="global-extension-with-plugins"></a>
<h2 id="global-extension-with-plugins">Global Extension with Plugins</h2>
<p>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.</p>
<p>Writing a plugin involves these steps:</p>
<ul>
<li>Implement a handler class that inherits from <a href="qversitcontacthandler.html">QVersitContactHandler</a>.</li>
<li>Implement a plugin class that inherits from QObject and QVersitContactHandlerFactory and implements the createHandler() function to create the handler class.</li>
<li>Include the following two lines at the top of the factory declaration:<pre class="cpp">
Q_OBJECT
Q_INTERFACES(<span class="type"><a href="qtversit-module.html">QtVersit</a></span><span class="operator">::</span><span class="type">QVersitContactHandlerFactory</span>)
</pre>
</li>
<li>Export the plugin using the Q_EXPORT_PLUGIN2 macro.</li>
<li>Build the plugin using a suitable <code>.pro</code> file.</li>
<li>Deploy the plugin in the <code>plugins/versit</code> directory.</li>
</ul>
<p>Please see the relevant documentation in Qt for more details on writing a plugin.</p>
<a name="example-plugin-backup-and-restore"></a>
<h3 >Example Plugin: Backup and Restore</h3>
<p>A plugin is provided with the Qt Versit module that provides backup and restore functionality to the exporter and importer.</p>
<p>These can be used by creating the exporter and importer under the "backup" profile:</p>
<pre class="cpp">
<span class="type"><a href="qversitcontactexporter.html">QVersitContactExporter</a></span> exporter(<span class="type">QVersitContactHandlerFactory</span><span class="operator">::</span>ProfileBackup);
</pre>
<pre class="cpp">
<span class="type"><a href="qversitcontactimporter.html">QVersitContactImporter</a></span> importer(<span class="type">QVersitContactHandlerFactory</span><span class="operator">::</span>ProfileBackup);
</pre>
<p>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:</p>
<ul>
<li>All generated properties will have the name X-NOKIA-QCONTACTFIELD</li>
<li>All generated properties will have a single Versit group, and all properties generated from a single detail will have the same group.</li>
<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>
<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 <a href="qversitwriter.html">QVersitWriter</a> will base-64 encode it.)</li>
<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>
<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 <a href="qversitwriter.html">QVersitWriter</a>). In this case, the parameter DATATYPE=VARIANT is added to the Versit property.</li>
</ul>
<p>For example, a detail with definition name "Pet" and fields "Name"="Rex" and "Age"=(int)14 will be exported to the vCard properties:</p>
<pre class="cpp">
G0<span class="operator">.</span>X<span class="operator">-</span>NOKIA<span class="operator">-</span>QCONTACTFIELD;DETAIL<span class="operator">=</span>Pet;FIELD<span class="operator">=</span>Name:Rex
G0<span class="operator">.</span>X<span class="operator">-</span>NOKIA<span class="operator">-</span>QCONTACTFIELD;DETAIL<span class="operator">=</span>Pet;FIELD<span class="operator">=</span>Age;DATATYPE<span class="operator">=</span>INT:<span class="number">14</span>
</pre>
<p>And the next detail (say, "Pet" with a field "Name"="Molly" will generate:</p>
<pre class="cpp">
G1<span class="operator">.</span>X<span class="operator">-</span>NOKIA<span class="operator">-</span>QCONTACTFIELD;DETAIL<span class="operator">=</span>Pet;FIELD<span class="operator">=</span>Name:Molly
</pre>
<p>When applied to the importer, this handler decodes the properties that were generated by the exporter under the backup profile.</p>
<p>The code for this plugin can be perused in the <code>plugins/versit/backuphandler</code> directory.</p>
</div>
<!-- @@@versitplugins.html -->
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2017 The Qt Company Ltd.
Documentation contributions included herein are the copyrights of
their respective owners.<br> The documentation provided herein is licensed under the terms of the <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation License version 1.3</a> as published by the Free Software Foundation.<br> Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. </p>
</div>
</body>
</html>
|