API 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, etc.
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.
Use Cases
The most common use cases of the Calendar Interim Utils2 API are the following:
-
Allocating a new global UID for Calendar entry
-
Checking whether the Meeting Request Viewer functionality is enabled and
available to use
-
Populating empty fields of a child entry with data from the parent entry
-
Storing a Calendar entry
-
Checking if a given entry has properties consistent with a meeting request
API Class Structure
The classes of the Calendar Interim Utils2 API are shown in
Figure
1
.
Class
CCalenInterimUtils2
is derived from
CBase
,
and it contains some utility methods.
Related APIs
-
CBase
-
CCalenInterimUtils2
Using the Calendar Interim Utils2 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.
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 );
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;
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 );
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
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 );
Related APIs
-
CCalEntryView::StoreL
-
CCalEntryView::UpdateL
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 );
Error handling
All methods leave in case of an error situation. Normal Symbian error handling
practises should be used, e.g. using cleanup stack and trap harness.
Extensions to the API
The Calendar Interim Utils2 API is a utility class and does not explicitly
support any kinds of extensions to it.
Related APIs
-
CCalenInterimUtils2
-
GlobalUidL()
-
MRViewersEnabledL()
