--- a/qtmobility/src/versit/qversitcontactimporter.cpp Mon Jun 21 22:38:54 2010 +0100
+++ b/qtmobility/src/versit/qversitcontactimporter.cpp Thu Jul 22 16:42:52 2010 +0100
@@ -1,6 +1,6 @@
/****************************************************************************
**
-** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
@@ -42,6 +42,7 @@
#include "qcontactmanagerengine.h"
#include "qversitcontactimporter.h"
#include "qversitcontactimporter_p.h"
+#include "qvcardbackuphandlers_p.h"
#include "qversitdocument.h"
#include "qversitproperty.h"
#include "qmobilityglobal.h"
@@ -49,10 +50,58 @@
QTM_USE_NAMESPACE
/*!
+ \deprecated
\class QVersitContactImporterPropertyHandler
- \preliminary
\brief The QVersitContactImporterPropertyHandler class is an interface for clients wishing to
- implement custom import behaviour for versit properties
+ implement custom import behaviour for vCard properties
+
+ This interface is replaced by QVersitContactImporterPropertyHandlerV2.
+
+ \ingroup versit
+
+ \sa QVersitContactImporter
+ */
+
+/*!
+ \fn QVersitContactImporterPropertyHandler::~QVersitContactImporterPropertyHandler()
+ Frees any memory in use by this handler.
+ */
+
+/*!
+ \fn bool QVersitContactImporterPropertyHandler::preProcessProperty(const QVersitDocument& document, const QVersitProperty& property, int contactIndex, QContact* contact)
+ Process \a property and update \a contact with the corresponding QContactDetail(s).
+ \a document provides the context within which the property was found.
+ \a contactIndex specifies the position that \a contact will take in the list returned by
+ \l QVersitContactImporter::importDocuments().
+
+ Returns true if the property has been handled and requires no further processing, false
+ otherwise.
+
+ This function is called on every QVersitProperty encountered during an import. Supply this
+ function and return true to implement custom import behaviour.
+ */
+
+/*!
+ \fn bool QVersitContactImporterPropertyHandler::postProcessProperty(const QVersitDocument& document, const QVersitProperty& property, bool alreadyProcessed, int contactIndex, QContact* contact)
+ Process \a property and update \a contact with the corresponding QContactDetail(s).
+ \a document provides the context within which the property was found.
+ \a contactIndex specifies the position that \a contact will take in the list returned by
+ \l QVersitContactImporter::importDocuments().
+ \a alreadyProcessed is true if the detail has already been processed either by
+ \l preProcessProperty() or by QVersitContactImporter itself.
+
+ Returns true if the property has been handled, false otherwise.
+
+ This function is called on every QVersitProperty encountered during an import. This can be
+ used to implement support for vCard properties not supported by QVersitContactImporter.
+ */
+
+/*!
+ \class QVersitContactImporterPropertyHandlerV2
+ \brief The QVersitContactImporterPropertyHandlerV2 class is an interface for clients wishing to
+ implement custom import behaviour for vCard properties.
+
+ This interface supercedes QVersitContactImporterPropertyHandler.
\ingroup versit
@@ -60,74 +109,79 @@
*/
/*!
- * \fn QVersitContactImporterPropertyHandler::~QVersitContactImporterPropertyHandler()
- * Frees any memory in use by this handler.
+ \fn QVersitContactImporterPropertyHandlerV2::~QVersitContactImporterPropertyHandlerV2()
+ Frees any memory in use by this handler.
*/
/*!
- * \fn virtual bool QVersitContactImporterPropertyHandler::preProcessProperty(const QVersitDocument& document, const QVersitProperty& property, int contactIndex, QContact* contact) = 0;
- * Process \a property and update \a contact with the corresponding QContactDetail(s).
- * \a document provides the context within which the property was found.
- * \a contactIndex specifies the position that \a contact will take in the list returned by
- * \l QVersitContactImporter::importDocuments().
- *
- * Returns true if the property has been handled and requires no further processing, false
- * otherwise.
- *
- * This function is called on every QVersitProperty encountered during an import. Supply this
- * function and return true to implement custom import behaviour.
- */
+ \fn void QVersitContactImporterPropertyHandlerV2::propertyProcessed(const QVersitDocument& document, const QVersitProperty& property, bool alreadyProcessed, const QContact& contact, QList<QContactDetail>* updatedDetails)
+ Process \a property and provide a list of updated details by adding them to \a updatedDetails.
-/*!
- * \fn virtual bool QVersitContactImporterPropertyHandler::postProcessProperty(const QVersitDocument& document, const QVersitProperty& property, bool alreadyProcessed, int contactIndex, QContact* contact) = 0;
- * Process \a property and update \a contact with the corresponding QContactDetail(s).
- * \a document provides the context within which the property was found.
- * \a contactIndex specifies the position that \a contact will take in the list returned by
- * \l QVersitContactImporter::importDocuments().
- * \a alreadyProcessed is true if the detail has already been processed either by
- * \l preProcessProperty() or by QVersitContactImporter itself.
- *
- * Returns true if the property has been handled, false otherwise.
- *
- * This function is called on every QVersitProperty encountered during an import. This can be
- * used to implement support for QVersitProperties not supported by QVersitContactImporter.
+ This function is called on every QVersitProperty encountered during an import, after the property
+ has been processed by the QVersitContactImporter. An implementation of this function can be made
+ to provide support for vCard properties not supported by QVersitContactImporter.
+
+ The supplied \a document is the container for the \a property. \a alreadyProcessed is true if the
+ QVersitContactImporter was successful in processing the property. \a contact holds the state of
+ the contact before the property was processed by the importer. \a updatedDetails is initially
+ filled with a list of details that the importer will update, and can be modified (by removing,
+ modifying or adding details to the list)
*/
/*!
- * \class QVersitContactImporter
- * \preliminary
- * \brief The QVersitContactImporter class creates QContacts from QVersitDocuments.
- *
- * \ingroup versit
- *
- * A \l QVersitResourceHandler is associated with the importer to supply the behaviour for saving
- * files to persistent storage. By default, this is set to a \l QVersitDefaultResourceHandler,
- * which does not save files to persistent storage. Note that although avatars found in vCards
- * are not saved to disk by default, the importer does set the pixmap of the contact detail to the
- * image. If a full-sized avatar image needs to be persisted, a custom QVersitResourceHandler
- * should be supplied which implements this.
- *
- * By associating a QVersitContactImporterPropertyHandler with the importer using
- * setPropertyHandler(), the client can pass in a handler to override the processing of properties
- * and/or handle properties that QVersitContactImporter doesn't support.
- *
- * An example property handler that logs unknown properties:
- * \snippet ../../doc/src/snippets/qtversitdocsample/qtversitdocsample.cpp Property handler
- *
- * An example usage of QVersitContactImporter
- * \snippet ../../doc/src/snippets/qtversitdocsample/qtversitdocsample.cpp Import example
- *
- * \section1 Importing categories
- * The importer imports the vCard CATEGORIES property by converting each category to a QContactTag.
- * Some managers may not have support for QContactTag, but instead support categorization using the
- * \l{QContactRelationship::HasMember}{HasMember} QContactRelationship along with contacts of type
- * \l{QContactType::TypeGroup}{TypeGroup}. For these backends, if the categorization information
- * needs to be retained through group relationships, extra work needs to be done to do the
- * conversion. Below is some example code that does this translation.
- *
- * \snippet ../../doc/src/snippets/qtversitdocsample/qtversitdocsample.cpp Import relationship example
- *
- * \sa QVersitDocument, QVersitReader, QVersitContactImporterPropertyHandler
+ \fn void QVersitContactImporterPropertyHandlerV2::documentProcessed(const QVersitDocument& document, QContact* contact)
+ Perform any final processing on the \a contact generated by the \a document. This can be
+ implemented by the handler to clear any internal state before moving onto the next document.
+
+ This function is called after all QVersitProperties have been handled by the
+ QVersitContactImporter.
+*/
+
+/*!
+ \fn int QVersitContactImporterPropertyHandlerV2::version() const
+ Returns the version of the handler. Currently, always returns 2.
+*/
+
+/*!
+ \class QVersitContactImporter
+ \brief The QVersitContactImporter class converts \l{QVersitDocument}{QVersitDocuments} to
+ \l{QContact}{QContacts}.
+
+ \ingroup versit
+
+ This class is used to convert lists of \l{QVersitDocument}{QVersitDocuments} (which may be
+ produced by a QVersitReader) to lists of \l{QContact}{QContacts} (which may be saved into a
+ QContactManager. Unless there is an error, there is a one-to-one mapping between Versit
+ documents and QContacts. The importer can be extended by clients by associating resource
+ and property handlers.
+
+ A \l QVersitResourceHandler is associated with the importer to supply the behaviour for saving
+ files to persistent storage. By default, this is set to a \l QVersitDefaultResourceHandler,
+ which does not save files to persistent storage. Note that although photos found in vCards
+ are not saved to disk by default, the importer does add a QContactThumbnail detail to the
+ image. If a full-sized image needs to be loaded from a URL and persisted on disk, a custom
+ QVersitResourceHandler should be supplied which implements this.
+
+ By associating a QVersitContactImporterPropertyHandlerV2 with the importer using
+ setPropertyHandler(), the client can pass in a handler to override the processing of properties
+ and/or handle properties that QVersitContactImporter doesn't support. A "backup" handler is
+ provided by QVersitContactImporterPropertyHandlerV2::createBackupHandler() which imports
+ properties generated by the corresponding backup handler for the QVersitContactExporter.
+
+ An example usage of QVersitContactImporter:
+ \snippet ../../doc/src/snippets/qtversitdocsample/qtversitdocsample.cpp Import example
+
+ \section1 Importing categories
+ The importer imports the vCard CATEGORIES property by converting each category to a QContactTag.
+ Some managers may not have support for QContactTag, but instead support categorization using the
+ \l{QContactRelationship::HasMember}{HasMember} QContactRelationship along with contacts of type
+ \l{QContactType::TypeGroup}{TypeGroup}. For these backends, if the categorization information
+ needs to be retained through group relationships, extra work needs to be done to do the
+ conversion. Below is some example code that does this translation.
+
+ \snippet ../../doc/src/snippets/qtversitdocsample/qtversitdocsample.cpp Import relationship example
+
+ \sa QVersitDocument, QVersitProperty, QVersitResourceHandler, QVersitContactImporterPropertyHandlerV2
*/
/*!
@@ -138,6 +192,22 @@
\value EmptyDocumentError One of the documents is empty
*/
+
+/*!
+ Constructs and returns a property handler that restores data from a vCard generated using the
+ exporter backup detail handler (see QVersitContactExporterDetailHandlerV2::createBackupHandler()).
+ The caller is responsible for deleting the object.
+
+ Clients wishing to implement their own property handler and also benefit from the functionality of
+ the default handler can use this function to construct one, and wrap a custom
+ QVersitContactImporterPropertyHandlerV2 around it. In the implementation of propertyProcessed and
+ documentProcessed, the respective functions in the backup handler should be called as the last
+ step (ensuring the arguments are correctly updated and passed through).
+ */
+QVersitContactImporterPropertyHandlerV2* QVersitContactImporterPropertyHandlerV2::createBackupHandler() {
+ return new QVCardImporterBackupHandler;
+}
+
/*! Constructs a new importer */
QVersitContactImporter::QVersitContactImporter()
: d(new QVersitContactImporterPrivate)
@@ -205,17 +275,41 @@
}
/*!
+ * \deprecated
* Sets \a handler to be the handler for processing QVersitProperties, or 0 to have no handler.
*
* Does not take ownership of the handler. The client should ensure the handler remains valid for
- * the lifetime of the exporter.
+ * the lifetime of the exporter. This function is used for version 1 handlers.
+ *
+ * Only one property handler can be set. If another property handler (of any version) was
+ * previously set, it will no longer be associated with the importer.
*/
void QVersitContactImporter::setPropertyHandler(QVersitContactImporterPropertyHandler* handler)
{
+ d->mPropertyHandlerVersion = 1;
d->mPropertyHandler = handler;
+ d->mPropertyHandler2 = NULL;
}
/*!
+ * Sets \a handler to be the handler for processing QVersitProperties, or 0 to have no handler.
+ *
+ * Does not take ownership of the handler. The client should ensure the handler remains valid for
+ * the lifetime of the exporter. This function is used for version 2 and higher handlers.
+ *
+ * Only one property handler can be set. If another property handler (of any version) was
+ * previously set, it will no longer be associated with the importer.
+ */
+void QVersitContactImporter::setPropertyHandler(QVersitContactImporterPropertyHandlerV2* handler)
+{
+ if (handler)
+ d->mPropertyHandlerVersion = handler->version();
+ d->mPropertyHandler = 0;
+ d->mPropertyHandler2 = handler;
+}
+
+/*!
+ * \internal
* Gets the handler for processing QVersitProperties.
*/
QVersitContactImporterPropertyHandler* QVersitContactImporter::propertyHandler() const