Qt Versit Overview
Overview
The Versit API is part of a collection of Personal Information Management API's providing 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 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.
For full list of classes, see Qt Versit C++ API.
Importing and Exporting Data
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:
- QVersitProperty
- QVersitDocument
- QVersitReader
- QVersitWriter
- QVersitContactImporter
- QVersitContactExporter
- QVersitOrganizerImporter
- QVersitOrganizerExporter
It is also possible to extend the behaviour of the importer and exporter classes by writing handlers and plugins. For more details, see Qt Versit Plugins.
Supported Features
Please see the following documents for supported Versit Module features:
- Supported vCard Features document for a list of vCard features that the Versit module supports.
- Supported iCalendar Features document for a list of iCal features that the Organizer Versit module supports.