EPOC   SDK Home Glossary Indexes Previous Next Up

CMsvSession class


Contents


CMsvSession class — Message Server session

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

CActive

Abstract: active object abstraction

Defined in

msvapi.h

Link against

mcld.lib

Description

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.


Creation

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.


OpenSyncL() — Create session object synchronously

static CMsvSession* OpenSyncL(MMsvSessionObserver& aObserver);

Description

Use this function to create a session synchronously. The session can be used once the function returns.

Arguments

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.

Return value

CMsvSession*

New session object

Leave considerations

KErrNoMemory

Not enough memory to create object.


OpenASyncL() — Create session object asynchronously

static CMsvSession* OpenAsyncL(MMsvSessionObserver& aObserver);

Description

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.

Arguments

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.

Return value

CMsvSession*

New session object

Leave considerations

KErrNoMemory

Not enough memory to create object.


Session observers


AddObserverL() — Register new session observer

void AddObserverL(MMsvSessionObserver& aObserver);

Description

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.

Arguments

MMsvSessionObserver& aObserver

A reference to an observer to be registered for events

Leave considerations

KErrNoMemory

Not enough memory to register the observer


RemoveObserver() — Remove session observer

void RemoveObserver(MMsvSessionObserver& aObserver);

Description

Use this function to unregister a previously registered observer.

Arguments

MMsvSessionObserver& aObserver

A reference to an observer to be unregistered for events


Entries


GetEntryL() — Access entry

CMsvEntry* GetEntryL(TMsvId aId);

Description

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.

Arguments

TMsvId aId

The ID of the entry to access

Return value

CMsvEntry*

A new entry object

Leave considerations

KErrNotFound

The requested entry does not exist


RemoveEntry() — Delete entry

void RemoveEntry(TMsvId aId);

Description

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.

Arguments

TMsvId aId

The ID of the entry to remove


Cleanup

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.


CleanupEntryPushL() — Push entry to cleanup stack

void CleanupEntryPushL(TMsvId aId);

Description

Use this function to push the entry specified by aId to the entry cleanup stack.

Arguments

TMsvId aId

The ID of the entry to push onto the entry cleanup stack

Leave considerations

ErrNoMemory

The entry will have been pushed onto the entry cleanup stack before the leave occurs


CleanupEntryPop() — Pop entry from cleanup stack

void CleanupEntryPop(TInt aCount=1);

Description

Use this function to pop one or more entries from the entry cleanup stack.

Arguments

TInt aCount

The number of entries to pop off the entry cleanup stack


MTM functions


ServiceActive() — Test if Server-side MTM is loaded

TBool ServiceActive(TMsvId aServiceId);

Description

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.

Arguments

TMsvId aServiceId

The ID of the relevant service

Return value

TBool

ETrue if the Server-side MTM for the service is loaded, otherwise EFalse


ServiceProgress() — Get current progress information

TInt ServiceProgress(TMsvId aServiceId, TDes8& aProgress);

Description

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.

Arguments

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.

Return value

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


StopService() — Forced unload of Server-side MTM

TInt StopService(TMsvId aServiceId);

Description

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.

Arguments

TMsvId aServiceId

The ID of the service to stop

Return value

KErrNone

Success


TransferCommandL() — Call Server-side MTM operation

CMsvOperation* TransferCommandL(const CMsvEntrySelection& aSelection, TInt aCommandId, const TDesC8& aParameter, TRequestStatus& aStatus);

Description

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.

Arguments

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

Return value

CMsvOperation*

The CMsvOperation object used to control the operation.

Leave considerations

KErrNoMemory

Not enough memory


Close Message Server


CloseMessageServer() — Close Message Server

void CloseMessageServer();

Description

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.


Installation


InstallMtmGroup() — Install new MTM

TInt InstallMtmGroup(const TDesC& aFullName);

Description

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.

Arguments

const TDesC& aFullName

The full path name of the MTM group file

Return value

KErrNone

Success

KErrAlreadyExists

MTM already installed


DeInstallMtmGroup() — Remove installed MTM

TInt DeInstallMtmGroup(const TDesC& aFullName);

Description

Use this function to remove an installed MTM. It is used by specialised MTM-deinstallation programs. For details of MTM installation, see Installation.

Arguments

const TDesC& aFullName

The full path name of the MTM group file

Return value
KErrNone

Success

KErrInUse

The MTM is currently being used

EPOC       SDK Home Glossary Indexes Previous Next Up