--- a/Symbian3/SDK/Source/GUID-8D7AEB5A-9A88-5B6D-B6B0-7126A56AA495.dita Wed Mar 31 11:11:55 2010 +0100
+++ b/Symbian3/SDK/Source/GUID-8D7AEB5A-9A88-5B6D-B6B0-7126A56AA495.dita Fri Jun 11 12:39:03 2010 +0100
@@ -1,213 +1,213 @@
-<?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 & generator. </p> </li>
-<li id="GUID-830FF6FC-A5F1-54C1-AE99-67BC447F704D"><p>VCal.dll - implements
-a vCalendar 1.0 parser & 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_d0e381534_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_d0e381570_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>
+<?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 & generator. </p> </li>
+<li id="GUID-830FF6FC-A5F1-54C1-AE99-67BC447F704D"><p>VCal.dll - implements
+a vCalendar 1.0 parser & 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>
</related-links></concept>
\ No newline at end of file