Class CMsvEntry

CMsvEntry

Support

Supported from 5.0

Description

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. The second provides a means to discover and access other entries that the entry owns (its 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.

A CMsvEntry object is relatively expensive in RAM usage, as it caches its children, updating them as necessary when notified of changes. They should therefore be created sparingly.

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

In pre-Unicode versions this class had the import library mcld.lib.

Derivation

CBase Base class for all classes to be instantiated on the heap CMsvEntry Accesses and acts upon a particular Message Server entry MMsvSessionObserver Provides the interface for notification of events from a Message Server session MMsvStoreObserver An intermediary class used in the derivation of CMsvServerEntry and CMsvEntry

Defined in CMsvEntry:
AddObserverL(), ChangeL(), ChildDataL(), ChildEntryL(), ChildrenL(), ChildrenWithMtmL(), ChildrenWithServiceL(), ChildrenWithTypeL(), CopyL(), Count(), CreateL(), DeleteL(), EditStoreL(), Entry(), EntryId(), GetFilePath(), HasDirectory(), HasDirectoryL(), HasStore(), HasStoreL(), MoveL(), NewL(), OwningService(), ReadStoreL(), RemoveObserver(), Session(), SetEntryL(), SetMtmListL(), SetSortTypeL(), SortType(), operator[](), ~CMsvEntry()

Inherited from CBase:
operator new()

Inherited from MMsvSessionObserver:
EMsvCloseSession, EMsvCorruptedIndexRebuilding, EMsvCorruptedIndexRebuilt, EMsvGeneralError, EMsvMediaAvailable, EMsvMediaChanged, EMsvMediaIncorrect, EMsvMediaUnavailable, EMsvMtmGroupDeInstalled, EMsvMtmGroupInstalled, EMsvServerFailedToStart, EMsvServerReady, EMsvServerTerminated, EMsvStoreCommitted, EMsvStoreCreated, EMsvStoreDeleted, EmsvEntriesChanged, EmsvEntriesDeleted, EmsvEntriesMoved, EmsvEntryCreated, HandleSessionEvent(), HandleSessionEventL(), TMsvSessionEvent

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

Description

Creates a new CMsvEntry for the specified entry ID.

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().

Parameters

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 codes

KErrNotFound The requested entry does not exist KErrNoMemory A memory allocation failed

~CMsvEntry();

Description

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

void ChangeL(const TMsvEntry& aEntry);

Description

Sets the context’s index entry to the specified values. The function is performed synchronously.

This function can only be used on local entries.

Parameters

const TMsvEntry& aEntry The new index entry values for the context

Leave codes

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

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

Description

Sets the context’s index entry to the specified values. 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.

Parameters

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 codes

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

const TMsvEntry& Entry() const;

Description

Gets the index entry for the context.

Return value

TMsvEntry& Current context’s index entry

TMsvId EntryId() const;

Description

Gets the ID of the context.

Return value

TMsvId Current context’s entry ID

TMsvId OwningService() const;

Description

Gets the ID of the service entry that owns the context.

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

Return value

TMsvId ID of the service entry that the context is under.

void SetEntryL(TMsvId aMsvId);

Description

Sets the context to the specified entry.

If the function leaves, the context is unchanged.

Parameters

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

Leave codes

KErrNotFound aMsvId could not be found in the index

CMsvStore* EditStoreL();

Description

Gets 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 codes

KErrAccessDenied Store is locked by another process or the entry is read only KErrNoMemory Not enough memory to open the store

TBool HasStore() const;

Support

Supported from 5.1
Withdrawn in 6.0

Description

Checks if the context has an associated message store.

In pre-Unicode versions a message store flag was available, and could be accessed through TMsvEntry::Store(). This function replaces that functionality.

Return value

TBool ETrue: entry has a message store EFalse: entry does not have a message store

TBool HasStoreL() const;

Support

Supported from 6.0

Description

Checks if the context has an associated message store.

Return value

TBool ETrue: entry has a message store EFalse: entry does not have a message store

CMsvStore* ReadStoreL();

Description

Obtains 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 codes

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

TInt GetFilePath(TFileName& aDirectory) const;

Description

Gets the context’s binary file directory.

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

Parameters

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.

TBool HasDirectory() const;

Support

Supported from 5.1
Withdrawn in 6.0

Description

Checks if the context has an associated binary files directory.

In pre-Unicode versions a Folder index flag was available, and could be accessed through TMsvEntry::Folder(). This function replaces that functionality.

Return value

TBool ETrue: entry has a binary files directory EFalse: entry does not have a binary files directory

TBool HasDirectoryL() const;

Support

Supported from 6.0

Description

Checks if the context has an associated binary files directory.

Return value

TBool ETrue: entry has a binary files directory EFalse: entry does not have a binary files directory

void AddObserverL(MMsvEntryObserver& aObserver);

Description

Registers an observer for the object. CMsvEntry objects can call back observer objects that implement the MMsvEntryObserver interface when certain events occur. Any number of observers can be registered.

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

Parameters

MMsvEntryObserver& aObserver The observer to be registered for events

Leave codes

KErrNoMemory Not enough memory to register the observer

void RemoveObserver(MMsvEntryObserver& aObserver);

Description

Unregisters an observer previously registered with AddObserverL().

Parameters

MMsvEntryObserver& aObserver A reference to an observer to be unregistered for events

CMsvSession& Session();

Description

Gets 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

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

Description

Sets the MTM order to the specified sort order. When children of an entry are sorted, entries belonging to the same MTM type can be grouped together.

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.

Parameters

const CArrayFix<TUid>& aMtmList The order of MTMs to use for sorting

Leave codes

KErrNoMemory Insufficient memory to resort the entries

void SetSortTypeL(const TMsvSelectionOrdering& aSortType);

Description

Sets the sort order that is used when listing children, for example with ChildrenL().

If the function leaves, the sort order is unchanged.

Parameters

const TMsvSelectionOrdering& aSortType Sort order to use

Leave codes

KErrNoMemory Insufficient memory to resort the entries

const TMsvSelectionOrdering& SortType() const;

Description

Gets the current sort order of children of the entry. The sort order is initially set through NewL().

Return value

TMsvSelectionOrdering& Current sort order

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

Description

Gets the index entry of the child at the position specified by the array index. The child entries of the context can be considered as a zero-based array, with entries sorted according to the current sort order.

Note:

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

Parameters

TInt aIndex Array index

Return value

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

const TMsvEntry& ChildDataL(TMsvId aMsvId) const;

Description

Gets the index entry of context’s child with the specified ID.

Parameters

TMsvId aMsvId ID of the child

Return value

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

Leave codes

KErrNotFound No child exists with that ID

CMsvEntry* ChildEntryL(TMsvId aMsvId) const;    

Description

Gets a new CMsvEntry object with its context set to the child entry ID. 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.

Parameters

TMsvId aMsvId ID of a child entry

Return value

CMsvEntry* CMsvEntry object with its context set to child entry

Leave codes

KErrNotFound aMsvId does not specify a child of the context

CMsvEntrySelection* ChildrenL() const;

Description

Gets 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 codes

KErrNoMemory Not enough memory to create the selection

CMsvEntrySelection* ChildrenWithMtmL(TUid aMtm) const;

Description

Gets a selection containing the IDs of all the context children filtered by MTM type. i.e. the 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.

Parameters

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 codes

KErrNoMemory Not enough memory to create the selection

CMsvEntrySelection* ChildrenWithServiceL(TMsvId aId) const;

Description

Gets a selection containing the IDs of all the context children filtered by message service. ie. the 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.

Parameters

TMsvId aId Service by which to filter

Return value

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

Leave codes

KErrNoMemory Not enough memory to create the selection

CMsvEntrySelection* ChildrenWithTypeL(TUid aEntryType) const;

Description

Gets 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.

Parameters

TUid aEntryType Entry type by which to filter.

Return value

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

Leave codes

KErrNoMemory Not enough memory to create the selection

See also:

• Messaging entry type constants

TInt Count() const;

Description

Gets the number of children of the context.

Return value

TInt Count of the child entries for the current context

void CreateL(TMsvEntry& aEntry);

Description

Creates a new child entry owned by the context synchronously.

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.

This function can only be used on local entries.

Parameters

TMsvEntry& aEntry Index entry value for the new entry

Leave codes

KErrArgument aEntry is invalid

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

Description

Creates a new child entry owned by the context synchronously.

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.

The returned CMsvOperation object completes when creation is complete.

Parameters

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 codes

KErrArgument aEntry is invalid

void DeleteL(TMsvId aMsvId);

Description

Deletes a child entry of the context synchronously.

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. Any files and stores associated with the entry are deleted.

This function can only be used on local entries.

Parameters

TMsvId aMsvId ID of entry to be deleted

Leave codes

KErrNotFound The specified entry was not a child of the context

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

Description

Deletes a child entry of the context asynchronously.

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. Any files and stores associated with the entry are deleted.

The returned CMsvOperation object completes when deletion is complete.

Parameters

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 codes

KErrNotFound The specified entry was not a child of the context

CMsvOperation* DeleteL(const CMsvEntrySelection& aSelection);

Description

Deletes 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. Any files and stores associated with the entries are deleted.

Parameters

const CMsvEntrySelection& aSelection List of ID of the entries to be deleted

Leave codes

KErrNotFound A specified entry was not a child of the context

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

Description

Deletes 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. Any files and stores associated with the entries are deleted.

The returned CMsvOperation object completes when deletion is complete.

Parameters

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 codes

KErrNotFound A specified entry was not a child of the context

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

Description

Creates 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. Any files and stores associated with the entry are also copied.

The returned CMsvOperation object completes when copying is complete.

Parameters

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 codes

KErrNoMemory The operation could not be created or passed to the server KErrNotFound An entry was not a child of the context

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

Description

Creates copies of children of the context as new entries owned by the specified target ID.

All descendants will be copied as well. Any files and stores associated with the entries are also copied.

The returned CMsvOperation object completes when copying is complete.

Parameters

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 codes

KErrNoMemory The operation could not be created or passed to the server KErrNotFound An entry was not a child of the context

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

Description

Moves a child of the context to become an entry owned by the target entry.

All descendants will be moved as well. Any files and stores associated with the entry are also moved.

The returned CMsvOperation object completes when moving is complete.

Parameters

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 codes

KErrNoMemory The operation could not be created or passed to the server KErrNotFound An entry was not a child of the context

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

Description

Moves children of the context to become entries owned by the target entry.

All descendants will be moved as well. Any files and stores associated with the entries are also moved.

The returned CMsvOperation object completes when moving is complete.

Parameters

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 codes

KErrNoMemory The operation could not be created or passed to the server KErrNotFound An entry was not a child of the context