EPOC   SDK Home Glossary Indexes Previous Next Up

CMsvServerEntry class


Contents


CMsvServerEntry class — Entry access for Server-side MTMs —

Section Contents


Overview

Compatibility

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

Derivation

CBase

Abstract: CBase behaviour

MMsvStoreObserver

Abstract class providing the interface for notification of events from a message store.

Defined in

msventry.h

Link against

msvd.lib

Description

This class is the central abstraction through which a Server-side MTM accesses and acts upon a particular Message Server entry. It provides similar functionality to that which CMsvEntry gives to client-side programs. The current entry that a CMsvServerEntry object relates is similarly referred to as its context.

A difference to note is that CMsvEntry functions, when used on a remote context, can result in requests to Server-side MTMs to change data on a remote server, as well as the local Message Server index. Naturally, as CMsvServerEntry is designed to be used by Server-side MTMs themselves, its comparable functions only alter the Message Server index.

A CBaseServerMTM-derived object gets an initial CMsvServerEntry on construction. It can get further CMsvServerEntry objects by calling NewEntryL(). The context can be changed by SetEntry().

The context is locked, preventing it being accessed by other MTMs. The lock is released when the object is deleted, or the context changes.

As with CMsvEntry, CBaseServerMTM functions can be divided into two broad groups. The first provides means to access the various types of storage associated with an entry—see Message store access, Binary file directory, and Index entry access. The second provides a means to discover and access other entries that the entry owns (its children)—see Children sorting, Access children, Create and delete children, and Move children.


Destructor


~CMsvServerEntry() — Destructor

~CMsvServerEntry();

Description

The destructor:


Get new CMsvServerEntry


NewEntryL() — Get new CMsvServerEntry

CMsvServerEntry* NewEntryL(TMsvId aId);

Description

Use this function to get a new CMsvServerEntry object for the entry specified by aMsvId.

The call locks the entry, preventing it being accessed by other clients.

The object must be deleted when it is no longer required. The lock is released when the object is deleted or the context is changed with SetEntry().

Arguments

TMsvId aId

ID of the entry to access

Return value

CMsvServerEntry*

If the function succeeds, this is a pointer to a newly allocated and initialised object.

Leave considerations

KErrLocked

Entry is locked

KErrNoMemory

A memory allocation failed

KErrNotFound

The entry does not exist


Index entry access


ChangeEntry() — Set context index entry

TInt ChangeEntry(const TMsvEntry& aEntry);

Description

Use this function to set the context’s index entry to the values specified by aEntry.

For the minimum requirements to form a valid entry, see Validity.

Arguments

const TMsvEntry& aEntry

The new details for the entry

Return value

KErrNone

Success

KErrAccessDenied

The entry is read only (deleted entry, standard folder, or locked)

KErrNotSupported

aEntry is invalid or the ID specified in aEntry is not the same as the context ID or no context has been set for the object

KErrNoMemory

A memory allocation failed


Entry() — Get context index entry

const TMsvEntry& Entry() const;

Description

Use this function to get the context’s index entry.

Return value

TMsvEntry&

The current entry


OwningService() — Get owning service entry ID

TMsvId OwningService() const;

Description

Use this function to get the ID of the service that owns the context.

Local entries are considered as being members of the local service: see Structure.

If the entry is the root, then the root ID (KMsvRootIndexEntryId) is returned.

Return value

TMsvId

ID of the service that owns this entry


SetEntry() — Set new context

TInt SetEntry(TMsvId aId);

Description

Use this function to change the context to the entry specified by aMsvId.

The call locks the entry, preventing it from being accessed by other clients. The lock is released when the object is deleted or the context is changed.

Note that you can change the context to KMsvNullIndexEntryId to unlock an entry without locking another.

Arguments

TMsvId aId

ID of the entry to access

Return value

KErrNone

Success

KErrNotFound

The entry does not exist

KErrLocked

The entry is locked


Message store access


EditStoreL() — Get read-write message store

CMsvStore* EditStoreL();

Description

Use this function to obtain the message store for the current context with read-write access.

Only one client can edit a message store at one time. If another client is already writing to the store, KErrAccessDenied is returned. However, any number of clients can read from the store simultaneously.

If the message store does not exist when EditStore() is called, a new message store is created.

The returned CMsvStore must be deleted when it is no longer required.

Return value

CMsvStore*

Context’s message store open for read-write access

Leave considerations

KErrAccessDenied

Store is locked by another process or is read-only

KErrNoMemory

Not enough memory to open store


ReadStoreL() — Get read-only message store

CMsvStore* ReadStoreL();

Description

Use this function to obtain the message store for the current context with read-only access. Multiple clients can read from a store simultaneously. If another client is already writing to the store, the function leaves with KErrAccessDenied.

The returned CMsvStore must be deleted when it is no longer required.

Return value

CMsvStore*

Context’s message store open for read-only access

Leave considerations

KErrAccessDenied

Store is locked by another process

KErrNoMemory

Not enough memory to open store

KErrNotFound

There is no store associated with this entry


Binary file directory


GetFilePath() — Get binary file directory

TInt GetFilePath(TFileName& aFilePath) const;

Description

Use this function to get the context’s binary file directory.

If the directory specified in the context does not exist, it is created.

Arguments

TFileName& aFilePath

On return, contains the binary file directory path

Return value

KErrNone

Success

Usual file server errors

The server was unable to create the directory.


Children sorting


SetMtm() — Set MTM to sort by

void SetMtm(TUid aMtm);

Description

When children of an entry are sorted, entries belonging to the same MTM type can be grouped together. Use this function to set this MTM sorting type to aMtm.

Arguments

TUid aMtm

UID of MTM for sort


SetSort() — Set sort order

void SetSort(TMsvSelectionOrdering& aOrdering);

Description

Use this function to set the sort order that is used when listing children, for example with GetChildren().

Arguments

TMsvSelectionOrdering& aOrdering

Sort order to use


Sort() — Get sort order

const TMsvSelectionOrdering& Sort();

Description

Use this function to get the current sort order of children of the entry.

Return value

TMsvSelectionOrdering&

Current sort type


Access children


GetChildren() — Get children

TInt GetChildren(CMsvEntrySelection& aSelection);

Description

Use this function to get a selection containing the IDs of all the context children. If the entry has no children, the selection is empty.

Arguments

CMsvEntrySelection& aSelection

Initially, this must be an empty selection. On return, it lists the children.

Return value

KErrNone

Success

KErrNoMemory

A memory allocation failed


Create and delete children


CreateEntry() — Create new child entry

TInt CreateEntry(TMsvEntry& aEntry);

Description

Use this function to create a new entry as a child of the current context.

The parent ID and entry ID are set by the Message Server.

For the minimum requirements to form a valid entry, see Validity.

Arguments

TMsvEntry& aEntry

Index entry value for the new entry

Return value

KErrNone

Success

KErrNoMemory

A memory allocation failed

KErrNotSupported

aEntry is invalid


DeleteEntry() — Delete child entry

TInt DeleteEntry(TMsvId aId);

Description

Use this function to delete a child entry of the context. The delete works recursively through all the descendants.

If a child or any descendant is locked by another client, then no entries are deleted.

Arguments

TMsvId aId

The ID of the entry to delete

Return value

KErrNone

Success

KErrAccessDenied

The entry or a descendant was locked by another client

KErrInUse

The store or a file associated with the entry is open

KErrNotFound

Entry is not a child of the context


DeleteEntry() — Delete child entry and return list of deleted entries

TInt DeleteEntry(TMsvId aId, CMsvEntrySelection& aDeletedEntries);

Description

Use this function to delete a child entry of the context. The delete works recursively through all the descendants.

If a child or any descendant is locked by another client, then no entries are deleted.

CMsvEntrySelection& returns the IDs of all the entries deleted.

Arguments

TMsvId aId

The ID of the entry to delete

CMsvEntrySelection& aDeletedEntries

Initially, this must be an empty selection. On return, it lists the IDs of all the entries deleted.

Return value

KErrNone

Success

KErrAccessDenied

The entry or a descendant was locked by another client

KErrInUse

The store or a file associated with the entry is open

KErrNotFound

Entry is not a child of the context


Move children


MoveEntry() — Move entry within service

TInt MoveEntry(TMsvId aId, TMsvId aDestination);

Description

Use this function to move a child of the context to under another entry. All descendants will be moved as well. The destination must belong to the same service as the context.

If an error occurs, no changes are made.

Arguments

TMsvId aId

The ID of the entry to move

TMsvId aDestination

The ID of new parent

Return value

KErrNone

Success

KErrArgument

The destination is a child of aId

KErrInUse

The store or a file associated with the entry is open

KErrNotFound

aId is not a child of the context

KErrPathNotFound

The destination does not exist


MoveEntryL() — Move entry to another service

void MoveEntryL(TMsvId aId, TMsvId aDestination, TRequestStatus& aObserverStatus);

Description

Use this function to move a child of the context to another entry that belongs to a different service. All descendants will be moved as well.

The move is carried out asynchronously. The caller should supply in aObserverStatus the status word of an active object that it owns. The function will signal this to be completed when the move is complete.

If the function leaves, no changes are made.

Arguments

TMsvId aId

The ID of the entry to move

TMsvId aDestination

The ID of new parent

TRequestStatus& aObserverStatus

The request status to be completed when the operation has finished

Leave considerations

KErrArgument

The destination is a child of aId

KErrInUse

The store or a file associated with the entry is open

KErrNoMemory

A memory allocation failed

KErrNotFound

aId is not a child of the context

KErrPathNotFound

The destination does not exist


MoveEntryCompleted() — Complete asynchronous move

void MoveEntryCompleted(TInt aError);

Description

When an asynchronous MoveEntryL() function completes, it informs the client of this by signalling an active object that the client has supplied for the purpose. Clients must call MoveEntryCompleted() after this occurs. This ensures that all session observers are notified of the change.

Arguments

TInt aError

Status code received when active object completed


CancelMoveEntry() — Cancel asynchronous move

void CancelMoveEntry();

Description

Use this function to cancel an asynchronous move that has been begun with MoveEntryL().

EPOC       SDK Home Glossary Indexes Previous Next Up