<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-8D7AEB5A-9A88-5B6D-B6B0-7126A56AA495" xml:lang="en"><title>Versit

Overview</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>This topic describes the Versit component, which can be used to import

and export contact and calendar information. </p>

<section id="GUID-AECE894E-FC12-4A34-85C6-DA1693678E0C"><title>Purpose</title> <p>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. </p> <p>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. </p> <p>Although

the information contained in vCard is different from that contained in vCalendar,

the basic formatting of the information follows the same style. </p> </section>

<section id="GUID-D85D8717-F895-4AA2-A8F7-7BA3F7F2C1FF"><title>Required background</title> <p>Some

knowledge of vCard and vCalendar specifications, which are documented on the

Internet Mail Consortium's website at <xref href="http://www.imc.org/pdi/" scope="external">http://www.imc.org</xref>. </p> </section>

<section id="GUID-928B9A7F-5A93-4549-877E-19B48F747422"><title>Key concepts</title> <p>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. </p> <p>The

component has the following key concepts: </p> <dl>

<dlentry>

<dt>Parser</dt>

<dd><p>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 <xref href="GUID-6D7CB0C1-2311-30A3-B0E8-A9B5BBBA395C.dita"><apiname>CVersitParser</apiname></xref> which provides the basic functionality

for both vCard and vCal. </p> <p>The <codeph>CVersitParser</codeph> 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: </p> <ul>

<li id="GUID-9D84C4F1-1802-56F6-AA12-611759FE04D5"><p> <xref href="GUID-F4BEE3F4-F268-345D-B727-2C1D5E25F3F7.dita"><apiname>CParserVCard</apiname></xref> 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. </p> </li>

<li id="GUID-F03F393F-4D4C-5CD3-A914-CA9FA90BC3DE"><p> <xref href="GUID-6BEFF6A7-FBD8-306D-98A4-8711E788C702.dita"><apiname>CParserVCal</apiname></xref> is

a vCalendar parser that converts between a vCalendar entities stored in a

stream, and vCalender entities stored on a Symbian phone. </p> </li>

<li id="GUID-078030ED-1974-55DF-948F-2F56544EE0F2"><p> <xref href="GUID-7E0772C1-42AC-3204-95CB-E0D2FB7FA17A.dita"><apiname>CParserVCalEntity</apiname></xref> is

a parser for vCalendar sub-entities such as, events and to-do lists. </p> </li>

</ul> <p>The <codeph>CVersitParser</codeph> 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 <codeph>MVersitPlugIn</codeph> abstract class. An implementation of <codeph>MVersitPlugIn</codeph> class

along with a derived class of <codeph>CParserVCard</codeph> can extend the

parser support to vCard versions above 2.1. </p> </dd>

</dlentry>

<dlentry>

<dt>Property</dt>

<dd><p>A property consists of a property name, a property value and optionally

one or more property parameters. They have the general form: </p> <codeblock id="GUID-52BCA483-C9AD-5F54-9733-3A1D45E638A0" xml:space="preserve">Property Name (; Parameter Name(= Parameter Value))* : Property Value</codeblock> <p>where

items in brackets are optional and * indicates that the item may be repeated. </p> <p>For

example, </p> <codeblock id="GUID-1AF7B9AA-6D83-5BF8-8CB4-919F069310D6" xml:space="preserve">TEL; HOME; ENCODING=QUOTED-PRINTABLE; CHARSET=US-ASCII : 01234 567890</codeblock> <p>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. </p> <p>The property

interface is provided by <xref href="GUID-895C3D03-FE10-329C-9437-2948686509C5.dita"><apiname>CParserProperty</apiname></xref>. </p> </dd>

</dlentry>

<dlentry>

<dt>Property parameter</dt>

<dd><p>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. </p> <p>The property parameter interface

is provided by <xref href="GUID-4A02E5BD-39D3-34AD-B70B-8177144FF12C.dita"><apiname>CParserParam</apiname></xref>. </p> </dd>

</dlentry>

<dlentry>

<dt>Property value</dt>

<dd><p>A property value may be of any type, such as date/time, integer, string

etc. </p> <p>A number of classes are provided to support any type of data

as a property value, these classes are derived from <xref href="GUID-76E6CCFA-5BAC-34F1-A5B2-FB505A68E784.dita"><apiname>CParserPropertyValue</apiname></xref>. </p> </dd>

</dlentry>

<dlentry>

<dt>Observer</dt>

<dd><p>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 <xref href="GUID-509B56E6-FA7B-3903-9DBC-908EC5363CFB.dita"><apiname>MVersitObserver</apiname></xref>,

for use in conjunction with <codeph>MVersitPlugIn</codeph> class. </p> <p>The

implementor of <codeph>MVersitObserver</codeph> class can respond to new parser

creation by setting <codeph>MVersitPlugIn</codeph> as the parser, and itself

as the observer to parse the embedded sub-entity. </p> </dd>

</dlentry>

</dl> </section>

<section id="GUID-4E0DF6B1-B9B1-4A6C-966F-2C0237307E83"><title>Architectural

relationships</title> <p>Any application or system intending to import or

export vCards or vCalendars can use this component. At present, it is used

by <xref href="GUID-40E64445-CBA3-59E4-A777-937609B311C9.dita">Contacts Model</xref> and <xref href="GUID-3A6BEF56-ADBF-543E-B70A-52195DE3E92A.dita">Calendar</xref> components

to support import and export of contact and calendar information. </p> <p>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). </p> <p>In

broad terms, the Versit API allows clients to: </p> <ul>

<li id="GUID-F1CAD47E-986F-5BFD-906A-70FCEF8CAD56"><p>Internalise Versit formatted

data into container classes. </p> </li>

<li id="GUID-34EC2D80-F27E-54FE-827C-36EFC3692442"><p>Externalise contact

and calendar data. </p> </li>

<li id="GUID-FF90C782-49BE-57F8-8FEB-F97D62D7451B"><p>Derive a custom Versit

parser from the base classes. </p> </li>

<li id="GUID-DA2EDC5F-DD00-5F68-8EB8-D28CEDEDC5C5"><p>Perform various utility

functions (searching, modifying etc.) on the data. </p> </li>

</ul> <p>It delivers four files: </p> <ul>

<li id="GUID-56543C10-C588-5B03-A78D-4B473DF9DCEA"><p>Versit.dll - defines

the client API common to all versit parser. </p> </li>

<li id="GUID-BD75E9BB-DB18-5121-985D-B342D9920854"><p>VCard.dll - implements

a vCard v2.1 parser &amp; generator. </p> </li>

<li id="GUID-830FF6FC-A5F1-54C1-AE99-67BC447F704D"><p>VCal.dll - implements

a vCalendar 1.0 parser &amp; generator. </p> </li>

<li id="GUID-212C14CC-7D30-54B0-812D-1BEEA041D348"><p>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 <xref href="GUID-F18D0E06-2FB8-5339-AF31-02CC7D5A8010.dita">Using

MIME</xref>. </p> </li>

</ul> <p><b>Internal Relationships </b> </p> <p>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. </p> <fig id="GUID-EF3BAA2A-3072-551A-B89C-99AB7F0A70DF">

<title>              Abstraction of Versit deliverables            </title>

<image href="GUID-48D06D0E-C4D6-54F1-B603-7A75DEF669AA_d0e375455_href.png" placement="inline"/>

</fig> <p>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. </p> <p>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. </p> <p><b>External Relationships </b> </p> <p>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. </p> <p>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 <xref href="GUID-40E64445-CBA3-59E4-A777-937609B311C9.dita">Contacts Model</xref> and <xref href="GUID-3A6BEF56-ADBF-543E-B70A-52195DE3E92A.dita">Calendar</xref> components. </p> </section>

<section id="GUID-10536254-0D16-475C-82B3-451ADAFEC983"><title>API summary </title> <fig id="GUID-41DFB840-D409-5B34-949E-27E9B62A0F1E">

<title>              Relationship between different classes of the Versit

component            </title>

<image href="GUID-2A109FEC-5173-55FD-ACA8-3CAE48A93540_d0e375491_href.png" placement="inline"/>

</fig> <table id="GUID-B009CAB5-2555-5AB2-AF90-41C7E61C2401">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<thead>

<row>

<entry>Class Name</entry>

<entry>Description</entry>

</row>

</thead>

<tbody>

<row>

<entry><p> <xref href="GUID-6D7CB0C1-2311-30A3-B0E8-A9B5BBBA395C.dita"><apiname>CVersitParser</apiname></xref>  </p> </entry>

<entry><p>This is a generic parser class which provides functions implementing

behaviour common to both vCalendar and vCard parsers. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-F4BEE3F4-F268-345D-B727-2C1D5E25F3F7.dita"><apiname>CParserVCard</apiname></xref>  </p> </entry>

<entry><p>This is a vCard parser class derived from <codeph>CVersitParser</codeph>.

It implements additional functionality needed to parse vCards, other than

the generic functionality inherited from <codeph>CVersitParser</codeph>. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-6BEFF6A7-FBD8-306D-98A4-8711E788C702.dita"><apiname>CParserVCal</apiname></xref>  </p> </entry>

<entry><p>This is a vCalendar parser class derived from <codeph>CVersitParser</codeph>.

It also implements additional functionality needed to parse vCalendar, other

than the generic functionality inherited from <codeph>CVersitParser</codeph>. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-7E0772C1-42AC-3204-95CB-E0D2FB7FA17A.dita"><apiname>CParserVCalEntity</apiname></xref>  </p> </entry>

<entry><p>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 <xref href="GUID-5C95B1DF-4BBC-3196-AFA6-DC839837CF02.dita"><apiname>CRecurrenceParser</apiname></xref>, which provides recurrence functionality. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-895C3D03-FE10-329C-9437-2948686509C5.dita"><apiname>CParserProperty</apiname></xref>  </p> </entry>

<entry><p>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. </p> </entry>

</row>

</tbody>

</tgroup>

</table> </section>

<section id="GUID-2BC8DF31-058E-447F-A186-A563CBFAE550"><title>Typical uses</title> <p>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. </p> <p><b>Importing contact and calendar data </b> </p> <p>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 <xref href="GUID-2A39CCBD-CADB-56B7-872A-1EC617AC7D93.dita">How

to Import Contact and Calendar Data</xref>. </p> <p><b>Exporting contact and calendar data </b> </p> <p>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 <xref href="GUID-082E47B3-8AAB-51B7-93F9-3C528B97D0A9.dita">How

to Export Contact and Calendar Data</xref>. </p> <p><b>Creating a custom Versit parser </b> </p> <p>Apart from the typical vCard

and vCalendar parsers, custom versit parser can be implemented using the <xref href="GUID-6D7CB0C1-2311-30A3-B0E8-A9B5BBBA395C.dita"><apiname>CVersitParser</apiname></xref> class

as the base class. These kind of parsers are needed, when the functionality

provided by <codeph>CVersitParser</codeph>, <xref href="GUID-F4BEE3F4-F268-345D-B727-2C1D5E25F3F7.dita"><apiname>CParserVCard</apiname></xref> and <xref href="GUID-6BEFF6A7-FBD8-306D-98A4-8711E788C702.dita"><apiname>CParserVCal</apiname></xref> classes

are not sufficient. </p> <p><b>Using various utility functions </b> </p> <p>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 <xref href="GUID-71CCD94C-4F1B-3F80-A1F1-C8708B4181C6.dita"><apiname>VersitUtils</apiname></xref> class. </p> </section>

</conbody><related-links>

<link href="GUID-40E64445-CBA3-59E4-A777-937609B311C9.dita"><linktext>Contacts

Model Overview</linktext></link>

<link href="GUID-3A6BEF56-ADBF-543E-B70A-52195DE3E92A.dita"><linktext>Calendar

Overview</linktext></link>