Versit Overview

This topic describes the Versit component, which can be used to import and export contact and calendar information.

Purpose

The Versit component provides a set of classes that can be used by application or system developers, to import and export data formatted according to a set of standards initially prescribed by the Versit consortium.

The plain-text formatted data can be included in emails, saved to disk or transferred from one application to another using streams. Two specifications have been published, one for the transmission of contact information and the other for the transmission of calendaring information in the form of vCards and vCalendars.

Although the information contained in vCard is different from that contained in vCalendar, the basic formatting of the information follows the same style.

Required background

Some knowledge of vCard and vCalendar specifications, which are documented on the Internet Mail Consortium's website at http://www.imc.org.

Key concepts

In this component a vCard or vCalendar is referred to as an entity. An entity has an array of properties. Entities can be nested, making them sub-entities.

The component has the following key concepts:

Parser

The parser converts the vCard and vCal data into a format understandable by the current system and vice-a-versa. The vCard and vCal are common standards used for exchanging contact and calendar data across different systems such as handheld devices, PDA and so on. Each handheld device or PDA store and interpret these kind of personal information in their own way. A parser reads and writes properties and sub-entities for an entity. The base class for parsers is provided by CVersitParser which provides the basic functionality for both vCard and vCal.

The CVersitParser class is extended to provide separate implementations for vCard, vCal and their sub-entities such as vEvent, vTodo and so on. The following are few such classes:

CParserVCard is a vCard parser that converts between a vCard entities, stored in a stream using the format standard set by the Internet Mail Consortium, and a vCard entities stored on a Symbian phone.
CParserVCal is a vCalendar parser that converts between a vCalendar entities stored in a stream, and vCalender entities stored on a Symbian phone.
CParserVCalEntity is a parser for vCalendar sub-entities such as, events and to-do lists.

The CVersitParser class provides support for vCard version 2.1 and vCalendar version 1.0 by default. But this class is not compatible with higher versions of vCard, and these compatibility issues are addressed in MVersitPlugIn abstract class. An implementation of MVersitPlugIn class along with a derived class of CParserVCard can extend the parser support to vCard versions above 2.1.

Property

A property consists of a property name, a property value and optionally one or more property parameters. They have the general form:

Property Name (; Parameter Name(= Parameter Value))* : Property Value

where items in brackets are optional and * indicates that the item may be repeated.

For example,

TEL; HOME; ENCODING=QUOTED-PRINTABLE; CHARSET=US-ASCII : 01234 567890

Here, TEL is the property name, HOME, ENCODING and CHARSET are property parameter names and QUOTED-PRINTABLE and US-ASCII are property parameter values. The component following the colon is the property value.

The property interface is provided by CParserProperty.

Property parameter

A property parameter describes an aspect of a property. A property may have multiple aspects. In the above example the TEL property has several aspects (parameters), such as HOME, ENCODING and CHARSET with their associated values QUOTED-PRINTABLE and US-ASCII.

The property parameter interface is provided by CParserParam.

Property value

A property value may be of any type, such as date/time, integer, string etc.

A number of classes are provided to support any type of data as a property value, these classes are derived from CParserPropertyValue.

Observer

The versit parser observer can find out the version of the entity being parsed, which is the version number of the vCard/vCalendar. Then the behaviour of the parser is adjusted according to the version number detected. The observer is implemented as a pure virtual plug-in class MVersitObserver, for use in conjunction with MVersitPlugIn class.

The implementor of MVersitObserver class can respond to new parser creation by setting MVersitPlugIn as the parser, and itself as the observer to parse the embedded sub-entity.

Architectural relationships

Any application or system intending to import or export vCards or vCalendars can use this component. At present, it is used by Contacts Model and Calendar components to support import and export of contact and calendar information.

The Versit libraries export a set of utility classes that allow clients to parse and generate data formatted according to the specifications first published by the Versit consortium (The specifications are now owned by the IMC).

In broad terms, the Versit API allows clients to:

Internalise Versit formatted data into container classes.
Externalise contact and calendar data.
Derive a custom Versit parser from the base classes.
Perform various utility functions (searching, modifying etc.) on the data.

It delivers four files:

Versit.dll - defines the client API common to all versit parser.
VCard.dll - implements a vCard v2.1 parser & generator.
VCal.dll - implements a vCalendar 1.0 parser & generator.
RVERSIT.MDL - implements a Recognizer which recognises Versit vCalendar and vCard files and reports their file type. This is according to the standard Symbian file recognizer pattern. For more information about recognizers, refer to Using MIME.

Internal Relationships

The Versit libraries are designed to provide a self contained set of tools. As such, they have no internal dependencies with other App-Services components. The diagram below gives an abstract illustration of the internal dependencies of the Versit components themselves.

Figure: Abstraction of Versit deliverables

As the diagram above illustrates, it is possible to make use of the Versit.dll library on its own. If vCard or vCalendar support is required then the Versit library must be included as both vCard.dll and vCal.dll depend on it.

It is also possible for users to develop their own Versit parsers using the base classes provided in Versit.dll and not include the vCard and vCalendar libraries.

External Relationships

It is possible for any third party code to make use of the Versit libraries. The only Symbian components that have a dependency on Versit are the App-Engines. The application engines provide API’s which allow their users to import and export Versit formatted data.

The mechanism used to allow these operations differs depending on the application engine and the documentation associated to each should be referred to for more detail. The two application engines that make use of Versit are the Contacts Model and Calendar components.

API summary

Figure: Relationship between different classes of the Versit component

Class Name	Description
CVersitParser	This is a generic parser class which provides functions implementing behaviour common to both vCalendar and vCard parsers.
CParserVCard	This is a vCard parser class derived from `CVersitParser`. It implements additional functionality needed to parse vCards, other than the generic functionality inherited from `CVersitParser`.
CParserVCal	This is a vCalendar parser class derived from `CVersitParser`. It also implements additional functionality needed to parse vCalendar, other than the generic functionality inherited from `CVersitParser`.
CParserVCalEntity	This is a parser for vCalendar sub-entities. A vCalendar sub-entity is a vEvent or vToDo contained in a vCalendar. vEvents and vToDos are derived from CRecurrenceParser, which provides recurrence functionality.
CParserProperty	This is a property class used to store properties of vCard and vCalendar, and also sub-entities of vCalendar such as vEvent and vToDo. Each property has a name, an optional value and one or more optional parameters.

Typical uses

The Versit component can be used by any application which needs to import or export vCards or vCalendars. The following are the typical use cases for this API.

Importing contact and calendar data

Any application can import contact and/or calendar data using this API. To import contact or calendar data from an external source, the client has to make use of appropriate parsers. That is, vCard parser to import contact data, and vCalendar parser to import calendar data. For more information, refer to How to Import Contact and Calendar Data.

Exporting contact and calendar data

Any application can export contact and/or calendar data using this API. To export contact or calendar data to an external source, clients have to make use of appropriate parsers. That is, vCard parser to export contact data, and vCalendar parser to export calendar data. For more information, refer to How to Export Contact and Calendar Data.

Creating a custom Versit parser

Apart from the typical vCard and vCalendar parsers, custom versit parser can be implemented using the CVersitParser class as the base class. These kind of parsers are needed, when the functionality provided by CVersitParser, CParserVCard and CParserVCal classes are not sufficient.

Using various utility functions

In addition to the normal import and export functionality, the client applications can use these APIs for character set conversions and to parse character strings using the VersitUtils class.