Class CMsvSession

CMsvSession

Support

Supported from 5.0

Description

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.

In pre-Unicode releases, this class had an import library mcld.lib.

Note the following significant groups of functions:

Creation functions: a message client application must use OpenSyncL() or OpenASyncL() 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.

Cleanup functions: 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. 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.

Derivation

CActive The core class of the active object abstraction CBase Base class for all classes to be instantiated on the heap CMsvSession Represents a channel of communication between a client thread (Client-side MTM, User Interface MTM, or message client application) and the Message Server thread

Defined in CMsvSession:
AddObserverL(), ChangeAttributesL(), ChangeDriveL(), CleanupEntryPop(), CleanupEntryPushL(), CloseMessageServer(), DeInstallMtmGroup(), DecPcSyncCountL(), FileSession(), GetChildIdsL(), GetEntry(), GetEntryL(), IncPcSyncCountL(), InstallMtmGroup(), OpenASyncL(), OpenSyncL(), OutstandingOperationsL(), RemoveEntry(), RemoveObserver(), ServiceActive(), ServiceProgress(), StopService(), TransferCommandL()

Inherited from CActive:
Cancel(), Deque(), DoCancel(), EPriorityHigh, EPriorityIdle, EPriorityLow, EPriorityStandard, EPriorityUserInput, IsActive(), IsAdded(), Priority(), RunError(), RunL(), SetActive(), SetPriority(), TPriority, iStatus

Inherited from CBase:
operator new()

static CMsvSession* OpenSyncL(MMsvSessionObserver& aObserver);

Description

Creates a session synchronously.

The session can be used once the function returns.

Parameters

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 codes

KErrNoMemory Not enough memory to create object.

static CMsvSession* OpenAsyncL(MMsvSessionObserver& aObserver);

Description

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

Parameters

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 codes

KErrNoMemory Not enough memory to create object.

void AddObserverL(MMsvSessionObserver& aObserver);

Description

Registers a new session observer.

CMsvSession objects can call back observer objects that implement the MMsvSessionObserver::HandleSessionEvent() when certain events occur. Any number of observers can be registered.

For details of when observers are called, see TMsvSessionEvent::TMsvEntryEvent.

Parameters

MMsvSessionObserver& aObserver A reference to an observer to be registered for events

Leave codes

KErrNoMemory Not enough memory to register the observer

void RemoveObserver(MMsvSessionObserver& aObserver);

Description

Deregisters a previously registered observer.

Parameters

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

void ChangeAttributesL(const CMsvEntrySelection& aSelection,
TUint aSetAttributes, TUint aClearAttributes);

Support

Supported from 6.0

Description

Provides a quick way to set or clear multiple fields in a selection of entries.

Fields to change are specified using a bitmask of TMsvAttribute values. Possible fields that can be changed using this function are:

• PC synchronisation

• Visibility flag

• Read flag

• In-preparation flag

• Connected flag

• New flag

Parameters

const CMsvEntrySelection& aSelection The entries to change TUint aSetAttributes A bitmask of the fields to set TUint aClearAttributes A bitmask of the fields to clear

See also:

• TMsvAttribute

CMsvEntry* GetEntryL(TMsvId aId);

Description

Accesses the entry with the specified ID.

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.

Parameters

TMsvId aId The ID of the entry to access

Return value

CMsvEntry* A new entry object

Leave codes

KErrNotFound The requested entry does not exist

TInt GetEntry(TMsvId aId, TMsvId& aService, TMsvEntry& aEntry);

Support

Supported from 6.0

Description

Gets the index entry for the specified entry ID.

Parameters

TMsvId aId The ID of the entry to access TMsvId& aService On return, the ID of the service that owns the entry TMsvEntry& aEntry On return, the index entry

Return value

TInt KErrNone if successful, otherwise one of the system-wide error codes

void GetChildIdsL(TMsvId aId, const CMsvEntryFilter& aFilter, CMsvEntrySelection& aSelection);

Support

Supported from 6.0

Description

Gets filtered list of children of a specified message entry.

Parameters

TMsvId aId Message entry of which to get children const CMsvEntryFilter& aFilter Filter by which various message entries can be excluded CMsvEntrySelection& aSelection On return, a list of message entry IDs

void RemoveEntry(TMsvId aId);

Description

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

Parameters

TMsvId aId The ID of the entry to remove

void CleanupEntryPushL(TMsvId aId);

Description

Pushes the specified entry ID to the entry cleanup stack.

Parameters

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

Leave codes

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

void CleanupEntryPop(TInt aCount=1);

Description

Pops one or more entries from the entry cleanup stack.

Parameters

TInt aCount The number of entries to pop off the entry cleanup stack

TBool ServiceActive(TMsvId aServiceId);

Description

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

Parameters

TMsvId aServiceId The ID of the relevant service

Return value

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

TInt ServiceProgress(TMsvId aServiceId, TDes8& aProgress);

Description

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

Parameters

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

TInt StopService(TMsvId aServiceId);

Description

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.

Parameters

TMsvId aServiceId The ID of the service to stop

Return value

KErrNone Success

void TransferCommandL(const CMsvEntrySelection& aSelection, TInt aCommandId, const TDesC8& aParameter, TDes8& aProgress);

Support

Supported from 5.1

Description

Passes MTM-specific operations synchronously to the associated Server-side MTM by means of the Message Server.

It is typically used in the implementation of CBaseMtm::InvokeSyncFunctionL() and CBaseMtmUi::InvokeSyncFunctionL(). 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.

Parameters

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 TDes8& aProgress Progress information returned from the Message Server

Leave codes

KErrNoMemory Not enough memory

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

Description

Passes MTM-specific operations asynchronously 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.

Parameters

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 codes

KErrNoMemory Not enough memory

void CloseMessageServer();

Description

Closes down the Message Server.

Normal clients should not use this function, as it will affect other message clients.

The function 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);

Description

Installs a new group of MTMs.

It is used by specialised MTM-installation programs.

Parameters

const TDesC& aFullName The full path name of the MTM group file

Return value

KErrNone Success KErrAlreadyExists MTM already installed

TInt DeInstallMtmGroup(const TDesC& aFullName);

Description

Removes an installed MTM.

It is used by specialised MTM-deinstallation programs.

Parameters

const TDesC& aFullName The full path name of the MTM group file

Return value

KErrNone Success KErrInUse The MTM is currently being used

CMsvOperation* ChangeDriveL(TInt aDrive, TRequestStatus& aStatus);

Support

Supported from 6.0

Description

Moves the Message Server index to the specified drive.

Progress information is provided by a TMsvIndexLoadProgress object.

If an error occurs, the index is unchanged.

Parameters

TInt aDrive The drive to which to move the Message Server index, specified by a TDriveNumber value TRequestStatus& aStatus Asynchronous completion status

Return value

CMsvOperation* Asynchronous operation used to control the move. The operation's MTM value is set to KUidMsvServerMtm, which can be used to distinguish it from a local operation.

Leave codes

KErrServerBusy Cannot change drive because there are outstanding Message Server operations.

See also:

• TDriveNumber
• TMsvIndexLoadProgress

void DecPcSyncCountL(const CMsvEntrySelection& aSelection);

Support

Supported from 5.1

Description

Decreases the PC synchronisation index field for a selection of entries.

If an entry has its Deleted flag set, and this call causes its PC synchronisation field to become zero, then the entry is permanently deleted.

Parameters

const CMsvEntrySelection& aSelection Entries for which to decrease the PC synchronisation index field

RFs& FileSession();

Support

Supported from 5.1

Description

Allows a Server-side MTM to access the file session handle created by the Message Server.

This is preferable, as more efficient, to creating another handle.

Return value

RFs& File session handle

void IncPcSyncCountL(const CMsvEntrySelection& aSelection);

Support

Supported from 5.1

Description

Increases the PC synchronisation index field for a selection of entries.

Parameters

const CMsvEntrySelection& aSelection Entries for which to increase the PC synchronisation index field

TInt OutstandingOperationsL();

Support

Supported from 6.0

Description

Gets the number of outstanding operations.

Return value

TInt The number of outstanding operations