|
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-3A6BEF56-ADBF-543E-B70A-52195DE3E92A" xml:lang="en"><title>Calendar |
|
13 Overview</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>The Calendar component provides access to calendar stores, with functionality |
|
15 to fetch, update, save and delete calendar entries. </p> |
|
16 <section id="GUID-E6396A88-AAA2-489F-AFDF-5E07229C1690"><title>Purpose and scope </title> <p>Calendar provides access to |
|
17 calendar stores, with functionality to fetch, update, save and delete calendar |
|
18 entries. This functionality is as the standard RFC 2445, which defines a common |
|
19 format for openly exchanging calendar and scheduling information across the |
|
20 internet. New functionality includes: attachment support, defining geographic |
|
21 locations, logging, expanded search capabilities and support for removable |
|
22 media. </p> </section> |
|
23 <section id="GUID-9821DA75-4245-411B-AADF-AB7AB98E1D07"><title>Architectural relationship</title> <p>The Calendar component |
|
24 uses the Alarm server and TZ (time zone converter) components and merges CalInterimApi |
|
25 and AgnModel. </p> <p>Calendar is a single component that contains: Agenda |
|
26 Server, AgnModel and CalInterimAPI. CalInterimAPI contains classes that hold |
|
27 information about calendar entries. AgnModel is a DLL which is shared across |
|
28 the client and the server. Agenda Server provides calendar file management |
|
29 on behalf of all clients. </p> <p>Calendar's implementation of import and |
|
30 export behaviour is done using the AgnVersit2 plug-in. </p> <fig id="GUID-EFB35AEC-41B2-5DD4-B029-D4BDC8A682DF"> |
|
31 <title> Calendar dependencies </title> |
|
32 <image href="GUID-E2F6A71A-4A18-5E0B-AE77-C059C59448E4_d0e374591_href.png" placement="inline"/> |
|
33 </fig> </section> |
|
34 <section id="GUID-1E37BF6E-B69F-49AB-BA6A-F60463FACC5A"><title>Description</title> <p>This document describes the following |
|
35 key areas: </p> <p id="GUID-BFCC991A-B456-5662-AFDE-5B86AAC6056F"><b>The Calendar Server</b> </p> <p>The |
|
36 Calendar Server manipulates calendar files and connects to the |
|
37 client when single or multiple sessions (<xref href="GUID-609318A7-43F1-3FC1-952B-146B1EA8115D.dita"><apiname>CCalSession</apiname></xref>) are |
|
38 instantiated. </p> <p id="GUID-69F4F826-D9BC-50D1-A6DA-8CB82891BEB8"><b>Calendar entries</b> </p> <p>A <xref href="GUID-9B428B4E-83B7-5EE3-8D63-E2B0602D1D91.dita">calendar entry</xref>, class <xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita"><apiname>CCalEntry</apiname></xref>, |
|
39 can be an appointment, a to-do item, an event, a reminder, or an anniversary. |
|
40 It contains repeat definition and synchronisation information as well as group |
|
41 scheduling data. </p> <p id="GUID-21C9AB08-D5E0-5E2C-91CE-2C8218EF8514"><b>Calendar views</b> </p> <p>The |
|
42 API provides the following <xref href="GUID-CD8A3420-6C9B-5774-86FA-85CFE062C400.dita">views</xref> for |
|
43 accessing the calendar: </p> <p><b>Entry view </b> </p> <p> <xref href="GUID-D2835D4E-F0A8-3EDE-BC13-B45E52170556.dita"><apiname>CCalEntryView</apiname></xref> allows accessing |
|
44 and manipulating calendar entries. For example, you can add, delete update |
|
45 and search for a calendar entry, </p> <p><b>Instance view </b> </p> <p> <xref href="GUID-58BA8611-A364-3E30-B5F0-E5787E19C48C.dita"><apiname>CCalInstanceView</apiname></xref> allows |
|
46 individual instance(s) that are generated from an entry to be accessed and |
|
47 deleted. </p> <p id="GUID-20ACA14A-954F-58FC-B422-E42B5B19B04E"><b>Calendar user</b> </p> <p> <xref href="GUID-FBFE40BE-BF1A-3A12-A3B6-D2BDB5B6406D.dita"><apiname>CCalUser</apiname></xref> represents |
|
48 a <xref href="GUID-62195532-3FD0-5A3B-90E6-D624C4A60594.dita">calendar user</xref>, |
|
49 such as a meeting participant. The class provides attributes and methods that |
|
50 are common to all the calendar users, including the user’s email address, |
|
51 sent-by and common name fields. </p> <p><b>Setting |
|
52 the Repeat Rule</b> </p> <p><xref href="GUID-131A9070-AF80-5BC5-91D2-0F1C7019ABF2.dita">Setting |
|
53 the repeat rule</xref> allows events to occur regularly at specified intervals. </p> <p><b>Setting the alarm</b> </p> <p>Within a calendar entry <xref href="GUID-211D3640-9862-3F78-98FC-9793578117A9.dita"><apiname>CCalAlarm</apiname></xref> allows |
|
54 you to <xref href="GUID-7BB38C3E-BEA9-545B-AEC2-5E9078D0B8A2.dita">set an alarm</xref> of |
|
55 a specific type. </p> <p><b>Categorising |
|
56 an entry</b> </p> <p><xref href="GUID-710FADA2-7A6C-5D60-BCE5-8772071F2BD4.dita">Categorisation</xref> of |
|
57 calendar entries can be done using built-in or user-defined types. </p> <p><b>Importing and Exporting Entries</b> </p> <p>This API enables calendar |
|
58 entries to be <xref href="GUID-0F1D1BC4-C8FB-55BE-83FE-DD604C4A9CA3.dita">exported |
|
59 and imported</xref> to and from a specific data format. </p> <p id="GUID-EDE3A38D-8B6B-56B6-B301-B6D64BF69181"><b>Callback interfaces</b> </p> <p>The |
|
60 API uses two types of <xref href="GUID-3987D040-27F7-5226-96AC-D578ECA4C0A2.dita">callback |
|
61 interfaces</xref>: change notifications, and progress/completion notifications. |
|
62 Change notifications monitor changes to calendar entries. Progress/completion |
|
63 notifications monitor the progress and completion of asynchronous tasks. </p> <p id="GUID-2FED42C3-251E-5713-8A75-AAC6393175EF"><b>Attachment support</b> </p> <p>Calendar |
|
64 provides the ability to associate an object with a calendar entry. An <xref href="GUID-32F8114A-B7EF-5B0B-BD9B-0D3C5F09D7E6.dita">attachment</xref> can be |
|
65 a URI reference, a file or binary data. </p> <p id="GUID-87AC8BD1-2F12-5A51-9498-9A5BBE5C306A"><b>Removable media support</b> </p> <p>Creates, |
|
66 modifies and deletes calendar files on <xref href="GUID-DA0F4990-DDC4-5B0A-A446-A3C8672DA95A.dita">removable |
|
67 media</xref>. </p> <p id="GUID-EB0BABDA-2949-5C5D-8F6E-83E9075A236C"><b>GEO property</b> </p> <p>The <xref href="GUID-01299529-4390-5C16-8459-1D9C1B6F3EF3.dita">GEO property</xref> represents |
|
68 the geographical location of a calendar entry. </p> <p id="GUID-2C4FA107-1C56-5C44-9B78-AF567ED936B1"><b>TRANSP property</b> </p> <p>The <xref href="GUID-6D29FF23-B034-5FE9-90C3-A62CD54D67D3.dita">TRANSP property</xref> indicates |
|
69 whether an entry 'blocks' a calendar busy view. </p> <p><b>iCalendar and vCalendar properties</b> </p> <p>Lists the <xref href="GUID-7811C33D-96D3-5001-B4D3-92BF44F39B2C.dita">properties</xref> in |
|
70 iCalendar and vCalendar that Calendar supports using the AgnVersit2 plug-in. |
|
71 Also details the import and export of time properties. </p> <p id="GUID-E680C30C-BD55-5F1B-9B68-DB07BCA79D05"><b>Expanded search capabilities</b> </p> <p>These |
|
72 offer the ability to <xref href="GUID-20DDA21D-B5DE-5D24-9E75-69C68EAF1782.dita">search</xref> all |
|
73 text fields, to search entries within a given time frame, and to return results |
|
74 in an iterator class. </p> <p id="GUID-4084C15D-CC3C-57F3-8605-10CF62CEDD27"><b>Adding a user-defined 32-bit |
|
75 field</b> </p> <p>Calendar entries now allows for creation of a <xref href="GUID-0A66A882-09C8-5BB6-89A2-87133BD63338.dita">user-defined |
|
76 32-bit field</xref>. The value of the field is defined by the vendor. Field |
|
77 creation, storage and access are carried out by APIs within the <xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita"><apiname>CCalEntry</apiname></xref> class. </p> </section> |
|
78 </conbody></concept> |