EPOC   SDK Home Glossary Indexes Previous Next Up

CAgnEntryModel class


Contents


CAgnEntryModel class — Agenda entry model

Section Contents


Overview

Derivation

CBase

Abstract: CBase behaviour

MAgnActiveStep

Specifies the callback interface for communication between the active object and the Agenda model.

Defined in

agmmodel.h

Link against

agnmodel.lib

Description

The API through which a user interface accesses the data stored in an Agenda file. Base class for CAgnIndexedModel and for CAgnModel.

This topic describes the functions which have been added to CAgnEntryModel in EPOC Release 5. For more information about the CAgnEntryModel class, see Model classes.

Note that many of the existing CAgnEntryModel functions have been re-written in EPOC Release 5 so that if the model is in client mode, calls will be routed to the Agenda server, and if the model is not in client mode, the function will work as it did before ER5. This ensures that existing applications will continue to work in the new ER5 architecture, without modification.

All of the following CAgnEntryModel functions apart from SetServer() and CreateL() use the Agenda server, and should only be called after the model has been assigned a server pointer.


Setting up the server


SetServer() — Set the server

void SetServer(RAgendaServ* aServer);

Compatibility

Applications that call this member function will not work correctly on a version of EPOC earlier than ER5.

Description

Sets the server to use for all agenda operations and sets the model's mode of operation to EClient. The server must be connected (using RAgendaServ::Connect()) before use.

Arguments

RAgendaServ* aServer

Pointer to an agenda server.


File creation and opening


CreateL() — Create an Agenda file

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

Compatibility

Applications that call this member function will not work correctly on a version of EPOC earlier than ER5.

Description

Creates a new, empty Agenda file with a valid Agenda stream structure. Also creates an empty default to-do list. 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 will occur.

Note that this functions is provided for testing purposes only — using this function, it may be possible to create files which do not operate correctly in the Agenda application.

Arguments

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 will be created. Can have up to KAgnMaxTodoListNameLength (=50) characters.

const CParaFormatLayer* aParaFormatLayer

The format layer on which the paragraph formatting for entries in the file will be based.

const CCharFormatLayer* aCharFormatLayer

The format layer on which the character formatting for entries in the file will be based.

Note

This function should be used in conjunction with OpenL(), described below. When file opening and closing is carried out using the server, filenames rather than stream stores must be specified.


OpenL() — Open Agenda file

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

Compatibility

Applications that call this member function will not work correctly on a version of EPOC earlier than ER5.

Description

Uses the server to open an Agenda file. If another Agenda file is open in the same server session, it will be closed.

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.

Arguments

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.

Note

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


Stream persistence


StreamId() — Return the streamid associated with unique identifier

TStreamId StreamId(TUid aUid);

Compatibility

Applications that call this member function will not work correctly on a version of EPOC earlier than ER5.

Description

Retrieves the stream ID for the specified unique identifier.

Arguments

TUid aUid

The unique identifier.

Return value

TStreamId

The stream id associated with the unique identifier aUid.


GetReadStreamL() — Retrieve read stream

RReadStream& GetReadStreamL(TStreamId aStreamId);

Compatibility

Applications that call this member function will not work correctly on a version of EPOC earlier than ER5.

Description

This function retrieves a read stream directly from the server. It enables the other stream information e.g. general preferences to be made available to the application.

Arguments

TStreamId aStreamId

The id identifying the read stream.

Return value

RReadStream&

The stream from which the information can be read.


GetEmbeddedStore() — Get store containing embedded objects

CStreamStore* GetEmbeddedStore(TStreamId aId);

Compatibility

Applications that call this member function will not work correctly on a version of EPOC earlier than ER5.

Description

Retrieves an embedded store from a stream, based on stream id.

This function is used to retrieve embedded objects.

Arguments

TStreamId aId

The id identifying the stream store.

Return value

CStreamStore*

The stream store from which the embedded objects can be restored.


SaveTodoListsL() — Save to-do lists to file

TStreamId SaveTodoListsL(TFileName aFileName) const;

Compatibility

Applications that call this member function will not work correctly on a version of EPOC earlier than ER5.

Description

Saves the to-do list settings in the current model to the Agenda file specified. The file specified in aFileName must exist, must be closed and must not be read-only.

Used for example by the Agenda application's Create new file command.

Arguments

TFileName aFileName

The agenda file to which to save the current file's to-do lists

Return value

TStreamId

The ID of the stream to which the to-do lists have been saved.


Model mode


SetMode() — Set the model's mode of operation

void SetMode(TModelMode aMode);

Compatibility

Applications that call this member function will not work correctly on a version of EPOC earlier than ER5.

Description

Sets the mode of operation for the model to server or client.

This function is called by CAgnEntryModel::SetServer() which sets the mode to client, so normally it should only be used in test code.

Arguments

TModelMode aMode

ENormal, EClient or EServer.


IsClient() — Get whether client

TBool IsClient() const;

Compatibility

Applications that call this member function will not work correctly on a version of EPOC earlier than ER5.

Description

Retrieves whether the model is running as a client of the Agenda server.

Return value

TBool

ETrue if the model is a client of the server, EFalse if not.


Instance extraction


GetDayListFromExtractorL() — Get list of entries for day

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

Compatibility

Applications that call this member function will not work correctly on a version of EPOC earlier than ER5.

Description

Retrieves a list of entries for the specified day, using a previously set up instance extractor

Arguments

TAgnInstanceExtractor* aExtractor

The instance extractor.

TAgnDate aDay

The date for which entries will be retrieved.

CArrayFixFlat<TAgnSortInstance>* aDayInfoList

On return, pointer to the filtered list of instances.

TAgnDate aToday

Today's date.

Note

The aToday parameter is used to determine if to-do items should be returned in the list, i.e. if the aToday and aDate parameters have the same value, then any undated to-do items are also returned as part of the list, at the default display time.

This mechanism is used to display to-do items in the Agenda day and week views.


GetSymbolInstanceList() — Get list of entries with symbols

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

Compatibility

Applications that call this member function will not work correctly on a version of EPOC earlier than ER5.

Description

Retrieves a filtered list of entries for the specified date which have entry symbols.

Used by the Agenda application's year view for example.

Arguments

CAgnSymbolList* aList

Pointer to an existing CAgnSymbolList object.

TTime& aToday

The day for which entries will be retrieved.

TAgnFilter& aFilter

Specifies the entry types of interest.

Not changed on return.


Notification


CheckNotifier() — Check for changes to file

TBool CheckNotifier();

Compatibility

Applications that call this member function will not work correctly on a version of EPOC earlier than ER5.

Description

This function tests whether the currently open file has been updated by another client. 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.

Return value

TBool

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


Retrieving entries


FetchEntryL() — Retrieve entry using global ID

CAgnEntry* FetchEntryL(TAgnGlobalId aGlobalId);

Compatibility

Applications that call this member function will not work correctly on a version of EPOC earlier than ER5.

Description

Retrieves an entry based on its global ID.

Arguments

TAgnGlobalId aGlobalId

The global ID of the entry to retrieve.

Return value

CAgnEntry*

Pointer to the entry.

Leave considerations

This function will leave if no entry matching aGlobalId is found.


FetchEntryL() — Retrieve entry using UID

CAgnEntry* FetchEntryL(TAgnUniqueId aUniqueId);

Compatibility

Applications that call this member function will not work correctly on a version of EPOC earlier than ER5.

Description

Retrieves an entry based on its UID.

Arguments

TAgnUniqueId aUniqueId

The UID of the entry to retrieve.

Return value

CAgnEntry*

Pointer to the entry.

Leave considerations

This function will leave if no entry matching aUniqueId is found.

EPOC       SDK Home Glossary Indexes Previous Next Up