--- a/src/versit/qversitcontactexporter.cpp Fri Sep 17 08:34:34 2010 +0300
+++ b/src/versit/qversitcontactexporter.cpp Mon Oct 04 01:37:06 2010 +0300
@@ -42,7 +42,6 @@
#include "qversitcontactexporter.h"
#include "qversitcontactexporter_p.h"
-#include "qvcardbackuphandlers_p.h"
#include "qmobilityglobal.h"
#include <qcontact.h>
@@ -57,7 +56,6 @@
implement custom export behaviour for certain contact details.
This interface is replaced by QVersitContactExporterDetailHandlerV2.
- \ingroup versit
\sa QVersitContactExporter
*/
@@ -95,11 +93,11 @@
\class QVersitContactExporterDetailHandlerV2
\brief The QVersitContactExporterDetailHandlerV2 class is an interface for clients wishing to
implement custom export behaviour for certain contact details.
+ \ingroup versit-extension
+ \inmodule QtVersit
This interface supercedes QVersitContactImporterPropertyHandler.
- \ingroup versit
-
\sa QVersitContactExporter
*/
@@ -109,7 +107,7 @@
*/
/*!
- \fn void QVersitContactExporterDetailHandlerV2::detailProcessed(const QContact& contact, const QContactDetail& detail, const QSet<QString>& processedFields, const QVersitDocument& document, QList<QVersitProperty>* toBeRemoved, QList<QVersitProperty>* toBeAdded)
+ \fn void QVersitContactExporterDetailHandlerV2::detailProcessed(const QContact& contact, const QContactDetail& detail, const QVersitDocument& document, QSet<QString>* processedFields, QList<QVersitProperty>* toBeRemoved, QList<QVersitProperty>* toBeAdded)
Process \a detail and provide a list of updated \l{QVersitProperty}{QVersitProperties} by
modifying the \a toBeRemoved and \a toBeAdded lists.
@@ -119,15 +117,17 @@
provide support for QContactDetails not supported by QVersitContactExporter.
The supplied \a contact is the container for the \a detail. \a processedFields contains a list of
- fields in the \a detail that were considered by the QVersitContactExporter in processing the
- detail. \a document holds the state of the document before the detail was processed by the
- exporter.
+ fields in the \a detail that were considered by the QVersitContactExporter or another handler in
+ processing the detail. \a document holds the state of the document before the detail was
+ processed by the exporter.
\a toBeRemoved and \a toBeAdded are initially filled with a list of properties that the exporter
will remove from and add to the document. These lists can be modified (by removing, modifying or
adding properties) by the handler to control the changes that will actually be made to the
document. If a property is to be modified in the document, the old version will appear in the
- \a toBeRemoved list and the new version will appear in the \a toBeAdded list.
+ \a toBeRemoved list and the new version will appear in the \a toBeAdded list. When the handler
+ uses a field from the detail, it should update the processedFields set to reflect this to inform
+ later handlers that the field has already been processed.
After the handler returns control back to the exporter, the properties in the \a toBeRemoved
list will be removed and the properties in the \a toBeAdded list will be appended to the document.
@@ -143,15 +143,11 @@
*/
/*!
- \fn int QVersitContactExporterDetailHandlerV2::version() const
- Returns the version of the handler. Currently, always returns 2.
-*/
-
-/*!
\class QVersitContactExporter
\brief The QVersitContactExporter class converts \l {QContact}{QContacts} into
\l {QVersitDocument}{QVersitDocuments}.
\ingroup versit
+ \inmodule QtVersit
This class is used to convert lists of \l {QContact}{QContacts} (which may be stored in a
QContactManager) into lists of \l {QVersitDocument}{QVersitDocuments} (which may be written to
@@ -159,6 +155,11 @@
between contacts and Versit documents. The exporter can be extended by clients by associating
resource and detail handlers.
+ Here is a simple example of how to use QVersitContactExporter:
+ \snippet ../../doc/src/snippets/qtversitdocsample/qtversitdocsample.cpp Export example
+
+ \section1 Extension via handlers
+
A \l QVersitResourceHandler is associated with the exporter to supply the behaviour for loading
files from persistent storage. By default, this is set to a \l QVersitDefaultResourceHandler,
which supports basic resource loading from the file system. An alternative resource handler
@@ -166,13 +167,17 @@
By associating a \l QVersitContactExporterDetailHandlerV2 with the exporter using
setDetailHandler(), the client can pass in a handler to override the processing of details and/or
- handle details that QVersitContactExporter doesn't support. A "backup" handler is provided by
- QVersitContactExporterDetailHandlerV2::createBackupHandler(), which serializes any details
- that the standard QVersitContactExporter doesn't support to the vCard.
-
-
- An example usage of QVersitContactExporter:
- \snippet ../../doc/src/snippets/qtversitdocsample/qtversitdocsample.cpp Export example
+ handle details that QVersitContactExporter doesn't support. Also, handlers can be implicitly
+ associated to an exporter through the \l{Versit Plugins}{handler plugin mechanism}. The exporter
+ can be constructed with a profile, which gives hints about what kind of handlers should be added
+ to it. For example, the backup profile can be used to instruct the exporter to encode any unknown
+ details in the vCard such that it can be reconstructed later (a QVersitContactImporter constructed
+ under the backup profile can be used to decode it). To illustrate, a backup exporter can be
+ constructed with:
+ \code
+ QVersitContactExporter exporter(QVersitContactHandlerFactory::ProfileBackup);
+ \endcode
+ For more details on how the backup plugin works, see \l{Versit Plugins}
\section1 Exporting group relationships
The exporter does not handle QContactRelationships at all.
@@ -201,55 +206,6 @@
/*!
- Constructs and returns a detail handler that encodes all details not handled by the base exporter.
- The caller is responsible for deleting the object.
-
- This handler encodes all writable details that the exporter doesn't recognise. The format it uses
- to encode the detail is as follows:
- \list
- \o All generated properties will have the name X-NOKIA-QCONTACTFIELD
- \o All generated properties will have a single Versit group, and all properties generated from a
- single detail will have the same group.
- \o 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.
- \o 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.)
- \o 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.
- \o 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
-
- The properties produced by this class can be imported by the importer "backup" property handler
- (created by QVersitContactImporterPropertyHandlerV2::createBackupHandler()) to reproduce the
- original \l{QContactDetail}{QContactDetails}.
-
- Clients wishing to implement their own detail handler and also benefit from the functionality of
- the backup handler can use this function to construct one, and wrap a custom
- QVersitContactExporterDetailHandlerV2 around it. In the implementation of detailProcessed and
- contactProcessed, the respective functions in the backup handler should be called as the last
- step (ensuring the arguments are correctly updated and passed through).
- */
-QVersitContactExporterDetailHandlerV2* QVersitContactExporterDetailHandlerV2::createBackupHandler() {
- return new QVCardExporterBackupHandler;
-}
-
-/*!
* Constructs a new contact exporter
*/
QVersitContactExporter::QVersitContactExporter()
@@ -258,6 +214,18 @@
}
/*!
+ * Constructs a new exporter for the given \a profile. The profile strings should be one of those
+ * defined by QVersitContactHandlerFactory, or a value otherwise agreed to by a \l{Versit
+ * Plugin}{Versit plugin}.
+ *
+ * The profile determines which plugins will be loaded to supplement the exporter.
+ */
+QVersitContactExporter::QVersitContactExporter(const QString& profile)
+ : d(new QVersitContactExporterPrivate(profile))
+{
+}
+
+/*!
* Frees any memory in use by this contact exporter.
*/
QVersitContactExporter::~QVersitContactExporter()
@@ -283,6 +251,7 @@
foreach (const QContact& contact, contacts) {
QVersitDocument versitDocument;
versitDocument.setType(versitType);
+ versitDocument.setComponentType(QLatin1String("VCARD"));
QVersitContactExporter::Error error;
if (d->exportContact(contact, versitDocument, &error)) {
d->mDocuments.append(versitDocument);
@@ -346,8 +315,7 @@
*/
void QVersitContactExporter::setDetailHandler(QVersitContactExporterDetailHandlerV2* handler)
{
- if (handler)
- d->mDetailHandlerVersion = handler->version();
+ d->mDetailHandlerVersion = 2;
d->mDetailHandler = 0;
d->mDetailHandler2 = handler;
}