Class CCalEntry

class CCalEntry : public CBase;

Description

Class representing a calendar entry. This can be an appointment, to-do item, reminder, event or anniversary.

CCalEntry contains information about a calendar entry, including a repeat definition, synchronisation information, and group scheduling data.

A repeating calendar entry has more than one occurrence. Instances are represented by the CCalInstance class.

Synchronisation information includes a record of the date/time the entry was last modified. This can be found by calling the LastModifiedDateL() function.

Derivation

• CBase - Base class for all classes to be instantiated on the heap

• CCalEntry - Class representing a calendar entry

Members

Defined in CCalEntry:
AddAttendeeL(), AddCategoryL(), AlarmL(), AttendeesL(), CategoryListL(), ClearRepeatingPropertiesL(), CompareL(), CompletedTimeL(), CopyFromL(), CopyFromL(), DTStampL(), DeleteAttendeeL(), DeleteCategoryL(), DescriptionL(), EAnniv, EAppt, ECancelled, EConfirmed, ECopyAll, EDontCopyId, EEvent, EMethodAdd, EMethodCancel, EMethodCounter, EMethodDeclineCounter, EMethodNone, EMethodPublish, EMethodRefresh, EMethodReply, EMethodRequest, ENullStatus, EOpen, EPrivate, EReminder, ERestricted, ETentative, ETodo, ETodoCompleted, ETodoInProcess, ETodoNeedsAction, EndTimeL(), EntryTypeL(), GetExceptionDatesL(), GetRDatesL(), GetRRuleL(), LastModifiedDateL(), LocalUidL(), LocationL(), MethodL(), NewL(), NewL(), OrganizerL(), PhoneOwnerL(), PriorityL(), RecurrenceIdL(), RecurrenceRangeL(), ReplicationStatusL(), SequenceNumberL(), SetAlarmL(), SetCompletedL(), SetDTStampL(), SetDescriptionL(), SetExceptionDatesL(), SetLastModifiedDateL(), SetLocalUidL(), SetLocationL(), SetMethodL(), SetOrganizerL(), SetPhoneOwnerL(), SetPriorityL(), SetRDatesL(), SetRRuleL(), SetReplicationStatusL(), SetSequenceNumberL(), SetStartAndEndTimeL(), SetStatusL(), SetSummaryL(), SetTzRulesL(), SetTzRulesL(), StartTimeL(), StatusL(), SummaryL(), TCopyType, TMethod, TReplicationStatus, TStatus, TType, TzRulesL(), UidL(), ~CCalEntry()

Inherited from CBase:
Delete(), Extension_(), operator new()

See also

• Class Summary

Capability:

Illegal

static IMPORT_C CCalEntry *NewL(TType aType, HBufC8 *aUid, TMethod aMethod, TUint aSeqNum);

Description

Allocates and constructs a new entry of the specified type, Global UID and sequence number.

The entry's data is all initialised to default values, e.g. the start and end dates are reset to null.

The entry takes ownership of the Uid descriptor.

Note that this function will not work unless a CCalSession has been created by calling CCalSession::NewL().

Parameters

TType aType One of: EAppt, ETodo, EEvent, EReminder, EAnniv to create an appointment, a todo, an event, a reminder or an anniversary entry. HBufC8 *aUid The Global UID of the entry. This field is mandatory. TMethod aMethod The Method value describing the entry. Default value is EGSMethodNone. TUint aSeqNum The sequence number of the entry. Default value is 0.

Return value

CCalEntry * Pointer to the new entry.

Capability:

Illegal

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

Description

Allocates and constructs a new entry of the specified type, Global UID, sequence number and recurrence ID.

The entry takes ownership of the Uid descriptor.

Parameters

TType aType One of: EAppt, ETodo, EEvent, EReminder, EAnniv to create an appointment, a todo, an event, a reminder or an anniversary entry. HBufC8 *aUid The Global UID of the entry. TMethod aMethod The Method value describing the entry. TUint aSeqNum The sequence number of the entry. const TCalTime &aRecurrenceId The recurrence ID of the entry. CalCommon::TRecurrenceRange aRange The recurrence ID range of the entry.

Return value

CCalEntry * Pointer to the new entry.

Leave codes

KErrArgument If the UID passed is invalid

Panic codes

CalInterimAPI 8 If the entry type passed is invalid

Capability:

Illegal

IMPORT_C ~CCalEntry();

Description

The destructor frees all resources owned by the entry, prior to its destruction.

Capability:

Illegal

IMPORT_C TCalTime StartTimeL() const;

Description

Gets the start date/time for an entry.

Return value

TCalTime The entry's start date/time.

Capability:

Illegal

IMPORT_C TCalTime EndTimeL() const;

Description

Gets the entry's end date/time.

Return value

TCalTime The entry's end date/time.

Capability:

Illegal

IMPORT_C void SetStartAndEndTimeL(const TCalTime &aStartTime, const TCalTime &aEndTime);

Description

Sets the start and end date/times for an entry.

For an appointment, event or anniversary, the start time must be earlier than or equal to the end time. For a reminder, the end time will be ignored. For a to-do entry, the end time is the 'due date'. The time portion of the start date will not be stored for todos, only the number of days until the due date. Only Undated Todo's can have both start and end date as NullTime.

This function adjusts the start time of the repeat rule to the first instance. For EAppt, EEvent, EReminder, EAnniv this function also aligns the start time of the entry with that of the repeat rule. For ETodo, the due date (i.e. the end time) is aligned to the repeat rule start date.

Parameters

const TCalTime &aStartTime The entry's new start date/time. const TCalTime &aEndTime The entry's new end date/time.

Leave codes

KErrArgument If the start and end times are invalid.

Capability:

Illegal

IMPORT_C void SetLastModifiedDateL();

Description

Sets the entry's last modified date to the current time.

IMPORT_C TCalTime LastModifiedDateL() const;

Description

Gets the entry's last changed date/time.

Return value

TCalTime The time at which the entry was last modified.

Capability:

Illegal

IMPORT_C void SetDTStampL(const TCalTime &aTime);

Description

Sets the entry's DTSTAMP to the time specified.

This method may be called by clients to record the date/time that the entry was prepared for sending to a recipient as a scheduling object, as specified in RFC 2445, the Internet Calendaring and Scheduling Core Object Specification iCalendar). This value will be Time::NullTTime by default unless the client sets it otherwise.

Parameters

const TCalTime &aTime The time that the DTSTAMP will be set to

IMPORT_C TCalTime DTStampL() const;

Description

Gets the entry's DTSTAMP.

Return value

TCalTime The DTSTAMP of the entry.

Capability:

Illegal

IMPORT_C TCalTime CompletedTimeL() const;

Description

Gets a to-do entry's completed date.

This is the date on which the required action was carried out. If the entry has not been crossed out, or if this is not a to-do entry, then this function returns a null value.

Return value

TCalTime The to-do entry's crossed out date.

Capability:

Illegal

IMPORT_C void SetCompletedL(TBool aCompleted, const TCalTime &aTime);

Description

Sets the crossed out date for a to-do entry. This is the date on which the required action was carried out.

If this function is called on an entry which is not a to-do, it will leave with KErrNotSupported.

Parameters

TBool aCompleted ETrue if the to-do entry is complete - the entry's status is set to ETodoCompleted; EFalse if the to-do entry is not complete - the entry's status is set to ETodoNeedsAction const TCalTime &aTime The to-do entry's crossed out date. The time mode should not be floating, it will leave with KErrArgument if it is.

Capability:

Illegal

IMPORT_C void SetRRuleL(const TCalRRule &aRule);

Description

Sets the entry's repeat definition.

The repeat definition includes daily, weekly, monthly and yearly repeat details, and start and end details.

The start time of the repeat rule and the start and end time of the entry will be adjusted to match the first instance of the repeat rule.

This does not take ownership of the parameter.

Parameters

const TCalRRule &aRule The new repeat definition.

Leave codes

KErrNotSupported If the repeat rule passed is not one that is currently supported KErrArgument if this is a todo entry and its end date has not been set or this is a non-todo entry and its start date has not been set

Capability:

Illegal

IMPORT_C TBool GetRRuleL(TCalRRule &aRule) const;

Description

Get the entry's repeat rule.

In the returned TCalRRule, both the Count and the Until values can be accessed. However, in the case of a repeat rule which repeats forever, the Count will always be returned as 0.

Parameters

TCalRRule &aRule On return contains the entry's repeat rule data, if present.

Return value

TBool ETrue if the entry has a repeat rule, EFalse if not.

Capability:

Illegal

IMPORT_C void SetRDatesL(const RArray< TCalTime > &aRDateList);

Description

Replaces this group scheduling entry's list of RDATEs.

Parameters

const RArray< TCalTime > &aRDateList List of RDATEs to replace current RDATEs.

Leave codes

KErrArgument If the time mode of the RDATEs don't match the time mode of the entry

Capability:

Illegal

IMPORT_C void GetRDatesL(RArray< TCalTime > &aRDateList) const;

Description

Gets a list of all RDATEs in this group scheduling entry.

Parameters

RArray< TCalTime > &aRDateList On return, an array of RDATEs for this entry.

Capability:

Illegal

IMPORT_C void SetExceptionDatesL(const RArray< TCalTime > &aExDateList);

Description

Adds the given exception dates to this group scheduling entry.

Parameters

const RArray< TCalTime > &aExDateList The exception dates to be added.

Leave codes

KErrArgument If the time mode of the exception dates don't match the time mode of the entry

Capability:

Illegal

IMPORT_C void GetExceptionDatesL(RArray< TCalTime > &aExDateList) const;

Description

Gets a list of all exception dates on this group scheduling entry.

Parameters

RArray< TCalTime > &aExDateList On return, an array of exception dates for this entry.

Capability:

Illegal

IMPORT_C void ClearRepeatingPropertiesL();

Description

Clears the repeat details including exceptions and unsets the entry's 'is repeating' property.

Capability:

Illegal

IMPORT_C void SetAlarmL(CCalAlarm *aAlarm);

Description

Set the alarm for the entry.

This doesn't take ownership of the parameter. This function will leave with KErrNotSupported if the alarm is not on same day.

Parameters

CCalAlarm *aAlarm Pointer to the alarm, or NULL if the alarm is to be cleared.

Capability:

Illegal

IMPORT_C CCalAlarm *AlarmL() const;

Description

Creates an alarm class containing data for this entry's alarm.

Return value

CCalAlarm * Pointer to a new alarm object, or NULL if this entry doesn't have one.

Capability:

Illegal

IMPORT_C TBool CompareL(const CCalEntry &aEntry) const;

Description

Compares another entry for equality with this one.

Parameters

const CCalEntry &aEntry Pointer to an entry.

Return value

TBool ETrue if aEntry is the same as this entry, EFalse if not.

Capability:

Illegal

IMPORT_C void CopyFromL(const CCalEntry &aOther);

Description

Copies the contents of another entry to this one. All entry fields will be overwritten, including the UID and the local UID. This is identical to calling CopyFromL(aOther, ECopyAll).

Parameters

const CCalEntry &aOther Reference to source entry.

Panic codes

CalInterimAPI 7 If the entry type is invalid

Capability:

Illegal

IMPORT_C void CopyFromL(const CCalEntry &aOther, TCopyType aCopyType);

Description

Copies the contents of another entry to this one. The entry fields that are copied can be specified using the TCopyType parameter.

Parameters

const CCalEntry &aOther Reference to source entry. TCopyType aCopyType Which entry details are to be copied. ECopyAll if original entry and new entry should be identical. This is identical to calling CopyFromL(aOther). EDontCopyId if UID and local UID should not be copied, this should be used when creating a modifying entry.

Panic codes

CalInterimAPI 7 If the entry type is invalid

Capability:

Illegal

IMPORT_C void SetSummaryL(const TDesC &aSummary);

Description

Sets the summary text for this entry.

Parameters

const TDesC &aSummary The summary text.

Leave codes

KErrNotFound If a handle to the entry's summary could not be obtained

Capability:

Illegal

IMPORT_C const TDesC &SummaryL() const;

Description

Gets the summary for the entry.

Return value

const TDesC & Descriptor pointer to the summary text.

Leave codes

KErrNotFound If a handle to the entry's summary could not be obtained

Capability:

Illegal

IMPORT_C void SetDescriptionL(const TDesC &aDescription);

Description

Sets the description text for this entry.

Parameters

const TDesC &aDescription The summary text.

IMPORT_C const TDesC &DescriptionL() const;

Description

Gets the description text for the entry.

Return value

const TDesC & Descriptor pointer to the description text.

Capability:

Illegal

IMPORT_C void SetLocationL(const TDesC &aLocation);

Description

Sets the contents of the entry's location field.

Parameters

const TDesC &aLocation Descriptor containing a location, e.g. for a meeting.

Capability:

Illegal

IMPORT_C const TDesC &LocationL() const;

Description

Gets the contents of the entry's location field.

Return value

const TDesC & The location field.

Capability:

Illegal

IMPORT_C void AddCategoryL(CCalCategory *aCategory);

Description

Appends a category to the entry's list of categories.

The entry takes ownership of the category specified.

Parameters

CCalCategory *aCategory The category to be added.

Capability:

Illegal

IMPORT_C void DeleteCategoryL(TInt aIndex);

Description

Deletes a category from the entry's list of categories.

Parameters

TInt aIndex The category to be deleted.

Capability:

Illegal

IMPORT_C const RPointerArray< CCalCategory > &CategoryListL();

Description

Gets a list of the entry's categories.

Return value

const RPointerArray< CCalCategory > & An array of categories.

Capability:

Illegal

IMPORT_C void AddAttendeeL(CCalAttendee *aAttendee);

Description

Adds an attendee for this entry.

Parameters

CCalAttendee *aAttendee The attendee to be added.

Capability:

Illegal

IMPORT_C void DeleteAttendeeL(TInt aIndex);

Description

Deletes an attendee from this entry.

Parameters

TInt aIndex The index of the attendee (found in FetchAttendeesL) to be removed.

Leave codes

KErrArgument If the Index passed in is out of bounds

Capability:

Illegal

IMPORT_C RPointerArray< CCalAttendee > &AttendeesL() const;

Description

Gets the attendees for this entry.

Return value

RPointerArray< CCalAttendee > & An array of attendees.

Capability:

Illegal

IMPORT_C void SetOrganizerL(CCalUser *aUser);

Description

Sets the organizer for this entry.

Parameters

CCalUser *aUser The organizer (Entry takes ownership).

Capability:

Illegal

IMPORT_C CCalUser *OrganizerL() const;

Description

Gets the organizer for this entry. This function creates a new CCalUser object containing the organizer data.

Return value

CCalUser * The organizer if present, NULL if not.

Capability:

Illegal

IMPORT_C void SetPhoneOwnerL(const CCalUser *aOwner);

Description

Sets the phone owner for this entry.

Parameters

const CCalUser *aOwner The phone owner (entry takes ownership).

Capability:

Illegal

IMPORT_C CCalUser *PhoneOwnerL() const;

Description

Gets the phone owner for this entry. This function creates a new CCalUser object containing the phone owner data.

Return value

CCalUser * The phone owner if present, NULL if not.

Capability:

Illegal

IMPORT_C TType EntryTypeL() const;

Description

Gets the type of entry.

Return value

TType The entry type. One of: EAppt, ETodo, EEvent, EReminder, EAnniv.

Capability:

Illegal

IMPORT_C void SetStatusL(TStatus aStatus);

Description

Sets the entry status.

For a to-do entry, this is one of: ECancelled, ETodoNeedsAction, ETodoCompleted, ETodoInProgress.

For any other entry types, this is one of: ECancelled, ETentative, EConfirmed.

Passing a value in which does not match the entry type will result in a panic.

Parameters

TStatus aStatus The status.

Leave codes

KErrArgument If the status passed in is invalid

Capability:

Illegal

IMPORT_C TStatus StatusL() const;

Description

Gets the entry status.

For a to-do entry, this is one of: ECancelled, ETodoNeedsAction, ETodoCompleted, ETodoInProgress.

For any other entry types, this is one of: ECancelled, ETentative, EConfirmed.

Return value

TStatus The status.

Panic codes

CalInterimAPI 4 The status of the entry is invalid

Capability:

Illegal

IMPORT_C void SetReplicationStatusL(TReplicationStatus aReplicationStatus);

Description

Sets the entry replication status.

Parameters

TReplicationStatus aReplicationStatus the replication status.

Capability:

Illegal

IMPORT_C TReplicationStatus ReplicationStatusL() const;

Description

Gets the entry replication status.

This is defined by TReplicationStatus. Default is TReplicationStatus::EOpen

Return value

TReplicationStatus The replication status.

Capability:

Illegal

IMPORT_C void SetPriorityL(TUint aPriority);

Description

Sets the priority for the entry.

The default value is zero.

Parameters

TUint aPriority Priority value between 0 and 255. The behaviour is undefined if the priority is greater than 255.

Capability:

Illegal

IMPORT_C TUint PriorityL() const;

Description

Gets the priority of the entry.

Return value

TUint Priority value between 0 and 255.

Capability:

Illegal

IMPORT_C void SetMethodL(TMethod aMethod);

Description

Sets the entry's method property for group scheduling.

Parameters

TMethod aMethod The method, this is one of: EMethodNone, EMethodPublish, EMethodRequest, EMethodReply, EMethodAdd, EMethodCancel, EMethodRefresh, EMethodCounter, EMethodDeclineCounter.

Capability:

Illegal

IMPORT_C TMethod MethodL() const;

Description

Returns the entry's method property for group scheduling.

Return value

TMethod The method, this is one of: EMethodNone, EMethodPublish, EMethodRequest, EMethodReply, EMethodAdd, EMethodCancel, EMethodRefresh, EMethodCounter, EMethodDeclineCounter.

Capability:

Illegal

IMPORT_C void SetSequenceNumberL(TInt aSeq);

Description

Sets the entry's sequence number for group scheduling.

Parameters

TInt aSeq The sequence number.

Capability:

Illegal

IMPORT_C TInt SequenceNumberL() const;

Description

Returns the entry's sequence number for group scheduling.

Return value

TInt The sequence number.

Capability:

Illegal

IMPORT_C const TDesC8 &UidL() const;

Description

Returns the entry's Global UID for group scheduling.

Return value

const TDesC8 & The Global UID.

Capability:

Illegal

IMPORT_C TCalTime RecurrenceIdL() const;

Description

Returns the entry's recurrence ID for group scheduling.

Return value

TCalTime The recurrence ID.

Capability:

Illegal

IMPORT_C CalCommon::TRecurrenceRange RecurrenceRangeL() const;

Description

Returns the recurrence range for the entry's recurrence ID.

Return value

CalCommon::TRecurrenceRange The recurrence range.

Capability:

Illegal

IMPORT_C CTzRules *TzRulesL() const;

Description

Gets the timezone rules for this entry's repeat rule.

Return value

CTzRules * A copy of the entry's timezone rules.

Capability:

Illegal

IMPORT_C void SetTzRulesL(const CTzRules &aTzRule);

Description

Sets the timezone rules for this entry's repeat rule.

Parameters

const CTzRules &aTzRule The entry's timezone rules. This function does not take ownership.

Leave codes

KErrNotFound If there is not a repeat definition in the entry KErrArgument If the entry uses floating time mode

Capability:

Illegal

IMPORT_C void SetTzRulesL();

Description

Creates the timezone rules for this entry's repeat rule from the local time zone settings.

Leave codes

KErrNotFound If there is not a repeat definition in the entry KErrArgument If the entry uses floating time mode

Capability:

Illegal

IMPORT_C void SetLocalUidL(TCalLocalUid aLocalId);

Description

Sets the calendar local id for this entry. This should be only used to set the same unique id on a new entry which is the replacement of an existing one in the Calendar store.

Parameters

TCalLocalUid aLocalId

Capability:

Illegal

IMPORT_C TCalLocalUid LocalUidL() const;

Description

Gets the calendar local id of this entry. Note that this is the unique (for each Calendar file) Id of the entry allocated by the Calendar server internally and will remain unchanged for lifetime of the entry.

Return value

TCalLocalUid The calendar local id.

TType

Description

Defines the type of the calendar entry.

EAppt An appointment, which has a start time and end time. ETodo A to-do, which can have a start time and end time (the end time is the due date), or can be undated. EEvent An event, which has a start time and end time. EReminder A reminder, which has a start time only. EAnniv An anniversary, which has a start time and end time.

TStatus

Description

Defines the possible status values of the entry.

ETentative The entry is tentative. EConfirmed The entry has been confirmed. ECancelled The entry has been cancelled. ETodoNeedsAction The to-do entry needs action. ETodoCompleted The to-do entry has been completed. ETodoInProcess The to-do entry is in progress. ENullStatus No Status is Set

TReplicationStatus

Description

Replication status.

EOpen No restriction on access. EPrivate Data is private (no access). ERestricted Data is confidential (restricted access).

TMethod

Description

The method property of a Group Scheduling entry.

EMethodNone The RFC2445-defined method value 'None'. EMethodPublish The RFC2445-defined method value 'Publish'. EMethodRequest The RFC2445-defined method value 'Request'. EMethodReply The RFC2445-defined method value 'Reply'. EMethodAdd The RFC2445-defined method value 'Add'. EMethodCancel The RFC2445-defined method value 'Cancel'. EMethodRefresh The RFC2445-defined method value 'Refresh'. EMethodCounter The RFC2445-defined method value 'Counter'. EMethodDeclineCounter The RFC2445-defined method value 'DeclineCounter'.

TCopyType

Description

Specify which entry details are to be copied in CCalEntry::CopyFromL functions.

ECopyAll Copy the ID of the entry EDontCopyId Dont copy ID of the entry