<?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 xml:lang="en" id="GUID-9B428B4E-83B7-5EE3-8D63-E2B0602D1D91"><title>Calendar Entries</title><prolog><metadata><keywords/></metadata></prolog><conbody><section><title>Overview</title> <p>A calendar entry has a number of properties. Firstly, it has a type, which is one of the following: </p> <ul><li id="GUID-65BB35D3-C4C3-523E-8CFB-B407B51008AD"><p>an appointment </p> </li> <li id="GUID-9278D429-D6C9-59E3-A133-6A1B2C93EAB4"><p>a to-do item </p> </li> <li id="GUID-AAB0A11C-948A-55B1-A19F-05F4E7CAB169"><p>a reminder </p> </li> <li id="GUID-F26F1AD3-CC4E-5B89-AF53-9D99F4B4A0A0"><p>an event </p> </li> <li id="GUID-A259A672-333D-51A9-BC10-E9BBBC182F0F"><p>an anniversary </p> </li> </ul> <p>Other properties that can be set on calendar entries include attendees, location, description, status, and alarm setting. These are discussed in the appropriate sections that follow. </p> <p>There are also properties provided to enable simple group scheduling services. Entries can hold properties defined in RFC2445 such as the unique identifier (UID), sequence number (SEQUENCE), Recurrence ID (RECURRENCE-ID), repeating events defined by the RDATE property, local time zone rules and the METHOD property. Group scheduling entries that act on the same event can be a stored and retrieved in an associative manner by means of a common UID. </p> </section> <section><title>Creating a calendar entry object</title> <p>Once you have a calendar session object, you can create a calendar entry object using <xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita"><apiname>CCalEntry::NewL()</apiname></xref>. </p> <codeblock id="GUID-E7AF1B7D-0A69-5AC9-ACB3-04BF130F0A34" xml:space="preserve">CCalEntry::NewL(TType aType, HBufC8 *aUid, TMethod aMethod, TUint aSeqNum, const TCalTime &amp;aRecurrenceId, CalCommon::TRecurrenceRange aRange);</codeblock> <p> <i>aType</i> specifies the type of calendar entry. This can also be set later using <xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita"><apiname>TCalRRule::SetType()</apiname></xref>. </p> <p>Further arguments are relevant to group scheduling: </p> <ul><li id="GUID-C0288BAF-F3E9-5D14-877C-A133A4103FA8"><p>global UID of the entry </p> </li> <li id="GUID-91EDC103-28F4-578A-8CEB-FC506083A404"><p>optionally, the method property such as add, publish, request and reply. This can also be set later, using <xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita"><apiname>CCalEntry::SetMethodL()</apiname></xref>  </p> </li> <li id="GUID-73EB1D22-4318-56E3-BBFC-1C91E940C071"><p>the entry sequence number </p> </li> <li id="GUID-505AC8D9-BDA5-5030-AC71-A3CB0B7E78DD"><p>the recurrence ID and recurrence range. </p> </li> </ul> <p>When a calendar entry object has been obtained you can set further properties, as described below. For brevity, only the 'setter' function for a property is usually described, without the corresponding 'get' property function. </p> </section> <section><title> Setting the calendar entry details</title> <p> <xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita"><apiname>CCalEntry::SetSummaryL()</apiname></xref> sets the summary text for calendar entry. </p> <codeblock id="GUID-06331311-19E3-583C-84E4-F4D6414FF6D9" xml:space="preserve">_LIT(KSummaryText1,"Project meeting schedule"); 

entry->SetSummaryL(KSummaryText1);

//This is used to set one line information about the event, for example, the meeting topic. 

CCalEntry::SetLocationL() sets the location field (venue) for the calendar entry.  

_LIT(KLocation1,"Lake View Discussion Room");

entry->SetLocationL(KDLocation1);

CCalEntry::SetDescriptionL() sets the description text to the calendar entry. 

_LIT(KDescription1,"Project kick off meeting is scheduled for 1st week of August");  

entry-&gt;SetDescriptionL(KDescription1);</codeblock> <p>This is used to give detailed information of the calendar entry, such as the meeting agenda. </p> </section> <section><title>Setting the calendar entry dates</title> <p>You can set the start and end date for a calendar entry. For example: </p> <codeblock id="GUID-C472913F-0103-5B92-B7A1-F60E2AFE62CD" xml:space="preserve">//Set the start and end time for a calendar entry 

TCalTime startTime; 

TCalTime endTime; 

entry->SetStartAndEndDateL(startTime,endTime);

//You can find the date/time when a calendar entry was last modified by calling CCalEntry::LastModifiedDateL(). You can also set this using CCalEntry::SetLastModifiedDateL(). 

TCalTime lastModified; 

entry->SetLastModifiedDateL(lastModified);//set last modified time for entry

</codeblock> </section> <section><title>Setting the recurring dates</title> <p>You can set dates for repeating entries using <xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita"><apiname>CCalEntry::SetRDatesL()</apiname></xref>: </p> <codeblock id="GUID-5F671AF9-E2F7-5847-A726-302E5B0666B1" xml:space="preserve">SetRDatesL(const RArray&lt; TCalTime &gt; &amp;aRDateList); //Set the repeat dates to the calendar entry</codeblock> <p> <xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita"><apiname>CCalEntry::SetExceptionDatesL()</apiname></xref> allows you to provide the dates that need to be excluded from the recurrence dates for an entry. For example, for a project meeting scheduled for 3rd, 10th, 17th, 24th and 31st, if you have to cancel meetings scheduled on 17th and 24th, call <xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita"><apiname>CCalEntry::SetExceptionDatesL()</apiname></xref> and pass these dates. </p> <codeblock id="GUID-9E42F48C-18A6-5DE8-B770-09A5A0250D80" xml:space="preserve">SetExceptionDatesL(const RArray&lt; TCalTime &gt; &amp;aExDateList); //Set the exception dates to the calendar entry.</codeblock> </section> <section><title>Setting status for a calendar entry</title> <p>An event can have a status such as tentative, confirmed or cancelled. For a to-do type event, the status can indicate whether an item needs action, is completed, is in progress or has been cancelled. </p> <codeblock id="GUID-F167F25C-951E-5840-B1B6-57D67EA5BDA5" xml:space="preserve">entry-&gt;SetStatusL(EConfirmed); // Set meeting status to ‘Confirmed’ </codeblock> <p>To protect the data in a calendar entry, you can impose certain restrictions on accessing the data. These can be: no restrictions, no access or restricted access. Call <xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita"><apiname>CCalEntry::SetReplicationStatusL()</apiname></xref> to set the above restrictions to a calendar entry. To get the restrictions set for a specific entry call <xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita"><apiname>CCalEntry::ReplicationStatusL()</apiname></xref>. </p> <codeblock id="GUID-B014FBA0-98E4-5672-8B41-E30A0314F44E" xml:space="preserve">entry-&gt;SetReplicationStatusL(ERestricted); // entry data has restricted access</codeblock> <p>When more than one event is scheduled for a given time period, it can be useful to give a specific event a priority value. Priority values ranges from 0 to 255. 0 is the default value. 1 is the for highest priority. </p> <codeblock id="GUID-D1B1D6B4-8BAE-5857-99EE-B204A6F104D9" xml:space="preserve">entry-&gt;SetPriorityL(1); // the meeting is of high priority </codeblock> </section> <section><title>To do list entries</title> <p>To strike out an action item in a to-do list call <xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita"><apiname>CCalEntry::SetCompletedL()</apiname></xref>. When this function is called for an entry other than a to-do list, it leaves with <xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita"><apiname>KErrNotSupported</apiname></xref>. </p> </section> <section><title>Comparing and copying</title> <p>You can compare a calendar entry with another entry using <xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita"><apiname>CCalEntry::CompareL()</apiname></xref>. You can also copy the contents of an entry to the current entry using <xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita"><apiname>CCalEntry::CopyFromL()</apiname></xref>. </p> </section> </conbody></concept>