EPOC   SDK Home Glossary Indexes Previous Next Up

RAgendaServ class


Contents


RAgendaServ class — The Agenda server

Section Contents


Overview

Compatibility

Applications that use this class will not work correctly on a version of EPOC earlier than ER5.

Derivation

RHandleBase

Base handle class

RSessionBase

Abstraction for session base class

RAgendaServ

Manages concurrent access to an Agenda file by more than one client.

Defined in

agclient.h

Link against

agnmodel.lib

Description

In EPOC Release 5, the Agenda model has been converted to use a client-server architecture. The RAgendaServ class is the interface between the Agenda model and the Agenda server.

The Agenda model class, CAgnEntryModel has been re-written in EPOC Release 5 so that if the model is in client mode, calls will be routed to the server if necessary. This means that there are very few functions in the new RAgendaServ class which will need to be called by an application's UI.

The Agenda server may typically be set up as follows: —

    RAgendaServ* agnServer = RAgendaServ::NewL(); // allocate and construct server
    agnServer->Connect(); // connect to the agenda server
    RFs fileServer;
    fileServer.Connect();// connect to the file server
    CAgnEntryModel* model = CAgnEntryModel::NewL(); // allocate and construct model
    model->SetServer(agnServer); // set server pointer for model
    model->OpenL(fileName) // Open file using server
    // ...
    delete model; // clean up
    agnServer->Close(); // close session with server, (Close() is defined in server base class, RHandleBase)
    delete agnServer;

The call to CAgnEntryModel::OpenL() in the code above will cause the corresponding server function to be invoked.

A separate instance of the RAgendaServ class is required for each Agenda file that is opened simultaneously — only one file can be open at any one time in the same server session.


Entry iteration

The Agenda server API defines several public, exported functions which have not been documented. In general, these undocumented functions are not intended for use by developers. Many are provided specifically for use by the Agenda application, or require detailed knowledge about the Agenda file format. Such functions include the date and entry iteration functions. Iteration functionality is available through other classes, for instance CAgnSyncIter.

For example, the following code sets up a CAgnSyncIter and uses it to iterate through all entries:

    CAgnSyncIter* iter = CAgnSyncIter::NewL(agnServer);
    CleanupStack::PushL(iter); // Push onto cleanup stack
    iter->First(); // go to the first entry
    while (iter->Available())
          {
          CAgnEntry* entry = model->FetchEntryL(iter->UniqueId());
          // ... do something with the entry
          iter->Next(); // move to next entry
          }
    CleanupStack::PopAndDestroy(); // iter

Construction and destruction


NewL() — Static constructor

static RAgendaServ* NewL();

Description

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

Return value

RAgendaServ*

A pointer to the agenda server object.


~RAgendaServ() — Destructor

~RAgendaServ();

Description

The destructor frees all resources owned by the server, prior to its destruction. If the application is using an update notifier, this function cancels and deletes it.


Connection


Connect() — Connect to Agenda server

TInt Connect();

Description

Use this function to connect the client process to the Agenda server.

Return value

TInt

An error code: see e32 error codes.


File opening and closing


OpenAgendaL() — Open Agenda file

void OpenAgendaL(TDesC& aFileName);

Description

Use this function to open an Agenda file. If another file is already open in the current session, this function will close it before opening the file specified. This ensures that a model can only access one file at a time.

Arguments

TDesC& aFileName

The name of the Agenda file to open.

Note

The specified file must exist, or a panic will occur.


CloseAgenda() — Close Agenda file

void CloseAgenda();

Description

If a file is open in the current Agenda server session, use this function to close it.


File utilities


FileLoaded() — Get whether file open

TBool FileLoaded();

Description

Use this function to get 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.


FileIsReadOnly() — Get whether file is read only

TBool FileIsReadOnly();

Description

Use this function to get whether the currently open file is read only.

Return value

TBool

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


UID lookup functions


TypeByUniqueId() — Get type from UID

CAgnEntry::TType TypeByUniqueId(TAgnUniqueId aUniqueId);

Description

This function retrieves an entry's type by its UID.

Arguments

TAgnUniqueId aUniqueId

The entry's UID.

Return value

CAgnEntry::TType

The entry's type (EAppt, ETodo, EEvent, or EAnniv).


HasUniqueIdBeenDeleted() — Get whether entry synchronized and deleted

TBool HasUniqueIdBeenDeleted(TAgnUniqueId aUniqueId);

Description

Retrieves whether an entry, identified by its UID, has been both synchronized and deleted.

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

Arguments

TAgnUniqueId aUniqueId

UID which identifies an agenda entry.

Return value

TBool

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


UniqueIdLastChangedDate() — Get entry's last modified date/time

TAgnDateTime UniqueIdLastChangedDate(TAgnUniqueId aUniqueId);

Description

Retrieves the date an entry was last changed, based on its UID.

Arguments

TAgnUniqueId aUniqueId

The entry's UID.

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 matching aUniqueId is found.


GetUniqueId() — Retrieve UID

TAgnUniqueId GetUniqueId(TAgnEntryId aEntryId);

TAgnUniqueId GetUniqueId(TAgnTodoListId aTodoId);

Description

Retrieves the UID, given an entry or to-do list ID.

Arguments

TAgnEntryId aEntryId

If specified, the entry ID.

TAgnTodoListId aTodoId

If specified, the to-do list ID.

Return value

TAgnUniqueId

The entry's UID.


DeleteEntry() — Delete entry

void DeleteEntry(TAgnUniqueId aUid);

Description

Use this function to delete an entry, identifying it by its UID.

Arguments

TAgnUniqueId aUid

The UID of the entry to delete.


DeleteTodoList() — Delete to-do list

void DeleteTodoList(TAgnUniqueId aUid);

Description

Use this function to delete a to-do list, identifying it by its UID.

Arguments

TAgnUniqueId aUid

The UID of the to-do list to delete.


Change notification


StartNotifierL() — Start notification

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

Description

Starts the 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 to KNotifierUpdateFrequency (5 seconds).

Arguments

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.


Loading and index building


WaitUntilLoaded() — Wait until file loaded

void WaitUntilLoaded();

Description

Use this function to wait 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 indexes of the Agenda model's data to be built.


BuildIndex() — Build indexes

void BuildIndex(TInt aIndex);

Description

This function forces the model to build all of its indexes. Indexes are also built by a call to WaitUntilLoaded(). BuildIndex() is provided separately from WaitUntilLoaded() so that an application can carry out some processing between opening the file and building the indexes. This ensures for instance that drawing the initial view does not need to be held up by index building. The parameter to BuildIndex() is not used and can have any value.

Arguments

TInt aIndex

Not used

EPOC       SDK Home Glossary Indexes Previous Next Up