Calendar Interim Utils2 API Specification

Contents

1 Overview

The purpose of Calendar Interim Utils2 API is to provide utility methods that extend Calendar Interim API. Calendar Interim API is introduced in Symbian OS v9.1 (S60 3rd Edition) and replaces Agenda Model API in previous version.


API categorypublic
API typec++
API librariesCalenInterimUtils2.lib
Location/sf/app/organizer/organizer_pub/calendar_interim_utils2_api
Buildfiles/sf/app/organizer/organizer_pub/calendar_interim_utils2_api/group/bld.inf


1.1 Description

Calendar Interim Utils2 API can be categorized as a library API and offers common functions used in Calendar entry manipulation, such as allocating a new global UID or checking to see if the given entry has properties consistent with a meeting request, and so on.

The type of this API is a normal method call interface. This API provides both static and non-static methods buffering some of the results, so that they do not need to be re-fetched.

This API is meant for applications that need to manipulate Calendar entries.

1.2 Use Cases

The following are the most common use cases of the Calendar Interim Utils2 API:

1.3 Class Structure

Summary of API classes and header files
ClassesFiles
CCalenInterimUtils2 /epoc32/include/app/CalenInterimUtils2.h

Class CCalenInterimUtils2 is derived from CBase , and it contains some utility methods. The classes of the Calendar Interim Utils2 API are shown in the following class diagram:

Class diagram of the Calendar Interim Utils2 API
Class diagram of the Calendar Interim Utils2 API

2 Using The API

If you intend to use the non-static methods of this API, it is recommended for performance reasons, to allocate a single instance of the CCalenInterimUtils2 object for the lifetime of a process. The GlobalUidL() and MRViewersEnabledL() methods buffer data that is non-trivial to retrieve, so it is worth keeping an instance of the CCalenInterimUtils2 object between calls. If you intend to use only the static methods, then it is not really worth keeping an instance of the CCalenInterimUtils2 object in memory.

2.1 Allocating a new global UID for Calendar entry

The following code snippet demonstrates how to allocate a new global UID and return the ownership to the caller.

#include <CalEntry.h>
#include <CalenInterimUtils2.h>
// Instantiate utils
//
CCalenInterimUtils2* utils = CCalenInterimUtils2::NewL();
CleanupStack::PushL( utils );
// Generate a new UID
//
HBufC8* uid = utils->GlobalUidL();
CleanupStack::PushL( uid );
// Create a new Calendar entry using the UID
//
CCalEntry* entry = CCalEntry::NewL( CCalEntry::EAppt, uid, CCalEntry::EMethodNone, 0);
CleanupStack::Pop( uid );
CleanupStack::PushL( entry );
// Set other property
...
// Clean up temporary variables
//
CleanupStack::Pop( entry );
CleanupStack::PopAndDestroy( utils );

2.2 Checking whether the Meeting Request Viewer functionality is enabled and available for use

The following code snippet demonstrates how to check to see if the Meeting Request Viewer functionality is enabled and available for use.

#include <CalenInterimUtils2.h>
// Instantiate utils
//
CCalenInterimUtils2* utils = CCalenInterimUtils2::NewL();
// Check the Meeting Request Viewer status
//
TBool enabled = utils->MRViewersEnabledL();
// Clean up temporary variables
//
delete utils;
utils = NULL;

2.3 Populating empty fields of a child entry with data from the parent entry

The following code snippet demonstrates how to populate empty fields of a child entry with data from the parent entry.

#include <CalEntry.h>
#include <CalenInterimUtils2.h>
// Instantiate utils
//
CCalenInterimUtils2* utils = CCalenInterimUtils2::NewL();
CleanupStack::PushL( utils );
// Get the parent Calendar entry
//
CCalEntry* parent = ...;
CleanupStack::PushL(parent);
// Create child Calendar entry
//
CCalEntry* child = CCalEntry::NewL( parent->EntryTypeL(),
                                    parent->UidL().AllocL(),
                                    parent->MethodL(),
                                    parent->SequenceNumberL(),
                                    parent->StartTimeL(),
                                    CalCommon::EThisOnly );
CleanupStack::PushL( child );
// Populate empty fields of child entity
//
utils->PopulateChildFromParentL( *child, *parent);
// StartAndEndTime should be set separately
//
child->SetStartAndEndTimeL( parent->StartTimeL(), parent->EndTimeL() );
// Clean up temporary variables
//
CleanupStack::PopAndDestroy( child );
CleanupStack::PopAndDestroy( parent );
CleanupStack::PopAndDestroy( utils );

2.4 Storing a Calendar entry

The following code snippet demonstrates how to store the Calendar entry to the Calendar database. The use of this function should be favoured over the direct use of the CCalEntryView::StoreL() function. It wraps around CCalEntryView::StoreL() or CCalEntryView::UpdateL() and makes the appropriate call to either of those methods, depending on several factors, such as whether the entry is a child or parent, and whether it has exceptions or not. This function also handles preserving child entries which would be lost by a direct call to CCalEntryView::StoreL() .

#include <CalEntry.h>
#include <CalEntryView.h>
#include <CalSession.h>
#include <CalenInterimUtils2.h>
// Instantiate CCalSession
//
CCalSession* calSession = ...;
CleanupStack::PushL( calSession );
// Instantiate CCalEntryView
//
CCalEntryView* entryView = CCalEntryView::NewL( *calSession, *this );
CleanupStack::PushL( entryView );
// Instantiate utils
//
CCalenInterimUtils2* utils = CCalenInterimUtils2::NewL();
CleanupStack::PushL( utils );
// Create Calendar entry
//
CCalEntry* entry = ...;
CleanupStack::PushL( entry );
// Store the Calendar entry to repository
//
iUtils->StoreL( *entryView, *entry );
// Clean up temporary variables
//
CleanupStack::PopAndDestroy( entry );
CleanupStack::PopAndDestroy( utils );
CleanupStack::PopAndDestroy( entryView );
CleanupStack::PopAndDestroy( calSession );

2.5 Checking whether the given entry has properties consistent with a meeting request

The following code snippet demonstrates how to check if the given entry has properties consistent with a meeting request.

#include <CalenInterimUtils2.h>
// Instantiate utils
//
CCalenInterimUtils2* utils = CCalenInterimUtils2::NewL();
CleanupStack::PushL( utils );
// Create Calendar entry
//
CCalEntry* entry = ...;
CleanupStack::PushL( entry );
// Check if the entry is a meeting request or not
//
TBool isMeetingRequest = utils->IsMeetingRequestL( *entry );
// Clean up temporary variables
//
CleanupStack::PopAndDestroy( entry );
CleanupStack::PopAndDestroy( utils );

2.6 Error handling

All methods leave in case of an error situation. Normal Symbian error handling practises should be used, for example, using cleanup stack and trap harness.

2.7 Extensions to the API

The Calendar Interim Utils2 API is a utility class and does not explicitly support any kinds of extensions to it.

3 References

Symbian Calendar Interim API [mk:@MSITStore:Symbian_DevLib.chm::/doc_source/reference/reference-cpp/CALINTERIMAPI/index.html CALINTERIMAPI]