Versit -Overview

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.

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

-Contacts -Model Overview -Calendar -Overview + + + + + +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.

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

+Contacts +Model Overview +Calendar +Overview

\ No newline at end of file