Calendar Entries

Overview

A calendar entry has a number of properties. Firstly, it has a type, which is one of the following:

• an appointment

• a to-do item

• a reminder

• an event

• an anniversary

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.

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.

Creating a calendar entry object

Once you have a calendar session object, you can create a calendar entry object using CCalEntry::NewL().

CCalEntry::NewL(TType aType, HBufC8 *aUid, TMethod aMethod, TUint aSeqNum, const TCalTime &aRecurrenceId, CalCommon::TRecurrenceRange aRange);

aType specifies the type of calendar entry. This can also be set later using TCalRRule::SetType().

Further arguments are relevant to group scheduling:

• global UID of the entry

• optionally, the method property such as add, publish, request and reply. This can also be set later, using CCalEntry::SetMethodL()

• the entry sequence number

• the recurrence ID and recurrence range.

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.

Setting the calendar entry details

CCalEntry::SetSummaryL() sets the summary text for calendar entry.

_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->SetDescriptionL(KDescription1);

This is used to give detailed information of the calendar entry, such as the meeting agenda.

Setting the calendar entry dates

You can set the start and end date for a calendar entry. For example:

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

Setting the recurring dates

You can set dates for repeating entries using CCalEntry::SetRDatesL():

SetRDatesL(const RArray< TCalTime > &aRDateList); //Set the repeat dates to the calendar entry

CCalEntry::SetExceptionDatesL() 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 CCalEntry::SetExceptionDatesL() and pass these dates.

SetExceptionDatesL(const RArray< TCalTime > &aExDateList); //Set the exception dates to the calendar entry.

Setting status for a calendar entry

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.

entry->SetStatusL(EConfirmed); // Set meeting status to ‘Confirmed’ 

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 CCalEntry::SetReplicationStatusL() to set the above restrictions to a calendar entry. To get the restrictions set for a specific entry call CCalEntry::ReplicationStatusL().

entry->SetReplicationStatusL(ERestricted); // entry data has restricted access

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.

entry->SetPriorityL(1); // the meeting is of high priority 

To do list entries

To strike out an action item in a to-do list call CCalEntry::SetCompletedL(). When this function is called for an entry other than a to-do list, it leaves with KErrNotSupported.

Comparing and copying

You can compare a calendar entry with another entry using CCalEntry::CompareL(). You can also copy the contents of an entry to the current entry using CCalEntry::CopyFromL().