1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the Qt Mobility Components.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 #include "qcontactmanagerengine.h"

    43 #include "qversitcontactimporter.h"

    44 #include "qversitcontactimporter_p.h"

    45 #include "qvcardbackuphandlers_p.h"

    46 #include "qversitdocument.h"

    47 #include "qversitproperty.h"

    48 #include "qmobilityglobal.h"

    49 

    50 QTM_USE_NAMESPACE

    51 

    52 /*!

    53   \deprecated

    54   \class QVersitContactImporterPropertyHandler

    55   \brief The QVersitContactImporterPropertyHandler class is an interface for clients wishing to

    56   implement custom import behaviour for vCard properties

    57 

    58   This interface is replaced by QVersitContactImporterPropertyHandlerV2.

    59 

    60   \ingroup versit

    61 

    62   \sa QVersitContactImporter

    63  */

    64 

    65 /*!

    66   \fn QVersitContactImporterPropertyHandler::~QVersitContactImporterPropertyHandler()

    67   Frees any memory in use by this handler.

    68  */

    69 

    70 /*!

    71   \fn bool QVersitContactImporterPropertyHandler::preProcessProperty(const QVersitDocument& document, const QVersitProperty& property, int contactIndex, QContact* contact)

    72   Process \a property and update \a contact with the corresponding QContactDetail(s).

    73   \a document provides the context within which the property was found.

    74   \a contactIndex specifies the position that \a contact will take in the list returned by

    75   \l QVersitContactImporter::importDocuments().

    76 

    77   Returns true if the property has been handled and requires no further processing, false

    78   otherwise.

    79 

    80   This function is called on every QVersitProperty encountered during an import.  Supply this

    81   function and return true to implement custom import behaviour.

    82  */

    83 

    84 /*!

    85   \fn bool QVersitContactImporterPropertyHandler::postProcessProperty(const QVersitDocument& document, const QVersitProperty& property, bool alreadyProcessed, int contactIndex, QContact* contact)

    86   Process \a property and update \a contact with the corresponding QContactDetail(s).

    87   \a document provides the context within which the property was found.

    88   \a contactIndex specifies the position that \a contact will take in the list returned by

    89   \l QVersitContactImporter::importDocuments().

    90   \a alreadyProcessed is true if the detail has already been processed either by

    91   \l preProcessProperty() or by QVersitContactImporter itself.

    92 

    93   Returns true if the property has been handled, false otherwise.

    94 

    95   This function is called on every QVersitProperty encountered during an import.  This can be

    96   used to implement support for vCard properties not supported by QVersitContactImporter.

    97  */

    98 

    99 /*!

   100   \class QVersitContactImporterPropertyHandlerV2

   101   \brief The QVersitContactImporterPropertyHandlerV2 class is an interface for clients wishing to

   102   implement custom import behaviour for vCard properties.

   103 

   104   This interface supercedes QVersitContactImporterPropertyHandler.

   105 

   106   \ingroup versit

   107 

   108   \sa QVersitContactImporter

   109  */

   110 

   111 /*!

   112   \fn QVersitContactImporterPropertyHandlerV2::~QVersitContactImporterPropertyHandlerV2()

   113   Frees any memory in use by this handler.

   114  */

   115 

   116 /*!

   117   \fn void QVersitContactImporterPropertyHandlerV2::propertyProcessed(const QVersitDocument& document, const QVersitProperty& property, bool alreadyProcessed, const QContact& contact, QList<QContactDetail>* updatedDetails)

   118   Process \a property and provide a list of updated details by adding them to \a updatedDetails.

   119 

   120   This function is called on every QVersitProperty encountered during an import, after the property

   121   has been processed by the QVersitContactImporter.  An implementation of this function can be made

   122   to provide support for vCard properties not supported by QVersitContactImporter.

   123 

   124   The supplied \a document is the container for the \a property.  \a alreadyProcessed is true if the

   125   QVersitContactImporter was successful in processing the property.  \a contact holds the state of

   126   the contact before the property was processed by the importer.  \a updatedDetails is initially

   127   filled with a list of details that the importer will update, and can be modified (by removing,

   128   modifying or adding details to the list)

   129  */

   130 

   131 /*!

   132   \fn void QVersitContactImporterPropertyHandlerV2::documentProcessed(const QVersitDocument& document, QContact* contact)

   133   Perform any final processing on the \a contact generated by the \a document.  This can be

   134   implemented by the handler to clear any internal state before moving onto the next document.

   135 

   136   This function is called after all QVersitProperties have been handled by the

   137   QVersitContactImporter.

   138 */

   139 

   140 /*!

   141   \fn int QVersitContactImporterPropertyHandlerV2::version() const

   142   Returns the version of the handler.  Currently, always returns 2.

   143 */

   144 

   145 /*!

   146   \class QVersitContactImporter

   147   \brief The QVersitContactImporter class converts \l{QVersitDocument}{QVersitDocuments} to

   148   \l{QContact}{QContacts}.

   149 

   150   \ingroup versit

   151 

   152   This class is used to convert lists of \l{QVersitDocument}{QVersitDocuments} (which may be

   153   produced by a QVersitReader) to lists of \l{QContact}{QContacts} (which may be saved into a

   154   QContactManager.  Unless there is an error, there is a one-to-one mapping between Versit

   155   documents and QContacts.  The importer can be extended by clients by associating resource

   156   and property handlers.

   157 

   158   A \l QVersitResourceHandler is associated with the importer to supply the behaviour for saving

   159   files to persistent storage.  By default, this is set to a \l QVersitDefaultResourceHandler,

   160   which does not save files to persistent storage.  Note that although photos found in vCards

   161   are not saved to disk by default, the importer does add a QContactThumbnail detail to the

   162   image.  If a full-sized image needs to be loaded from a URL and persisted on disk, a custom

   163   QVersitResourceHandler should be supplied which implements this.

   164 

   165   By associating a QVersitContactImporterPropertyHandlerV2 with the importer using

   166   setPropertyHandler(), the client can pass in a handler to override the processing of properties

   167   and/or handle properties that QVersitContactImporter doesn't support.  A "backup" handler is

   168   provided by QVersitContactImporterPropertyHandlerV2::createBackupHandler() which imports

   169   properties generated by the corresponding backup handler for the QVersitContactExporter.

   170 

   171   An example usage of QVersitContactImporter:

   172   \snippet ../../doc/src/snippets/qtversitdocsample/qtversitdocsample.cpp Import example

   173 

   174   \section1 Importing categories

   175   The importer imports the vCard CATEGORIES property by converting each category to a QContactTag.

   176   Some managers may not have support for QContactTag, but instead support categorization using the

   177   \l{QContactRelationship::HasMember}{HasMember} QContactRelationship along with contacts of type

   178   \l{QContactType::TypeGroup}{TypeGroup}.  For these backends, if the categorization information

   179   needs to be retained through group relationships, extra work needs to be done to do the

   180   conversion.  Below is some example code that does this translation.

   181 

   182   \snippet ../../doc/src/snippets/qtversitdocsample/qtversitdocsample.cpp Import relationship example

   183 

   184   \sa QVersitDocument, QVersitProperty, QVersitResourceHandler, QVersitContactImporterPropertyHandlerV2

   185  */

   186 

   187 /*!

   188   \enum QVersitContactImporter::Error

   189   This enum specifies an error that occurred during the most recent call to importDocuments()

   190   \value NoError The most recent operation was successful

   191   \value InvalidDocumentError One of the documents is not a vCard

   192   \value EmptyDocumentError One of the documents is empty

   193   */

   194 

   195 

   196 /*!

   197   Constructs and returns a property handler that restores data from a vCard generated using the

   198   exporter backup detail handler (see QVersitContactExporterDetailHandlerV2::createBackupHandler()).

   199   The caller is responsible for deleting the object.

   200 

   201   Clients wishing to implement their own property handler and also benefit from the functionality of

   202   the default handler can use this function to construct one, and wrap a custom

   203   QVersitContactImporterPropertyHandlerV2 around it.  In the implementation of propertyProcessed and

   204   documentProcessed, the respective functions in the backup handler should be called as the last

   205   step (ensuring the arguments are correctly updated and passed through).

   206  */

   207 QVersitContactImporterPropertyHandlerV2* QVersitContactImporterPropertyHandlerV2::createBackupHandler() {

   208     return new QVCardImporterBackupHandler;

   209 }

   210 

   211 /*! Constructs a new importer */

   212 QVersitContactImporter::QVersitContactImporter()

   213     : d(new QVersitContactImporterPrivate)

   214 {

   215 }

   216 

   217 /*! Frees the memory used by the importer */

   218 QVersitContactImporter::~QVersitContactImporter()

   219 {

   220     delete d;

   221 }

   222 

   223 /*!

   224  * Converts \a documents into a corresponding list of QContacts.  After calling this, the converted

   225  * contacts can be retrieved by calling contacts().

   226  * Returns true on success.  If any of the documents cannot be imported as contacts (eg. they aren't

   227  * vCards), false is returned and errors() will return a list describing the errors that occurred.

   228  * The successfully imported documents will still be available via contacts().

   229  *

   230  * \sa contacts(), errors()

   231  */

   232 bool QVersitContactImporter::importDocuments(const QList<QVersitDocument>& documents)

   233 {

   234     int documentIndex = 0;

   235     int contactIndex = 0;

   236     d->mContacts.clear();

   237     d->mErrors.clear();

   238     bool ok = true;

   239     foreach (const QVersitDocument& document, documents) {

   240         QContact contact;

   241         QVersitContactImporter::Error error;

   242         if (d->importContact(document, contactIndex, &contact, &error)) {

   243             d->mContacts.append(contact);

   244             contactIndex++;

   245         } else {

   246             d->mErrors.insert(documentIndex, error);

   247             ok = false;

   248         }

   249         documentIndex++;

   250     }

   251 

   252     return ok;

   253 }

   254 

   255 /*!

   256  * Returns the contacts imported in the most recent call to importDocuments().

   257  *

   258  * \sa importDocuments()

   259  */

   260 QList<QContact> QVersitContactImporter::contacts() const

   261 {

   262     return d->mContacts;

   263 }

   264 

   265 /*!

   266  * Returns the map of errors encountered in the most recent call to importDocuments().  The key is

   267  * the index into the input list of documents and the value is the error that occurred on that

   268  * document.

   269  *

   270  * \sa importDocuments()

   271  */

   272 QMap<int, QVersitContactImporter::Error> QVersitContactImporter::errors() const

   273 {

   274     return d->mErrors;

   275 }

   276 

   277 /*!

   278  * \deprecated

   279  * Sets \a handler to be the handler for processing QVersitProperties, or 0 to have no handler.

   280  *

   281  * Does not take ownership of the handler.  The client should ensure the handler remains valid for

   282  * the lifetime of the exporter.  This function is used for version 1 handlers.

   283  *

   284  * Only one property handler can be set.  If another property handler (of any version) was

   285  * previously set, it will no longer be associated with the importer.

   286  */

   287 void QVersitContactImporter::setPropertyHandler(QVersitContactImporterPropertyHandler* handler)

   288 {

   289     d->mPropertyHandlerVersion = 1;

   290     d->mPropertyHandler = handler;

   291     d->mPropertyHandler2 = NULL;

   292 }

   293 

   294 /*!

   295  * Sets \a handler to be the handler for processing QVersitProperties, or 0 to have no handler.

   296  *

   297  * Does not take ownership of the handler.  The client should ensure the handler remains valid for

   298  * the lifetime of the exporter.  This function is used for version 2 and higher handlers.

   299  *

   300  * Only one property handler can be set.  If another property handler (of any version) was

   301  * previously set, it will no longer be associated with the importer.

   302  */

   303 void QVersitContactImporter::setPropertyHandler(QVersitContactImporterPropertyHandlerV2* handler)

   304 {

   305     if (handler)

   306         d->mPropertyHandlerVersion = handler->version();

   307     d->mPropertyHandler = 0;

   308     d->mPropertyHandler2 = handler;

   309 }

   310 

   311 /*!

   312  * \internal

   313  * Gets the handler for processing QVersitProperties.

   314  */

   315 QVersitContactImporterPropertyHandler* QVersitContactImporter::propertyHandler() const

   316 {

   317     return d->mPropertyHandler;

   318 }

   319 

   320 /*!

   321  * Sets \a handler to be the handler to save files with, or 0 to have no handler.

   322  *

   323  * Does not take ownership of the handler.  The client should ensure the handler remains valid for

   324  * the lifetime of the exporter.

   325  */

   326 void QVersitContactImporter::setResourceHandler(QVersitResourceHandler* handler)

   327 {

   328     d->mResourceHandler = handler;

   329 }

   330 

   331 /*!

   332  * Returns the associated resource handler.

   333  */

   334 QVersitResourceHandler* QVersitContactImporter::resourceHandler() const

   335 {

   336     return d->mResourceHandler;

   337 }