MeeGo 1.2 Harmattan Developer Documentation Develop for the Nokia N9

QVersitContactExporter Class Reference

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

 #include <QVersitContactExporter>

Public Types

enum Error { NoError, EmptyContactError, NoNameError }

Public Functions

QVersitContactExporter ()
QVersitContactExporter ( const QString & profile )
QVersitContactExporter ( const QStringList & profiles )
~QVersitContactExporter ()
QVersitContactExporterDetailHandler * detailHandler () const (deprecated)
QList<QVersitDocument> documents () const
QMap<int, Error> errorMap () const
bool exportContacts ( const QList<QContact> & contacts, QVersitDocument::VersitType versitType = QVersitDocument::VCard30Type )
QVersitResourceHandler * resourceHandler () const
void setDetailHandler ( QVersitContactExporterDetailHandlerV2 * handler )
void setDetailHandler ( QVersitContactExporterDetailHandler * handler ) (deprecated)
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.

Here is a simple example of how to use QVersitContactExporter:

 QVersitContactExporter contactExporter;

 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

Extension via 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. Also, handlers can be implicitly associated to an exporter through the handler plugin mechanism. The exporter can be constructed with a profile, which gives hints about what kind of handlers should be added to it. For example, the backup profile can be used to instruct the exporter to encode any unknown details in the vCard such that it can be reconstructed later (a QVersitContactImporter constructed under the backup profile can be used to decode it). To illustrate, a backup exporter can be constructed with:

 QVersitContactExporter exporter(QVersitContactHandlerFactory::ProfileBackup);

For more details on how the backup plugin works, see Versit Plugins

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);
             }
         }
     }
 }

Other implementation notes

Some Symbian and Android devices do not properly handle the FN vCard property. If a CustomLabel is set on a contact and this class is used to generate a vCard, the receiving device might display this label in an unexpected field (eg. Last Name).

The vCard specification requires the FN property to be present. However, because of this interoperability issue, Qt Versit only generates an FN property if a CustomLabel is set.

See also QVersitDocument, QVersitProperty, QVersitResourceHandler, and QVersitContactExporterDetailHandlerV2.

Member Type Documentation

enum QVersitContactExporter::Error

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

Constant Value Description
QVersitContactExporter::NoError 0 The most recent operation was successful
QVersitContactExporter::EmptyContactError 1 One of the contacts was empty
QVersitContactExporter::NoNameError 2 One of the contacts has no QContactName field

Member Function Documentation

QVersitContactExporter::QVersitContactExporter ()

Constructs a new contact exporter

QVersitContactExporter::QVersitContactExporter ( const QString & profile )

Constructs a new exporter for the given profile. The profile strings should be one of those defined by QVersitContactHandlerFactory, or a value otherwise agreed to by a Versit plugin.

The profile determines which plugins will be loaded to supplement the exporter.

QVersitContactExporter::QVersitContactExporter ( const QStringList & profiles )

Constructs a new exporter for the given profiles. The profile strings should be one of those defined by QVersitContactHandlerFactory, or a value otherwise agreed to by a Versit plugin.

The profiles determine which plugins will be loaded to supplement the exporter.

QVersitContactExporter::~QVersitContactExporter ()

Frees any memory in use by this contact exporter.

QVersitContactExporterDetailHandler * QVersitContactExporter::detailHandler () const

This function is deprecated.

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::errorMap () 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 = QVersitDocument::VCard30Type )

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 errorMap() will return a list describing the errors that occurred. The successfully exported documents will still be available via documents().

See also documents() and errorMap().

QVersitResourceHandler * QVersitContactExporter::resourceHandler () const

Returns the associated resource handler.

See also setResourceHandler().

void QVersitContactExporter::setDetailHandler ( QVersitContactExporterDetailHandlerV2 * 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. This function is used for version 2 and higher handlers.

Only one detail handler can be set. If another detail handler (of any version) was previously set, it will no longer be associated with the exporter.

See also detailHandler().

void QVersitContactExporter::setDetailHandler ( QVersitContactExporterDetailHandler * handler )

This function is deprecated.

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. This function is used for version 1 handlers.

Only one detail handler can be set. If another detail handler (of any version) was previously set, it will no longer be associated with the exporter.

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().