<?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-3A6BEF56-ADBF-543E-B70A-52195DE3E92A" xml:lang="en"><title>Calendar

Overview</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>The Calendar component provides access to calendar stores, with functionality

to fetch, update, save and delete calendar entries. </p>

<section id="GUID-E6396A88-AAA2-489F-AFDF-5E07229C1690"><title>Purpose and scope </title> <p>Calendar provides access to

calendar stores, with functionality to fetch, update, save and delete calendar

entries. This functionality is as the standard RFC 2445, which defines a common

format for openly exchanging calendar and scheduling information across the

internet. New functionality includes: attachment support, defining geographic

locations, logging, expanded search capabilities and support for removable

media. </p> </section>

<section id="GUID-9821DA75-4245-411B-AADF-AB7AB98E1D07"><title>Architectural relationship</title> <p>The Calendar component

uses the Alarm server and TZ (time zone converter) components and merges CalInterimApi

and AgnModel. </p> <p>Calendar is a single component that contains: Agenda

Server, AgnModel and CalInterimAPI. CalInterimAPI contains classes that hold

information about calendar entries. AgnModel is a DLL which is shared across

the client and the server. Agenda Server provides calendar file management

on behalf of all clients. </p> <p>Calendar's implementation of import and

export behaviour is done using the AgnVersit2 plug-in. </p> <fig id="GUID-EFB35AEC-41B2-5DD4-B029-D4BDC8A682DF">

<title>              Calendar dependencies            </title>

<image href="GUID-E2F6A71A-4A18-5E0B-AE77-C059C59448E4_d0e368521_href.png" placement="inline"/>

</fig> </section>

<section id="GUID-1E37BF6E-B69F-49AB-BA6A-F60463FACC5A"><title>Description</title> <p>This document describes the following

key areas: </p> <p id="GUID-BFCC991A-B456-5662-AFDE-5B86AAC6056F"><b>The Calendar Server</b> </p> <p>The

Calendar Server manipulates calendar files and connects to the

client when single or multiple sessions (<xref href="GUID-609318A7-43F1-3FC1-952B-146B1EA8115D.dita"><apiname>CCalSession</apiname></xref>) are

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>,

can be an appointment, a to-do item, an event, a reminder, or an anniversary.

It contains repeat definition and synchronisation information as well as group

scheduling data. </p> <p id="GUID-21C9AB08-D5E0-5E2C-91CE-2C8218EF8514"><b>Calendar views</b> </p> <p>The

API provides the following <xref href="GUID-CD8A3420-6C9B-5774-86FA-85CFE062C400.dita">views</xref> for

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

and manipulating calendar entries. For example, you can add, delete update

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

individual instance(s) that are generated from an entry to be accessed and

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

a <xref href="GUID-62195532-3FD0-5A3B-90E6-D624C4A60594.dita">calendar user</xref>,

such as a meeting participant. The class provides attributes and methods that

are common to all the calendar users, including the user’s email address,

sent-by and common name fields. </p> <p><b>Setting

the Repeat Rule</b> </p> <p><xref href="GUID-131A9070-AF80-5BC5-91D2-0F1C7019ABF2.dita">Setting

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

you to <xref href="GUID-7BB38C3E-BEA9-545B-AEC2-5E9078D0B8A2.dita">set an alarm</xref> of

a specific type. </p> <p><b>Categorising

an entry</b> </p> <p><xref href="GUID-710FADA2-7A6C-5D60-BCE5-8772071F2BD4.dita">Categorisation</xref> of

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

entries to be <xref href="GUID-0F1D1BC4-C8FB-55BE-83FE-DD604C4A9CA3.dita">exported

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

API uses two types of <xref href="GUID-3987D040-27F7-5226-96AC-D578ECA4C0A2.dita">callback

interfaces</xref>: change notifications, and progress/completion notifications.

Change notifications monitor changes to calendar entries. Progress/completion

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

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

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,

modifies and deletes calendar files on <xref href="GUID-DA0F4990-DDC4-5B0A-A446-A3C8672DA95A.dita">removable

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

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

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

iCalendar and vCalendar that Calendar supports using the AgnVersit2 plug-in.

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

offer the ability to <xref href="GUID-20DDA21D-B5DE-5D24-9E75-69C68EAF1782.dita">search</xref> all

text fields, to search entries within a given time frame, and to return results

in an iterator class. </p> <p id="GUID-4084C15D-CC3C-57F3-8605-10CF62CEDD27"><b>Adding a user-defined 32-bit

field</b> </p> <p>Calendar entries now allows for creation of a <xref href="GUID-0A66A882-09C8-5BB6-89A2-87133BD63338.dita">user-defined

32-bit field</xref>. The value of the field is defined by the vendor. Field

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>