|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-8D7AEB5A-9A88-5B6D-B6B0-7126A56AA495" xml:lang="en"><title>Versit |
|
13 Overview</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>This topic describes the Versit component, which can be used to import |
|
15 and export contact and calendar information. </p> |
|
16 <section id="GUID-AECE894E-FC12-4A34-85C6-DA1693678E0C"><title>Purpose</title> <p>The |
|
17 Versit component provides a set of classes that can be used by application |
|
18 or system developers, to import and export data formatted according to a set |
|
19 of standards initially prescribed by the Versit consortium. </p> <p>The plain-text |
|
20 formatted data can be included in emails, saved to disk or transferred from |
|
21 one application to another using streams. Two specifications have been published, |
|
22 one for the transmission of contact information and the other for the transmission |
|
23 of calendaring information in the form of vCards and vCalendars. </p> <p>Although |
|
24 the information contained in vCard is different from that contained in vCalendar, |
|
25 the basic formatting of the information follows the same style. </p> </section> |
|
26 <section id="GUID-D85D8717-F895-4AA2-A8F7-7BA3F7F2C1FF"><title>Required background</title> <p>Some |
|
27 knowledge of vCard and vCalendar specifications, which are documented on the |
|
28 Internet Mail Consortium's website at <xref href="http://www.imc.org/pdi/" scope="external">http://www.imc.org</xref>. </p> </section> |
|
29 <section id="GUID-928B9A7F-5A93-4549-877E-19B48F747422"><title>Key concepts</title> <p>In |
|
30 this component a vCard or vCalendar is referred to as an entity. An entity |
|
31 has an array of properties. Entities can be nested, making them sub-entities. </p> <p>The |
|
32 component has the following key concepts: </p> <dl> |
|
33 <dlentry> |
|
34 <dt>Parser</dt> |
|
35 <dd><p>The parser converts the vCard and vCal data into a format understandable |
|
36 by the current system and vice-a-versa. The vCard and vCal are common standards |
|
37 used for exchanging contact and calendar data across different systems such |
|
38 as handheld devices, PDA and so on. Each handheld device or PDA store and |
|
39 interpret these kind of personal information in their own way. A parser reads |
|
40 and writes properties and sub-entities for an entity. The base class for parsers |
|
41 is provided by <xref href="GUID-6D7CB0C1-2311-30A3-B0E8-A9B5BBBA395C.dita"><apiname>CVersitParser</apiname></xref> which provides the basic functionality |
|
42 for both vCard and vCal. </p> <p>The <codeph>CVersitParser</codeph> class |
|
43 is extended to provide separate implementations for vCard, vCal and their |
|
44 sub-entities such as vEvent, vTodo and so on. The following are few such classes: </p> <ul> |
|
45 <li id="GUID-9D84C4F1-1802-56F6-AA12-611759FE04D5"><p> <xref href="GUID-F4BEE3F4-F268-345D-B727-2C1D5E25F3F7.dita"><apiname>CParserVCard</apiname></xref> is |
|
46 a vCard parser that converts between a vCard entities, stored in a stream |
|
47 using the format standard set by the Internet Mail Consortium, and a vCard |
|
48 entities stored on a Symbian phone. </p> </li> |
|
49 <li id="GUID-F03F393F-4D4C-5CD3-A914-CA9FA90BC3DE"><p> <xref href="GUID-6BEFF6A7-FBD8-306D-98A4-8711E788C702.dita"><apiname>CParserVCal</apiname></xref> is |
|
50 a vCalendar parser that converts between a vCalendar entities stored in a |
|
51 stream, and vCalender entities stored on a Symbian phone. </p> </li> |
|
52 <li id="GUID-078030ED-1974-55DF-948F-2F56544EE0F2"><p> <xref href="GUID-7E0772C1-42AC-3204-95CB-E0D2FB7FA17A.dita"><apiname>CParserVCalEntity</apiname></xref> is |
|
53 a parser for vCalendar sub-entities such as, events and to-do lists. </p> </li> |
|
54 </ul> <p>The <codeph>CVersitParser</codeph> class provides support for vCard |
|
55 version 2.1 and vCalendar version 1.0 by default. But this class is not compatible |
|
56 with higher versions of vCard, and these compatibility issues are addressed |
|
57 in <codeph>MVersitPlugIn</codeph> abstract class. An implementation of <codeph>MVersitPlugIn</codeph> class |
|
58 along with a derived class of <codeph>CParserVCard</codeph> can extend the |
|
59 parser support to vCard versions above 2.1. </p> </dd> |
|
60 </dlentry> |
|
61 <dlentry> |
|
62 <dt>Property</dt> |
|
63 <dd><p>A property consists of a property name, a property value and optionally |
|
64 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 |
|
65 items in brackets are optional and * indicates that the item may be repeated. </p> <p>For |
|
66 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 |
|
67 parameter names and QUOTED-PRINTABLE and US-ASCII are property parameter values. |
|
68 The component following the colon is the property value. </p> <p>The property |
|
69 interface is provided by <xref href="GUID-895C3D03-FE10-329C-9437-2948686509C5.dita"><apiname>CParserProperty</apiname></xref>. </p> </dd> |
|
70 </dlentry> |
|
71 <dlentry> |
|
72 <dt>Property parameter</dt> |
|
73 <dd><p>A property parameter describes an aspect of a property. A property |
|
74 may have multiple aspects. In the above example the TEL property has several |
|
75 aspects (parameters), such as HOME, ENCODING and CHARSET with their associated |
|
76 values QUOTED-PRINTABLE and US-ASCII. </p> <p>The property parameter interface |
|
77 is provided by <xref href="GUID-4A02E5BD-39D3-34AD-B70B-8177144FF12C.dita"><apiname>CParserParam</apiname></xref>. </p> </dd> |
|
78 </dlentry> |
|
79 <dlentry> |
|
80 <dt>Property value</dt> |
|
81 <dd><p>A property value may be of any type, such as date/time, integer, string |
|
82 etc. </p> <p>A number of classes are provided to support any type of data |
|
83 as a property value, these classes are derived from <xref href="GUID-76E6CCFA-5BAC-34F1-A5B2-FB505A68E784.dita"><apiname>CParserPropertyValue</apiname></xref>. </p> </dd> |
|
84 </dlentry> |
|
85 <dlentry> |
|
86 <dt>Observer</dt> |
|
87 <dd><p>The versit parser observer can find out the version of the entity being |
|
88 parsed, which is the version number of the vCard/vCalendar. Then the behaviour |
|
89 of the parser is adjusted according to the version number detected. The observer |
|
90 is implemented as a pure virtual plug-in class <xref href="GUID-509B56E6-FA7B-3903-9DBC-908EC5363CFB.dita"><apiname>MVersitObserver</apiname></xref>, |
|
91 for use in conjunction with <codeph>MVersitPlugIn</codeph> class. </p> <p>The |
|
92 implementor of <codeph>MVersitObserver</codeph> class can respond to new parser |
|
93 creation by setting <codeph>MVersitPlugIn</codeph> as the parser, and itself |
|
94 as the observer to parse the embedded sub-entity. </p> </dd> |
|
95 </dlentry> |
|
96 </dl> </section> |
|
97 <section id="GUID-4E0DF6B1-B9B1-4A6C-966F-2C0237307E83"><title>Architectural |
|
98 relationships</title> <p>Any application or system intending to import or |
|
99 export vCards or vCalendars can use this component. At present, it is used |
|
100 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 |
|
101 to support import and export of contact and calendar information. </p> <p>The |
|
102 Versit libraries export a set of utility classes that allow clients to parse |
|
103 and generate data formatted according to the specifications first published |
|
104 by the Versit consortium (The specifications are now owned by the IMC). </p> <p>In |
|
105 broad terms, the Versit API allows clients to: </p> <ul> |
|
106 <li id="GUID-F1CAD47E-986F-5BFD-906A-70FCEF8CAD56"><p>Internalise Versit formatted |
|
107 data into container classes. </p> </li> |
|
108 <li id="GUID-34EC2D80-F27E-54FE-827C-36EFC3692442"><p>Externalise contact |
|
109 and calendar data. </p> </li> |
|
110 <li id="GUID-FF90C782-49BE-57F8-8FEB-F97D62D7451B"><p>Derive a custom Versit |
|
111 parser from the base classes. </p> </li> |
|
112 <li id="GUID-DA2EDC5F-DD00-5F68-8EB8-D28CEDEDC5C5"><p>Perform various utility |
|
113 functions (searching, modifying etc.) on the data. </p> </li> |
|
114 </ul> <p>It delivers four files: </p> <ul> |
|
115 <li id="GUID-56543C10-C588-5B03-A78D-4B473DF9DCEA"><p>Versit.dll - defines |
|
116 the client API common to all versit parser. </p> </li> |
|
117 <li id="GUID-BD75E9BB-DB18-5121-985D-B342D9920854"><p>VCard.dll - implements |
|
118 a vCard v2.1 parser & generator. </p> </li> |
|
119 <li id="GUID-830FF6FC-A5F1-54C1-AE99-67BC447F704D"><p>VCal.dll - implements |
|
120 a vCalendar 1.0 parser & generator. </p> </li> |
|
121 <li id="GUID-212C14CC-7D30-54B0-812D-1BEEA041D348"><p>RVERSIT.MDL - implements |
|
122 a Recognizer which recognises Versit vCalendar and vCard files and reports |
|
123 their file type. This is according to the standard Symbian file recognizer |
|
124 pattern. For more information about recognizers, refer to <xref href="GUID-F18D0E06-2FB8-5339-AF31-02CC7D5A8010.dita">Using |
|
125 MIME</xref>. </p> </li> |
|
126 </ul> <p><b>Internal Relationships </b> </p> <p>The Versit libraries are designed |
|
127 to provide a self contained set of tools. As such, they have no internal dependencies |
|
128 with other App-Services components. The diagram below gives an abstract illustration |
|
129 of the internal dependencies of the Versit components themselves. </p> <fig id="GUID-EF3BAA2A-3072-551A-B89C-99AB7F0A70DF"> |
|
130 <title> Abstraction of Versit deliverables </title> |
|
131 <image href="GUID-48D06D0E-C4D6-54F1-B603-7A75DEF669AA_d0e381534_href.png" placement="inline"/> |
|
132 </fig> <p>As the diagram above illustrates, it is possible to make use of |
|
133 the Versit.dll library on its own. If vCard or vCalendar support is required |
|
134 then the Versit library must be included as both vCard.dll and vCal.dll depend |
|
135 on it. </p> <p>It is also possible for users to develop their own Versit parsers |
|
136 using the base classes provided in Versit.dll and not include the vCard and |
|
137 vCalendar libraries. </p> <p><b>External Relationships </b> </p> <p>It is possible for any third party |
|
138 code to make use of the Versit libraries. The only Symbian components that |
|
139 have a dependency on Versit are the App-Engines. The application engines provide |
|
140 API’s which allow their users to import and export Versit formatted data. </p> <p>The |
|
141 mechanism used to allow these operations differs depending on the application |
|
142 engine and the documentation associated to each should be referred to for |
|
143 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> |
|
144 <section id="GUID-10536254-0D16-475C-82B3-451ADAFEC983"><title>API summary </title> <fig id="GUID-41DFB840-D409-5B34-949E-27E9B62A0F1E"> |
|
145 <title> Relationship between different classes of the Versit |
|
146 component </title> |
|
147 <image href="GUID-2A109FEC-5173-55FD-ACA8-3CAE48A93540_d0e381570_href.png" placement="inline"/> |
|
148 </fig> <table id="GUID-B009CAB5-2555-5AB2-AF90-41C7E61C2401"> |
|
149 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
|
150 <thead> |
|
151 <row> |
|
152 <entry>Class Name</entry> |
|
153 <entry>Description</entry> |
|
154 </row> |
|
155 </thead> |
|
156 <tbody> |
|
157 <row> |
|
158 <entry><p> <xref href="GUID-6D7CB0C1-2311-30A3-B0E8-A9B5BBBA395C.dita"><apiname>CVersitParser</apiname></xref> </p> </entry> |
|
159 <entry><p>This is a generic parser class which provides functions implementing |
|
160 behaviour common to both vCalendar and vCard parsers. </p> </entry> |
|
161 </row> |
|
162 <row> |
|
163 <entry><p> <xref href="GUID-F4BEE3F4-F268-345D-B727-2C1D5E25F3F7.dita"><apiname>CParserVCard</apiname></xref> </p> </entry> |
|
164 <entry><p>This is a vCard parser class derived from <codeph>CVersitParser</codeph>. |
|
165 It implements additional functionality needed to parse vCards, other than |
|
166 the generic functionality inherited from <codeph>CVersitParser</codeph>. </p> </entry> |
|
167 </row> |
|
168 <row> |
|
169 <entry><p> <xref href="GUID-6BEFF6A7-FBD8-306D-98A4-8711E788C702.dita"><apiname>CParserVCal</apiname></xref> </p> </entry> |
|
170 <entry><p>This is a vCalendar parser class derived from <codeph>CVersitParser</codeph>. |
|
171 It also implements additional functionality needed to parse vCalendar, other |
|
172 than the generic functionality inherited from <codeph>CVersitParser</codeph>. </p> </entry> |
|
173 </row> |
|
174 <row> |
|
175 <entry><p> <xref href="GUID-7E0772C1-42AC-3204-95CB-E0D2FB7FA17A.dita"><apiname>CParserVCalEntity</apiname></xref> </p> </entry> |
|
176 <entry><p>This is a parser for vCalendar sub-entities. A vCalendar sub-entity |
|
177 is a vEvent or vToDo contained in a vCalendar. vEvents and vToDos are derived |
|
178 from <xref href="GUID-5C95B1DF-4BBC-3196-AFA6-DC839837CF02.dita"><apiname>CRecurrenceParser</apiname></xref>, which provides recurrence functionality. </p> </entry> |
|
179 </row> |
|
180 <row> |
|
181 <entry><p> <xref href="GUID-895C3D03-FE10-329C-9437-2948686509C5.dita"><apiname>CParserProperty</apiname></xref> </p> </entry> |
|
182 <entry><p>This is a property class used to store properties of vCard and vCalendar, |
|
183 and also sub-entities of vCalendar such as vEvent and vToDo. Each property |
|
184 has a name, an optional value and one or more optional parameters. </p> </entry> |
|
185 </row> |
|
186 </tbody> |
|
187 </tgroup> |
|
188 </table> </section> |
|
189 <section id="GUID-2BC8DF31-058E-447F-A186-A563CBFAE550"><title>Typical uses</title> <p>The |
|
190 Versit component can be used by any application which needs to import or export |
|
191 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 |
|
192 contact and/or calendar data using this API. To import contact or calendar |
|
193 data from an external source, the client has to make use of appropriate parsers. |
|
194 That is, vCard parser to import contact data, and vCalendar parser to import |
|
195 calendar data. For more information, refer to <xref href="GUID-2A39CCBD-CADB-56B7-872A-1EC617AC7D93.dita">How |
|
196 to Import Contact and Calendar Data</xref>. </p> <p><b>Exporting contact and calendar data </b> </p> <p>Any application can export |
|
197 contact and/or calendar data using this API. To export contact or calendar |
|
198 data to an external source, clients have to make use of appropriate parsers. |
|
199 That is, vCard parser to export contact data, and vCalendar parser to export |
|
200 calendar data. For more information, refer to <xref href="GUID-082E47B3-8AAB-51B7-93F9-3C528B97D0A9.dita">How |
|
201 to Export Contact and Calendar Data</xref>. </p> <p><b>Creating a custom Versit parser </b> </p> <p>Apart from the typical vCard |
|
202 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 |
|
203 as the base class. These kind of parsers are needed, when the functionality |
|
204 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 |
|
205 are not sufficient. </p> <p><b>Using various utility functions </b> </p> <p>In addition to the normal |
|
206 import and export functionality, the client applications can use these APIs |
|
207 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> |
|
208 </conbody><related-links> |
|
209 <link href="GUID-40E64445-CBA3-59E4-A777-937609B311C9.dita"><linktext>Contacts |
|
210 Model Overview</linktext></link> |
|
211 <link href="GUID-3A6BEF56-ADBF-543E-B70A-52195DE3E92A.dita"><linktext>Calendar |
|
212 Overview</linktext></link> |
|
213 </related-links></concept> |