CBaseServerMtm Class Reference

#include <mw/mtsr.h>

class CBaseServerMtm : public CActive, public CActive

Inherits from

CBaseServerMtm
- CActive
  - CBase
- CActive
  - CBase

Protected Attributes
CMsvServerEntry *	iServerEntry

Public Member Functions
	~CBaseServerMtm()
TInt	ChangeEntries(const CMsvEntrySelection &, TInt, TRequestStatus &)
pure virtual void	ChangeL(TMsvEntry, TRequestStatus &)
pure virtual TBool	CommandExpected()
pure virtual void	CopyFromLocalL(const CMsvEntrySelection &, TMsvId, TRequestStatus &)
pure virtual void	CopyToLocalL(const CMsvEntrySelection &, TMsvId, TRequestStatus &)
pure virtual void	CopyWithinServiceL(const CMsvEntrySelection &, TMsvId, TRequestStatus &)
pure virtual void	CreateL(TMsvEntry, TRequestStatus &)
pure virtual void	DeleteAllL(const CMsvEntrySelection &, TRequestStatus &)
TInt	GetNonOperationMtmData(TNonOperationMtmDataType &, TPtrC8 &)
pure virtual void	MoveFromLocalL(const CMsvEntrySelection &, TMsvId, TRequestStatus &)
pure virtual void	MoveToLocalL(const CMsvEntrySelection &, TMsvId, TRequestStatus &)
pure virtual void	MoveWithinServiceL(const CMsvEntrySelection &, TMsvId, TRequestStatus &)
pure virtual const TDesC8 &	Progress()
pure virtual void	StartCommandL(CMsvEntrySelection &, TInt, const TDesC8 &, TRequestStatus &)
IMPORT_C TInt	SystemProgress(TMsvSystemProgress &)

Protected Member Functions
	CBaseServerMtm(CRegisteredMtmDll &, CMsvServerEntry *)
pure virtual void	DoComplete(TInt)
pure virtual void	DoRunL()
virtual IMPORT_C TInt	Extension_(TUint, TAny &, TAny )
virtual IMPORT_C TAny *	GetInterface(TUid)

Inherited Attributes
	CActive::iStatus

Inherited Enumerations
	CActive:TPriority

Inherited Functions
	CActive::CActive(TInt)
	CActive::Cancel()
	CActive::Deque()
	CActive::DoCancel()
	CActive::IsActive()const
	CActive::IsAdded()const
	CActive::Priority()const
	CActive::SetActive()
	CActive::SetPriority(TInt)
	CActive::~CActive()
	CBase::CBase()
	CBase::Delete(CBase *)
	CBase::operator new(TUint)
	CBase::operator new(TUint,TAny *)
	CBase::operator new(TUint,TLeave)
	CBase::operator new(TUint,TLeave,TUint)
	CBase::operator new(TUint,TUint)
	CBase::~CBase()

Detailed Description

Base class for Server-side MTM components. Server-side MTMs provide all message transport functionality for a particular messaging protocol.

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:

1. the Message Server instantiates a Server-side MTM object through the factory function

2. the Message Server calls the appropriate asynchronous function on the Server-side MTM interface, passing a TRequestStatus argument

3. the Server-side MTM function typically starts whatever asynchronous communications it requires and returns

4. the Server-side MTM is signalled when the asynchronous communications complete, and handles the result

5. the Server-side MTM signals the Message Server, through the TRequestStatus passed earlier

6. the Message Server deletes the Server-side MTM object

To qualify this somewhat:

1. it is up to the Server-side MTM implementation to decide how to translate data back and forth between the formats used by Message Server (index entry, message store, binary files), and that required by the protocol; this is another important design task

2. depending on the protocol being used, the communications sequence can be of considerable complexity; typically it requires division into a number of asynchronous steps

3. for greater efficiency where further commands are shortly expected, deletion of the Server-side MTM object can be prevented

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

Note the following significant groups of functions:

1. Copy and move from remote functions: CopyToLocalL() and MoveToLocalL() 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.

2. Copy and move to remote functions: CopyFromLocalL() and MoveFromLocalL() 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.

3. Copy and move within remote functions: CopyWithinServiceL() and MoveWithinServiceL() 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.

Member Attribute Documentation

iServerEntry

CMsvServerEntry *

iServerEntry

[protected]

The entry on which to operate. It is set in the constructor.

The destructor deletes this member.

Constructor & Destructor Documentation

CBaseServerMtm ( CRegisteredMtmDll &, CMsvServerEntry * )

IMPORT_C	CBaseServerMtm	(	CRegisteredMtmDll &	aRegisteredMtmDll,
			CMsvServerEntry *	aServerEntry
		)	[protected]

Constructor.

The function is passed a CMsvServerEntry object in aServerEntry. This object is used to access and change Message Server entries. Its context is initially set either to the parent of the entry or selection being operated on, or the entry itself. The constructor stores it in the protected iServerEntry member.

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.

Parameters
aRegisteredMtmDll	Registration data for the MTM DLL
aServerEntry	Context on which to operate

~CBaseServerMtm ( )

IMPORT_C

~CBaseServerMtm

(

)

Destructor.

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

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

Member Function Documentation

ChangeEntries ( const CMsvEntrySelection &, TInt, TRequestStatus & )

TInt	ChangeEntries	(	const CMsvEntrySelection &	aSelection,
			TInt	aMark,
			TRequestStatus &	aStatus
		)

Updates a remote selection of id with relevant data when called by the Message Server.

Implementations should implement Extension_ and handle KUIDChangeEntriesExtension if the messaging protocol supports updating of remote entries. If this is not supported, implementations can ignore the KUIDChangeEntriesExtension. However implentations should chain the extension ids to their base class if they are not handled.

This function wraps the call to Extension_ passing the necessary params in the form of TChangeEntriesParams as the second argument.

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 Symbian OS 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:

1. check for a folder type entry

2. extract the folder name from aNewEntry.iDetails

3. check if the folder name has changed by comparing the new name with iDetails in the index entry currently; if not, complete with KErrNone

4. initiate a protocol-specific action to rename the remote folder

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

Parameters
aSelection	Selection of TMsvId which to update
aMark	Read and Unread mark value.
aStatus	Asynchronous completion word for the operation.

Return Value: KErrNotSupported if the Server-side MTM does not support this operation Other codes Dependent on implementation

ChangeL ( TMsvEntry, TRequestStatus & )

void	ChangeL	(	TMsvEntry	aNewEntry,
			TRequestStatus &	aStatus
		)	[pure virtual]

Updates a remote entry with relevant data when called by the Message Server.

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

1. check for a folder type entry

2. extract the folder name from aNewEntry.iDetails

3. check if the folder name has changed by comparing the new name with iDetails in the index entry currently; if not, complete with KErrNone

4. initiate a protocol-specific action to rename the remote folder

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

Parameters
aNewEntry	Data by which to update entry
aStatus	Asynchronous completion word for the operation.

Leave Codes
KErrNotSupported	The Server-side MTM does not support this operation
Other	leave codes Dependent on implementation

CommandExpected ( )

TBool

CommandExpected

(

)

[pure virtual]

Tests if the Server-side MTM object should be deleted when called by the Message Server

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: ETrue: the MTM object should not be deleted EFalse: the MTM object can be deleted

CopyFromLocalL ( const CMsvEntrySelection &, TMsvId, TRequestStatus & )

void	CopyFromLocalL	(	const CMsvEntrySelection &	aSelection,
			TMsvId	aDestination,
			TRequestStatus &	aStatus
		)	[pure virtual]

Copies a selection of entries from a local location to a remote location.

Requirements:

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 this function have three fundamental steps:

1. reading entry data

2. converting entry data from the Message Server format into that required by the protocol

3. doing the transfer operation using the appropriate communications protocols

Parameters
aSelection	The collection of message index entries for which the copy is required
aDestination	The entry ID of the service by which the entries should be transferred
aStatus	Asynchronous completion word for the operation

Leave Codes
KErrNotSupported	The Server-side MTM does not support this operation
Other	leave codes Dependent on implementation

CopyToLocalL ( const CMsvEntrySelection &, TMsvId, TRequestStatus & )

void	CopyToLocalL	(	const CMsvEntrySelection &	aSelection,
			TMsvId	aDestination,
			TRequestStatus &	aStatus
		)	[pure virtual]

Copies a selection of entries from a remote location to a local location. This will only be meaningful for some protocols.

Requirements:

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 this function have three fundamental steps:

1. doing the transfer operation using the appropriate communications protocols

2. converting protocol-specific data into the three-part storage format (index entry, message store, binary files) required by the Message Server

3. updating entries in the Message Server

Parameters
aSelection	The collection of message index entries for which the copy/moving is required.
aDestination	The entry ID to which the selection is to be copied
aStatus	Asynchronous completion word for the operation

Leave Codes
KErrNotSupported	The Server-side MTM does not support this operation
Other	leave codes Dependent on implementation

CopyWithinServiceL ( const CMsvEntrySelection &, TMsvId, TRequestStatus & )

void	CopyWithinServiceL	(	const CMsvEntrySelection &	aSelection,
			TMsvId	aDestination,
			TRequestStatus &	aStatus
		)	[pure virtual]

Copies a selection of entries within a remote location.

Requirements:

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

Parameters
aSelection	The collection of message index entries for which the copy is required
aDestination	The server entry ID to which the selection is to be copied
aStatus	Asynchronous completion word for the operation

Leave Codes
KErrNotSupported	The Server-side MTM does not support this operation
Other	leave codes Dependent on implementation

CreateL ( TMsvEntry, TRequestStatus & )

void	CreateL	(	TMsvEntry	aNewEntry,
			TRequestStatus &	aStatus
		)	[pure virtual]

Creates a new remote entry with relevant data when called by the Message Server.

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 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:

1. check for a folder type entry

2. get the folder name and parent details from aNewEntry

3. initiate a protocol-specific action to create the remote folder

Parameters
aNewEntry	Data by which to create entry
aStatus	Asynchronous completion word for the operation.

Leave Codes
KErrNotSupported	The Server-side MTM does not support this operation
Other	leave codes Dependent on implementation

DeleteAllL ( const CMsvEntrySelection &, TRequestStatus & )

void	DeleteAllL	(	const CMsvEntrySelection &	aSelection,
			TRequestStatus &	aStatus
		)	[pure virtual]

Deletes each entry in the supplied selection when called by the message Server. 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.

Parameters
aSelection	The collection of entries that are to be deleted.
aStatus	Asynchronous completion object.

Leave Codes
KErrNotSupported	The Server-side MTM does not support this operation
Other	leave codes Dependent on implementation

DoComplete ( TInt )

void

DoComplete

(

TInt

aError

)

[protected, pure virtual]

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.

Parameters
aError	The leave code given by DoRunL().

DoRunL ( )

void

DoRunL

(

)

[protected, pure virtual]

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

Extension_ ( TUint, TAny &, TAny )

IMPORT_C TInt	Extension_	(	TUint	aExtensionId,
			TAny *&	a0,
			TAny *	a1
		)	[protected, virtual]

Reimplemented from CActive::Extension_(TUint,TAny *&,TAny *)

The extension method provides a polymorphic behaviour to call the correct SystemProgress function.

Parameters
aExtensionId	The Uid passed in as KUIDMsgMsvSystemProgress to obtain the System Progress.

Return Value: KErrExtensionNotSupported retuned if no Extension_ function is overriddden by the derived class.

GetInterface ( TUid )

IMPORT_C TAny *

GetInterface

(

TUid

aUid

)

[protected, virtual]

Returns a pointer to the interface with the specified Uid.

This method is the first part of an extension pattern to allow for more functionality to be supported without adding virtual methods to this base class.

The default implementation returns a NULL pointer.

Parameters
aUid	Uid of the extension interface

Return Value: Pointer to the extension interface

GetNonOperationMtmData ( TNonOperationMtmDataType &, TPtrC8 & )

TInt	GetNonOperationMtmData	(	TNonOperationMtmDataType &	aMtmDataType,
			TPtrC8 &	aResultBuffer
		)

Call to this method leads to call Extension_ method of server MTMs, to which the thread handle of the client application is passed.

MoveFromLocalL ( const CMsvEntrySelection &, TMsvId, TRequestStatus & )

void	MoveFromLocalL	(	const CMsvEntrySelection &	aSelection,
			TMsvId	aDestination,
			TRequestStatus &	aStatus
		)	[pure virtual]

Moves a selection of entries from a local location to a remote location.

Requirements:

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 this function have three fundamental steps:

1. reading entry data

2. converting entry data from the Message Server format into that required by the protocol

3. doing the transfer operation using the appropriate communications protocols

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

Parameters
aSelection	The collection of message index entries for which the move is required
aDestination	The entry ID of the service by which the entries should be transferred
aStatus	Asynchronous completion word for the operation

Leave Codes
KErrNotSupported	The Server-side MTM does not support this operation
Other	leave codes Dependent on implementation

MoveToLocalL ( const CMsvEntrySelection &, TMsvId, TRequestStatus & )

void	MoveToLocalL	(	const CMsvEntrySelection &	aSelection,
			TMsvId	aDestination,
			TRequestStatus &	aStatus
		)	[pure virtual]

Moves a selection of entries from a remote location to a local location.

Requirements:

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 this function have three fundamental steps:

1. doing the transfer operation using the appropriate communications protocols

2. converting protocol-specific data into the three-part storage format (index entry, message store, binary files) required by the Message Server

3. updating entries in the Message Server

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

Parameters
aSelection	The collection of message index entries for which the moving is required.
aDestination	The entry ID to which the selection is to be copied/moved
aStatus	Asynchronous completion word for the operation

Leave Codes
KErrNotSupported	The Server-side MTM does not support this operation
Other	leave codes Dependent on implementation

MoveWithinServiceL ( const CMsvEntrySelection &, TMsvId, TRequestStatus & )

void	MoveWithinServiceL	(	const CMsvEntrySelection &	aSelection,
			TMsvId	aDestination,
			TRequestStatus &	aStatus
		)	[pure virtual]

Moves a selection of entries within a remote location.

Requirements:

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

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

Parameters
aSelection	The collection of message index entries for which the move is required
aDestination	The server entry ID to which the selection is to be moved
aStatus	Asynchronous completion word for the operation

Leave Codes
KErrNotSupported	The Server-side MTM does not support this operation
Other	leave codes Dependent on implementation

Progress ( )

const TDesC8 &

Progress

(

)

[pure virtual]

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.

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

Return Value: Progress information on current asynchronous operation

StartCommandL ( CMsvEntrySelection &, TInt, const TDesC8 &, TRequestStatus & )

void	StartCommandL	(	CMsvEntrySelection &	aSelection,
			TInt	aCommand,
			const TDesC8 &	aParameter,
			TRequestStatus &	aStatus
		)	[pure virtual]

Executes an MTM-specific operation on a selection of entries when called by the Message Server.

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.

Parameters
aSelection	A selection of message entries on which the command is to be executed
aCommand	The MTM-specific command to be carried out
aParameter	Command-specific parameters
aStatus	Asynchronous completion word for the operation

SystemProgress ( TMsvSystemProgress & )

IMPORT_C TInt

SystemProgress

(

TMsvSystemProgress &

aOutSysProg

)

This call leads to calling one of the server Mtms to populate the TMsvSystemProgress structure.

Parameters
aOutSysProg	The TMsvSystemProgress structure to be populated by the server

Return Value: the error of the Extension_ method call

CBaseServerMtm Class Reference

Inherits from

Detailed Description

Member Attribute Documentation

iServerEntry

Constructor & Destructor Documentation

CBaseServerMtm ( CRegisteredMtmDll &, CMsvServerEntry * )

~CBaseServerMtm ( )

Member Function Documentation

ChangeEntries ( const CMsvEntrySelection &, TInt, TRequestStatus & )

ChangeL ( TMsvEntry, TRequestStatus & )

CommandExpected ( )

CopyFromLocalL ( const CMsvEntrySelection &, TMsvId, TRequestStatus & )

CopyToLocalL ( const CMsvEntrySelection &, TMsvId, TRequestStatus & )

CopyWithinServiceL ( const CMsvEntrySelection &, TMsvId, TRequestStatus & )

CreateL ( TMsvEntry, TRequestStatus & )

DeleteAllL ( const CMsvEntrySelection &, TRequestStatus & )

DoComplete ( TInt )

DoRunL ( )

Extension_ ( TUint, TAny *&, TAny * )

GetInterface ( TUid )

GetNonOperationMtmData ( TNonOperationMtmDataType &, TPtrC8 & )

MoveFromLocalL ( const CMsvEntrySelection &, TMsvId, TRequestStatus & )

MoveToLocalL ( const CMsvEntrySelection &, TMsvId, TRequestStatus & )

MoveWithinServiceL ( const CMsvEntrySelection &, TMsvId, TRequestStatus & )

Progress ( )

StartCommandL ( CMsvEntrySelection &, TInt, const TDesC8 &, TRequestStatus & )

SystemProgress ( TMsvSystemProgress & )

Extension_ ( TUint, TAny &, TAny )