![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
Section Contents
Applications that use this class will not work correctly on a version of EPOC earlier than ER5.
CBase |
Abstract: CBase behaviour |
CActive |
Abstract: active object abstraction |
msvapi.h
mcld.lib
This class represents a channel of communication between a client thread (Client-side MTM, User Interface MTM, or message client application) and the Message Server thread. A single instance of this class exists for each such client thread. The class provides the means by which clients are notified when important Message Server events occur.
The class also contains utility functions for handling cleanup of entries in leave conditions: see Cleanup.
A message client application must use one of these functions to create a session object, before it can instantiate any MTM or CMsvEntry object.
Only a single session should be created within a thread. As Client-side MTM, User Interface MTM, and CMsvEntry objects are created in the client thread, these use the client session, and do not create their own.
Note that to close a session, delete all objects relying on that session, and then the session object itself.
static CMsvSession* OpenSyncL(MMsvSessionObserver& aObserver);
Use this function to create a session synchronously. The session can be used once the function returns.
MMsvSessionObserver& aObserver |
A reference to a session observer, through which the program can be notified of important events regarding entries, MTMs, and the Message Server. |
CMsvSession* |
New session object |
KErrNoMemory |
Not enough memory to create object. |
static CMsvSession* OpenAsyncL(MMsvSessionObserver& aObserver);
Use this function to create a session asynchronously. The session cannot be used until the passed MMsvSessionObserver observer has been informed that the message server is ready with TMsvSessionEvent::EMsvServerReady. If any functions are called before this, they will fail with KErrNotReady.
MMsvSessionObserver& aObserver |
A reference to a session observer, through which the program can be notified of important events regarding entries, MTMs, and the Message Server. |
CMsvSession* |
New session object |
KErrNoMemory |
Not enough memory to create object. |
void AddObserverL(MMsvSessionObserver& aObserver);
CMsvSession objects can call back observer objects that implement the MMsvSessionObserver::HandleSessionEvent() when certain events occur. Use this function to register such an observer for the object. Any number of observers can be registered.
For details of when observers are called, see TMsvSessionEvent::TMsvEntryEvent.
MMsvSessionObserver& aObserver |
A reference to an observer to be registered for events |
KErrNoMemory |
Not enough memory to register the observer |
void RemoveObserver(MMsvSessionObserver& aObserver);
Use this function to unregister a previously registered observer.
MMsvSessionObserver& aObserver |
A reference to an observer to be unregistered for events |
CMsvEntry* GetEntryL(TMsvId aId);
Use this function to access the entry specified by aId.
If a client is unaware of the entries that exist, it can set aId to KMsvRootIndexEntryId to obtain the root entry, from where all other entries can be obtained.
The CMsvEntry object must be deleted by the client when it is no longer required.
TMsvId aId |
The ID of the entry to access |
CMsvEntry* |
A new entry object |
KErrNotFound |
The requested entry does not exist |
void RemoveEntry(TMsvId aId);
Use this function to delete the specified entry from the Message Server.
The call is guaranteed not to fail. If the entry cannot be deleted immediately, it will be deleted later. This call should only be used in preference to the normal deleting mechanism when no error reporting is required, typically in a destructor.
TMsvId aId |
The ID of the entry to remove |
CMsvSession provides the ability to handle the cleanup of entries in the event of a leave occurring, in a very similar manner to the standard EPOC cleanup stack (see Cleanup support). The difference is that, on a leave, any entries that are on the entry cleanup stack are removed from the Message Server.
The implementation uses the standard cleanup stack, so entry push and pop functions should be used in the same order as all other types of push and pop.
The functions can be used both by MTM implementations and message client applications.
void CleanupEntryPushL(TMsvId aId);
Use this function to push the entry specified by aId to the entry cleanup stack.
TMsvId aId |
The ID of the entry to push onto the entry cleanup stack |
ErrNoMemory |
The entry will have been pushed onto the entry cleanup stack before the leave occurs |
void CleanupEntryPop(TInt aCount=1);
Use this function to pop one or more entries from the entry cleanup stack.
TInt aCount |
The number of entries to pop off the entry cleanup stack |
TBool ServiceActive(TMsvId aServiceId);
Use this function to determine whether a Server-side MTM for a particular service is loaded by the Message Server. The Server-side MTM does not have to be executing a command it may be waiting for another command.
For details of MTM loading and unloading by the Message Server, see Server-side MTMs.
TMsvId aServiceId |
The ID of the relevant service |
TBool |
ETrue if the Server-side MTM for the service is loaded, otherwise EFalse |
TInt ServiceProgress(TMsvId aServiceId, TDes8& aProgress);
Use this function to get the current progress information from the Server-side MTM for the specified service. It is typically used by User Interface MTMs. The format of the progress information returned in the aProgress buffer is MTM-specific.
Calling this function results in the Message Server calling CBaseServerMtm::Progress() on the relevant Server-side MTM.
Note that the progress information is independent of which message client application started the current operation.
TMsvId aServiceId |
The ID of the service from which to get the progress information |
TDes8& aProgress |
On return, a descriptor holding progress information. It is the caller's responsibility to ensure the descriptor is large enough for this information. |
KErrNone |
Success |
KErrNotFound |
The service is not active (the relevant Server-side MTM is not loaded by the Message Server) |
KErrOverflow |
The descriptor was too small for the progress information |
TInt StopService(TMsvId aServiceId);
This function stops any operations that a Server-side MTM for the specified service is running, and then unloads the Server-side MTM. The current operation and any queued operations are cancelled.
TMsvId aServiceId |
The ID of the service to stop |
KErrNone |
Success |
CMsvOperation* TransferCommandL(const CMsvEntrySelection& aSelection, TInt aCommandId, const TDesC8& aParameter, TRequestStatus& aStatus);
This function is used by Client-side and User Interface MTMs to pass MTM-specific operations to the associated Server-side MTM by means of the Message Server. It is typically used in the implementation of CBaseMtm::InvokeSyncFunctionL()/InvokeAsyncFunctionL() and CBaseMtmUi::InvokeSyncFunctionL()/InvokeAsyncFunctionL(). It is not used by message client applications. How the passed aSelection and aParameter parameters are used is specific to the operation.
Calling this function results in the Message Server calling CBaseServerMtm::StartCommandL() on the relevant Server-side MTM. If the Server-side MTM is not already loaded, then the Message Server loads it.
The returned CMsvOperation object completes when the operation is complete.
const CMsvEntrySelection& aSelection |
A selection of entries that may be relevant to the operation |
TInt aCommandId |
The command ID. The interpretation of the command is MTM-specific. |
const TDesC8& aParameter |
A descriptor containing operation-specific parameters |
TRequestStatus& aStatus |
The request status to be completed when the operation has finished |
CMsvOperation* |
The CMsvOperation object used to control the operation. |
KErrNoMemory |
Not enough memory |
void CloseMessageServer();
Use this function to ask the Message Server to close down.
This results in the session sending a shutdown session notification (TMsvSessionEvent::EMsvCloseSession) to all current sessions. The Message Server closes when all sessions have been closed.
TInt InstallMtmGroup(const TDesC& aFullName);
Use this function to install a new group of MTMs. It is used by specialised MTM-installation programs. For details of MTM installation, see Installation.
const TDesC& aFullName |
The full path name of the MTM group file |
KErrNone |
Success |
KErrAlreadyExists |
MTM already installed |
TInt DeInstallMtmGroup(const TDesC& aFullName);
Use this function to remove an installed MTM. It is used by specialised MTM-deinstallation programs. For details of MTM installation, see Installation.
const TDesC& aFullName |
The full path name of the MTM group file |
KErrNone |
Success |
KErrInUse |
The MTM is currently being used |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |