Calendar overview

The Calendar API provides access to calendar stores, with functionality to fetch, update, save, and delete calendar entries.

This API replaces the Agenda Model used in previous versions of Symbian OS. The functionality is as per the standard RFC 2445, which defines a common format for openly exchanging calendar and scheduling information across the internet.

The component uses the Alarm server and TZ (time zone converter) components.

This document describes the following key areas:

• Connecting to the calendar server

• Calendar entry

• Calendar views

• Calendar user

• Setting the repeat rule

• Setting the alarm

• Categorising an entry

• Importing and exporting an entry

• Callback interfaces

You must create a session with the calendar server using CCalSession::NewL() before accessing a calendar entry. This provides a handle to the calendar file and connects you to the calendar server.

// Create a session with the calendar server
CCalSession* session= CCalSession NewL();

You use the same session handle to create other calendar API objects, such as entry view, category, data exchange, iterator and observers.

Using the calendar server object you can create a file, open a file, list the files in the server and delete a file using CCalSession::CreateCalFileL(), CCalSession::OpenL(), CCalSession::ListCalFilesL() and CCalSession::DeleteCalFilesL() respectively.

To create a calendar file:

_LIT(KFileName,"D:\\MyCalFile"); 
session->CreateCalFileL(KFileName); //pass the descriptor which hold the filename D:\MyCalFile

If D:\MyCalFile file already exists, then the function leaves.

To open a calendar file:

_LIT(KFileName,"D:\\MyCalFile");
session->OpenL(KFileName); //pass the filename D:\MyCalFile to be opened

The session object must be destroyed only after all the objects which were created by referencing it have been destroyed.

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

There are also properties provided to enable basic 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.

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 SetTypeL().

Futher arguments are relevant to group scheduling:

• global UID of the entry

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

• optionally, the entry sequence number

• optionally, 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.

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

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

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 a entry. For example, for a project meeting scheduled for 3^rd, 10^th, 17^th, 24^th and 31^st , if you have to cancel meetings scheduled on 17^th and 24^th, call SetExceptionDatesL() and pass these dates.

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

An event can have a status such as tentative, confirmed or cancelled. For a To-do type event, the status can indicate if an item needs action, is completed, is in process 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. This 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 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 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.

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().

The API provides the following views for accessing the calendar:

• Entry view: This view allows accessing and manipulating calendar entries. For example, you can add, delete update and search for a calendar entry.

• Instance view: This view allows you to access and delete individual instance(s) generated from an entry.

To access a calendar entry, you need to create an entry view using CalEntryView::NewL(). Using the entry view object, you can fetch, update, save and delete a calendar entry. The functions that support these are CalEntryView::FetchL(), CalEntryView::UpdateL(), CalEntryView::StoreL(), and CalEntryView::DeleteL() respectively.

To create a view you need to pass the CCalSession handle to the NewL. The code below shows how to fetch, update, save and delete an entry.

//Create an entry view 
entryView = CCalEntryView::NewL(*iCalSession,*this); 
//Fetch entries from the calendar file  
RPointerArray<CCalEntry> array;// pointer array of entries 
entryView->FetchL(KGUID(), array); 
// Update entries in the array 
Tint numberOfEntries(0);//number of entries updated successfully 
entryView->UpdateL(array, numberOfEntries); 
//Save entries in the calendar file 
entryView->StoreL(array, numberOfEntries); 
//Delete entries in the array 
entryView->DeleteL(array);

A calendar event can have one or more occurrences. An event occurs more than once if a repeat rule has been set. Each occurrence is known as an instance (also known as a schedule).

CCalInstanceView::FindInstanceL() allows you to search for instances of an entry within a given date range.

void FindInstanceL(RPointerArray< CCalInstance >
                &aMatchedInstanceList, CalCommon::TCalViewFilter aCalViewFilter, const
                CalCommon::TCalTimeRange &aTimeRange, const TCalSearchParams
                &aSearchParams) const;

FindInstanceL() returns the instances in the form of an RPointerArray object. The other parameters specify filtering criteria: the entry type, the time range within which the entries need to be found, and search text along with the search options.

You can also get the next and previous instances relative to a specified time using CCalInstanceView::NextInstanceL() and CCalInstanceView::PreviousInstanceL() respectively.

Call CCalInstanceView::DeleteL() to delete any instance returned by FindInstanceL. If all the instances are deleted, the entry gets deleted automatically. DeleteL() need to be used in conjunction with FindInstanceL.

CCalUser represents a calendar user, such as a meeting participant. The class provides attributes and methods that are common to all the calendar users, including the user’s email address, sent-by and common name fields.

You can construct a new calendar user with a specified email address, and optionally a sender, using the factory function NewL.

An Attendee is a specialised calendar user used for attendees of an event. It is used only in group scheduled entries, and not for a single calendar user. The CCalAttendee class, derived from CCalUser, provides additional methods to store and retrieve an Attendee's ROLE, PART-STAT, and RSVP fields.

//Create an attendee
_LIT(KAttendee1Address, "[email protected]");
CCalAttendee* attendee1 = CCalAttendee::NewL(KAttendee1Address);
_LIT(KAttendee1CommonName, "Tom");
attendee1->SetCommonNameL(KAttendee1CommonName);//set common name to Tom
attendee1->SetRoleL(CCalAttendee::EReqParticipant);// set the role of the attendee, other roles Chair and Optional participant
attendee1->SetStatusL(CCalAttendee::EAccepted);// set the status value

 // setup the entry
entry->CCalEntry::NewL(CCalEntry::EAppt, guid, CCalEntry::EMethodNone, 0);
entry->AddAttendeeL(attendee1);//add the attendee to the entry

You can get a list of attendees using CCalEntry::AttendeesL(), and delete a specified attendee using CCalEntry::DeleteAttendeeL() .

An entry can optionally have one phone owner and one organizer, which are both of class CCalUser. The organizer may or may not be an attendee of that entry, but the phone owner must be an attendee. An organizer is a required property for a group scheduled entry.

//Setup the Organizer 
_LIT(KOrganizerAddress1, "[email protected]"); 
CCalUser* organiser1 = CCalUser::NewL(KOrganizerAddress1, KOrganizerSentByA); 
entry->SetOrganizerL(organiser1); //set the organizer for the event
_LIT(KOrganiserCommonName, "Harry"); 
organiser1->SetCommonNameL(KOrganizerCommonName); //set the    common name to Harry 

//Setup the Phone owner for the calendar entry 
_LIT(KPhoneOwnerAddress1, "[email protected]"); 
CCalUser* phOwner1 = CCalUser::NewL(KPhoneOwnerAddress1, KOrganizerSentByB); 
entry->SetPhoneOwnerL(phOwner1); 
_LIT(KPhOwnerCommonName, "Dick"); 
organiser1->SetCommonNameL(KPhOwnerCommonName);//set the common name to Dick

For an event to occur repetitively, such as a weekly progress meeting, you need to set a repeat rule. You can set the repeat frequency as daily, weekly, monthly by day (for example every Monday of first week), monthly by date (for example 25^th of every month), yearly by day (for example every Monday of first week of October) and yearly by date to a calendar entry.

A repeat rule can be set by passing a TCalRRule to CCalEntry::SetRuleL(). TCalRule allows you to set any of the following iCal properties:

• FREQ (rule type)

• DTSTART (start date)

• UNTIL (end date)

• COUNT (number of instances)

• INTERVAL (interval between instances)

• BYDAY

• BYMONTHDAY

• BYYEARDAY

• WKST (start day of week)

You can set the repeat rule as following:

// set the repeat definition type
TCalRRule rrule = TCalRRule(EWeekly);
// set interval between each instance 
rrule.SetInterval(1);
// set the start Time 
TCalTime startTime; 
startTime.SetTimeLocalL(TDateTime(2005, EJuly, 26, 0, 0, 0, 0)); 
rpt.SetDtStart(startTime); 
// set the end Time 
TCalTime endTime; 
endTime.SetTimeLocalL(TDateTime(2007, EAugust, 28, 14, 0, 0, 0)); 
rrule.SetUntil(endTime); 
// set the repeat rule in the calendar entry 
entry->SetRRuleL(rrule); 
// You can set the time zone rules for the entry’s repeat rules
entry->SetTzRulesL(*tzrule); // tzrule object is of CTzRules type

You can assign an alarm to a calendar entry. CCalAlarm specifies the alarm type and the time prior to the scheduled event at which to activate the alarm.

The following shows how to create and initialise a CCalAlarm object, and use it to set an alarm on an entry.

// Set the alarm to a calendar entry using following steps: 
CCalAlarm* alarm = CCalAlarm::NewL();// pointer to alarm 
alarm->SetTimeOffset(5); //alarm is set to occur 5 minutes prior to the event 
// set the name of alarm to ‘Buzzing Alarm’ 
_LIT(KAlarmSoundName, "Buzzing Alarm"); 
entry->SetAlarmSoundNameL(KAlarmSoundName); 
// set the alarm
entry->SetAlarmL(alarm);

If no alarm sound is set, the default alarm sound is used.

To clear an already set alarm from an entry, pass NULL to SetAlarmL().

You can categorise a calendar entry using twelve built-in types such as appointment, business, education, holiday, meeting, travel etc. CCalCategory encapsulates a category. CCalEntry::AddCategoryL() sets a category for an entry.

You can also specify new categories. CCalCategoryManager allows you to add and delete a category, list the categories in the file, and filter the calendar entries for a given category.

Calendar entries can be imported and exported in the vCalendar format using CCalDataExchange.

To import a calendar entry, call CCalDataExchange::ImportL(), specifying the data format (currently vCalendar) and the read stream that contains the data.

To export a calendar entry, call CCalDataExchange::ExportL(), specifying the data format (currently vCalendar), the write stream, and an array of entries to export.

The API uses two types of callback interfaces: change notifications, and progress/completion notifications.

The MCalChangeCallBack interface is implemented to monitor changes to calendar entries, such as the addition, deletion, and update of entries.

Call CCalSession::StartChangeNotification() to request change notifications. The following requests notifications of all changes for entries between 1 Jan 2005 and 1 Jan 2006.

// set up notification of all changes on all entries in 2005 
TTime startTime(TDateTime(2005, EJanuary, 0, 0, 0, 0, 0)); // start time
TTime endTime(startTime + TTimeIntervalYears(1)); // end time 
// assume this object implements MCalChangeCallBack
session->StartChangeNotification(this, EChangeEntryAll, ETrue, startTime, endTime);

The observer's implementation of MCalChangeCallBack::CalChangeNotification() is called whenever a change to the calendar entries occurs that matches the specified criteria.

You can disable a change notification by using CCalSession::StopChangeNotification().

The MCalProgressCallBack interface is used for monitoring the progress and completion of asynchronous tasks, such as the addition, deletion or updating of a calendar entry carried out on the entry view or instance view. Progress() reports the percentage completion of the current task. Completed() is called when the current task is completed.