CalInterimAPI: -Using the Calendar API

Description

This example demonstrates how to use -the Calendar API. The main class in the example, CCalExample, -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.

The -calendar file

CCalExample::ConstructL() instantiates -a CCalSession with the calendar server by calling CCalSession::NewL(). -All calendar file operations, for instance creation and opening, are done -through the CCalSession class.

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.

Next, CCalExample::ConstructL() creates -and opens a named calendar file, to store the calendar entries (using CCalSession::CreateCalFileL() and CCalSession::OpenL()). File creation leaves with KErrAlreadyExists if a file -with that name already exists.

The calendar entry view

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 (CCalEntryView) is used to access and manipulate -calendar entries. In this example it is used to display the non-repeating -appointment.

View creation can take some time because of the processing -that must be done in the server to prepare entry indexes. So, CCalEntryView::NewL() takes -a progress callback object (MCalProgressCallBack). When -the callback function MCalProgressCallBack::Completed() is -called, the view is ready for use. CCalExample implements -the MCalProgressCallBack interface.

Calendar -entries

A calendar entry is created using CCalEntry::NewL(). -This specifies the type of entry, its global UID and some optional properties -used for group scheduling.

An entry's start and end times are represented -using class TCalTime. 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 TCalTime::SetTimeLocalL() is called before -setting the entry's start and end times using CCalEntry::SetStartAndEndTimeL().

CCalEntryView::StoreL() is used to store one or more new entries into the file. CCalEntryView::FetchL() is -used to retrieve entries, based on their UID and CCalEntryView::UpdateL() is -used to update one or more entries.

Originating and modifying an -entry

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.

Calendar user

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. CCalEntry::AttendeesL() is called to get -a list of attendees. Attendees can be added to or deleted from a calendar -entry using CCalEntry::AddAttendeeL and CCalEntry::DeleteAttendeeL() respectively.

Categorising -an entry

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.

Create -a new category using CCalCategory::NewL() and pass a buffer -as argument. CCalEntry::AddCategoryL() is called to set -a category for the calendar entry. To get a list of available categories call CalCategory::CategoryListL().

Repeat -rules

For an event which occurs repetitively, such as a weekly -progress meeting, you need to set a repeat rule. Repeat frequency (TCalRRule)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 TCalRRule to CCalEntry::SetRuleL().

Instance views

An instance view is used to display instances -of a repeating entry. It gets a list of all entry views or instances by calling InstanceList(). CCalInstanceView::FindInstanceL() is used to fetch all instances within the specified date and time range.

Deleting -an entry

A calendar entry is deleted by specifying a pointer to -the enrty array index. In this example, the originating entry is deleted using CCalEntryView::DeleteL().

Download

Click on the following link to download -the example: CalExample.zip

Click: browse to view the example code.

Usage

The Symbian -OS build process describes how to build an application.

This -is a console application, so does not have a GUI. It builds an executable -called calexample.exe in the standard location (\epoc32\release\winscw\ <build_variant> 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.

Class Summary

CCalSession
CCalEntryView
CCalEntry
MCalProgressCallBack
TCalTime

See also

Calendar -overview

+ + + + + +CalInterimAPI: +Using the Calendar API +

Description

This example demonstrates how to use +the Calendar API. The main class in the example, CCalExample, +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.

The +calendar file

CCalExample::ConstructL() instantiates +a CCalSession with the calendar server by calling CCalSession::NewL(). +All calendar file operations, for instance creation and opening, are done +through the CCalSession class.

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.

Next, CCalExample::ConstructL() creates +and opens a named calendar file, to store the calendar entries (using CCalSession::CreateCalFileL() and CCalSession::OpenL()). File creation leaves with KErrAlreadyExists if a file +with that name already exists.

The calendar entry view

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 (CCalEntryView) is used to access and manipulate +calendar entries. In this example it is used to display the non-repeating +appointment.

View creation can take some time because of the processing +that must be done in the server to prepare entry indexes. So, CCalEntryView::NewL() takes +a progress callback object (MCalProgressCallBack). When +the callback function MCalProgressCallBack::Completed() is +called, the view is ready for use. CCalExample implements +the MCalProgressCallBack interface.

Calendar +entries

A calendar entry is created using CCalEntry::NewL(). +This specifies the type of entry, its global UID and some optional properties +used for group scheduling.

An entry's start and end times are represented +using class TCalTime. 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 TCalTime::SetTimeLocalL() is called before +setting the entry's start and end times using CCalEntry::SetStartAndEndTimeL().

CCalEntryView::StoreL() is used to store one or more new entries into the file. CCalEntryView::FetchL() is +used to retrieve entries, based on their UID and CCalEntryView::UpdateL() is +used to update one or more entries.

Originating and modifying an +entry

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.

Calendar user

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. CCalEntry::AttendeesL() is called to get +a list of attendees. Attendees can be added to or deleted from a calendar +entry using CCalEntry::AddAttendeeL and CCalEntry::DeleteAttendeeL() respectively.

Categorising +an entry

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.

Create +a new category using CCalCategory::NewL() and pass a buffer +as argument. CCalEntry::AddCategoryL() is called to set +a category for the calendar entry. To get a list of available categories call CalCategory::CategoryListL().

Repeat +rules

For an event which occurs repetitively, such as a weekly +progress meeting, you need to set a repeat rule. Repeat frequency (TCalRRule)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 TCalRRule to CCalEntry::SetRuleL().

Instance views

An instance view is used to display instances +of a repeating entry. It gets a list of all entry views or instances by calling InstanceList(). CCalInstanceView::FindInstanceL() is used to fetch all instances within the specified date and time range.

Deleting +an entry

A calendar entry is deleted by specifying a pointer to +the enrty array index. In this example, the originating entry is deleted using CCalEntryView::DeleteL().

Download

Click on the following link to download +the example: CalExample.zip

Click: browse to view the example code.

Usage

The Symbian +OS build process describes how to build an application.

This +is a console application, so does not have a GUI. It builds an executable +called calexample.exe in the standard location (\epoc32\release\winscw\ <build_variant> 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.

Class Summary

CCalSession
CCalEntryView
CCalEntry
MCalProgressCallBack
TCalTime