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

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

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

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

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

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

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

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

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

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

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

    23 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>.

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

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

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

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

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

    29 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

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

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

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

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

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

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

    36 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

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

    38 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

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

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

    41 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>.

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

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

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

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

    46 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

    47 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

    48 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

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

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

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

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

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

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

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

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

    57 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

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

    59 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

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

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

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

    63 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

    64 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

    65 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

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

    67 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

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

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

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

    71 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

    72 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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    90 </ul> </section>

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

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

    93 </conbody></concept>