QVersitContactExporter Class Reference
The QVersitContactExporter class converts QContacts into QVersitDocuments. More...
#include <QVersitContactExporter>
Public Types
enum | Error { NoError, EmptyContactError, NoNameError } |
Public Functions
QVersitContactExporter () | |
~QVersitContactExporter () | |
QList<QVersitDocument> | documents () const |
QMap<int, Error> | errors () const |
bool | exportContacts ( const QList<QContact> & contacts, QVersitDocument::VersitType versitType ) |
QVersitResourceHandler * | resourceHandler () const |
void | setDetailHandler ( QVersitContactExporterDetailHandlerV2 * handler ) |
void | setResourceHandler ( QVersitResourceHandler * handler ) |
Detailed Description
The QVersitContactExporter class converts QContacts into QVersitDocuments.
This class is used to convert lists of QContacts (which may be stored in a QContactManager) into lists of QVersitDocuments (which may be written to an I/O device using QVersitReader. Unless there is an error, there is a one-to-one mapping between contacts and Versit documents. The exporter can be extended by clients by associating resource and detail handlers.
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 QVersitContactExporterDetailHandlerV2 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. A "backup" handler is provided by QVersitContactExporterDetailHandlerV2::createBackupHandler(), which serializes any details that the standard QVersitContactExporter doesn't support to the vCard.
An example usage of QVersitContactExporter:
QVersitContactExporter contactExporter; QVersitContactExporterDetailHandlerV2* backupHandler = QVersitContactExporterDetailHandlerV2::createBackupHandler(); contactExporter.setDetailHandler(backupHandler); 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 delete backupHandler;
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); } } } }