QVersitContactImporter Class Reference
The QVersitContactImporter class converts QVersitDocuments to QContacts. More...
#include <QVersitContactImporter>
Public Types
enum | Error { NoError, InvalidDocumentError, EmptyDocumentError } |
Public Functions
QVersitContactImporter () | |
~QVersitContactImporter () | |
QList<QContact> | contacts () const |
QMap<int, Error> | errors () const |
bool | importDocuments ( const QList<QVersitDocument> & documents ) |
QVersitResourceHandler * | resourceHandler () const |
void | setPropertyHandler ( QVersitContactImporterPropertyHandlerV2 * handler ) |
void | setResourceHandler ( QVersitResourceHandler * handler ) |
Detailed Description
The QVersitContactImporter class converts QVersitDocuments to QContacts.
This class is used to convert lists of QVersitDocuments (which may be produced by a QVersitReader) to lists of QContacts (which may be saved into a QContactManager. Unless there is an error, there is a one-to-one mapping between Versit documents and QContacts. The importer can be extended by clients by associating resource and property handlers.
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 photos found in vCards are not saved to disk by default, the importer does add a QContactThumbnail detail to the image. If a full-sized image needs to be loaded from a URL and persisted on disk, a custom QVersitResourceHandler should be supplied which implements this.
By associating a QVersitContactImporterPropertyHandlerV2 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. A "backup" handler is provided by QVersitContactImporterPropertyHandlerV2::createBackupHandler() which imports properties generated by the corresponding backup handler for the QVersitContactExporter.
An example usage of QVersitContactImporter:
QVersitContactImporter importer; QVersitContactImporterPropertyHandlerV2* backupHandler = QVersitContactImporterPropertyHandlerV2::createBackupHandler(); importer.setPropertyHandler(backupHandler); 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 } delete backupHandler;
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 HasMember QContactRelationship along with contacts of type 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.
/*! 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); } } }