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 OS phone.

+
CParserVCal is +a vCalendar parser that converts between a vCalendar entities stored in a +stream, and vCalender entities stored on a Symbian OS 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 OS 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.

+ 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 OS 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 + 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.