--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/src/versit/qversitcontactimporter.cpp	Wed Aug 25 15:49:42 2010 +0300
@@ -0,0 +1,337 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the Qt Mobility Components.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights.  These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include "qcontactmanagerengine.h"
+#include "qversitcontactimporter.h"
+#include "qversitcontactimporter_p.h"
+#include "qvcardbackuphandlers_p.h"
+#include "qversitdocument.h"
+#include "qversitproperty.h"
+#include "qmobilityglobal.h"
+
+QTM_USE_NAMESPACE
+
+/*!
+  \deprecated
+  \class QVersitContactImporterPropertyHandler
+  \brief The QVersitContactImporterPropertyHandler class is an interface for clients wishing to
+  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
+
+  \sa QVersitContactImporter
+ */
+
+/*!
+  \fn QVersitContactImporterPropertyHandlerV2::~QVersitContactImporterPropertyHandlerV2()
+  Frees any memory in use by this handler.
+ */
+
+/*!
+  \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.
+
+  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)
+ */
+
+/*!
+  \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
+ */
+
+/*!
+  \enum QVersitContactImporter::Error
+  This enum specifies an error that occurred during the most recent call to importDocuments()
+  \value NoError The most recent operation was successful
+  \value InvalidDocumentError One of the documents is not a vCard
+  \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)
+{
+}
+
+/*! Frees the memory used by the importer */
+QVersitContactImporter::~QVersitContactImporter()
+{
+    delete d;
+}
+
+/*!
+ * Converts \a documents into a corresponding list of QContacts.  After calling this, the converted
+ * contacts can be retrieved by calling contacts().
+ * Returns true on success.  If any of the documents cannot be imported as contacts (eg. they aren't
+ * vCards), false is returned and errors() will return a list describing the errors that occurred.
+ * The successfully imported documents will still be available via contacts().
+ *
+ * \sa contacts(), errors()
+ */
+bool QVersitContactImporter::importDocuments(const QList<QVersitDocument>& documents)
+{
+    int documentIndex = 0;
+    int contactIndex = 0;
+    d->mContacts.clear();
+    d->mErrors.clear();
+    bool ok = true;
+    foreach (const QVersitDocument& document, documents) {
+        QContact contact;
+        QVersitContactImporter::Error error;
+        if (d->importContact(document, contactIndex, &contact, &error)) {
+            d->mContacts.append(contact);
+            contactIndex++;
+        } else {
+            d->mErrors.insert(documentIndex, error);
+            ok = false;
+        }
+        documentIndex++;
+    }
+
+    return ok;
+}
+
+/*!
+ * Returns the contacts imported in the most recent call to importDocuments().
+ *
+ * \sa importDocuments()
+ */
+QList<QContact> QVersitContactImporter::contacts() const
+{
+    return d->mContacts;
+}
+
+/*!
+ * Returns the map of errors encountered in the most recent call to importDocuments().  The key is
+ * the index into the input list of documents and the value is the error that occurred on that
+ * document.
+ *
+ * \sa importDocuments()
+ */
+QMap<int, QVersitContactImporter::Error> QVersitContactImporter::errors() const
+{
+    return d->mErrors;
+}
+
+/*!
+ * \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.  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
+{
+    return d->mPropertyHandler;
+}
+
+/*!
+ * Sets \a handler to be the handler to save files with, 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.
+ */
+void QVersitContactImporter::setResourceHandler(QVersitResourceHandler* handler)
+{
+    d->mResourceHandler = handler;
+}
+
+/*!
+ * Returns the associated resource handler.
+ */
+QVersitResourceHandler* QVersitContactImporter::resourceHandler() const
+{
+    return d->mResourceHandler;
+}