QVersitContactExporter Class Reference

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

    /*! 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);
                }
            }
        }
    }