<?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-F8E4D4AC-878A-52C5-A04D-9E116A0087D5" xml:lang="en"><title>CalInterimAPI:

Using the Calendar API</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-F8DBB917-A597-4688-BE28-93EA2CAB64A7"><title>Description</title> <p>This example demonstrates how to use

the Calendar API. The main class in the example, <codeph>CCalExample</codeph>,

creates and opens a calendar file, then creates a view of the entries in the

file. It then creates a calendar entry and adds it to the file, via the view.

Next, it sets properties such as attendees, category, and description. It

then adds a repeat appointment called the 'originating entry' and an entry

modifying the instances of the originating entry (modifying entry). It finally

deletes the originating entry thereby deleting all the modifying entries. </p> <p><b> The

calendar file</b> </p> <p> <codeph>CCalExample::ConstructL()</codeph> instantiates

a <codeph>CCalSession</codeph> with the calendar server by calling <xref href="GUID-609318A7-43F1-3FC1-952B-146B1EA8115D.dita#GUID-609318A7-43F1-3FC1-952B-146B1EA8115D/GUID-B7B697D9-05CF-399A-9509-60E08BF5A04C"><apiname>CCalSession::NewL()</apiname></xref>.

All calendar file operations, for instance creation and opening, are done

through the <codeph>CCalSession</codeph> class. </p> <p>Note that a session

with the calendar server must exist before you can use any of the Calendar

API classes, and the session object must not be destroyed until all the objects

which were created by referencing it have been destroyed. </p> <p>Next, <codeph>CCalExample::ConstructL()</codeph> creates

and opens a named calendar file, to store the calendar entries (using <xref href="GUID-609318A7-43F1-3FC1-952B-146B1EA8115D.dita#GUID-609318A7-43F1-3FC1-952B-146B1EA8115D/GUID-ED607714-0F76-3708-A303-29E376936E32"><apiname>CCalSession::CreateCalFileL()</apiname></xref> and <xref href="GUID-609318A7-43F1-3FC1-952B-146B1EA8115D.dita#GUID-609318A7-43F1-3FC1-952B-146B1EA8115D/GUID-8A49B99E-6272-3A19-9032-FBDDDF6AEFE9"><apiname>CCalSession::OpenL()</apiname></xref>). File creation leaves with <codeph>KErrAlreadyExists</codeph> if a file

with that name already exists. </p> <p><b>The calendar entry view</b> </p> <p>A

calendar entry defines a type of calendar event. There are several types of

entries; to-do, appointment, all day event, reminder and anniversary. A calendar

entry view (<xref href="GUID-D2835D4E-F0A8-3EDE-BC13-B45E52170556.dita"><apiname>CCalEntryView</apiname></xref>) is used to access and manipulate

calendar entries. In this example it is used to display the non-repeating

appointment. </p> <p>View creation can take some time because of the processing

that must be done in the server to prepare entry indexes. So, <xref href="GUID-D2835D4E-F0A8-3EDE-BC13-B45E52170556.dita#GUID-D2835D4E-F0A8-3EDE-BC13-B45E52170556/GUID-795FE89C-9074-3DFB-9C67-99E002DE386C"><apiname>CCalEntryView::NewL()</apiname></xref> takes

a progress callback object (<xref href="GUID-1A1D94E6-AD7C-3202-B1BD-A1583FA34A5F.dita"><apiname>MCalProgressCallBack</apiname></xref>). When

the callback function <xref href="GUID-1A1D94E6-AD7C-3202-B1BD-A1583FA34A5F.dita#GUID-1A1D94E6-AD7C-3202-B1BD-A1583FA34A5F/GUID-CDF9D6D4-BE72-3FF3-8E65-2C3D5B5B6230"><apiname>MCalProgressCallBack::Completed()</apiname></xref> is

called, the view is ready for use. <codeph>CCalExample</codeph> implements

the <xref href="GUID-1A1D94E6-AD7C-3202-B1BD-A1583FA34A5F.dita"><apiname>MCalProgressCallBack</apiname></xref> interface. </p> <p><b>Calendar

entries </b> </p> <p>A calendar entry is created using <xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita#GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801/GUID-AAFDB9B2-260A-3CB4-BD6E-058A04FEC327"><apiname>CCalEntry::NewL()</apiname></xref>.

This specifies the type of entry, its global UID and some optional properties

used for group scheduling. </p> <p>An entry's start and end times are represented

using class <xref href="GUID-5C206B40-0ED3-33F3-A52A-A25311C996C1.dita"><apiname>TCalTime</apiname></xref>. This class requires the caller to

specify whether the time is UTC or local. In this example, the times are considered

to be local, so <xref href="GUID-5C206B40-0ED3-33F3-A52A-A25311C996C1.dita#GUID-5C206B40-0ED3-33F3-A52A-A25311C996C1/GUID-D725177F-A243-376C-BD26-53E97FC1ED8C"><apiname>TCalTime::SetTimeLocalL()</apiname></xref> is called before

setting the entry's start and end times using <xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita#GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801/GUID-4DCAD199-2A36-364D-98CE-BB6222FD2523"><apiname>CCalEntry::SetStartAndEndTimeL()</apiname></xref>. </p> <p> <xref href="GUID-D2835D4E-F0A8-3EDE-BC13-B45E52170556.dita#GUID-D2835D4E-F0A8-3EDE-BC13-B45E52170556/GUID-41282158-9CC7-3563-A542-834BE2B10D78"><apiname>CCalEntryView::StoreL()</apiname></xref> is used to store one or more new entries into the file. <xref href="GUID-D2835D4E-F0A8-3EDE-BC13-B45E52170556.dita#GUID-D2835D4E-F0A8-3EDE-BC13-B45E52170556/GUID-43FA0568-E254-3C7C-BC4C-1C73AFB6421A"><apiname>CCalEntryView::FetchL()</apiname></xref> is

used to retrieve entries, based on their UID and <xref href="GUID-D2835D4E-F0A8-3EDE-BC13-B45E52170556.dita#GUID-D2835D4E-F0A8-3EDE-BC13-B45E52170556/GUID-536FA411-5D58-3CE5-8F10-22FA8089FBBF"><apiname>CCalEntryView::UpdateL()</apiname></xref> is

used to update one or more entries. </p> <p><b>Originating and modifying an

entry</b> </p> <p>The originating entry (parent entry) is a repeating appointment.

The modifying entry (child entry) inherits all properties of the originating

entry. It can have a different repeat rule and description from its originating

entry. The originating and its modified (children) entries will have the same

UID. </p> <p><b>Calendar user</b> </p> <p>Attendee is a specialised calendar

user information (for example, email ID, phone number etc.) which is used

only in group scheduled entries for attendees of an event, and not for a single

calendar user. <xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita#GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801/GUID-D6202737-D180-34C5-9FB0-D19673689ECE"><apiname>CCalEntry::AttendeesL()</apiname></xref> is called to get

a list of attendees. Attendees can be added to or deleted from a calendar

entry using <xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita#GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801/GUID-88CD1003-A7EE-332D-98DF-784B8BACE39C"><apiname>CCalEntry::AddAttendeeL</apiname></xref> and <xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita#GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801/GUID-21A0AA94-BBB4-3547-9559-0B137348AC30"><apiname>CCalEntry::DeleteAttendeeL()</apiname></xref> respectively. </p> <p><b>Categorising

an entry</b> </p> <p>A calendar entry can be categorised into pre-defined

or user defined types such as appointment, business,education, holiday etc.

In this example we have used extended category and not the pre-defined ones. </p> <p>Create

a new category using <xref href="GUID-B04F36D1-88B6-3D87-836A-130C0B862515.dita#GUID-B04F36D1-88B6-3D87-836A-130C0B862515/GUID-A3E3148D-BF9A-3B5D-AFD8-C21C3FF21ED9"><apiname>CCalCategory::NewL()</apiname></xref> and pass a buffer

as argument. <xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita#GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801/GUID-09038E6D-63B8-38F8-9B83-BA6693675A06"><apiname>CCalEntry::AddCategoryL()</apiname></xref> is called to set

a category for the calendar entry. To get a list of available categories call <xref href="GUID-C880013D-3E6F-38C7-B8C5-EB90E7070FEB.dita#GUID-C880013D-3E6F-38C7-B8C5-EB90E7070FEB/GUID-2F84B113-A463-352E-900C-E0A7B09BA4D3"><apiname>CalCategory::CategoryListL()</apiname></xref>. </p> <p><b>Repeat

rules</b> </p> <p>For an event which occurs repetitively, such as a weekly

progress meeting, you need to set a repeat rule. Repeat frequency (<xref href="GUID-010934C4-DC1F-37F3-8121-E497B0BC9CDE.dita"><apiname>TCalRRule</apiname></xref>)can

be set to daily, weekly, monthly by day and yearly by date to a calendar entry.

When a repeat rule is assigned to an entry, that entry's start time should

be an instance of the repeat rule. It can be either same as the start time

value or a later instance. Repeat rule is set by passing an instance of <xref href="GUID-010934C4-DC1F-37F3-8121-E497B0BC9CDE.dita"><apiname>TCalRRule</apiname></xref> to <xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita#GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801/GUID-C6EB1EC3-8CA0-3E9E-9EBB-8F0973F63A53"><apiname>CCalEntry::SetRuleL()</apiname></xref>. </p> <p><b>Instance views </b> </p> <p>An instance view is used to display instances

of a repeating entry. It gets a list of all entry views or instances by calling <xref href="GUID-7B49A9D5-ACA0-3D96-A49C-0F19712E24E2.dita"><apiname>InstanceList()</apiname></xref>. <xref href="GUID-58BA8611-A364-3E30-B5F0-E5787E19C48C.dita#GUID-58BA8611-A364-3E30-B5F0-E5787E19C48C/GUID-961D3CE4-3C92-3A15-BDD1-19FF3D970F83"><apiname>CCalInstanceView::FindInstanceL()</apiname></xref> is used to fetch all instances within the specified date and time range. </p> <p><b>Deleting

an entry</b> </p> <p>A calendar entry is deleted by specifying a pointer to

the enrty array index. In this example, the originating entry is deleted using <xref href="GUID-D2835D4E-F0A8-3EDE-BC13-B45E52170556.dita#GUID-D2835D4E-F0A8-3EDE-BC13-B45E52170556/GUID-4B78A543-8F12-3E68-8C09-D178FBB8F83E"><apiname>CCalEntryView::DeleteL()</apiname></xref>. </p> </section>

<section id="GUID-FEB7E2BB-CFB7-48E7-A9D7-D5F93DE3DA2D"><title>Download</title> <p>Click on the following link to download

the example: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-e304a659-d708-4a39-86c9-2334ca994ec5.zip" scope="external">CalExample.zip</xref></p><p>Click: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-e304a659-d708-4a39-86c9-2334ca994ec5.html" scope="peer">browse</xref> to view the example code. </p> </section>

<section id="GUID-81696D29-7835-42B3-B527-C2999B07BD58"><title>Usage</title> <p>The <xref href="GUID-3100800B-B2F7-50EF-BD4C-3C345ECCB2A5.dita">Symbian

OS build process</xref> describes how to build an application. </p> <p>This

is a console application, so does not have a GUI. It builds an executable

called <filepath>calexample.exe</filepath> in the standard location (<filepath>\epoc32\release\winscw\</filepath> <i>&lt;build_variant&gt;</i> for

CodeWarrior). After launching the executable, depending on the emulator you

are using, you may need to task away from the app launcher/shell screen to

view the console. </p> </section>

<section id="GUID-CCC737B7-EAC5-42AA-9A7E-6FC3F94C7615"><title>Class Summary</title> <ul>

<li id="GUID-881CD688-462B-53EB-8A45-78109EA2F264"><p> <xref href="GUID-609318A7-43F1-3FC1-952B-146B1EA8115D.dita"><apiname>CCalSession</apiname></xref> </p> </li>

<li id="GUID-B7C99265-CC7B-5460-859E-47AA1DF6B288"><p> <xref href="GUID-D2835D4E-F0A8-3EDE-BC13-B45E52170556.dita"><apiname>CCalEntryView</apiname></xref> </p> </li>

<li id="GUID-CB229CEA-618A-56B2-987B-605B41684A16"><p> <xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita"><apiname>CCalEntry</apiname></xref> </p> </li>

<li id="GUID-2559C1E7-EF3F-5F26-8505-BD2DA71AD124"><p> <xref href="GUID-1A1D94E6-AD7C-3202-B1BD-A1583FA34A5F.dita"><apiname>MCalProgressCallBack</apiname></xref> </p> </li>

<li id="GUID-46143FD1-FB79-5161-A317-B2B2030F72E1"><p><xref href="GUID-5C206B40-0ED3-33F3-A52A-A25311C996C1.dita"><apiname>TCalTime</apiname></xref> </p> </li>

</ul> </section>

<section id="GUID-AA957A78-BC29-45C0-98DF-30FC05DCF5C8"><title>See also</title> <p><xref href="GUID-3A6BEF56-ADBF-543E-B70A-52195DE3E92A.dita">Calendar

overview</xref>  </p> </section>