Home · All Classes · All Functions ·

QVersitContactExporter Class Reference

The QVersitContactExporter class converts QContacts into QVersitDocuments. More...

    #include <QVersitContactExporter>

Public Types

Public Functions


Detailed Description

The QVersitContactExporter class converts QContacts into QVersitDocuments.

A QVersitResourceHandler is associated with the exporter to supply the behaviour for loading files from persistent storage. By default, this is set to a QVersitDefaultResourceHandler, which supports basic resource loading from the file system. An alternative resource handler can be specified with setResourceHandler().

By associating a QVersitContactExporterDetailHandler with the exporter using setDetailHandler(), the client can pass in a handler to override the processing of details and/or handle details that QVersitContactExporter doesn't support.

An example detail handler that encodes all unknown details as nonstandard vCard propreties:

    class MyDetailHandler : public QVersitContactExporterDetailHandler {
    public:
        MyDetailHandler() : detailNumber(0) {}
        bool preProcessDetail(const QContact& contact, const QContactDetail& detail,
                              QVersitDocument* document) {
            Q_UNUSED(contact) Q_UNUSED(detail) Q_UNUSED(document)
            return false;
        }
        /* eg. a detail with definition name "Detail1" and fields "Field1"="Value1" and
         * "Field2"="Value2" will be exported to the vCard properties:
         * G0.DETAIL1-FIELD1:Value1
         * G0.DETAIL1-FIELD2:Value2
         * And the next detail (say, "Detail2" with a field "Field3"="Value3" will generate:
         * G1.DETAIL2-FIELD3:Value3
         * ie. Different details will have different vCard groups.
         */
        bool postProcessDetail(const QContact& contact, const QContactDetail& detail,
                               bool alreadyProcessed, QVersitDocument* document) {
            Q_UNUSED(contact)
            // beware: if the base implementation exports some but not all fields, alreadyProcessed
            // will be true and the unprocessed fields won't be exported
            if (alreadyProcessed)
                return false;
            if (detail.definitionName() == QContactType::DefinitionName)
                return false; // special case of an unhandled detail that we don't export
            QVersitProperty property;
            QVariantMap fields = detail.variantValues();
            // fields from the same detail have the same group so the importer can collate them
            QString detailGroup = QLatin1String("G") + QString::number(detailNumber++);
            for (QVariantMap::const_iterator it = fields.constBegin();
                 it != fields.constEnd();
                 it++) {
                property.setGroups(QStringList(detailGroup));
                // beware: detail.definitionName and the field name will be made uppercase on export
                property.setName(QLatin1String("X-QCONTACTDETAIL-")
                                 + detail.definitionName()
                                 + QLatin1String("-")
                                 + it.key());
                // beware: this might not handle nonstring values properly:
                property.setValue(it.value());
                document->addProperty(property);
            }
            return true;
        }
    private:
        int detailNumber;
    };

An example usage of QVersitContactExporter

        QVersitContactExporter contactExporter;

        MyDetailHandler detailHandler;
        contactExporter.setDetailHandler(&detailHandler);

        QContact contact;
        // Create a name
        QContactName name;
        name.setFirstName(QString::fromAscii("John"));
        contact.saveDetail(&name);

        if (!contactExporter.exportContacts(QList<QContact>() << contact, QVersitDocument::VCard30Type))
            return;
        QList<QVersitDocument> versitDocuments = contactExporter.documents();

        // detailHandler.mUnknownDetails now contains the list of unknown details

Exporting group relationships

The exporter does not handle QContactRelationships at all.

Some managers use the HasMember QContactRelationship along with contacts of type TypeGroup to indicate categorization of contacts. In vCard, categorization is represented by the CATEGORIES property, which has semantics most similar to the QContactTag detail. For contact manager backends that supports groups but not QContactTag, if the categorization information needs to be retained through CATEGORIES vCard properties, extra work can be done to convert from group relationships to QContactTag before passing the contact list to the exporter. Below is some example code that does this translation.

    /*! Adds QContactTag details to the \a contacts, based on the \a relationships.

      Tags are created such that if a group contact, B with display label "b", has a HasMember
      relationship with a contact, A, then a QContactTag, "b", is added to A.

      Group contacts can be passed in with the \a contacts list.  If a contact is part of a group which
      is not in \a contacts, the \a manager is queried to find them.
      */
    void createTagsFromGroups(QList<QContact>* contacts,
                              const QList<QContactRelationship>& relationships,
                              const QContactManager* manager)
    {
        // Map from QContactIds to group names
        QMap<QContactId, QString> groupMap;

        // Map from QContactIds to indices into the contacts list
        QMap<QContactId, int> indexMap;
        // Build up groupMap and indexMap
        for (int i = 0; i < contacts->size(); ++i) {
            QContact contact = contacts->at(i);
            if (contact.type() == QContactType::TypeGroup) {
                // In practice, you may want to check that there aren't two distinct groups with the
                // same name, and you may want to use a field other than display label.
                groupMap.insert(contact.id(), contact.displayLabel());
            }
            indexMap.insert(contact.id(), i);
        }

        // Now add all the tags specified by the group relationships
        foreach (const QContactRelationship& rel, relationships) {
            if (rel.relationshipType() == QContactRelationship::HasMember
                && indexMap.contains(rel.second())) {
                QString groupName = groupMap.value(rel.first()); // Have we seen the group before?
                if (groupName.isEmpty()) {
                    // Try and find the group in the manager
                    QContactId groupId = rel.second();
                    QContactFetchHint fetchHint;
                    fetchHint.setDetailDefinitionsHint(QStringList(QContactDisplayLabel::DefinitionName));
                    QContact contact = manager->contact(groupId.localId(), fetchHint);
                    if (!contact.isEmpty()) {
                        groupName = contact.displayLabel();
                        groupMap.insert(groupId, groupName); // Cache the group id/name
                    }
                }
                if (!groupName.isEmpty()) {
                    // Add the tag
                    QContactTag tag;
                    tag.setTag(groupName);
                    (*contacts)[indexMap.value(rel.second())].saveDetail(&tag);
                }
            }
        }
    }

See also QVersitDocument, QVersitProperty, QVersitContactExporterDetailHandler, and QVersitResourceHandler.


Member Type Documentation

enum QVersitContactExporter::Error

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

ConstantValueDescription
QVersitContactExporter::NoError0The most recent operation was successful
QVersitContactExporter::EmptyContactError1One of the contacts was empty
QVersitContactExporter::NoNameError2One of the contacts has no QContactName field


Member Function Documentation

QVersitContactExporter::QVersitContactExporter ()

Constructs a new contact exporter

QVersitContactExporter::~QVersitContactExporter ()

Frees any memory in use by this contact exporter.

QVersitContactExporterDetailHandler * QVersitContactExporter::detailHandler () const

Gets the handler for processing QContactDetails.

See also setDetailHandler().

QList<QVersitDocument> QVersitContactExporter::documents () const

Returns the documents exported in the most recent call to exportContacts().

See also exportContacts().

QMap<int, Error> QVersitContactExporter::errors () const

Returns the map of errors encountered in the most recent call to exportContacts(). The key is the index into the input list of contacts and the value is the error that occurred on that contact.

See also exportContacts().

bool QVersitContactExporter::exportContacts ( const QList<QContact> & contacts, QVersitDocument::VersitType versitType )

Converts contacts into a list of corresponding QVersitDocuments, using the format given by versitType. Returns true on success. If any of the contacts could not be exported, false is returned and errors() will return a list describing the errors that occurred. The successfully exported documents will still be available via documents().

QVersitResourceHandler * QVersitContactExporter::resourceHandler () const

Returns the associated resource handler.

See also setResourceHandler().

void QVersitContactExporter::setDetailHandler ( QVersitContactExporterDetailHandler * handler )

Sets handler to be the handler for processing QContactDetails, 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.

See also detailHandler().

void QVersitContactExporter::setResourceHandler ( QVersitResourceHandler * handler )

Sets handler to be the handler to load 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.

See also resourceHandler().


Copyright © 2010 Nokia Corporation and/or its subsidiary(-ies) Trademarks
Qt Mobility Project 1.0.1