Class CAgnEntryModel

CAgnEntryModel

Support

Supported from 5.0

Description

Provides the interface through which the data stored in an agenda file can be accessed. It is the base class for the indexed model, CAgnIndexedModel and for the instance model, CAgnModel.

For an application to access the data in an agenda file, it must open an agenda model at run-time. There are three different types of agenda model: —

• the entry model (class CAgnEntryModel) should be used by an application without a user interface, such as a format conversion application

• the instance model (class CAgnModel) should be used by an application which has a user interface

• the indexed model (class CAgnIndexedModel) can be used for greater efficiency by applications which have no user interface and which need to access only a subset of the data in the file

If the entry model is used, the agenda data can be accessed as entries. There are four types of entry: —

• appointments (CAgnAppt)

• to-dos (CAgnTodo)

• events (CAgnEvent)

• anniversaries (CAgnAnniv)

Agenda entries are stored in an entry store, to-do lists are stored in a list of to-do lists. Both the entry store and the list of to-do lists are owned by the model.

The agenda model can be used in client mode or in normal mode. Client mode means that the model is a client of the agenda server. When in client mode, all model function calls which access data in the file make an asynchronous request to the server. This allows other applications to access the same data concurrently. When the model is in normal mode, it accesses the model data directly, preventing other applications from accessing the data until the file is closed. Applications written for EPOC Release 5 or later should only use the model in client mode. Normal mode has been preserved so that applications written before EPOC Release 5 are compatible. The extended entry details (for instance attendees and location) which were intoduced in EPOC Release 5 can only be used if the model is in client mode.

Derivation

CAgnEntryModel Provides the interface through which the data stored in an agenda file can be accessed CBase Base class for all classes to be instantiated on the heap MAgnActiveStep Base class used in the derivation of CAgnEntryModel

Defined in CAgnEntryModel:
AddEntryL(), AddTodoListL(), Anonymous, BufferedDeleting(), BufferedStoring(), Cancel(), ChangeTodoListOrderL(), ChangeTodoOrderL(), CharFormatLayer(), CheckNotifier(), CommitL(), CreateL(), CutEntryL(), DefaultAnnivDisplayTime(), DefaultDayNoteDisplayTime(), DefaultDisplayTime(), DefaultEventDisplayTime(), DeleteEntryL(), DeleteLiteEntry(), DeleteTodoListL(), EAddTodoListAtEnd, EBlocked, EClient, ENoFile, ENormal, EOk, ESaveAsCallBackHigh, ESaveAsCallBackLow, ESaveAsCallBackMedium, EServer, ExportVCalL(), FetchEntryL(), FetchTodoListL(), FileVersion(), FlushAndCommitL(), GetDayListFromExtractorL(), GetEmbeddedStore(), GetInstanceExtractorL(), GetReadStreamL(), GetSymbolInstanceList(), GetSymbolInstanceListL(), ImportVCalL(), IsClient(), IsInUseObserverController(), IsValidL(), LastSynchronizedDateL(), ModelVersion(), NewL(), NumberOfObserversLoaded(), NumberOfObserversRegistered(), ObserverController(), OpenL(), ParaFormatLayer(), PasteEntryL(), PeekAtDeletedTodoListList(), PeekAtTodoListList(), PictureFactory(), PopulateTodoListNamesL(), RegisterAlarm(), RegisterObserverL(), RegisteredAlarm(), RegisteredIndex(), RollbackL(), SaveAsL(), SaveTodoListsL(), Server(), SetDefaultAnnivDisplayTime(), SetDefaultDayNoteDisplayTime(), SetDefaultEventDisplayTime(), SetEntryServer(), SetLastSynchronizedDateL(), SetMode(), SetParaAndCharFormatLayersL(), SetPictureFactory(), SetServer(), State(), StreamId(), StreamStore(), TModelMode, TSaveAsCallBackFrequency, TState, TodoListCount(), TodoListIdsL(), UnregisterObserverL(), UpdateDefaultEntryTimes(), UpdateEntryL(), UpdateTodoListL(), ~CAgnEntryModel()

Inherited from CBase:
operator new()

static CAgnEntryModel* NewL(MAgnModelStateCallBack* aStateCallBack=NULL);

Description

Constructs a new CAgnEntryModel object, optionally with a pointer to a state callback object. The model's state is initialised to ENoFile and the model mode to ENormal.

Parameters

MAgnModelStateCallBack* aStateCallBack=NULL If specified, provides a callback function which notifies the user that the model is about to change state.

Return value

CAgnEntryModel* Pointer to the newly created entry model.

virtual ~CAgnEntryModel();

Description

Frees all resources owned by the agenda model, prior to its destruction.

TStreamId CreateL(CStreamStore& aStore,const TDesC& aDefaultTodoListName, const CParaFormatLayer* aParaFormatLayer, const CCharFormatLayer* aCharFormatLayer);
TStreamId CreateL(CStreamStore& aStore, const TDesC& aDefaultTodoListName, const CParaFormatLayer* aParaFormatLayer, const CCharFormatLayer* aCharFormatLayer, TBool aCreateTodoList);

Description

Creates an empty network of streams within aStore — overloaded function. The function returns the single root stream ID of the store.

These functions are identical except that the first variant creates a default to-do list with the name aDefaultTodoListName and saved with its ID being added to the model's list of to-do lists. The second variant only does this if aCreateTodoList is ETrue.

The model's state is set to EOk.

Parameters

CStreamStore& aStore A reference to the store object in which the model's data is stored. const TDesC& aDefaultTodoListName The name for the default to-do list which may be created. The maximum number of characters for the name can be found by using AgnModel::MaxTodoListNameLength(). const CParaFormatLayer* aParaFormatLayer The paragraph formatting layer for the model's agenda entries. const CCharFormatLayer* aCharFormatLayer The character formatting layer for the model's agenda entries. TBool aCreateTodoList If specified, ETrue creates a default to-do list with name aDefaultTodoListName. If EFalse, it does not.

Return value

TStreamId The root stream ID of the store.

void CreateL(RFs& aFs, TFileName aFileName, const TDesC& aDefaultTodoListName, const CParaFormatLayer* aParaFormatLayer, const CCharFormatLayer* aCharFormatLayer);

Description

Creates a new, empty agenda file with a valid agenda stream structure, which can be opened by the UI without modification. Also creates an empty default to-do list.

Note that this function should be called before the model has been assigned a server pointer. If the model is in EClient mode when this function is called, a panic occurs.

Parameters

RFs& aFs A session with the file server. TFileName aFileName The name of the file to create. const TDesC& aDefaultTodoListName The name for the default to-do list which is created. The maximum number of characters for the name can be found by using AgnModel::MaxTodoListNameLength(). const CParaFormatLayer* aParaFormatLayer Pointer to the format layer on which the paragraph formatting for entries in the model is based. const CCharFormatLayer* aCharFormatLayer Pointer to the format layer on which the character formatting for entries in the model is based.

void OpenL(CStreamStore& aStore, TStreamId aId, TTimeIntervalMinutes aDefaultEventDisplayTime = 0, TTimeIntervalMinutes aDefaultAnnivDisplayTime = 0, TTimeIntervalMinutes aDefaultDayNoteDisplayTime = 0);

Description

Opens an existing model store, whose root ID is aId in the store aStore. Does not use the agenda server, so should not be called if the model is in client mode. If the model is in client mode, you should use the "Open named agenda file" variant of this function.

The three TTimeIntervalMinutes arguments specify the default display times for the different entry types. The display time values are numbers of minutes from midnight — between zero and 1439 inclusive. These values can be changed using one of the model's SetDefaultXxxDisplayTime() functions. The parameters specifying the default display times have default values of zero.

Note:

• The default display time for events, anniversaries and day notes can be overridden using the relevant class's SetDisplayTime() function, (see classes CAgnEvent, CAgnAnniv, CAgnAppt).

Parameters

CStreamStore& aStore The store in which the model's data is stored. TStreamId aId The root stream ID of the store aStore. TTimeIntervalMinutes aDefaultEventDisplayTime The default display time for events. TTimeIntervalMinutes aDefaultAnnivDisplayTime The default display time for anniversaries. TTimeIntervalMinutes aDefaultDayNoteDisplayTime The default display time for day notes.

void OpenL(const TDesC& aFileName, TTimeIntervalMinutes aDefaultEventDisplayTime = 0, TTimeIntervalMinutes aDefaultAnnivDisplayTime = 0, TTimeIntervalMinutes aDefaultDayNoteDisplayTime = 0);

Description

Opens an agenda file using the server. If another agenda file is open in the same server session, it is closed. This function should only be used if the model is in client mode.

The three TTimeIntervalMinutes arguments specify the default display times for the different entry types. The display time values are numbers of minutes from midnight — between zero and 1439 inclusive. They all have default values of zero.

Parameters

const TDesC& aFileName The agenda file to open. TTimeIntervalMinutes aDefaultEventDisplayTime The default display time for events. TTimeIntervalMinutes aDefaultAnnivDisplayTime The default display time for anniversaries. TTimeIntervalMinutes aDefaultDayNoteDisplayTime The default display time for day notes.

TStreamId SaveAsL(CStreamStore& aStoreToSaveTo,MAgnProgressCallBack* aProgressCallBack, TSaveAsCallBackFrequency aSaveAsCallBackFrequency = ESaveAsCallBackMedium) const;

Description

Saves the model's entries and to-do lists to another stream store. The model's state must be EOk when this function is called, otherwise a panic is raised.

Parameters

CStreamStore& aStoreToSaveTo The stream store to which to save the agenda model. MAgnProgressCallBack* aProgressCallBack Pointer to a progress callback object. The operation uses an active object. This callback provides progress information and information about how the operation terminated. TSaveAsCallBackFrequency aSaveAsCallBackFrequency = ESaveAsCallBackMedium Specifies how often the model should callback the user with the MAgnProgressCallBack::Progress() method. It should not normally be necessary to change this value from the default.

Return value

TStreamId The ID of the stream store created by this function in which the model is saved.

void Cancel();

Description

Cancels an active object driven operation, such as saving, merging or tidying.

TAgnEntryId AddEntryL(CAgnEntry* aEntry,TAgnEntryId aTodoPositionReferenceId = AgnModel::NullId());

Description

Adds an entry to the model's store. If the entry is alarmed, the next due alarm is queued with the alarm server. The date/time of the entry's creation is set to the current date/time.

Notes

If the entry is a to-do, it must specify a to-do list ID to identify the to-do list to which it should be added.

The function notifies the model's observer controller that an entry has been added.

Parameters

CAgnEntry* aEntry Pointer to the entry to add. TAgnEntryId aTodoPositionReferenceId = AgnModel::NullId() If the new entry is a to-do, this argument is used to specify the position in the to-do list at which aEntry is added. aEntry is inserted at the position immediately before the entry with the ID specified. If this ID is null, (the default), aEntry is added at the end of the to-do list. The value is ignored if the entry is not a to-do.

Return value

TAgnEntryId The entry ID for aEntry.

CAgnEntry* FetchEntryL(TAgnEntryId aId) const;

Description

Retrieves an entry based on its entry ID.

Parameters

TAgnEntryId aId The entry ID of the entry to retrieve.

Return value

CAgnEntry* Pointer to the entry.

Leave codes

This function leaves with KErrNotFound if no entry matching aId is found.

CAgnEntry* FetchEntryL(TAgnUniqueId aId) const;

Description

Retrieves an entry based on its unique ID using the agenda server. The model must be in client mode before this function is called.

Parameters

TAgnUniqueId aId The unique ID of the entry to retrieve.

Return value

CAgnEntry* Pointer to the entry.

Leave codes

This function leaves with KErrNotFound if no entry matching aId is found.

void CutEntryL(TAgnEntryId aEntryId);

Description

Cuts the entry identified by aEntryId from the model's store.

Cutting an entry is the same as deleting it, except that if the entry has a synchronisation count greater than zero, then cutting the entry preserves its entry ID and unique ID if the entry is subsequently pasted back into the model's store.

Note

The function notifies the model's observer controller that an entry has been deleted.

Parameters

TAgnEntryId aEntryId The ID of the entry to cut.

Leave codes

If the entry cannot be found, the function leaves with KErrNotFound .

void CutEntryL(CAgnEntry* aEntry);

Description

Cuts aEntry from the model's store.

Cutting an entry is the same as deleting it, except that if the entry has a synchronisation count greater than zero, then cutting the entry preserves its entry ID and unique ID if the entry is subsequently pasted back into the model's store.

Note

The function notifies the model's observer controller that an entry has been deleted.

Parameters

CAgnEntry* aEntry Pointer to the entry to cut.

void PasteEntryL(CAgnEntry* aEntry, TAgnEntryId aTodoPositionReferenceId = AgnModel::NullId());

Description

Pastes aEntry into the model's store.

If the entry is a to-do, its position within the to-do list may be specified using aTodoPositionReferenceId.

Note

If aEntry's entry ID and unique ID correspond to those of the last entry to be cut (using CutEntryL()), then the entry's unique ID is preserved. Otherwise, calling this function has the same effect as calling AddEntryL() — the entry is assigned a new unique ID, like any other new entry.

Parameters

CAgnEntry* aEntry Pointer to the entry to paste. TAgnEntryId aTodoPositionReferenceId = AgnModel::NullId() If aEntry is a to-do, this argument is used to specify the position in the to-do list at which it is added. aEntry is inserted at the position immediately before the entry with the ID specified. If this ID is null, (the default), aEntry is added at the end of the to-do list. The value is ignored if the entry is not a to-do.

void UpdateEntryL(CAgnEntry* aEntry,TAgnEntryId aTodoPositionReferenceId = AgnModel::NullId());

Description

Updates the details for the existing entry aEntry in the model's store.

If the entry is alarmed, its next due alarm is queued with the alarm server.

If the entry is a to-do and it is being moved from one to-do list to another, the position of the entry in the new list is identified by aTodoPositionReferenceId.

Notes

If the entry passed to this function has previously been marked as deleted, and its synchronisation count is now zero then the entry is fully deleted from the model's store.

The function notifies the model's observer controller that the entry has been updated.

Parameters

CAgnEntry* aEntry Pointer to an agenda entry which contains the updated details. TAgnEntryId aTodoPositionReferenceId = AgnModel::NullId() If the entry is a to-do, and the to-do is being moved from one to-do list to another, this specifies the position in the to-do list at which aEntry is added. aEntry is inserted at the position immediately before the entry with the ID specified. If this ID is null, (this is the default), aEntry is appended to the to-do list. The value is ignored if the entry is not a to-do, or if it is not being moved to another to-do list.

void DeleteEntryL(CAgnEntry* aEntry);

Description

Deletes aEntry from the model's store. If the entry is a to-do then additionally, its ID is removed from the to-do list.

Notes

If the entry has a positive synchronisation count, it is marked as having been deleted but is not removed from the store. It is removed from the model's indexes, so is not visible to views, but can still be accessed using an entry iterator (see class TAgnEntryIter).

The model's observer controller is notified that the entry has been deleted.

Parameters

CAgnEntry* aEntry Pointer to the entry to delete.

virtual void DeleteEntryL(TAgnEntryId aEntryId);

Description

Deletes the entry identified by aEntryId from the store. If the entry is a to-do then additionally, its ID is removed from the to-do list.

Notes

If the entry has a positive synchronisation count, it is marked as having been deleted but is not removed from the store. It is removed from the model's indexes, so is not visible to views, but can still be accessed using an entry iterator (see class TAgnEntryIter).

The model's observer controller is notified that the entry has been deleted.

Parameters

TAgnEntryId aEntryId The ID of the entry to delete.

Leave codes

If the specified entry cannot be found, the function leaves with KErrNotFound .

void DeleteLiteEntry(const CAgnSortEntry* aSortEntry);

Description

Deletes a sort entry from the sort entry allocator (a specialised memory handler for sort entry objects). A sort entry is an entry in an agenda index. The function frees the sort entry object and puts it on the free list.

Parameters

const CAgnSortEntry* aSortEntry Pointer to the sort entry to delete.

CAgnSortEntryTable* RegisteredIndex() const;

Description

Returns a pointer to the model's entry index. This index can be used to find entries which are the same apart from their entry IDs.

Return value

CAgnSortEntryTable* The model's entry index.

virtual TAgnTodoListId AddTodoListL(CAgnTodoList* aTodoList,TInt aPosition=EAddTodoListAtEnd);

Description

Adds a to-do list to the model's store and sets the to-do list's position in the model's list of to-do lists.

If the position is not specified, the to-do list is added at the end of the list of to-do lists. Specifying a position of zero indicates it is the first to-do list. If the position specified is equal to the number of to-do lists in the model, the new to-do list is added at the end. If the position specified is greater than the number of to-do lists in the model, or is negative, the function raises a panic.

Note

The function notifies the model's observer controller that the to-do list has been added.

Parameters

CAgnTodoList* aTodoList Pointer to the to-do list to add. TInt aPosition=EAddTodoListAtEnd Position within the model's list of to-do lists at which to insert the to-do list.

Return value

TAgnTodoListId The to-do list ID.

CAgnTodoList* FetchTodoListL(TAgnTodoListId aTodoListId) const;

Description

Retrieves a to-do list based on its to-do list ID from the model's store.

Parameters

TAgnTodoListId aTodoListId The ID of the to-do list to retrieve.

Return value

CAgnTodoList* Pointer to the to-do list.

CAgnTodoList* FetchTodoListL(TAgnUniqueId aUniqueId) const;

Description

Retrieves a to-do list based on its unique ID from the model's store, using the server.

The model must be in client mode before this function is called.

Parameters

TAgnUniqueId aUniqueId The unique ID of the to-do list to retrieve.

Return value

CAgnTodoList* Pointer to the to-do list.

virtual void DeleteTodoListL(CAgnTodoList* aTodoList);

Description

Deletes all the to-do entries which belong to the to-do list specified, then deletes the to-do list itself from the model's store.

If the model has only one to-do list, this function has no effect.

Notes

The function notifies the model's observer controller that the to-do list has been deleted.

If the to-do list, or any to-do entry in the list, has a positive synchronisation count, the list or entry is marked as having been deleted but is not removed from the store. It is removed from the model's indexes, so is not visible to views, but can still be accessed using an entry iterator (see class TAgnEntryIter).

Parameters

CAgnTodoList* aTodoList Pointer to the to-do list to delete.

virtual void DeleteTodoListL(TAgnTodoListId aTodoListId);

Description

Deletes all the to-do entries which belong to the to-do list with the specified ID, then deletes the to-do list itself from the model's store.

If the model has only one to-do list, this function has no effect.

Notes

The model's observer controller is notified that the to-do list has been deleted.

If the to-do list, or any to-do entry in the list, has a positive synchronisation count, the list, or entry is marked as having been deleted but is not removed from the store. It is removed from the indexes, so is not visible to views, but can still be accessed using an entry iterator (see class TAgnEntryIter). It is also added to the model's list of deleted to-do lists.

Parameters

TAgnTodoListId aTodoListId The ID of the to-do list to delete.

virtual void UpdateTodoListL(CAgnTodoList* aTodoList);

Description

Updates a to-do list. A to-do list with the same to-do list ID as aTodoList must already exist in the model's store, and if so, it is replaced by aTodoList.

Notes

The model's observer controller is notified that the to-do list has been updated.

When a to-do list which has previously been marked as deleted is passed to this function, but its synchronisation count is now zero, then it is physically removed from the store and its ID removed from the model's list of deleted to-do lists.

Parameters

CAgnTodoList* aTodoList Pointer to a to-do list object containing the new details.

Leave codes

The function leaves with KErrNotFound if aTodoList does not already exist in the model's store.

void ChangeTodoListOrderL(TInt aOldPosition,TInt aNewPosition);

Description

Changes the position of a to-do list in the model's list of to-do lists.

The two positions specified are indexes into the model's list of to-do lists, so should be specified as relative to zero, i.e. zero indicates the first position in the list. Specify EAddTodoListAtEnd to indicate the position at the end of the list. Both positions must be valid, or a panic is raised.

Parameters

TInt aOldPosition The position of the to-do list to move. TInt aNewPosition The new position for the to-do list.

void ChangeTodoOrderL(TAgnTodoListId aTodoListId,TAgnEntryId aTodoId,TAgnEntryId aTodoPositionReferenceId= AgnModel::NullId());

Description

Moves the to-do entry with the entry ID aTodoId to the position immediately before the position occupied by aTodoPositionReferenceId. The to-do list affected is identified by aTodoListId. If aTodoPositionReferenceId is null (the default), or if it cannot be found in the list, then the to-do entry is moved to the end of the list.

Note

A to-do instance list (CAgnTodoInstanceList) should be used to determine the position to which to move the to-do entry. This is because the user sees the order of the to-do entries as they appear in a to-do instance list. A to-do list (CAgnTodoList), on the other hand, may contain to-do entries which are not visible to the user (for instance if they are crossed out, and crossed out entries are not being displayed).

Parameters

TAgnTodoListId aTodoListId Identifies the to-do list to which aTodoId belongs. TAgnEntryId aTodoId Identifies the to-do entry to move. TAgnEntryId aTodoPositionReferenceId= AgnModel::NullId() Specifies a position in the to-do list. The entry identified by aTodoId is moved to the position immediately before this. If this is null (the default) then aTodoId is moved to the end of the list.

Leave codes

The function leaves if the to-do list specified cannot be found.

void ChangeTodoOrderL(CAgnTodoList* aTodoList,TAgnEntryId aTodoId,TAgnEntryId aTodoPositionReferenceId= AgnModel::NullId());

Description

Moves the to-do entry with the entry ID aTodoId to the position immediately before the position occupied by aTodoPositionReferenceId in the to-do list aTodoList. If aTodoPositionReferenceId is null (the default), or if it cannot be found in the list, then the to-do entry is moved to the end of the list.

Notes

A to-do instance list (CAgnTodoInstanceList) must be used to determine the position to which to move the to-do entry. This is because the user sees the order of the to-do entries as they appear in a to-do instance list. A to-do list (CAgnTodoList), on the other hand, may contain to-do entries which are not visible to the user (for instance if they are crossed out, and crossed out entries are not being displayed).

If this function leaves, the contents of the to-do list aTodoList are invalid and the list should be deleted.

Parameters

CAgnTodoList* aTodoList Pointer to the to-do list to which aTodoId belongs. TAgnEntryId aTodoId Identifies the to-do entry to move. TAgnEntryId aTodoPositionReferenceId= AgnModel::NullId() Specifies a position in the to-do list. The entry identified by aTodoId is moved to the position immediately before this. If this is null (the default) then aTodoId is moved to the end of the list.

TInt TodoListCount() const;

Description

Returns the number of to-do lists in the model's list of to-do lists.

This count does not include the deleted to-do lists.

Return value

TInt The number of to-do lists in the model's list of to-do lists.

CArrayFixFlat<TAgnTodoListId>* TodoListIdsL() const;

Description

Creates and returns an array of to-do list IDs for all the to-do lists in the model. The returned array includes deleted to-do lists.

Note

This function is provided for use by synchronisation applications.

Return value

CArrayFixFlat<TAgnTodoListId>* Pointer to an array of all to-do list IDs owned by the model.

TStreamId SaveTodoListsL(CStreamStore& aStoreToSaveTo) const;

Description

Saves the model's to-do lists into the stream store specified. This does not include the model's deleted to-do lists. It returns the root stream ID of the stream store used.

Note

This function is synchronous, so calling it on a model which has a large number of to-do lists may cause a few seconds delay before it completes.

Parameters

CStreamStore& aStoreToSaveTo The stream store into which to save the to-do lists.

Return value

TStreamId The root stream ID of the stream store which was used.

TStreamId SaveTodoListsL(TFileName aFileName) const;

Description

Uses the agenda server to save the model's to-do lists to the file specified. This does not include the model's deleted to-do lists. The file aFileName must already exist, and must not be read-only. The model must be in client mode before this function is called.

Parameters

TFileName aFileName The agenda file to which to save the model's to-do lists.

Return value

TStreamId The root stream ID of the stream store used to store the to-do lists.

const CAgnTodoListList* PeekAtTodoListList() const;

Description

Returns a pointer to the model's list of to-do lists. This pointer can be used to retrieve the model's to-do lists and their order.

Return value

CAgnTodoListList* Constant pointer to the model's list of to-do lists.

const CAgnDeletedTodoListList* PeekAtDeletedTodoListList() const;

Description

This function returns a pointer to the list of deleted to-do lists. It is provided for use by synchronisation apps.

Note

To get an array of the todo list IDs for all the to-do lists held by the model, whether deleted or not, use the function TodoListIdsL().

Return value

CAgnDeletedTodoListList* Ponter to the model's list of deleted to-do lists.

void PopulateTodoListNamesL(CAgnTodoListNames* aList) const;

Description

Fills aList with the details (name, ID and sort order) for all of the to-do lists in the model's list of to-do lists (not including the deleted to-do lists).

Parameters

CAgnTodoListNames* aList On return, a pointer to a list containing the names and IDs of the model's to-do lists.

const CCharFormatLayer* CharFormatLayer() const;

Description

Returns a pointer to the character format layer used by the model's entries.

Return value

CCharFormatLayer* A pointer to the model's character format layer.

const CParaFormatLayer* ParaFormatLayer() const;

Description

Returns a pointer to the paragraph format layer used by the model's entries.

Return value

CParaFormatLayer* A pointer to the model's paragraph format layer.

void SetParaAndCharFormatLayersL(const CParaFormatLayer* aParaFormatLayer,const CCharFormatLayer* aCharFormatLayer);

Description

Changes the format layers used for the model's entries to the values specified.

Parameters

const CParaFormatLayer* aParaFormatLayer Pointer to the new paragraph format layer. const CCharFormatLayer* aCharFormatLayer Pointer to the new character format layer.

TTimeIntervalMinutes DefaultAnnivDisplayTime() const;

Description

Retrieves the default display time for anniversary entries. This value is initialised when the model is opened. It may be changed by calling SetDefaultAnnivDisplayTime().

Return value

TTimeIntervalMinutes The default display time for anniversary entries, as a number of minutes from midnight.

TTimeIntervalMinutes DefaultDayNoteDisplayTime() const;

Description

Retrieves the default display time for day notes. This value is initialised when the model is opened. It may be changed by calling SetDefaultDayNoteDisplayTime().

Return value

TTimeIntervalMinutes The default display time for day notes, as a number of minutes from midnight.

TTimeIntervalMinutes DefaultEventDisplayTime() const;

Description

Retrieves the default display time for events. This value is initialised when the model is opened. It may be changed by calling SetDefaultEventDisplayTime().

Return value

TTimeIntervalMinutes The default display time for events, as a number of minutes from midnight.

TTimeIntervalMinutes DefaultDisplayTime(CAgnEntry::TType aType,TAgnTodoListId = AgnModel::NullId()) const;

Description

Retrieves the default display time for the entry type specified. If the entry type is a to-do, a to-do list ID must be specified because each to-do list has its own default display time.

Parameters

CAgnEntry::TType aType The entry type of interest. TAgnTodoListId = AgnModel::NullId() If the entry type is a to-do, (CAgnEntry::ETodo), this specifies the to-do list of interest.

Return value

TTimeIntervalMinutes The default display time for the entry type specified, or, if the entry type was a to-do, the default display time for the to-do list specified.

void SetDefaultAnnivDisplayTime(TTimeIntervalMinutes aDefaultAnnivDisplayTime);

Description

Sets the default display time for anniversary entries.

Parameters

TTimeIntervalMinutes aDefaultAnnivDisplayTime The new default display time for anniversary entries, as a number of minutes from midnight.

void SetDefaultDayNoteDisplayTime(TTimeIntervalMinutes aDefaultDayNoteDisplayTime);

Description

Sets the default display time for day notes.

Parameters

TTimeIntervalMinutes aDefaultDayNoteDisplayTime The new default display time for day notes, as a number of minutes from midnight.

void SetDefaultEventDisplayTime(TTimeIntervalMinutes aDefaultEventDisplayTime);

Description

Sets the default display time for events.

Parameters

TTimeIntervalMinutes aDefaultEventDisplayTime The new default display time for events, as a number of minutes from midnight.

void UpdateDefaultEntryTimes();

Description

Propagates changes made to the default display time for all entry types by a call to one of the SetDefaultXxxDisplayTime() functions to the server. The model must be in client mode before calling this function.

TAgnInstanceExtractor* GetInstanceExtractorL(TAgnDate aToday, TAgnFilter& aFilter);

Description

Creates an instance extractor using the specified filter and date. An instance extractor selects entries from the model's index that match the criteria specified by the filter and date. After calling this function, the instance extractor can be passed to GetDayListFromExtractorL() which uses the extractor to return an array of TAgnSortInstance objects which match the criteria.

Parameters

TAgnDate aToday The date of interest. TAgnFilter& aFilter Filters the entry types.

Return value

TAgnInstanceExtractor* Pointer to the instance extractor.

void GetDayListFromExtractorL(TAgnInstanceExtractor* aExtractor, TAgnDate aDay, CArrayFixFlat<TAgnSortInstance>* aDayInfoList, TAgnDate aToday);

Description

Retrieves a list of instances for the specified day, using a previously set up instance extractor. Do not use this function if the model is a client of the agenda server — use RAgendaServ::GetDayDateTimeListFromExtractorL() instead.

Parameters

TAgnInstanceExtractor* aExtractor The instance extractor. This may be created using GetInstanceExtractorL(). TAgnDate aDay The date for which entries are retrieved. CArrayFixFlat<TAgnSortInstance>* aDayInfoList On return, pointer to the filtered list of instances. TAgnDate aToday Today's date. Used to determine if undated to-do items should be returned in the list. i.e. if it has the same value as the aDay parameter, then any undated to-do items may also be returned as part of the instance list.

void GetSymbolInstanceListL(CAgnSymbolList* aList,TTime& aToday, TAgnFilter& aFilter);

Support

Supported from 5.1

Description

Retrieves a filtered list of entry symbols for the instances which occur within a month. The year and month of interest should be specified in aList.

A symbol list is a list of the days in a month which have entry symbols. The day is stored as a number (0 to 30) and each day can have a maximum of two symbols. The list is ordered by day number. The symbol list also specifies the month and the year.

Parameters

CAgnSymbolList* aList Pointer to an existing CAgnSymbolList object. Should specify the year and month of interest. On return, the list contains the entry symbols which belong to instances occuring within the specified month. TTime& aToday Today's date. Used to determine if undated to-do items should be included in the list. TAgnFilter& aFilter Filters the entry types of interest.

void GetSymbolInstanceList(CAgnSymbolList* aList,TTime& aToday, TAgnFilter& aFilter);

Support

Withdrawn in 5.1

Description

Retrieves a filtered list of entry symbols for the instances which occur within a month. The year and month of interest should be specified in aList.

A symbol list is a list of the days in a month which have entry symbols. The day is stored as a number (0 to 30) and each day can have a maximum of two symbols. The list is ordered by day number. The symbol list also specifies the month and the year.

Parameters

CAgnSymbolList* aList Pointer to an existing CAgnSymbolList object. Should specify the year and month of interest. On return, the list contains the entry symbols which belong to instances occuring within the specified month. TTime& aToday Today's date. Used to determine if undated to-do items should be included in the list. TAgnFilter& aFilter Filters the entry types of interest.

void SetLastSynchronizedDateL(const TTime& aTime) const;

Description

Sets the date/time that the model was last synchronised

Parameters

const TTime& aTime The new date/time that the model was last synchronised.

TTime LastSynchronizedDateL() const;

Description

Retrieves the date/time that the model was last synchronised, as set by SetLastSynchronizedDateL(). When the model is created, this date/time is initialised to null (Time::NullTTime()).

Return value

TTime The date/time that the model was last synchronised.

void SetServer(RAgendaServ* aServer);

Description

Sets the server to use for model functions and sets the model's mode to EClient.

Note

The server must be connected (using RAgendaServ::Connect()) before you call a function which uses it.

Parameters

RAgendaServ* aServer Pointer to an agenda server.

RAgendaServ* Server() const;

Description

Returns a pointer to the model's server object, as set by SetServer().

Return value

RAgendaServ* Pointer to the model's server object.

void SetEntryServer(CAgnEntry* aEntry);

Description

Sets the server for an agenda entry to be the same as the server used by the model.

The server object used by the entry is set automatically by the model whenever the entry is fetched from the server. It should only be necessary for third party applications to call this function if they are creating an entry and attaching embedded data to it before adding it to the model.

Arguments

Parameters

CAgnEntry* aEntry Pointer to the entry.

void SetMode(TModelMode aMode);

Description

Sets the model's mode.

If the model uses the server, the model's mode needs to be set to EClient so that the model will use the server rather than directly accessing the file. Note that when a call to SetServer() is made, the mode is set to client.

Parameters

TModelMode aMode The model's mode of operation. ENormal, EClient or EServer.

TBool IsClient() const;

Description

Returns whether or not the model is running as a client of the agenda server.

Return value

TBool ETrue if the model is in client mode, EFalse if not.

TBool CheckNotifier();

Description

Tests whether the currently open file has been updated by another client of the agenda server. May be used by the UI to test whether it needs to be updated in response to changes made to the model by other applications. It also should be called in order to avoid fetching entries deleted by other clients. This function is only relevant if the model is in client mode. If not, it returns EFalse.

Return value

TBool ETrue if the file has been updated by another client. EFalse if not. Also returns EFalse if the model is not in client mode, or if no agenda file is currently open.

CStreamStore& StreamStore() const;

Description

Returns a reference to the stream store in which the model's data is stored.

Note

This function is deprecated when the model is using the agenda server. This is because the model data should not be accessed directly if the file has multiple clients.

Return value

CStreamStore& A reference to the stream store in which the model's data is stored.

TStreamId StreamId(TUid aUid);

Description

Retrieves the stream ID for the specified stream UID. For use only by a client of the agenda server.

Parameters

TUid aUid The stream UID. This represents an application-specific stream which the client has created in the agenda file using RAgendaServ::CreateNewStreamL().

Return value

TStreamId The stream ID associated with the unique identifier aUid. This can be used to access the stream, e.g. by calling RAgendaServ::GetWriteStreamL().

RReadStream& GetReadStreamL(TStreamId aStreamId);

Description

Retrieves a reference to an application-specific stream in the model using the agenda server. For use only by a client of the agenda server.

Parameters

TStreamId aStreamId The ID identifying the read stream.

Return value

RReadStream& Reference to a read stream containing application-specific data.

CStreamStore* GetEmbeddedStore(TStreamId aId);

Description

Retrieves an embedded store based on stream ID using the server. For use only by a client of the agenda server.

Parameters

TStreamId aId The ID identifying the stream store.

Return value

CStreamStore* Pointer to the embedded stream store.

TInt IsValidL(CStreamStore& aStore,TStreamId aId) const;

Description

Tests whether the store aStore with the root ID aId is in a state that is readable by the model, i.e. that the stream framework is in place and useable. It returns KErrNone if it is, otherwise it returns the error code generated by trying to load the stream network, (e.g. KErrEof).

Note

This function does not check the contents of any entries in the model.

Parameters

CStreamStore& aStore A reference to the store object in which the model's data is stored. TStreamId aId The root stream ID of the store aStore.

Return value

TInt KErrNone if the stream network is valid, otherwise the error code generated by trying to load the stream network.

Leave codes

May leave with KErrNoMemory as it creates the necessary objects, or one of the other standard error codes.

void ExportVCalL(RWriteStream& aWriteStream, CAgnEntry* aEntry);

Support

Withdrawn in 6.0

Description

Exports an agenda entry as a vCalendar entity to the write stream specified. The entry is exported either as a vTodo, if it is a to-do, otherwise as a vEvent.

Parameters

RWriteStream& aWriteStream The stream to which the agenda entry should be externalised as a vCalendar entity. CAgnEntry* aEntry Pointer to the agenda entry.

void ExportVCalL(RWriteStream& aWriteStream, CArrayFixFlat<TAgnEntryId>* aEntryIdList);

Support

Withdrawn in 6.0

Description

Exports a list of agenda entries as multiple vCalendar entities to the write stream specified. The entries are exported either as vTodos, if they are to-dos, otherwise as vEvents.

Parameters

RWriteStream& aWriteStream The stream to which the agenda entries should be externalised as vCalendar entities. CArrayFixFlat<TAgnEntryId>* aEntryIdList Pointer to the array of entry IDs which identify the agenda entries.

Leave codes

If any entry in the list cannot be found, the function leaves with KErrNotFound .

void ExportVCalL(RWriteStream& aWriteStream, CAgnEntry* aEntry, const CVersitParser::TVersitCharSet aCharSet = CVersitParser::EUTF8CharSet);

Support

Supported from 5.1

Description

Exports an agenda entry as a vCalendar entity to the write stream specified. The entry is exported either as a vTodo, if it is a to-do, otherwise as a vEvent. The exported property values are converted from Unicode into the character set indicated by the last parameter (UTF-8 by default).

Parameters

RWriteStream& aWriteStream The stream to which the agenda entry should be externalised as a vCalendar entity. CAgnEntry* aEntry Pointer to the agenda entry. CVersitParser::TVersitCharSet aCharSet The character set into which the entry is converted before being exported.

void ExportVCalL(RWriteStream& aWriteStream, CArrayFixFlat<TAgnEntryId>* aEntryIdList, const CVersitParser::TVersitCharSet aCharSet = CVersitParser::EUTF8CharSet);

Support

Supported from 5.1

Description

Exports a list of agenda entries as multiple vCalendar entities to the write stream specified. The entries are exported either as vTodos, if they are to-dos, otherwise as vEvents. The exported property values are converted from Unicode into the character set indicated by the last parameter (UTF-8 by default).

Parameters

RWriteStream& aWriteStream The stream to which the agenda entries should be externalised as vCalendar entities. CArrayFixFlat<TAgnEntryId>* aEntryIdList Pointer to the array of entry IDs which identify the agenda entries. const CVersitParser::TVersitCharSet aCharSet The character set into which the entries are converted before being exported.

Leave codes

If any entry in the list cannot be found, the function leaves with KErrNotFound .

void ImportVCalL(RReadStream& aReadStream, CArrayPtr<CAgnEntry>* aEntryArray);

Description

Imports a vCalendar consisting of one or more vCalendar entities. The vCalendar is read from the read stream specified and its entities are converted into EPOC agenda entries and returned in the array aEntryArray.

Parameters

RReadStream& aReadStream The read stream which contains the vCalendar. CArrayPtr<CAgnEntry>* aEntryArray On return, a list of the agenda entries which were imported from the vCalendar. The list contains the vEvents followed by the vTodos.

void RegisterObserverL(const TFileName& aObserverName,const CAgnObserver* aObserver);

Description

Registers an observer with the model's observer controller and calls the observer's StartObserving() function.

The observer's DLL is loaded only when the model is opened, so this function should be called before calling OpenL().

Parameters

const TFileName& aObserverName The filename of the DLL where the observer's definition can be found. Does not need to include the .dll extension. This may specify the full path, if the DLL is not in the standard location. const CAgnObserver* aObserver Pointer to the agenda model observer.

Leave codes

If an observer with the specified name is already registered, the function leaves with KErrAlreadyExists .

void UnregisterObserverL(const TFileName& aObserverName);

Description

Removes the observer with the DLL name specified from the model's observer controller. Calls the observer's StopObserving() function.

Parameters

const TFileName& aObserverName The filename of the observer's DLL.

Leave codes

If an observer with the specified name is not registered, the function leaves with KErrNotFound .

CAgnObsController* ObserverController() const;

Description

Returns a pointer to the model's observer controller.

Return value

CAgnObsController* A pointer to the model's observer controller.

TBool IsInUseObserverController() const;

Description

Retrieves whether the observer controller is enabled or disabled. When the controller is initialised, it is set to be enabled.

Return value

TBool ETrue if the observer controller is enabled, EFalse if it is disabled.

TInt NumberOfObserversLoaded() const;

Description

Returns the number of registered observers whose DLLs are loaded.

This number can differ from the number returned by NumberOfObserversRegistered() because an observer is only loaded when the model is opened, but it can be registered at any time.

Note

A loaded observer means that the DLL which it is implemented in is loaded. A registered observer means that the name of the observer is stored in the model and its DLL will be loaded when the file is next opened.

Return value

Return value

TInt The number of registered observers whose DLLs are loaded.

TInt NumberOfObserversRegistered() const;

Description

Returns the number of registered observers.

Return value

TInt The number of registered observers.

MPictureFactory* PictureFactory() const;

Description

Returns a pointer to the model's picture factory.

Return value

MPictureFactory* Pointer to the agenda model's picture header factory.

void SetPictureFactory(MPictureFactory* aPictureFactory);

Description

Sets the model's picture factory.

Parameters

MPictureFactory* aPictureFactory Pointer to the model's picture header factory.

void RegisterAlarm(CAgnAlarm* aAlarm);

Description

Sets the model's registered alarm.

Parameters

CAgnAlarm* aAlarm Pointer to the alarm to set as the model's registered alarm.

CAgnAlarm* RegisteredAlarm() const;

Description

Returns a pointer to the model's registered alarm.

Return value

CAgnAlarm* Pointer to the model's registered alarm. NULL if no registered alarm has been set.

void FlushAndCommitL();

Description

Flushes the entry buffer and commits any changes that have occurred to the model.

This function is only relevant if buffered storing or deleting is in effect. Prolonged operations, for instance merging or tidying, do not update the entries in the model's store until the buffer is full. If one of these activities finishes before the buffer has had a chance to automatically update the store, then this function should be called to force it to do so.

void CommitL();

Description

Commits any changes both to file and internally that have occurred to the model. This function differs from FlushAndCommitL() in that it does not empty the buffers.

void RollbackL();

Description

Reverts the model to the state it was in after CommitL() or RollbackL() was last called, i.e. it deletes all entries which have been added, and reinstates all entries which have been deleted.

TBool BufferedDeleting() const;

Description

Returns whether or not the model is using buffered deletion for entries.

If buffered deletion is set, this means that when an entry is deleted, the agenda file is not updated immediately. The entry is marked as deleted in a memory buffer. The file is updated only when either every entry contained in the buffer has been marked as deleted, or when CommitL() is called (either directly or indirectly).

Buffered deletion and buffered storage are both unset when the model is created.

Return value

TBool ETrue if the model is using buffered deleting, EFalse if not.

TBool BufferedStoring() const;

Description

Returns whether or not the model is using buffered storage for entries.

If buffered storing is set, this means that when an entry is added to the model, it is held in a memory buffer and is not written to file. The contents of the buffer are written to the file when the buffer becomes full or when the buffer is flushed (this occurs when CommitL() is called, either directly or indirectly).

Return value

TBool ETrue if the model is using buffered storage. EFalse if not.

TAgnVersion FileVersion() const;

Description

Returns the version of the agenda model that was used to create the currently loaded file.

Return value

TAgnVersion The version of the agenda model that was used to create the currently loaded agenda file.

TAgnVersion ModelVersion() const;

Description

Returns the version of the agenda model being used.

Return value

TAgnVersion The model version.

TState State() const;

Description

Returns the state of the agenda model.

Return value

TState The state of the agenda model.

TState

Description

Model state

ENoFile The initial state of the model before a file has been created or opened. Also the state of the model after an unsuccessful operation, e.g. after an attempt to open a file has failed. Many agenda model operations raise a panic if the model's state is ENoFile, for instance those which add, delete or update entries or to-do lists. EBlocked The model's state while it is carrying out a prolonged activity. Indicates that the model is not available for use and any attempt to use it results in a panic. EOk A file is open, and the model is ready for use.

TSaveAsCallBackFrequency

Description

This enumeration specifies how frequently the user of a save as operation (CAgnEntryModel::SaveAsL()) should be notified of its progress with the MAgnProgressCallBack::Progress() method. It should not normally be necessary to change the value from the default (ESaveAsCallBackMedium).

ESaveAsCallBackHigh High frequency. ESaveAsCallBackMedium Medium frequency (the default). ESaveAsCallBackLow Low frequency.

TModelMode

Description

This enumeration is used in the CAgnEntryModel::SetMode() function to specify whether or not the model is a client of the server.

ENormal The model is not using the server. This is the default. EClient The model is a client of the server. EServer The model is in server mode. A client program should never set the model to EServer.

Anonymous

Description

Miscellaneous constants.

EAddTodoListAtEnd Indicates the last position in the model's list of to-do lists.