FCL/sf/mw/qtextensions: comparison qtmobility/src/versit/qversitcontactimporter.cpp

equal deleted inserted replaced

-:2b40d63a9c3d
+:90517678cc4f
 **
 ** $QT_END_LICENSE$
 **
 ****************************************************************************/
+#include "qcontactmanagerengine.h"
 #include "qversitcontactimporter.h"
 #include "qversitcontactimporter_p.h"
 #include "qversitdocument.h"
 #include "qversitproperty.h"
 #include "qmobilityglobal.h"
 /*!
 * \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::importContacts().
+* \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
 /*!
 * \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::importContacts().
+* \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.
 *
 * \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
 */
+/*!
+\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 a new importer */
 QVersitContactImporter::QVersitContactImporter()
 : d(new QVersitContactImporterPrivate)
 {
 {
 delete d;
 }
 /*!
-* Converts \a documents into a corresponding list of QContacts.
+* Converts \a documents into a corresponding list of QContacts.  After calling this, the converted
-*/
+* contacts can be retrieved by calling contacts().
-QList<QContact> QVersitContactImporter::importContacts(const QList<QVersitDocument>& documents)
+* 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.
-QList<QContact> list;
+* The successfully imported documents will still be available via contacts().
-int i = 0;
+*
-foreach (QVersitDocument document, documents) {
+* \sa contacts(), errors()
-list.append(d->importContact(document, i));
+*/
-i++;
+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 list;
+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;
 }
 /*!
 * Sets \a handler to be the handler for processing QVersitProperties, or 0 to have no handler.
 *

changeset 4	90517678cc4f
parent 1	2b40d63a9c3d
child 8	71781823f776