Mercurial Mercurial > oss > FCL > sf > mw > qtmobility / diff
summary | shortlog | changelog | graph | tags | bookmarks | branches | files | changeset | file | latest | revisions | annotate | diff | comparison | raw | help
Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
src/versit/qversitcontactimporter.cpp
changeset 5 603d3f8b6302
parent 0 876b1a06bc25 
--- a/src/versit/qversitcontactimporter.cpp	Fri Sep 17 08:34:34 2010 +0300
+++ b/src/versit/qversitcontactimporter.cpp	Mon Oct 04 01:37:06 2010 +0300
@@ -42,7 +42,6 @@
 #include "qcontactmanagerengine.h"
 #include "qversitcontactimporter.h"
 #include "qversitcontactimporter_p.h"
-#include "qvcardbackuphandlers_p.h"
 #include "qversitdocument.h"
 #include "qversitproperty.h"
 #include "qmobilityglobal.h"
@@ -57,8 +56,6 @@
 
   This interface is replaced by QVersitContactImporterPropertyHandlerV2.
 
-  \ingroup versit
-
   \sa QVersitContactImporter
  */
 
@@ -100,11 +97,11 @@
   \class QVersitContactImporterPropertyHandlerV2
   \brief The QVersitContactImporterPropertyHandlerV2 class is an interface for clients wishing to
   implement custom import behaviour for vCard properties.
+  \ingroup versit-extension
+  \inmodule QtVersit
 
   This interface supercedes QVersitContactImporterPropertyHandler.
 
-  \ingroup versit
-
   \sa QVersitContactImporter
  */
 
@@ -114,18 +111,20 @@
  */
 
 /*!
-  \fn void QVersitContactImporterPropertyHandlerV2::propertyProcessed(const QVersitDocument& document, const QVersitProperty& property, bool alreadyProcessed, const QContact& contact, QList<QContactDetail>* updatedDetails)
+  \fn void QVersitContactImporterPropertyHandlerV2::propertyProcessed(const QVersitDocument& document, const QVersitProperty& property, const QContact& contact, bool* alreadyProcessed, QList<QContactDetail>* updatedDetails)
   Process \a property and provide a list of updated details by adding them to \a updatedDetails.
 
   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)
+  The supplied \a document is the container for the \a property.  \a alreadyProcessed is true if
+  the QVersitContactImporter or another handler was successful in processing the property.  If it is
+  false and the handler processes the property, it should be set to true to inform later handlers
+  that the property requires no further processing.  \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)
  */
 
 /*!
@@ -138,16 +137,12 @@
 */
 
 /*!
-  \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
+  \inmodule QtVersit
 
   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
@@ -155,6 +150,11 @@
   documents and QContacts.  The importer can be extended by clients by associating resource
   and property handlers.
 
+  Here is a simple example of how to use QVersitContactImporter:
+  \snippet ../../doc/src/snippets/qtversitdocsample/qtversitdocsample.cpp Import example
+
+  \section1 Extension via 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
@@ -164,12 +164,16 @@
 
   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
+  and/or handle properties that QVersitContactImporter doesn't support.  Also, handlers can be
+  implicitly associated to an importer through the \l{Versit Plugins}{handler plugin mechanism}.
+  The importer 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 importer to
+  interpret properties that have been generated by a backup-profiled QVersitContactExporter.  To
+  illustrate, a backup importer can be constructed with:
+  \code
+  QVersitContactImporter importer(QVersitContactHandlerFactory::ProfileBackup);
+  \endcode
+  For more details on how the backup plugin works, see \l{Versit Plugins}
 
   \section1 Importing categories
   The importer imports the vCard CATEGORIES property by converting each category to a QContactTag.
@@ -193,27 +197,24 @@
   */
 
 
-/*!
-  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)
 {
 }
 
+/*!
+ * Constructs a new importer 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
+ * Plugins}{Versit plugin}.
+ *
+ * The profile determines which plugins will be loaded to supplement the importer.
+ */
+QVersitContactImporter::QVersitContactImporter(const QString& profile)
+    : d(new QVersitContactImporterPrivate(profile))
+{
+}
+
 /*! Frees the memory used by the importer */
 QVersitContactImporter::~QVersitContactImporter()
 {
@@ -302,8 +303,7 @@
  */
 void QVersitContactImporter::setPropertyHandler(QVersitContactImporterPropertyHandlerV2* handler)
 {
-    if (handler)
-        d->mPropertyHandlerVersion = handler->version();
+    d->mPropertyHandlerVersion = 2;
     d->mPropertyHandler = 0;
     d->mPropertyHandler2 = handler;
 }
FCL/sf/mw/qtmobility