EPOC   SDK Home Glossary Indexes Previous Next Up

CMsvEntry class


Contents


CMsvEntry class — Message Server entry —

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 behavior

Defined in

msvapi.h

Link against

mcld.lib

Description

This class is the central abstraction through which a program accesses and acts upon a particular Message Server entry. The current entry that a CMsvEntry object relates is referred to as its context.

It may be helpful to consider CMsvEntry functions in 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 Sorting children, Get children, Create and delete children, and Copy and move children.

Message client applications, Client-side MTMs, and User Interface MTMs all commonly use CMsvEntry objects. CMsvEntry objects though represent a lower level of access to an entry than that provided by a Client-side MTM or User Interface MTM. In particular, any MTM-specific functionality, such as address lists or subject fields, must be accessed by a message client application through an MTM inteface.

Note that Server-side MTMs do not use this class, but a similar one, CMsvServerEntry.


Construction and destruction


NewL() — Allocate and construct

static CMsvEntry* NewL(CMsvSession& aMsvSession, TMsvId aMsvId, const TMsvSelectionOrdering& aSortType);

Description

Use this function to create a new CMsvEntry for the entry specified by aMsvId.

Note that this function does not create a new entry, but simply a new object to access an existing entry. To create a new entry, use CreateL().

Arguments

CMsvSession& aMsvSession

The client’s Message Server session

TMsvId aMsvId

ID of the entry to access

const TMsvSelectionOrdering& aSortType

The initial sort order of children of the entry, for example, when returned by ChildrenL(). The order can be changed later by SetSortTypeL().

Return value

CMsvEntry*

On return, if the function succeeds, this is a pointer to a newly allocated and initialised object.

Leave considerations
KErrNotFound

The requested entry does not exist

KErrNoMemory

A memory allocation failed


~CMsvEntry() — Destructor

~CMsvEntry();

Description

CMsvEntry objects must be deleted by client applications when they are no longer required. This function cleans up the object. Note that deleting a CMsvEntry object does not delete the context, simply the immediate means of accessing it.


Index entry access


ChangeL() — Set context index entry

CMsvOperation* ChangeL(const TMsvEntry& aEntry, TRequestStatus& aStatus);

Description

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

The returned CMsvOperation object completes when the change is complete.

It is important to note that the state of the context is undefined until the observer of the entry has been informed that the entry has been changed, or the operation is completed with an error. If the function leaves, the context is unchanged.

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

Arguments

const TMsvEntry& aEntry

The new index entry values for the context

TRequestStatus& aStatus

The request status to be completed when the operation has finished

Return value

CMsvOperation*

An operation object controlling the change command

Leave considerations

KErrAccessDenied

The entry is locked by another client

KErrArgument

aEntry is invalid or the ID specified in aEntry is not the same as the context ID

KErrNoMemory

The operation could not be created or passed to the server


Entry() — Get context index entry

const TMsvEntry& Entry() const;

Description

Use this function to get the index entry for the context.

Return value

TMsvEntry&

Current context’s index entry


EntryId() — Get context entry ID

TMsvId EntryId() const;

Description

Use this function to get the ID of the context.

Return value

TMsvId

Current context’s entry ID


OwningService() — Get owning service entry ID

TMsvId OwningService() const;

Description

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

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

Return value

TMsvId

ID of the service entry that the context is under.


SetEntryL() — Set new context

void SetEntryL(TMsvId aMsvId);

Description

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

If the function leaves, the context is unchanged.

Arguments

TMsvId aMsvId

ID of the message entry which is to become the new context

Leave considerations

KErrNotFound

aMsvId could not be found in the index


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. Other clients can be reading the store.

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 the entry is read only

KErrNoMemory

Not enough memory to open the 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

KErrNoMemory

Not enough memory to open store

KErrAccessDenied

Another client is currently writing to the store

KErrNotFound

There is no store associated with this entry


Binary file directory


GetFilePath() — Get binary file directory

TInt GetFilePath(TFileName& aDirectory) 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& aDirectory

On return, contains the binary file directory path

Return value

KErrNone

Success

Usual file server errors

The server was unable to create the directory.


Observer functions


AddObserverL() — Register new event observer

void AddObserverL(MMsvEntryObserver& aObserver);

Description

CMsvEntry objects can call back observer objects that implement the MMsvEntryObserver interface when certain events occur. Use this function to register such an observer for the object. Any number of observers can be registered.

Observers are called primarily when the context changes state or contents. For details, see MMsvEntryObserver::TMsvEntryEvent.

Arguments

MMsvEntryObserver& aObserver

The observer to be registered for events

Leave considerations

KErrNoMemory

Not enough memory to register the observer


RemoveObserver() — Remove event observer

void RemoveObserver(MMsvEntryObserver& aObserver);

Description

Use this function to unregister an observer previously registered with AddObserverL().

Arguments

MMsvEntryObserver& aObserver

A reference to an observer to be unregistered for events


Session


Session() — Get session

CMsvSession& Session();

Description

Use this function to get the Message Server session used by this object. This is the same session passed by the client in NewL().

Return value

CMsvSession&

The session used by the object


Sorting children


SetMtmListL() — Set MTM sort order

void SetMtmListL(const CArrayFix<TUid>& aMtmList);

Description

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

MTM grouping can be switched on or off through setting the appropriate TMsvSelectionOrdering value by SetSortTypeL().

If the function leaves, the sort order is unchanged.

Arguments

const CArrayFix<TUid>& aMtmList

The order of MTMs to use for sorting

Leave considerations

KErrNoMemory

Insufficient memory to resort the entries


SetSortTypeL() — Set sort order

void SetSortTypeL(const TMsvSelectionOrdering& aSortType);

Description

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

If the function leaves, the sort order is unchanged.

Arguments

const TMsvSelectionOrdering& aSortType

Sort order to use

Leave considerations

KErrNoMemory

Insufficient memory to resort the entries


SortType() — Get sort order

const TMsvSelectionOrdering& SortType() const;

Description

Use this function to get the current sort order of children of the entry. The sort order is initially set through NewL().

Return value

TMsvSelectionOrdering&

Current sort order


Get children


operator[]() — Get child by position

const TMsvEntry& operator[](TInt aIndex) const;

Description

The child entries of the context can be considered as a zero-based array, with entries sorted according to the current sort order (see Sorting children). Use this function to get the index entry of the child at the position specified by aIndex.

Arguments

TInt aIndex

Array index

Return value

TMsvEntry&

Index entry for the specified child. Valid for in-range values of aIndex.

Notes

The function panics with E32USER-CBase 21 if aIndex was out of range.


ChildDataL() — Get child by ID

const TMsvEntry& ChildDataL(TMsvId aMsvId) const;

Description

Use this function to get the index entry of context’s child with the specified ID.

Arguments

TMsvId aMsvId

ID of the child

Return value

TMsvEntry&

Index entry for the specified child. Valid for in-range values of aIndex.

Leave considerations

KErrNotFound

No child exists with that ID


ChildEntryL() — Create CMsvEntry for child

CMsvEntry* ChildEntryL(TMsvId aMsvId) const;      

Description

Use this function to get a new CMsvEntry object with its context set to the entry aMsvId. aMsvId must specify a child of the current context.

The CMsvEntry object must be deleted by the client application when it is no longer required.

Arguments

TMsvId aMsvId

ID of a child entry

Return value

CMsvEntry*

CMsvEntry object with its context set to child entry

Leave considerations

KErrNotFound

aMsvId does not specify a child of the context


ChildrenL() — Get all children

CMsvEntrySelection* ChildrenL() const;

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.

The calling function is responsible for the deletion of the returned CMsvEntrySelection.

Return value

CMsvEntrySelection*

A selection containing the ID of all children of the context

Leave considerations

KErrNoMemory

Not enough memory to create the selection


ChildrenWithMtmL() — Get children filtered by MTM type

CMsvEntrySelection* ChildrenWithMtmL(TUid aMtm) const;

Description

Use this function to get a selection containing the IDs of all the context children filtered by MTM type (index entry’s iMtm field equals aMtm).

If the entry has no such children, the selection is empty.

The calling function is responsible for the deletion of the returned CMsvEntrySelection.

Arguments

TUid aMtm

MTM type by which to filter

Return value

CMsvEntrySelection*

A selection containing the ID of all children of the context meeting the criterion

Leave considerations

KErrNoMemory

Not enough memory to create the selection


ChildrenWithServiceL() — Get children filtered by service

CMsvEntrySelection* ChildrenWithServiceL(TMsvId aId) const;

Description

Use this function to get a selection containing the IDs of all the context children filtered by message service (index entry’s iServiceId field equals aId).

If the entry has no such children, the selection is empty.

The calling function is responsible for the deletion of the returned CMsvEntrySelection.

Arguments

TMsvId aId

Service by which to filter

Return value

CMsvEntrySelection*

List of IDs of all children of the context meeting the criterion

Leave considerations

KErrNoMemory

Not enough memory to create the selection


ChildrenWithTypeL() — Get children filtered by type

CMsvEntrySelection* ChildrenWithTypeL(TUid aEntryType) const;

Description

Use this function to get a selection containing the IDs of all the context children filtered by entry type (i.e. is the entry a folder, a message, etc.)

If the entry has no such children, the selection is empty.

The calling function is responsible for the deletion of the returned CMsvEntrySelection.

Arguments

TUid aEntryType

Entry type by which to filter. See Entry type constants.

Return value

CMsvEntrySelection*

A selection containing the ID of all children of the context meeting the criterion

Leave considerations

KErrNoMemory

Not enough memory to create the selection


Count() — Get number of children

TInt Count() const;

Description

Returns the number of children of the context.

Return value

TInt

Count of the child entries for the current context


Create and delete children


CreateL() — Create new child entry

CMsvOperation* CreateL(TMsvEntry& aEntry, TRequestStatus& aStatus);

Description

Use this function to create a new child entry owned by the context.

Note that all session observers are notified when a new entry is created with an EMsvEntriesCreated event (see TMsvSessionEvent). CMsvEntry objects are such session observers themselves. When the object receives such a session notification, it calls all registered entry observers with a TMsvEntryEvent event EMsvNewChildren, passing in the ID of the new child.

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

The returned CMsvOperation object completes when creation is complete.

Arguments

TMsvEntry& aEntry

Index entry value for the new entry

TRequestStatus& aStatus

The request status to be completed when the operation has finished

Return value

CMsvOperation*

The operation object controlling the create command.

Leave considerations

KErrArgument

aEntry is invalid

KErrNoMemory

The operation could not be created or passed to the server


DeleteL() — Delete child entry

CMsvOperation* DeleteL(TMsvId aMsvId, TRequestStatus& aStatus);

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 or any store or file is open, then that child will not be deleted.

The returned CMsvOperation object completes when deletion is complete.

Arguments

TMsvId aMsvId

ID of entry to be deleted

TRequestStatus& aStatus

The request status to be completed when the operation has finished

Return value

CMsvOperation*

The operation object controlling the deletion command

Leave considerations

KErrNotFound

A specified entry was not a child of the context

KErrNoMemory

The operation could not be created or passed to the server


DeleteL() — Delete child entries

CMsvOperation* DeleteL(const CMsvEntrySelection& aSelection, TRequestStatus& aStatus);

Description

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

If a child or any descendant is locked by another client or any store or file is open, then that child will not be deleted.

The returned CMsvOperation object completes when deletion is complete.

Arguments

const CMsvEntrySelection& aSelection

List of ID of the entries to be deleted

TRequestStatus& aStatus

The request status to be completed when the operation has finished

Return value

CMsvOperation*

The operation object controlling the deletion command

Leave considerations

KErrNotFound

A specified entry was not a child of the context

KErrNoMemory

The operation could not be created or passed to the server


Copy and move children


CopyL() — Copy entry

CMsvOperation* CopyL(TMsvId aMsvId, TMsvId aTargetId, TRequestStatus& aStatus);

Description

Use this function to create a copy of a child of the context as a new entry owned by the specified target ID. All descendants will be copied as well.

The returned CMsvOperation object completes when copying is complete.

Arguments

TMsvId aMsvId

The ID of the entry to be copied

TMsvId aTargetId

The ID of the entry to own the copy

TRequestStatus& aStatus

The request status to be completed when the operation has finished

Return value

CMsvOperation*

The operation object controlling the copy command.

Leave considerations

KErrNoMemory

The operation could not be created or passed to the server

KErrNotFound

An entry was not a child of the context


CopyL() — Copy entries

CMsvOperation* CopyL(const CMsvEntrySelection& aSelection, TMsvId aTargetId, TRequestStatus& aStatus);

Description

Use this function to create copies of children of the context as new entries owned by the specified target ID. All descendants will be copied as well.

The returned CMsvOperation object completes when copying is complete.

Arguments

const CMsvEntrySelection& aSelection

List of IDs of the entries to be copied

TMsvId aTargetId

The ID of the entry to own the copies

TRequestStatus& aStatus

The request status to be completed when the operation has finished

Return value

CMsvOperation*

The operation object controlling the copy command.

Leave considerations

KErrNoMemory

The operation could not be created or passed to the server

KErrNotFound

An entry was not a child of the context


MoveL() — Move entry

CMsvOperation* MoveL(TMsvId aMsvId, TMsvId aTargetId, TRequestStatus& aStatus);

Description

Use this function to move a child of the context to become an entry owned by the target entry. All descendants will be moved as well.

The returned CMsvOperation object completes when moving is complete.

Arguments

TMsvId aMsvId

The ID of the entry to be moved

TMsvId aTargetId

The ID of the entry to own the moved entries

TRequestStatus& aStatus

The request status to be completed when the operation has finished

Return value

CMsvOperation*

The operation object controlling the move command.

Leave considerations

KErrNoMemory

The operation could not be created or passed to the server

KErrNotFound

An entry was not a child of the context


MoveL() — Move entries

CMsvOperation* MoveL(const CMsvEntrySelection& aSelection, TMsvId aTargetId, TRequestStatus& aStatus);

Description

Use this function to move children of the context to become entries owned by the target entry. All descendants will be moved as well.

The returned CMsvOperation object completes when moving is complete.

Arguments

const CMsvEntrySelection& aSelection

List of IDs of the entries to be moved

TMsvId aTargetId

The ID of the entry to own the moved entires

TRequestStatus& aStatus

The request status to be completed when the operation has finished

Return value

CMsvOperation*

The operation object controlling the move command.

Leave considerations

KErrNoMemory

The operation could not be created or passed to the server

KErrNotFound

An entry was not a child of the context

EPOC       SDK Home Glossary Indexes Previous Next Up