EPOC   SDK Home Glossary Indexes Previous Next Up

CBaseServerMtm class


Contents


CBaseServerMtm classServer-side MTM base

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

mtsr.h

Link against

msvd.lib

Description

This class is the base class for Server-side MTM components. Server-side MTMs provide all message transport functionality for a particular messaging protocol. For an overview of their functionality, see Server-side MTMs.

MTM implementers implement a derived class to provide such functionality for their message protocol. Writers of message client applications are never concerned with this class and its sub-classes, as these are only accessed by the Message Server.

Each MTM interprets the generic commands in different ways. For example, a Fax MTM would transmit a fax when asked to copy a fax from a local folder to a fax service. For the same function, an IMAP MTM would create a copy of the message on the remote server and update the message index to show the copy of the message on the remote server. An important initial design task is to the map the functions to the functionality provided by the protocol.

Server-side MTM functions are called by the Message Server as a result of a client request that requires some remote operation with the MTM’s protocol. The following steps give a simplified view of the usual sequence of events:

To qualify this somewhat:

For asynchronous requests, a Server-side MTM should always complete the TRequestStatus with KErrNone. Any errors should be returned in the progress information.


Factory function, constructor, initialisation, and destructor


Factory function

<concrete-type>* <concrete-type>::<function-name>(CRegisteredMtmDll& aRegisteredMtmDll);

Requirements

A concrete Server-side MTM must implement an exported factory function conforming to this signature. This function is not declared in the base class. It is typically named NewL(), to conform to the general pattern for EPOC two-phase construction functions. It is called by the Server-side MTM registry when a client requests this Server-side MTM.

The function should create a new instance of the CBaseServerMtm-derived class that provides the implementation, and perform any dynamic allocation required. The arguments received should be passed to the constructor.

The function is called by ordinal. The ordinal of the function must match that recorded in the MTM’s registry information. See CMtmDllInfo for details.

Arguments

CRegisteredMtmDll& aRegisteredMtmDll

Registration data for the MTM DLL

Return value

A newly-created instance of the CBaseServerMtm-derived class for the Server-side MTM.

Leave considerations

The factory function should leave if it cannot create the object.

Example

For example, a Server-side MTM whose concrete class was CEgMtmServ could define a suitable factory function as:

ER5:

    EXPORT_C CEgMtmServ* CEgMtmServ::NewL(CRegisteredMtmDll& aRegisteredMtmDll)
          {
          CEgMtmServ* egSvrMtm=new(ELeave) CEgMtmServ(aRegisteredMtmDll);
          CleanupStack::PushL(egSvrMtm);
          egSvrMtm->ConstructL();
          CleanupStack::Pop();
          return egSvrMtm;
          }

CBaseServerMtm() — Constructor

protected: CBaseServerMtm(CRegisteredMtmDll& aRegisteredMtmDll);

Description

The base class constructor initialises member variables from the passed arguments.

Derived classes can implement a constructor to perform any additional MTM-specific setup that can be safely carried out in a constructor. Such constructors must call the base class constructor function.

Arguments

CRegisteredMtmDll& aRegisteredMtmDll

Registration data for the MTM DLL


~CBaseServerMtm() — Destructor

~CBaseServerMtm();

Description

CBaseServerMtm-derived objects are deleted by the Message Server when they are no longer required. This function cleans up the base class.

Derived classes can implement a destructor to do any additional clean up tasks that they require.


SetInitialEntry() — Set first context's index

virtual void SetInitialEntry(CMsvServerEntry* aEntry)=0;

Requirements

This function is called by the Message Server to set the initial context for the object. The context is initially set either to the parent of the entry or selection being operated on, or the entry itself.

The function should be implemented to store the passed CMsvServerEntry in a suitable piece of private data.

Arguments

CMsvServerEntry* aEntry

The entry that the object should set as its initial context.


Create, change, delete


ChangeL() — Change entry

virtual void ChangeL(TMsvEntry aNewEntry, TRequestStatus& aStatus)=0;

Requirements

This function is called by the Message Server to update a remote entry with relevant data from aNewEntry. Implementations should provide this function if the messaging protocol supports updating of remote entries. If this is not supported, implementations should leave with KErrNotSupported.

The Server-side MTM implementation must decide what information in the TMsvEntry is relevant to the remote entry, and translate it appropriately for the specific protocol. Most of the data contained in the TMsvEntry is specific to the EPOC Message Server, and would probably have no direct correlation with the protocol’s own storage format. Some entry data may however be useful. For example, if the protocol supports remote renaming of folders, the implementation could:

The implementation should also always update the local Message Server index through CMsvServerEntry::ChangeL().

Arguments

TMsvEntry aNewEntry

Data by which to update entry

TRequestStatus& aStatus

Asynchronous completion word for the operation.

Leave considerations

KErrNotSupported

The Server-side MTM does not support this operation

Other leave codes

Dependent on implementation


CreateL() — Create new entry

virtual void CreateL(TMsvEntry aNewEntry, TRequestStatus& aStatus)=0;

Requirements

This function is called by the Message Server to create a new remote entry with relevant data from aNewEntry. Implementations should provide this function if the messaging protocol supports creation of remote entries. If this is not supported, implementations should leave with KErrNotSupported.

As with ChangeL(), the Server-side MTM implementation must decide what information in the TMsvEntry is relevant to the remote entry, and translate it appropriately for the specific protocol. Most of the data contained in the TMsvEntry is specific to the EPOC Message Server, and would probably have no direct correlation with the protocol’s own storage format. For example, for a folder, probably only the name and parent are needed, so if the protocol supports creation of remote folders, the implementation could:

Arguments

TMsvEntry aNewEntry

Data by which to create entry

TRequestStatus& aStatus

Asynchronous completion word for the operation.

Leave considerations

KErrNotSupported

The Server-side MTM does not support this operation

Other leave codes

Dependent on implementation


DeleteAllL() — Delete entries recursively

virtual void DeleteAllL(const CMsvEntrySelection& aSelection, TRequestStatus& aStatus)=0;

Requirements

This function is called by the Message Server to delete each entry in the supplied selection. If any of the entries in the selection is a parent entry, then all its children should also be deleted, recursively to the bottom of the ownership tree.

Implementations should provide this function if the messaging protocol supports deletion of remote entries. If this is not supported, implementations should leave with KErrNotSupported.

Arguments

const CMsvEntrySelection& aSelection

The collection of entries that are to be deleted.

TRequestStatus& aStatus

Asynchronous completion object.

Leave considerations

KErrNotSupported

The Server-side MTM does not support this operation

Other leave codes

Dependent on implementation


Copy and move from remote

These functions are called by the Message Server to get a selection of entries from a remote location. For many protocols, this should be interpreted as message retrieval. For protocols where messages exist on a remote server, this function is typically used to download specific messages, after an initial connection has downloaded message headers.

MoveToLocalL() should differ from CopyToLocalL() in additionally deleting the original remote data. This will only be meaningful for some protocols.

Implementations should provide these functions if the messaging protocol supports retrieval of remote entries. If this is not supported, implementations should leave with KErrNotSupported.

Implementations of these functions have three fundamental steps:


CopyToLocalL() — Copy remote entries to local

virtual void CopyToLocalL(const CMsvEntrySelection& aSelection, TMsvId aDestination, TRequestStatus& aStatus)=0;

Description

Use this function to copy a selection of entries from a remote location to a local location.

Arguments

const CMsvEntrySelection& aSelection

The collection of message index entries for which the copy/moving is required.

TMsvId aDestination

The entry ID to which the selection is to be copied

TRequestStatus& aStatus

Asynchronous completion word for the operation

Leave considerations

KErrNotSupported

The Server-side MTM does not support this operation

Other leave codes

Dependent on implementation


MoveToLocalL() — Move remote entries to local

virtual void MoveToLocalL(const CMsvEntrySelection& aSelection, TMsvId aDestination, TRequestStatus& aStatus)=0;

Description

Use this function to move a selection of entries from a remote location to a local location.

Requirements

The implementation of MoveToLocalL() should differ from CopyToLocalL() in additionally deleting the original remote data.

Arguments

const CMsvEntrySelection& aSelection

The collection of message index entries for which the moving is required.

TMsvId aDestination

The entry ID to which the selection is to be copied/moved

TRequestStatus& aStatus

Asynchronous completion word for the operation

Leave considerations

KErrNotSupported

The Server-side MTM does not support this operation

Other leave codes

Dependent on implementation


Copy and move to remote

These functions are called by the Message Server to copy/move a selection of entries to a remote location. For many protocols, this should be interpreted as message sending.

MoveFromLocalL() should differ from CopyFromLocalL() in additionally deleting the local entries. This will only be meaningful for some protocols.

Implementations should provide this function if the messaging protocol supports retrieval of remote entries. If this is not supported, implementations should leave with KErrNotSupported.

Implementations of these functions have three fundamental steps:


CopyFromLocalL() — Copy local entries to remote

virtual void CopyFromLocalL(const CMsvEntrySelection& aSelection, TMsvId aDestination, TRequestStatus& aStatus)=0;

Description

Use this function to copy a selection of entries from a local location to a remote location.

Arguments

const CMsvEntrySelection& aSelection

The collection of message index entries for which the copy is required

TMsvId aDestination

The entry ID of the service by which the entries should be transferred

TRequestStatus& aStatus

Asynchronous completion word for the operation

Leave considerations

KErrNotSupported

The Server-side MTM does not support this operation

Other leave codes

Dependent on implementation


MoveFromLocalL() — Move local entries to remote

virtual void MoveFromLocalL(const CMsvEntrySelection& aSelection, TMsvId aDestination, TRequestStatus& aStatus)=0;

Description

Use this function to move a selection of entries from a local location to a remote location.

Requirements

The implementation of MoveFromLocalL() should differ from CopyFromLocalL() in additionally deleting the original local data.

Arguments

const CMsvEntrySelection& aSelection

The collection of message index entries for which the move is required

TMsvId aDestination

The entry ID of the service by which the entries should be transferred

TRequestStatus& aStatus

Asynchronous completion word for the operation

Leave considerations

KErrNotSupported

The Server-side MTM does not support this operation

Other leave codes

Dependent on implementation


Copy and move within remote

These functions are called by the Message Server to copy a selection of entries within a remote service. An example of their use might be for a user rearranging messages within remote folders.

MoveWithinServiceL() should differ from CopyWithinServiceL() in additionally deleting the original remote data.

Implementations should provide these functions if the messaging protocol supports the ability to copy/move entries within a remote service. If this is not supported, implementations should leave with KErrNotSupported.


CopyWithinServiceL() — Copy entries within service

virtual void CopyWithinServiceL(const CMsvEntrySelection& aSelection, TMsvId aDestination, TRequestStatus& aStatus)=0;

Description

Use this function to copy a selection of entries within a remote location.

Arguments

const CMsvEntrySelection& aSelection

The collection of message index entries for which the copy is required

TMsvId aDestination

The server entry ID to which the selection is to be copied

TRequestStatus& aStatus

Asynchronous completion word for the operation

Leave considerations

KErrNotSupported

The Server-side MTM does not support this operation

Other leave codes

Dependent on implementation


MoveWithinServiceL() — Move entries within service

virtual void MoveWithinServiceL(const CMsvEntrySelection& aSelection, TMsvId aDestination, TRequestStatus& aStatus)=0;

Description

Use this function to move a selection of entries within a remote location.

Requirements

The implementation of MoveWithinServiceL() should differ from CopyWithinServiceL() in additionally deleting the original data.

Arguments

const CMsvEntrySelection& aSelection

The collection of message index entries for which the move is required

TMsvId aDestination

The server entry ID to which the selection is to be moved

TRequestStatus& aStatus

Asynchronous completion word for the operation

Leave considerations

KErrNotSupported

The Server-side MTM does not support this operation

Other leave codes

Dependent on implementation


Command and progress


StartCommandL() — Run command on selection of entries

virtual void StartCommandL(CMsvEntrySelection& aSelection, TInt aCommand, const TDesC8& aParameter, TRequestStatus& aStatus)=0;

Requirements

This function is called by the Message Server to execute an MTM-specific operation on a selection of entries.

The call is made as a response to a client program invoking an MTM-specific operation through CBaseMtm::InvokeSyncFunctionL()/InvokeAsyncFunctionL(). The aSelection, aCommand, and aParameter arguments pass the values of the original aSelection, aFunctionId, and aParameter respectively arguments from such a call. The use (if any) of the aSelection and aParameter arguments by the function depends on the command.

Arguments

CMsvEntrySelection& aSelection

A selection of message entries on which the command is to be executed

TInt aCommand

The MTM-specific command to be carried out

const TDesC8& aParameter

Command-specific parameters

TRequestStatus& aStatus

Asynchronous completion word for the operation

Leave considerations

The function can leave with MTM- and command-specific leave codes.


CommandExpected() — Prevent object deletion on command completion

virtual TBool CommandExpected()=0;

Requirements

This function is called by the Message Server after a call has completed to query if it should delete the Server-side MTM object.

It is useful to stop the MTM being deleted when more commands are expected shortly. This would be the case, for example, after receiving a command to go online.

If there are no more commands expected by the Server-side MTM object, then the function should return EFalse, and the Message Server will delete it.

Return value

TBool

ETrue: the MTM object should not be deleted

EFalse: the MTM object can be deleted


Progress() — Return progress

virtual const TDesC8& Progress()=0;

Requirements

This function is called by the Message Server to get progress information for the current asynchronous operation.

The call is made as a response to a client program requesting progress information through CMsvOperation::ProgressL(). The packing format used in the TDesC8 is MTM-specific. Only the implementation of the User Interface MTM progress information functions need to understand the format: see Progress information.

The progress buffer should have a maximum size of 256 bytes.

Return value

TDesC8&

Progress information on current asynchronous operation


Active object completion


RunL() — Base class active object completion

void RunL();

Description

The base class provides a simple implementation of CActive::RunL() that calls the derived class's DoRunL() function. If that function leaves, then the leave is trapped, and DoComplete() is called to handle the error.

This implementation ensures that derived classes handle leave errors in RunL(), rather than the default of the error being passed to the active scheduler.


DoRunL() — Active object completion

protected: virtual void DoRunL()=0;

Requirements

This function should be implemented by the derived class to handle the completion of any asynchronous requests that it makes. It is called from the base class RunL() .

Note that any leaves made by this function result in DoComplete() being called with the leave code.


DoComplete() — Active object complete leave handler

virtual void DoComplete(TInt aError)=0;

Requirements

This function is called by the base class RunL() if DoRunL() leaves. It should be implemented to handle this error. For example, progress information could be updated to reflect the problem.

Arguments

TInt aError

The leave code given by DoRunL().

EPOC       SDK Home Glossary Indexes Previous Next Up