--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/PDK/Source/GUID-F8E4D4AC-878A-52C5-A04D-9E116A0087D5.dita	Fri Jan 22 18:26:19 2010 +0000
@@ -0,0 +1,93 @@
+<?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>
+</conbody></concept>
\ No newline at end of file