Class CAgnIndexedModel

CAgnIndexedModel

Support

Supported from 5.0

Description

Indexed agenda model.

To access the data in an agenda file, an agenda model must be opened at run-time. There are three types of model. The indexed model (CAgnIndexedModel) is opened as an intermediate stage in opening the instance model (CAgnModel). It can also be used in its own right for greater efficiency by applications which have no user interface and which need to access only a subset of the data in the file.

When an indexed model is opened, it builds indexes of the data in an agenda file, which allows the information to be filtered before whole entries are read.

An index is an array of sort entries (CAgnSortEntry). The main index class is CAgnSortEntryTable, which owns a number of specific entry type indexes. When an entry is added to the model, the index class filters it to find out which other indexes it should go into.

The indexed model provides functions for merging and tidying. Merging means adding the entries and to-do lists contained in one agenda file into another file. Tidying causes a subset of a file's entries or to-do lists to be deleted, or moved or copied to another file. Tidying and merging can be prolonged operations, so they use an active object.

Derivation

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

Defined in CAgnIndexedModel:
EAll, ECopy, ECopyAndDelete, ECrossedOut, EDelete, EDontMergeTodoListSettings, EExceptCrossedOut, EMergeCallBackHigh, EMergeCallBackLow, EMergeCallBackMedium, EMergeTodoListSettings, EOpenCallBackHigh, EOpenCallBackLow, EOpenCallBackMedium, ETidyByDateCallBackHigh, ETidyByDateCallBackLow, ETidyByDateCallBackMedium, ETidyByTodoListCallBachHigh, ETidyByTodoListCallBackHow, ETidyByTodoListCallBackMedium, EntryCount(), GetLiteEntryL(), IndexCount(), Indexes(), MergeL(), NewL(), OpenL(), TMergeCallBackFrequency, TMergeTodoListSettings, TOpenCallBackFrequency, TTidyByDateCallBackFrequency, TTidyByTodoListCallBackFrequency, TTidyDirective, TTidyTodoListHow, TidyByDateL(), TidyByTodoListL(), ~CAgnIndexedModel()

Inherited from 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(), NumberOfObserversLoaded(), NumberOfObserversRegistered(), ObserverController(), 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()

Inherited from CBase:
operator new()

static CAgnIndexedModel* NewL(MAgnModelStateCallBack* aStateCallBack);

Description

Allocates and constructs an indexed model, optionally with a pointer to a state callback object.

Parameters

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

Return value

CAgnIndexedModel* Pointer to the newly created indexed model.

virtual ~CAgnIndexedModel();

Description

Destructor.

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

TBool OpenL(CStreamStore& aStore, TStreamId aId, TTimeIntervalMinutes aDefaultEventDisplayTime, TTimeIntervalMinutes aDefaultAnnivDisplayTime, TTimeIntervalMinutes aDefaultDayNoteDisplayTime, MAgnProgressCallBack* aProgressCallBack, TBool aOpenSynchronously = EFalse, TOpenCallBackFrequency aCallBackFrequency = EOpenCallBackMedium);

Description

Open store

Opens an existing model store, whose root ID is aId in the store aStore. It retrieves all of the model's entries and builds the indexes. This function does not use the agenda server and should not be called if the model is in client mode.

The three TTimeIntervalMinutes arguments specify the default display times for the different entry types. 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.

It returns true or false depending on whether or not an active object was scheduled to build the indexes. This value is internal to the model, and should not normally be of interest to developers.

If an active object is scheduled then views are informed that the model is about to enter a blocked state, via the state callback object which was passed to the model's NewL() function. Views are informed when the model has exited the blocked state within the LoadCompleted() function. Views are kept informed of the progress of the operation via the progress callback aProgressCallBack at a frequency indicated by aCallBackFrequency.

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. MAgnProgressCallBack* aProgressCallBack Pointer to a progress callback object. The operation starts an active object (if aOpenSynchronously is EFalse), and this callback provides progress information and information about how the operation terminated. TBool aOpenSynchronously = EFalse ETrue to build the indexes synchronously, EFalse to build them asynchronously. TOpenCallBackFrequency aCallBackFrequency = EOpenCallBackMedium The frequency that the application should be notified of the progress of the operation via aProgressCallBack. It should not normally be necessary to change this from the default value. This value is only relevant if aOpenSynchronously is EFalse.

Return value

TBool ETrue if an active object was scheduled to build the indexes, EFalse if not. EFalse is returned if the model is opened synchronously, or if there were no entries in the model.

TBool OpenL(const TDesC& aFileName, TTimeIntervalMinutes aDefaultEventDisplayTime, TTimeIntervalMinutes aDefaultAnnivDisplayTime, TTimeIntervalMinutes aDefaultDayNoteDisplayTime, MAgnProgressCallBack* aProgressCallBack, TBool aOpenSynchronously = EFalse, TOpenCallBackFrequency aCallBackFrequency = EOpenCallBackMedium);

Description

Opens a named agenda file using the agenda server. The model must be in client mode before this function is called.

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.

It returns true or false depending on whether or not an active object was scheduled to build the indexes.

If an active object is scheduled then views are informed that the model is about to enter a blocked state, via the state callback object which was passed to the model's NewL() function. Views are informed when the model has exited the blocked state within the LoadCompleted() function. Views are kept informed of the progress of the operation via the progress callback aProgressCallBack at a frequency determined by aCallBackFrequency.

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. MAgnProgressCallBack* aProgressCallBack Pointer to a progress callback object. The operation starts an active object (if aOpenSynchronously is EFalse), and this callback provides progress information and information about how the operation terminated. TBool aOpenSynchronously = EFalse ETrue to build the indexes synchronously, EFalse to build them asynchronously. TOpenCallBackFrequency aCallBackFrequency = EOpenCallBackMedium The frequency that the application should be notified of the progress of the operation via aProgressCallBack. It should not normally be necessary to change this from the default value. This value is only relevant if aOpenSynchronously is EFalse.

Return value

TBool ETrue if an active object was scheduled to build the indexes, EFalse if not. EFalse is returned if the model is opened synchronously, or if there were no entries in the model.

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

Description

Opens a named agenda file, using the agenda server. The model must be in client mode before this function is called.

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.

TBool MergeL(CStreamStore& aStoreToMergeFrom, TStreamId aSrcStreamId, MAgnProgressCallBack* aProgressCallBack, TMergeTodoListSettings aMergeSettings = EDontMergeTodoListSettings, TMergeCallBackFrequency aCallBackFrequency = EMergeCallBackHigh);

Description

Merges the to-do lists and entries contained in an agenda model (the source model) into this agenda model (the target model).

After each step in the operation, the percentage completed is reported via the callback aProgressCallBack at a frequency specified in aCallBackFrequency. aProgressCallBack also reports how the operation completed.

If aMergeSettings is EMergeTodoListSettings, if any to-do list is present both in the source model and in the target model, the settings for the list in the target model are overwritten by the settings specified in the source model.

The function uses an active object so always returns ETrue.

If the model has a state callback, the function calls its StateCallBack() function to notify users when the model is about to enter the blocked state, and when it has left the blocked state.

Parameters

CStreamStore& aStoreToMergeFrom A reference to the store object in which the source model's data is stored. TStreamId aSrcStreamId The root stream ID of the store aStoreToMergeFrom. MAgnProgressCallBack* aProgressCallBack A callback object which reports the progress of the merge. TMergeTodoListSettings aMergeSettings = EDontMergeTodoListSettings EMergeTodoListSettings overwrites the settings for to-do lists in the target model with the settings for to-do lists with the same name in the source model.EDontMergeTodoListSettings retains the settings in the target model. TMergeCallBackFrequency aCallBackFrequency = EMergeCallBackHigh Specifies the frequency at which aProgressCallBack should notify the progress of the merge. It should not normally be necessary to change this from the default value.

Return value

TBool ETrue.

TBool TidyByDateL(const TAgnFilter& aFilter, const TTime& aTodaysDate, const TTime& aStartDate, const TTime& aEndDate, MAgnProgressCallBack* aProgressCallBack, TTidyDirective aDirective);
TBool TidyByDateL(const TAgnFilter& aFilter, const TTime& aTodaysDate, const TTime& aStartDate, const TTime& aEndDate, MAgnProgressCallBack* aProgressCallBack, TTidyDirective aDirective, CStreamStore* aStoreToTidyTo);
TBool TidyByDateL(const TAgnFilter& aFilter, const TTime& aTodaysDate, const TTime& aStartDate, const TTime& aEndDate, MAgnProgressCallBack* aProgressCallBack, TTidyDirective aDirective, CStreamStore* aStoreToTidyTo, TStreamId& aStoreStreamId, TTidyByDateCallBackFrequency aCallBackFrequency = ETidyByDateCallBackMedium);

Description

Deletes, copies or moves a subset of the model's entries — overloaded function.

The entries affected are those which occur within the date/time range starting at aStartDate and ending at aEndDate. aTodaysDate identifies which to-do entries fall within the specified range. aFilter identifies which entry types are affected by the operation.

If either of the operations ECopy or ECopyAndDelete is specified in aDirective then the function will either create or open a stream freamwork within the supplied store (aStoreToTidyTo) to which the tidied entries will be copied. If aStoreStreamId is KNullStreamId or is not specified, then a stream freamwork is created in aStoreToTidyTo, and on return, aStoreStreamId is set to the root stream ID of the store. If aStoreStreamId is not KNullStreamId then it is assumed that it is the root ID of an existing model and the function opens and uses that to tidy to. Any previous contents will remain untouched.

The return value is ETrue or EFalse depending on whether or not there were any entries which matched the criteria and were tidied.

After each step in the operation, the percentage completed is reported via the callback aProgressCallBack at a frequency which may be specified in aCallBackFrequency. If aCallBackFrequency is not specified, the callback frequency is the default value of ETidyByDateCallBackMedium. aProgressCallBack also reports how the operation completed.

If the model has a state callback, the function calls its StateCallBack() function to notify users when the model is about to enter the blocked state, and when it has left the blocked state.

Note

If the directive is either ECopy or ECopyAndDelete, then a store to copy to must be specified. If the directive is EDelete, then you can specify NULL and KNullStreamId for the store and stream ID, (or use the six parameter variant of the function).

Parameters

const TAgnFilter& aFilter Identifies which entry types should be included in the operation. const TTime& aTodaysDate Today's date. Identifies which to-do entries should be included in the operation. const TTime& aStartDate The start date for the operation. const TTime& aEndDate The end date for the operation. MAgnProgressCallBack* aProgressCallBack Pointer to a callback object which reports the progress of the operation. TTidyDirective aDirective The type of operation — delete, copy or move. If ECopy or ECopyAndDelete is specified, a store must be specified in aStoreToTidyTo. CStreamStore* aStoreToTidyTo If aDirective is either ECopy or ECopyAndDelete, the stream store of the model to tidy to. Not relevant if the directive is EDelete. TStreamId& aStoreStreamId If specified, the root stream ID of the store to which the entries are copied. Only relevant if aDirective is either ECopy or ECopyAndDelete. If a null value is specified, on return, this is set to the root stream ID of aStoreToTidyTo. TTidyByDateCallBackFrequency aCallBackFrequency = ETidyByDateCallBackMedium If specified, the frequency at which aProgressCallBack should notify the progress of the operation. It should not normally be necessary to change this from the default value.

Return value

TBool ETrue if there were entries to tidy, EFalse if not.

TBool TidyByTodoListL(const CArrayFixFlat<TAgnTodoListId>* aList, MAgnProgressCallBack* aProgressCallBack, TTidyDirective aDirective, TTidyTodoListHow aTidyHow);
TBool TidyByTodoListL(const CArrayFixFlat<TAgnTodoListId>* aList, MAgnProgressCallBack* aProgressCallBack, TTidyDirective aDirective, TTidyTodoListHow aTidyHow, CStreamStore* aStoreToTidyTo);
TBool TidyByTodoListL(const CArrayFixFlat<TAgnTodoListId>* aList, MAgnProgressCallBack* aProgressCallBack, TTidyDirective aDirective, TTidyTodoListHow aTidyHow, CStreamStore* aStoreToTidyTo, TStreamId& aStoreStreamId, TTidyByTodoListCallBackFrequency aCallBackFrequency = ETidyByTodoListCallBackMedium);

Description

Tidy to-do lists

Deletes, copies or moves the entries contained in a list of to-do lists — overloaded function. The operation may affect all the entries in the lists, just crossed out entries, or all entries except the crossed out ones.

After each step in the operation, the percentage completed is reported via the callback aProgressCallBack at a frequency which may be specified in aCallBackFrequency. If aCallBackFrequency is not specified, the callback frequency is the default value of ETidyByTodoListCallBackMedium. aProgressCallBack also reports how the operation completed.

If the model has a state callback, its StateCallBack() function is called to notify users when the model is about to enter the blocked state, and when it has left the blocked state.

If either of the operations ECopy or ECopyAndDelete is specified in aDirective then the function will either create or open a stream freamwork within the supplied store (aStoreToTidyTo) to which the tidied entries will be copied. If aStoreStreamId is KNullStreamId or is not specified, then a stream freamwork is created in aStoreToTidyTo, and on return, aStoreStreamId is set to the root stream ID of the store. If aStoreStreamId is not KNullStreamId then it is assumed that it is the root ID of an existing model and the function opens and uses that to tidy to. Any previous contents will remain unaffected.

Note

If the directive is either ECopy or ECopyAndDelete, then a store to copy to must be specified. If the directive is EDelete, then you can specify NULL and KNullStreamId for the store and stream ID, (or use the four parameter variant of the function).

Parameters

const CArrayFixFlat<TAgnTodoListId>* aList Pointer to a list of to-do list IDs which identify the to-do lists to be tidied. MAgnProgressCallBack* aProgressCallBack Pointer to a callback object which reports the progress of the operation. TTidyDirective aDirective The type of operation — delete, copy or move. If ECopy or ECopyAndDelete is specified, a store must be specified in aStoreToTidyTo. TTidyTodoListHow aTidyHow Specifies which to-do entries are to be tidied. CStreamStore* aStoreToTidyTo If aDirective is either ECopy or ECopyAndDelete, the stream store of the model to tidy to. Not relevant if the directive is EDelete. TStreamId& aStoreStreamId If specified, the root stream ID of the store to which the entries are copied. Only relevant if aDirective is either ECopy or ECopyAndDelete. If a null value is specified, on return, this is set to the root stream ID of aStoreToTidyTo. TTidyByTodoListCallBackFrequency aCallBackFrequency = ETidyByTodoListCallBackMedium If specified, the frequency at which aProgressCallBack should notify the progress of the operation. It should not normally be necessary to change this from the default value.

Return value

TBool Always ETrue.

TInt EntryCount() const;

Description

Gets the number of entries in the model.

Return value

TInt The number of entries in the model.

TInt IndexCount(TInt aIndexNumber) const;

Description

Gets the number of entries in a specified index.

The index number specified must be between zero and six inclusive, otherwise the function raises a panic. The index IDs are defined in agmxtab.h, i.e. KAgnEventIndexNum, KAgnApptNonRpt1DayIndexNum etc.

Parameters

TInt aIndexNumber An index ID, as defined in agmxtab.h.

Return value

TInt The number of entries in the specified index.

TAgnLiteEntry GetLiteEntryL(TAgnEntryId aId) const;

Description

Gets the details for an entry.

Parameters

TAgnEntryId aId The ID of the entry to find.

Return value

TAgnLiteEntry Provides access to most of the entry's details.

Leave codes

Leaves with KErrNotFound if the entry cannot be found.

CAgnSortEntryTable* Indexes() const;

Description

Gets a pointer to the model's indexes.

Return value

CAgnSortEntryTable* Pointer to the model's indexes.

TOpenCallBackFrequency

Description

Callback frequency for OpenL()

EOpenCallBackHigh High callback frequency. EOpenCallBackMedium Medium callback frequency. EOpenCallBackLow Low callback frequency.

TMergeCallBackFrequency

Description

Callback frequency for MergeL()

EMergeCallBackHigh High callback frequency. EMergeCallBackMedium Medium callback frequency. EMergeCallBackLow Low callback frequency.

TTidyByDateCallBackFrequency

Description

Callback frequency for TidyByDateL()

ETidyByDateCallBackHigh High callback frequency. ETidyByDateCallBackMedium Medium callback frequency. ETidyByDateCallBackLow Low callback frequency.

TTidyByTodoListCallBackFrequency

Description

Callback frequency for TidyByTodoListL()

ETidyByTodoListCallBachHigh High callback frequency. ETidyByTodoListCallBackMedium Medium callback frequency. ETidyByTodoListCallBackHow Low callback frequency.

TMergeTodoListSettings

Description

Overwrite to-do list settings during merge.

EMergeTodoListSettings Overwrite the settings for to-do lists in the target model with the settings for to-do lists with the same name in the source model. EDontMergeTodoListSettings Retain the settings for to-do lists in the target model.

TTidyDirective

Description

Type of tidy operation

EDelete Delete entries from the current model when tidying ECopy Copy entries to a file ECopyAndDelete Copy entries to a file and delete from current file

TTidyTodoListHow

Description

Which to-do entries to tidy

EAll Tidy all to-do entries. ECrossedOut Tidy only crossed-out to-do entries. EExceptCrossedOut Tidy all to-do entries except crossed-out ones.