QVersitContactImporter Class Reference

Detailed Description

The QVersitContactImporter class creates QContacts from QVersitDocuments.

A QVersitResourceHandler is associated with the importer to supply the behaviour for saving files to persistent storage. By default, this is set to a QVersitDefaultResourceHandler, which does not save files to persistent storage. Note that although avatars found in vCards are not saved to disk by default, the importer does set the pixmap of the contact detail to the image. If a full-sized avatar image needs to be persisted, a custom QVersitResourceHandler should be supplied which implements this.

By associating a QVersitContactImporterPropertyHandler 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.

An example property handler that decodes unknown properties generated by the example detail handler provided in the QVersitContactExporter documentation:

    class MyPropertyHandler : public QVersitContactImporterPropertyHandler {
    public:
        bool preProcessProperty(const QVersitDocument& document, const QVersitProperty& property,
                                int contactIndex, QContact* contact) {
            Q_UNUSED(document) Q_UNUSED(property) Q_UNUSED(contactIndex) Q_UNUSED(contact)
            return false;
        }
        /* eg. if the document has the properties:
         * G0.DETAIL-FIELD1:Value1
         * G0.DETAIL-FIELD2:Value2
         * G1.DETAIL-FIELD1:Value3
         * This will generate two details - the first with fields "FIELD1"="Value1" and
         * "FIELD2"="Value2" and the second with "FIELD1"="Value3"
         * ie. the vCard groups determine which properties form a single detail.
         */
        bool postProcessProperty(const QVersitDocument& document, const QVersitProperty& property,
                                 bool alreadyProcessed, int contactIndex, QContact* contact) {
            Q_UNUSED(document) Q_UNUSED(contactIndex)
            const QString prefix = QLatin1String("X-QCONTACTDETAIL-");
            if (alreadyProcessed)
                return false;
            if (!property.name().startsWith(prefix))
                return false;
            QString detailAndField = property.name().mid(prefix.size());
            QStringList detailAndFieldParts = detailAndField.split(QLatin1Char('-'),
                                                                   QString::SkipEmptyParts);
            if (detailAndFieldParts.size() != 2)
                return false;
            QString definitionName = detailAndFieldParts.at(0);
            QString fieldName = detailAndFieldParts.at(1);
            if (property.groups().size() != 1)
                return false;
            QString group = property.groups().first();
            // find a detail generated from the a property with the same group
            QContactDetail detail = handledDetails.value(group);
            // make sure the the existing detail has the same definition name
            if (detail.definitionName() != definitionName)
                detail = QContactDetail(definitionName);
            detail.setValue(fieldName, property.value());
            contact->saveDetail(&detail);
            handledDetails.insert(group, detail);
            return false;
        }
        QMap<QString, QContactDetail> handledDetails; // map from group name to detail
    };

An example usage of QVersitContactImporter

        QVersitContactImporter importer;

        MyPropertyHandler propertyHandler;
        importer.setPropertyHandler(&propertyHandler);

        QVersitDocument document;

        QVersitProperty property;
        property.setName(QString::fromAscii("N"));
        property.setValue("Citizen;John;Q;;");
        document.addProperty(property);

        property.setName(QString::fromAscii("X-UNKNOWN-PROPERTY"));
        property.setValue("some value");
        document.addProperty(property);

        if (importer.importDocuments(QList<QVersitDocument>() << document)) {
            QList<QContact> contactList = importer.contacts();
            // contactList.first() now contains the "N" property as a QContactName
            // propertyHandler.mUnknownProperties contains the list of unknown properties
        }

    /*! Adds contacts in  \a newContacts into \a manager, converting categories specified
      with tags into group membership relationships.  Note that this implementation uses the
      synchronous API of QContactManager for clarity.  It is recommended that the asynchronous
      API is used in practice.

      Relationships are added so that if a contact, A, has a tag "b", then a HasMember relationship is
      created between a group contact in the manager, B with display label "b", and contact A.  If there
      does not exist a group contact with display label "b", one is created.
      */
    void insertWithGroups(const QList<QContact>& newContacts, QContactManager* manager)
    {
        // Cache map from group names to QContactIds
        QMap<QString, QContactId> groupMap;

        foreach (QContact contact, newContacts) {
            if (!manager->saveContact(&contact))
                continue; // In practice, better error handling may be required
            foreach (const QContactTag& tag, contact.details<QContactTag>()) {
                QString groupName = tag.tag();
                QContactId groupId;
                if (groupMap.contains(groupName)) {
                    // We've already seen a group with the right name
                    groupId = groupMap.value(groupName);
                } else {
                    QContactDetailFilter groupFilter;
                    groupFilter.setDetailDefinitionName(QContactType::DefinitionName);
                    groupFilter.setValue(QLatin1String(QContactType::TypeGroup));
                    groupFilter.setMatchFlags(QContactFilter::MatchExactly);
                    // In practice, some detail other than the display label could be used
                    QContactDetailFilter nameFilter = QContactDisplayLabel::match(groupName);
                    QList<QContactLocalId> matchingGroups = manager->contactIds(groupFilter & nameFilter);
                    if (!matchingGroups.isEmpty()) {
                        // Found an existing group in the manager
                        QContactId groupId;
                        groupId.setManagerUri(manager->managerUri());
                        groupId.setLocalId(matchingGroups.first());
                        groupMap.insert(groupName, groupId);
                    }
                    else {
                        // Make a new group
                        QContact groupContact;
                        QContactName name;
                        name.setCustomLabel(groupName);
                        // Beware that not all managers support custom label
                        groupContact.saveDetail(&name);
                        if (!manager->saveContact(&groupContact))
                            continue; // In practice, better error handling may be required
                        groupId = groupContact.id();
                        groupMap.insert(groupName, groupId);
                    }
                }
                // Add the relationship
                QContactRelationship rel;
                rel.setFirst(groupId);
                rel.setRelationshipType(QContactRelationship::HasMember);
                rel.setSecond(contact.id());
                manager->saveRelationship(&rel);
            }
        }
    }