![[Index]](../../../../a_stock/images/btn_index.gif)
![[Previous]](../../../../a_stock/images/btn_prev_top.gif)
![[Next]](../../../../a_stock/images/btn_next_top.gif)
|
|
|
|
|
|
||
class CBaseServerMtm : public CActive;
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: CBaseServerMtm::CopyToLocalL(const CMsvEntrySelection &,TMsvId,TRequestStatus &) and CBaseServerMtm::MoveToLocalL(const CMsvEntrySelection &,TMsvId,TRequestStatus &) 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: CBaseServerMtm::CopyFromLocalL(const CMsvEntrySelection &,TMsvId,TRequestStatus &) and CBaseServerMtm::MoveFromLocalL(const CMsvEntrySelection &,TMsvId,TRequestStatus &) 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: CBaseServerMtm::CopyWithinServiceL(const CMsvEntrySelection &,TMsvId,TRequestStatus &) and CBaseServerMtm::MoveWithinServiceL(const CMsvEntrySelection &,TMsvId,TRequestStatus &) 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.
CBase -
Base class for all classes to be instantiated on the heap.
CActive -
The core class of the active object abstraction.
CBaseServerMtm - Base class for Server-side MTM components. Server-side MTMs provide all message ...
Defined in CBaseServerMtm:
CBaseServerMtm(CRegisteredMtmDll &,CMsvServerEntry *)Constructor.ChangeL(TMsvEntry,TRequestStatus &)Updates a remote entry with relevant data when called by the Message Server.CommandExpected()Tests if the Server-side MTM object should be deleted when called by the Message...CopyFromLocalL(const CMsvEntrySelection &,TMsvId,TRequestStatus &)Copies a selection of entries from a local location to a remote location.CopyToLocalL(const CMsvEntrySelection &,TMsvId,TRequestStatus &)Copies a selection of entries from a remote location to a local location. This w...CopyWithinServiceL(const CMsvEntrySelection &,TMsvId,TRequestStatus &)Copies a selection of entries within a remote location.CreateL(TMsvEntry,TRequestStatus &)Creates a new remote entry with relevant data when called by the Message Server.DeleteAllL(const CMsvEntrySelection &,TRequestStatus &)Deletes each entry in the supplied selection when called by the message Server. ...DoComplete(TInt)Called by the base class CBaseServerMtm::RunL() if CBaseServerMtm::DoRunL() leav...DoRunL()Handles the completion of any asynchronous requests that it makes. It is called ...Extension_(TUint,TAny *&,TAny *)The extension method provides a polymorphic behaviour to call the correct System...GetInterface(TUid)Returns a pointer to the interface with the specified Uid.MoveFromLocalL(const CMsvEntrySelection &,TMsvId,TRequestStatus &)Moves a selection of entries from a local location to a remote location.MoveToLocalL(const CMsvEntrySelection &,TMsvId,TRequestStatus &)Moves a selection of entries from a remote location to a local location.MoveWithinServiceL(const CMsvEntrySelection &,TMsvId,TRequestStatus &)Moves a selection of entries within a remote location.Progress()This function is called by the Message Server to get progress information for th...RunError(TInt)Handles the cases where RunL is leaving. RunL()Provides a simple implementation of CActive::RunL() that calls the derived class...StartCommandL(CMsvEntrySelection &,TInt,const TDesC8 &,TRequestStatus &)Executes an MTM-specific operation on a selection of entries when called by the ...SystemProgress(TMsvSystemProgress &)This call leads to calling one of the server Mtms to populate the TMsvSystemProg...iServerEntryThe entry on which to operate. It is set in the constructor.~CBaseServerMtm()Destructor.Inherited from CActive:
CActive(TInt)Constructs the active object with the specified priority.Cancel()Cancels the wait for completion of an outstanding request.Deque()Removes the active object from the active scheduler's list of active objects.DoCancel()Implements cancellation of an outstanding request.EPriorityHighA priority higher than EPriorityUserInput.EPriorityIdleA low priority, useful for active objects representing background processing.EPriorityLowA priority higher than EPriorityIdle but lower than EPriorityStandard.EPriorityStandardMost active objects will have this priority.EPriorityUserInputA priority higher than EPriorityStandard; useful for active objects handling use...IsActive()constDetermines whether the active object has a request outstanding.IsAdded()constDetermines whether the active object has been added to the active scheduler's li...Priority()constGets the priority of the active object.SetActive()Indicates that the active object has issued a request and that it is now outstan...SetPriority(TInt)Sets the priority of the active object.TPriorityDefines standard priorities for active objects. iStatusThe request status associated with an asynchronous request.Inherited from CBase:
Delete(CBase *)Deletes the specified object.operator new(TUint)Allocates the object from the heap and then initialises its contents to binary z...operator new(TUint,TAny *)Initialises the object to binary zeroes.operator new(TUint,TLeave)Allocates the object from the heap and then initialises its contents to binary z...operator new(TUint,TLeave,TUint)Allocates the object from the heap and then initialises its contents to binary z...operator new(TUint,TUint)Allocates the object from the heap and then initialises its contents to binary z...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.
protected: IMPORT_C CBaseServerMtm(CRegisteredMtmDll &aRegisteredMtmDll, CMsvServerEntry *aServerEntry);
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.
|
|
|
virtual void CopyToLocalL(const CMsvEntrySelection &aSelection, TMsvId aDestination, TRequestStatus &aStatus)=0;
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
|
|
virtual void CopyFromLocalL(const CMsvEntrySelection &aSelection, TMsvId aDestination, TRequestStatus &aStatus)=0;
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
|
|
virtual void CopyWithinServiceL(const CMsvEntrySelection &aSelection, TMsvId aDestination, TRequestStatus &aStatus)=0;
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.
|
|
virtual void DeleteAllL(const CMsvEntrySelection &aSelection, TRequestStatus &aStatus)=0;
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.
|
|
virtual void CreateL(TMsvEntry aNewEntry, TRequestStatus &aStatus)=0;
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 CBaseServerMtm::ChangeL(TMsvEntry,TRequestStatus &), 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
|
|
virtual void ChangeL(TMsvEntry aNewEntry, TRequestStatus &aStatus)=0;
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.
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().
|
|
virtual void StartCommandL(CMsvEntrySelection &aSelection, TInt aCommand, const TDesC8 &aParameter, TRequestStatus &aStatus)=0;
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(TInt,const CMsvEntrySelection &,TDes8 &)/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.
|
virtual TBool CommandExpected()=0;
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.
|
virtual const TDesC8& Progress()=0;
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.
|
![[Top]](../../../../a_stock/images/arrow_up_2.gif){kind=icon}
CBaseMtmUi::DisplayProgressSummary(const TDesC8 &)constDisplays a message describing the progress of an operation.CBaseMtmUi::GetProgress(const TDesC8 &,TBuf< EProgressStringMaxLen > &,TInt &,TInt &,TInt &,TInt &)constObtains progress information description and statistics. A message client applic...virtual void MoveToLocalL(const CMsvEntrySelection &aSelection, TMsvId aDestination, TRequestStatus &aStatus)=0;
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
CBaseServerMtm::MoveToLocalL(const CMsvEntrySelection &,TMsvId,TRequestStatus &) should differ from CBaseServerMtm::CopyToLocalL(const CMsvEntrySelection &,TMsvId,TRequestStatus &) in additionally deleting the original remote data.
|
|
virtual void MoveFromLocalL(const CMsvEntrySelection &aSelection, TMsvId aDestination, TRequestStatus &aStatus)=0;
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 CBaseServerMtm::MoveFromLocalL(const CMsvEntrySelection &,TMsvId,TRequestStatus &) should differ from CBaseServerMtm::CopyFromLocalL(const CMsvEntrySelection &,TMsvId,TRequestStatus &) in additionally deleting the original local data.
|
|
virtual void MoveWithinServiceL(const CMsvEntrySelection &aSelection, TMsvId aDestination, TRequestStatus &aStatus)=0;
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 CBaseServerMtm::MoveWithinServiceL(const CMsvEntrySelection &,TMsvId,TRequestStatus &) should differ from CBaseServerMtm::CopyWithinServiceL(const CMsvEntrySelection &,TMsvId,TRequestStatus &) in additionally deleting the original data.
|
|
IMPORT_C TInt SystemProgress(TMsvSystemProgress &aOutSysProg);
This call leads to calling one of the server Mtms to populate the TMsvSystemProgress structure.
|
|
protected: virtual void DoRunL()=0;
Handles the completion of any asynchronous requests that it makes. It is called from the base class CBaseServerMtm::RunL() .
Note that any leaves made by this function result in CBaseServerMtm::DoComplete(TInt) being called with the leave code.
protected: virtual void DoComplete(TInt aError)=0;
Called by the base class CBaseServerMtm::RunL() if CBaseServerMtm::DoRunL() leaves.
It should be implemented to handle this error. For example, progress information could be updated to reflect the problem.
|
protected: IMPORT_C virtual TInt Extension_(TUint aExtensionId, TAny *&a0, TAny *a1);
The extension method provides a polymorphic behaviour to call the correct SystemProgress function.
|
|
private: IMPORT_C virtual void RunL();
Provides a simple implementation of CActive::RunL() that calls the derived class's CBaseServerMtm::DoRunL() function. If that function leaves, then the leave is trapped, and CBaseServerMtm::DoComplete(TInt) is called to handle the error.
This implementation ensures that derived classes handle leave errors in CBaseServerMtm::RunL(), rather than the default of the error being passed to the active scheduler.
private: IMPORT_C virtual TInt RunError(TInt aError);
Handles the cases where RunL is leaving.
|
|
protected: IMPORT_C virtual TAny* GetInterface(TUid aUid);
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.
|
|
|
|
protected: CMsvServerEntry * iServerEntry;
The entry on which to operate. It is set in the constructor.
The destructor deletes this member.
|
Copyright © 2005-2008 Symbian Software Ltd. |
|
![[Previous]](../../../../a_stock/images/btn_prev.gif)
![[Top]](../../../../a_stock/images/btn_top.gif)
![[Next]](../../../../a_stock/images/btn_next.gif)