--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-8D7AEB5A-9A88-5B6D-B6B0-7126A56AA495.dita	Thu Jan 21 18:18:20 2010 +0000
@@ -0,0 +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 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>
\ No newline at end of file