![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
Section Contents
Applications that use this class will not work correctly on a version of EPOC earlier than ER5.
CBase |
Abstract: CBase behavior |
msvapi.h
mcld.lib
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 entrysee 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.
static CMsvEntry* NewL(CMsvSession& aMsvSession, TMsvId aMsvId, const TMsvSelectionOrdering& aSortType);
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().
CMsvSession& aMsvSession |
The clients 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(). |
CMsvEntry* |
On return, if the function succeeds, this is a pointer to a newly allocated and initialised object. |
KErrNotFound |
The requested entry does not exist |
KErrNoMemory |
A memory allocation failed |
~CMsvEntry();
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.
CMsvOperation* ChangeL(const TMsvEntry& aEntry, TRequestStatus& aStatus);
Use this function to set the contexts 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.
const TMsvEntry& aEntry |
The new index entry values for the context |
TRequestStatus& aStatus |
The request status to be completed when the operation has finished |
CMsvOperation* |
An operation object controlling the change command |
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;
Use this function to get the index entry for the context.
TMsvEntry& |
Current contexts index entry |
TMsvId EntryId() const;
Use this function to get the ID of the context.
TMsvId |
Current contexts entry ID |
TMsvId OwningService() const;
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.
TMsvId |
ID of the service entry that the context is under. |
void SetEntryL(TMsvId aMsvId);
Use this function to set the context to the entry specified by aMsvId.
If the function leaves, the context is unchanged.
TMsvId aMsvId |
ID of the message entry which is to become the new context |
KErrNotFound |
aMsvId could not be found in the index |
CMsvStore* EditStoreL();
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.
CMsvStore* |
Contexts message store open for read-write access |
KErrAccessDenied |
Store is locked by another process or the entry is read only |
KErrNoMemory |
Not enough memory to open the store |
CMsvStore* ReadStoreL();
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.
CMsvStore* |
Contexts message store open for read-only access |
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;
Use this function to get the contexts binary file directory.
If the directory specified in the context does not exist, it is created.
TFileName& aDirectory |
On return, contains the binary file directory path |
KErrNone |
Success |
Usual file server errors |
The server was unable to create the directory. |
void AddObserverL(MMsvEntryObserver& aObserver);
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.
MMsvEntryObserver& aObserver |
The observer to be registered for events |
KErrNoMemory |
Not enough memory to register the observer |
void RemoveObserver(MMsvEntryObserver& aObserver);
Use this function to unregister an observer previously registered with AddObserverL().
MMsvEntryObserver& aObserver |
A reference to an observer to be unregistered for events |
CMsvSession& Session();
Use this function to get the Message Server session used by this object. This is the same session passed by the client in NewL().
CMsvSession& |
The session used by the object |
void SetMtmListL(const CArrayFix<TUid>& aMtmList);
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.
const CArrayFix<TUid>& aMtmList |
The order of MTMs to use for sorting |
KErrNoMemory |
Insufficient memory to resort the entries |
void SetSortTypeL(const TMsvSelectionOrdering& aSortType);
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.
const TMsvSelectionOrdering& aSortType |
Sort order to use |
KErrNoMemory |
Insufficient memory to resort the entries |
const TMsvSelectionOrdering& SortType() const;
Use this function to get the current sort order of children of the entry. The sort order is initially set through NewL().
TMsvSelectionOrdering& |
Current sort order |
const TMsvEntry& operator[](TInt aIndex) const;
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.
TInt aIndex |
Array index |
TMsvEntry& |
Index entry for the specified child. Valid for in-range values of aIndex. |
The function panics with E32USER-CBase 21 if aIndex was out of range.
const TMsvEntry& ChildDataL(TMsvId aMsvId) const;
Use this function to get the index entry of contexts child with the specified ID.
TMsvId aMsvId |
ID of the child |
TMsvEntry& |
Index entry for the specified child. Valid for in-range values of aIndex. |
KErrNotFound |
No child exists with that ID |
CMsvEntry* ChildEntryL(TMsvId aMsvId) const;
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.
TMsvId aMsvId |
ID of a child entry |
CMsvEntry* |
CMsvEntry object with its context set to child entry |
KErrNotFound |
aMsvId does not specify a child of the context |
CMsvEntrySelection* ChildrenL() const;
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.
CMsvEntrySelection* |
A selection containing the ID of all children of the context |
KErrNoMemory |
Not enough memory to create the selection |
CMsvEntrySelection* ChildrenWithMtmL(TUid aMtm) const;
Use this function to get a selection containing the IDs of all the context children filtered by MTM type (index entrys 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.
TUid aMtm |
MTM type by which to filter |
CMsvEntrySelection* |
A selection containing the ID of all children of the context meeting the criterion |
KErrNoMemory |
Not enough memory to create the selection |
CMsvEntrySelection* ChildrenWithServiceL(TMsvId aId) const;
Use this function to get a selection containing the IDs of all the context children filtered by message service (index entrys 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.
TMsvId aId |
Service by which to filter |
CMsvEntrySelection* |
List of IDs of all children of the context meeting the criterion |
KErrNoMemory |
Not enough memory to create the selection |
CMsvEntrySelection* ChildrenWithTypeL(TUid aEntryType) const;
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.
TUid aEntryType |
Entry type by which to filter. See Entry type constants. |
CMsvEntrySelection* |
A selection containing the ID of all children of the context meeting the criterion |
KErrNoMemory |
Not enough memory to create the selection |
TInt Count() const;
Returns the number of children of the context.
TInt |
Count of the child entries for the current context |
CMsvOperation* CreateL(TMsvEntry& aEntry, TRequestStatus& aStatus);
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.
TMsvEntry& aEntry |
Index entry value for the new entry |
TRequestStatus& aStatus |
The request status to be completed when the operation has finished |
CMsvOperation* |
The operation object controlling the create command. |
KErrArgument |
aEntry is invalid |
KErrNoMemory |
The operation could not be created or passed to the server |
CMsvOperation* DeleteL(TMsvId aMsvId, TRequestStatus& aStatus);
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.
TMsvId aMsvId |
ID of entry to be deleted |
TRequestStatus& aStatus |
The request status to be completed when the operation has finished |
CMsvOperation* |
The operation object controlling the deletion command |
KErrNotFound |
A specified entry was not a child of the context |
KErrNoMemory |
The operation could not be created or passed to the server |
CMsvOperation* DeleteL(const CMsvEntrySelection& aSelection, TRequestStatus& aStatus);
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.
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 |
CMsvOperation* |
The operation object controlling the deletion command |
KErrNotFound |
A specified entry was not a child of the context |
KErrNoMemory |
The operation could not be created or passed to the server |
CMsvOperation* CopyL(TMsvId aMsvId, TMsvId aTargetId, TRequestStatus& aStatus);
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.
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 |
CMsvOperation* |
The operation object controlling the copy command. |
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);
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.
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 |
CMsvOperation* |
The operation object controlling the copy command. |
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);
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.
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 |
CMsvOperation* |
The operation object controlling the move command. |
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);
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.
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 |
CMsvOperation* |
The operation object controlling the move command. |
KErrNoMemory |
The operation could not be created or passed to the server |
KErrNotFound |
An entry was not a child of the context |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |