Versit

Namespace

The QtMobility APIs are placed into the QtMobility namespace. This is done to facilitate the future migration of QtMobility APIs into Qt. See the Quickstart guide for an example on how the namespace impacts on application development.

Overview

The Versit API provides a library to convert QContacts to and from vCard files, and to convert QOrganizerItems to and from iCalendar files.

Because vCard and iCalendar share the same structure, they are represented in abstract form with a common class, namely QVersitDocument. vCard and iCalendar files can be parsed into QVersitDocument form using QVersitReader. QVersitDocument objects can be written to an I/O device using QVersitWriter.

A QVersitDocument object can represent either a vCard or an iCalendar. QVersitDocuments representing vCards can be converted to QContacts using QVersitContactImporter. QVersitDocuments representing iCalendars can be converted to QOrganizerItems using QVersitOrganizerImporter. QContacts and QOrganizerItems can be converted to QVersitDocuments using QVersitContactExporter and QVersitOrganizerExporter, respectively.

Currently QVersitReader and QVersitWriter support reading and writing vCard 2.1, vCard 3.0 and iCalendar 2.0 format documents. Please note that the QtMobility Organizer API is still under development, so the Qt Versit API classes related to importing and exporting organizer items is subject to change.

Versit ^® is a trademark of the Internet Mail Consortium.

Usage

The following example goes through the process of reading a vCard and importing it to QContact format, then exporting and writing it back out.

First, let's create some data to read. In this case, we create a QBuffer as a demonstration, but any QIODevice will work.

 QBuffer input;
 input.open(QBuffer::ReadWrite);
 QByteArray inputVCard =
     "BEGIN:VCARD\r\nVERSION:2.1\r\nFN:John Citizen\r\nN:Citizen;John;Q;;\r\nEND:VCARD\r\n";
 input.write(inputVCard);
 input.seek(0);

QVersitReader can be used to parse a vCard or iCalendar from an I/O device to produce a list of QVersitDocuments.

 // Note: we could also use the more convenient QVersitReader(QByteArray) constructor.
 QVersitReader reader;
 reader.setDevice(&input);
 reader.startReading(); // Remember to check the return value
 reader.waitForFinished();
 QList<QVersitDocument> inputDocuments = reader.results();

QVersitDocuments aren't very useful to the QtContacts API. They need to be imported using the QVersitContactImporter. If the QVersitDocuments were iCalendar objects, they could be imported using QVersitOrganizerImporter.

 QVersitContactImporter importer;
 if (!importer.importDocuments(inputDocuments))
     return;
 QList<QContact> contacts = importer.contacts();
 // Note that the QContacts are not saved yet.
 // Use QContactManager::saveContacts() for saving if necessary

Conversely, QVersitContactExporter can be used to convert from QContacts to QVersitDocuments. (QVersitOrganizerExporter can be used for QOrganizerItem):

 QVersitContactExporter exporter;
 if (!exporter.exportContacts(contacts, QVersitDocument::VCard30Type))
     return;
 QList<QVersitDocument> outputDocuments = exporter.documents();

To complete the exporting process, QVersitWriter can be used to write to an I/O device.

 // Note: we could also use the more convenient QVersitWriter(QByteArray*) constructor.
 QBuffer output;
 output.open(QBuffer::ReadWrite);
 QVersitWriter writer;
 writer.setDevice(&output);
 writer.startWriting(outputDocuments); // Remember to check the return value
 writer.waitForFinished();
 // output.buffer() now contains a vCard

Classes

The main classes for a client interested in importing or exporting vCard and iCalendar documents are:

It is also possible to extend the behaviour of the importer and exporter classes by writing handlers and plugins. For more details, please see the document on Versit Plugins.

QVersitContactExporterDetailHandlerV2	Interface for specifying custom export behaviour for certain contact details
QVersitContactHandler	Union of the QVersitContactImporterPropertyHandlerV2 and QVersitContactExporterDetailHandlerV2 interfaces
QVersitContactHandlerFactory	The interface for Versit plugins
QVersitContactImporterPropertyHandlerV2	Interface for specifying custom import behaviour for vCard properties
QVersitDefaultResourceHandler	Default implementation of a Versit resource handler
QVersitOrganizerExporterDetailHandler	Interface for specifying custom export behaviour for certain organizer item details
QVersitOrganizerHandler	Union of the QVersitOrganizerImporterPropertyHandlerV2 and QVersitOrganizerExporterDetailHandlerV2 interfaces
QVersitOrganizerHandlerFactory	The interface for Versit plugins
QVersitOrganizerImporterPropertyHandler	Interface for specifying custom import behaviour for vCard properties
QVersitResourceHandler	Interface for clients wishing to implement custom behaviour for loading and saving files to disk when exporting and importing

Supported Features

Please see the Supported vCard Features document for a list of vCard features that the Versit module supports.

Contents