Class RAgendaServ

RAgendaServ

Support

Supported from 5.0

Description

The client interface to the agenda server. The agenda model can be used to access agenda data directly (when operating in normal mode) or indirectly, via the agenda server (when in client mode). A client-server architecture was added to the agenda model in order to allow shared access to an agenda file by more than one client. The existing architecture was maintained alongside the new architecture to allow for compatibility with existing software.

When the model is in client mode, it accesses agenda data by sending an asynchronous request to the server. When in normal mode, it accesses the data directly and exclusively. It is recommended that the model should always be used in client mode.

Most server functions should not be called directly — use the corresponding model function instead. This will route the call to the server, if appropriate.

The functions documented here are part of the client side API to the agenda server. They offer functionality which is not accessible using the model.

Note that a separate instance of the RAgendaServ class is required for each agenda file that is open — only one file can be open at any one time in the same server session.

The API can be used as follows: —

RAgendaServ* agnServer = RAgendaServ::NewL(); // allocate and construct server
CleanupStack::PushL(agnServer);
agnServer->Connect(); // connect to the agenda server
CleanupClosePushL(*agnServer); // guarantees that the server's Close() method gets called
CAgnEntryModel* model = CAgnEntryModel::NewL(); // allocate and construct model
CleanupStack::PushL(model);
model->SetServer(agnServer); // set server pointer for model
model->OpenL(fileName) // Open file using server
// ...Use agenda model API as normal - invokes corresponding server functions
CleanupStack::PopAndDestroy(3); // model, close session with server, agnServer

Derivation

RAgendaServ The client interface to the agenda server RHandleBase Handle to an object RSessionBase Client-side handle to a session with a server

Defined in RAgendaServ:
CloseAgenda(), CloseWriteStreamL(), CompactFile(), Connect(), CreateDateIterator(), CreateEntryIterator(), CreateNewStreamL(), DateIteratorAtEnd(), DateIteratorAtStart(), DateIteratorCurrentElement(), DateIteratorCurrentKey(), DateIteratorGoto(), DateIteratorGotoLessOrEqual(), DateIteratorNext(), DateIteratorPrevious(), DeleteEntry(), DeleteTodoList(), EntryIteratorNext(), EntryIteratorPosition(), EntryIteratorStreamCount(), EntryIteratorStreamCurrent(), FileIsReadOnly(), FileLoaded(), GetEntryId(), GetUniqueId(), GetWriteStreamL(), HasUniqueIdBeenDeleted(), NewL(), StartNotifierL(), TypeByUniqueId(), UniqueIdLastChangedDate(), WaitUntilLoaded(), ~RAgendaServ()

Inherited from RHandleBase:
Close(), Duplicate(), Handle(), SetHandle()

Inherited from RSessionBase:
Attach(), CreateSession(), EAutoAttach, EExplicitAttach, Send(), SendReceive(), SetRetry(), Share(), TAttachMode

static RAgendaServ* NewL();

Description

Constructs a new RAgendaServ, initialising all member data to NULL.

Return value

RAgendaServ* A pointer to the client interface to the agenda server.

~RAgendaServ();

Description

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

TInt Connect();

Description

Connects the client process to the agenda server. A connection must be made before the server can be used.

Return value

TInt An error code. KErrNone if successful.

void CloseAgenda();

Description

Closes the file which is open in the current agenda server session.

TBool CompactFile();

Description

Compacts the agenda file. The server carries out the compaction in the background using a CIdle object.

Return value

TBool Indicates how the compaction completed. ETrue if successful, EFalse if not.

void WaitUntilLoaded();

Description

Waits until the server has finished loading the file. Because the server loads files asynchronously, for large files there is a chance that the indexes are still being built when the client begins fetching entries. This function also causes the model's indexes to be built.

TBool FileLoaded();

Description

Tests whether a file is open in the current agenda server session.

Return value

TBool ETrue if a file is open, EFalse if no file is open.

TBool FileIsReadOnly();

Description

Tests whether the currently open file is read only.

Return value

TBool ETrue if the file is read only, EFalse if it is not.

CAgnEntry::TType TypeByUniqueId(TAgnUniqueId aUniqueId);

Description

Retrieves an entry's type by its unique ID.

Parameters

TAgnUniqueId aUniqueId The entry's unique ID.

Return value

CAgnEntry::TType The entry's type.

TBool HasUniqueIdBeenDeleted(TAgnUniqueId aUniqueId);

Description

Tests whether an entry, identified by its unique ID, has been both synchronised and deleted.

This function is provided for synchronisation. If it returns true, the synchroniser can delete the corresponding entry on the PC.

Parameters

TAgnUniqueId aUniqueId Unique ID which identifies an agenda entry.

Return value

TBool ETrue if the entry has been synchronised and deleted.EFalse if not, or if the entry was not found.

TAgnDateTime UniqueIdLastChangedDate(TAgnUniqueId aUniqueId);

Description

Retrieves the date an entry was last changed. The entry is identified by its unique ID.

Parameters

TAgnUniqueId aUniqueId The entry's unique ID.

Return value

TAgnDateTime The date and time the entry was last changed (or the date of its creation if unchanged). Returns a NULL date value if no entry matchingaUniqueId is found.

TAgnEntryId GetEntryId(TAgnUniqueId aUniqueId);

Support

Supported from 6.0

Description

Retrieves an entry's entry ID, given its unique ID.

Parameters

TAgnUniqueId aUniqueId The entry's unique ID.

Return value

TAgnEntryId The entry ID.

TAgnUniqueId GetUniqueId(TAgnEntryId aEntryId);
TAgnUniqueId GetUniqueId(TAgnTodoListId aTodoId);

Description

Retrieves an entry or to-do list's unique ID, given its entry or to-do list ID.

Parameters

TAgnEntryId aEntryId If specified, the entry ID. TAgnTodoListId aTodoId If specified, the to-do list ID.

Return value

TAgnUniqueId The entry or to-do list's unique ID.

void DeleteEntry(TAgnUniqueId aUid);

Support

Withdrawn in 6.0

Description

Deletes an entry, identified by its unique ID.

Parameters

TAgnUniqueId aUid The unique ID of the entry to delete.

TInt DeleteEntry(TAgnUniqueId aUid);

Support

Supported from 6.0

Description

Deletes an entry, identified by its unique ID.

Parameters

TAgnUniqueId aUid The unique ID of the entry to delete.

Return value

TInt KErrNone if the function completed without error, otherwise one of the system error codes, including KErrNotFound if the unique ID does not exist.

void DeleteTodoList(TAgnUniqueId aUid);

Support

Withdrawn in 6.0

Description

Deletes a to-do list, identified by its unique ID.

Parameters

TAgnUniqueId aUid The unique ID of the to-do list to delete.

TInt DeleteTodoList(TAgnUniqueId aUid);

Support

Supported from 6.0

Description

Deletes a to-do list, identified by its unique ID.

Parameters

TAgnUniqueId aUid The unique ID of the to-do list to delete.

Return value

TInt KErrNone if the function completed without error, otherwise one of the system error codes.

void StartNotifierL(TCallBack aCallback, TInt aFrequency = KNotifierUpdateFrequency);

Description

Starts notification of updates to the agenda server. Once notification has started, the server will notify the client of any changes made by other clients. The server will be polled at the given frequency for updates to the model, and if no value is specified for the parameter, it defaults toKNotifierUpdateFrequency (5 seconds).

Parameters

TCallBack aCallback The callback function which will be called when a change has occurred. TInt aFrequency = KNotifierUpdateFrequency The frequency at which the client will poll the server for updates.

TStreamId CreateNewStreamL(TUid aStreamUid);

Description

Creates a new write stream with the specified stream UID in the agenda file. The stream can be opened for writing usingGetWriteStreamL().

Parameters

TUid aStreamUid The UID of the stream to add to the agenda file. The file uses a dictionary store, so that the new stream is identified by UID rather than by stream ID.

Return value

TStreamId The stream ID which is associated with the UID in the dictionary store.

RWriteStream& GetWriteStreamL(TStreamId aStreamId);

Description

Opens a stream which has been created usingCreateNewStreamL() for writing.

Note

The stream ID aStreamId is returned byCreateNewStreamL(). It can also be obtained from the stream UID by calling the CAgnEntryModel::StreamId()method.

Parameters

TStreamId aStreamId Stream ID of the write stream to retrieve.

Return value

RWriteStream& Reference to the write stream.

void CloseWriteStreamL();

Description

Closes the previously opened write stream and sends the entire stream to the server for saving to file.

TBool CreateEntryIterator();

Description

Creates an iterator for iterating though all the entries in the file. This may be used for activities such as merging or finding. The function returns EFalse if no entries are available. If any entries are available, the iterator is set to the first entry in the model.

Note

When the model is in client mode, this and the following functions should be used for entry iteration. You should not use the TAgnEntryIterclass directly because this does not use the server.

Return value

TBool ETrue if there are entries in the file. EFalseif there are none.

TBool EntryIteratorNext();

Description

Moves the entry iterator to the next entry. Returns EFalseif no more entries exist.

Return value

TBool ETrue if there is are more entries. EFalse if there are no more entries.

TAgnEntryId EntryIteratorPosition();

Description

Retrieves the ID for the entry at the current iterator position. The ID can be used to retrieve the entry usingCAgnEntryModel::FetchEntryL().

Return value

TAgnEntryId The ID for the entry at the current iterator position

TInt EntryIteratorStreamCount();

Description

Retrieves a count of the total number of streams that contain entries, and need to be iterated through.

This value can be used in combination withEntryIteratorStreamCurrent() to calculate the amount of processing remaining, for use in progress indicators.

Return value

TInt A count of the total number of streams that contain entries.

TInt EntryIteratorStreamCurrent();

Description

Retrieves the index of the current stream being processed. The first stream has an index of 1.

This figure can be used in combination with the value returned byEntryIteratorStreamCount() to calculate the amount of processing remaining, for use in progress indicators.

Return value

TInt The index of the current stream being processed

void CreateDateIterator(TTime aToday, TAgnFilter* aFilter, TAgnDate aTidyStartDate);

Description

Creates a date iterator. A date iterator is used to iterate through entries according to their date. The iterator is set to the date specified inaTidyStartDate. The filter aFilter is used to specify which entry types should be included. The value of the aTodayparameter should be set to the current date/time.

Parameters

TTime aToday The current date/time TAgnFilter* aFilter Specifies which entry types should be included TAgnDate aTidyStartDate The start date for the iterator.

void DateIteratorPrevious();

Description

Moves the date iterator to the previous entry. A panic occurs if there are no previous entries.

void DateIteratorNext();

Description

Moves the date iterator to the next entry. A panic occurs if there are no more entries.

TBool DateIteratorAtStart();

Description

Tests whether the date iterator is at the first entry in the list of entries.

Return value

TBool ETrue if the date iterator is at the first entry.EFalse if not.

TBool DateIteratorAtEnd();

Description

Tests whether the date iterator is at the last entry in the list of entries.

Return value

TBool ETrue if the date iterator is at the last entry.EFalse if not.

TAgnDate DateIteratorCurrentKey();

Description

Retrieves the date of the entry at the current iterator position. ATAgnDate is the number of days since the start of the date range for agenda entries (1/1/1980). To convert between a TAgnDate and other time-related classes, for instance TTime, use the static functions provided by class AgnDateTime (defined in the header file agmdate.h).

Return value

TAgnDate The date of the entry at the current iterator position.

CAgnSortEntry* DateIteratorCurrentElement(CAgnSortEntryAllocator* aAllocator);

Description

Retrieves the entry at the current iterator position.

Parameters

CAgnSortEntryAllocator* aAllocator Pointer to the model's sort entry allocator. CallCAgnEntryModel::SortEntryAllocator() to get a pointer to the allocator.

Return value

CAgnSortEntry* The entry at the current iterator position.

void DateIteratorGoto(TAgnDate aDate);

Description

Sets the iterator to the entry at the date specified, or the entry at the closest following date if there is no matching entry at the date specified.

Parameters

TAgnDate aDate The date to which to set the iterator.

void DateIteratorGotoLessOrEqual(TAgnDate aDate);

Description

Sets the iterator to the entry at the date specified, or the entry at the closest previous date if there is no matching entry at the date specified.

Parameters

TAgnDate aDate The date to which to set the iterator.