<?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 OS 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 OS 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 OS 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_d0e355013_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 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. </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_d0e355049_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>
</related-links></concept>