class CBaseMtmUi : public CBase |
Provides MTM-specific user interaction, such as editing, viewing, deleting, and copying of message entries.
Message client applications use the class to access such functionality polymorphically. MTM implementers implement a derived class to provide such functionality for their message protocol.
The base class is largely an interface definition: it implements little important functionality itself. For implementers, this documentation defines conditions that any implementation must fulfil, plus suggested semantics for behaviour. This still leaves many decisions in the hands of the implementer. A key design time activity is to define how the particular characteristics of the implemented protocol are best mapped to the interface. As this class is concerned with user interfaces, implementers should be sensitive to the look and feel of the target phone.
Many functions are required to return an instance of a CMsvOperation-derived class to provide asynchronous control and monitoring to the caller of the operation being performed.
The following are some significant groups of functions:
Entry manipulation functions: OpenL(), CloseL(), EditL(), and ViewL() are all available in two overloaded versions. The first version operates on the current context. The second version operates upon groups of entries specified by a CMsvEntrySelection argument. All entries must be in same folder and all of the correct MTM type. The context may change after calling these functions. Concrete User Interface MTMs can legally ignore any of the entries within the selection - many may, for example, simply open the first entry.
Copying and moving functions: the CopyToL(), CopyFromL(), MoveToL(), and MoveFromL() functions are concerned with copying and moving entries to and from remote servers. MTMs can implement these functions to provide any user interaction needed before copying or moving can proceed, such as dialogs to confirm settings; and, any protocol-specific setup steps that can be done at this stage: for example, a fax MTM could render messages into the required image format.
Progress information functions: DisplayProgressSummary() and GetProgress() convert MTM-specific progress information about some asynchronous operation, such as message sending, to a human-readable form. The progress information to pass into these functions is, in general, obtained from an on-going CMsvOperation by calling CMsvOperation::Progress(). The nature of any information provided is MTM-specific.
MTM-specific UI functions: MTM components can offer protocol-specific functionality not provided by base class interface functions. MTM components define IDs that correspond to each protocol-specific operation offered, and implement the InvokeSyncFunctionL() and InvokeAsyncFunctionL() functions to allow clients to access these operations by passing in the appropriate ID. Two functions are provided to allow the MTM component to offer both synchronous and asynchronous functionality. Message client applications can dynamically add user-interface features for these operations using CBaseMtmUiData::MtmSpecificFunctions(). MTM developers should document the IDs if they wish to make the operations available to clients.
Protected Member Functions | |
---|---|
CBaseMtmUi(CBaseMtm &, CRegisteredMtmDll &) | |
IMPORT_C void | ConstructL() |
IMPORT_C TAny * | GetInterface(TUid) |
void | GetResourceFileName(TFileName &) |
IMPORT_C CMsvSession & | Session() |
Public Member Enumerations | |
---|---|
enum | anonymous { EProgressStringMaxLen = 255 } |
Protected Attributes | |
---|---|
CBaseMtm & | iBaseMtm |
CCoeEnv * | iCoeEnv |
TUint | iFlags |
Private Attributes | |
---|---|
TAny * | iExtensionData |
CRegisteredMtmDll & | iRegisteredMtmDll |
TInt | iResourceFileOffset |
IMPORT_C | CBaseMtmUi | ( | CBaseMtm & | aBaseMtm, |
CRegisteredMtmDll & | aRegisteredMtmDll | |||
) | [protected] |
CBaseMtm & aBaseMtm | |
CRegisteredMtmDll & aRegisteredMtmDll |
CMsvOperation * | CancelL | ( | TRequestStatus & | aStatus, |
const CMsvEntrySelection & | aSelection | |||
) | [pure virtual] |
Cancels the sending of specified messages.
leave
KErrNotSupported The User Interface MTM does not support cancel operations, or cancelling is inappropriate to the current context
leave
Other Dependent on implementation
If successful, this is an asynchronously completing cancel operation. If failed, this is a completed operation, with status set to the relevant error code.
TRequestStatus & aStatus | The request status to be completed when the operation has finished |
const CMsvEntrySelection & aSelection | Selection of message entries |
CMsvOperation * | CloseL | ( | TRequestStatus & | aStatus | ) | [pure virtual] |
Closes an entry. The behaviour that this implies is dependent on the current context:
1. for message contexts, this usually closes any launched editors or viewers
2. for folder contexts, leaves with KErrNotSupported
3. for service contexts, causes closure of a connection to a server
The returned CMsvOperation object completes when closing is complete.
Requirements:
Implementations should:
1. check aEntry.iType.iUid to ensure that they can close the requested type of entry and leave with code KErrNotSupported if they cannot
2. return a CMsvOperation-derived object to provide asynchronous control and monitoring of the operation
leave
KErrNotSupported The User Interface MTM does not support close operations, or closing is inappropriate to the current context
leave
Other Dependent on implementation
If successful, this is an asynchronously completing close operation. If failed, this is a completed operation, with status set to the relevant error code.
TRequestStatus & aStatus | The request status to be completed when the operation has finished |
CMsvOperation * | CloseL | ( | TRequestStatus & | aStatus, |
const CMsvEntrySelection & | aSelection | |||
) | [pure virtual] |
Closes a selection of entries.
The behaviour that this implies is dependent on the current context:
1. for message contexts, this usually closes any launched editors or viewers
2. for folder contexts, leaves with KErrNotSupported
3. for service contexts, causes closure of a connection to a server
The returned CMsvOperation object completes when closing is complete.
Requirements:
Implementations should:
1. check aEntry.iType.iUid to ensure that they can close the requested type of entry and leave with code KErrNotSupported if they cannot
2. return a CMsvOperation-derived object to provide asynchronous control and monitoring of the operation
leave
KErrNotSupported The User Interface MTM does not support close operations, or closing is inappropriate to the current context
leave
Other Dependent on implementation
If successful, this is an asynchronously completing close operation. If failed, this is a completed operation, with status set to the relevant error code.
TRequestStatus & aStatus | The request status to be completed when the operation has finished |
const CMsvEntrySelection & aSelection | Selection of message entries |
IMPORT_C CMsvOperation * | CopyFromL | ( | const CMsvEntrySelection & | aSelection, |
TMsvId | aTargetId, | |||
TRequestStatus & | aStatus | |||
) | [virtual] |
const CMsvEntrySelection & aSelection | |
TMsvId aTargetId | |
TRequestStatus & aStatus |
IMPORT_C CMsvOperation * | CopyToL | ( | const CMsvEntrySelection & | aSelection, |
TRequestStatus & | aStatus | |||
) | [virtual] |
const CMsvEntrySelection & aSelection | |
TRequestStatus & aStatus |
IMPORT_C CMsvOperation * | CreateL | ( | const TMsvEntry & | aEntry, |
CMsvEntry & | aParent, | |||
TRequestStatus & | aStatus | |||
) | [virtual] |
const TMsvEntry & aEntry | |
CMsvEntry & aParent | |
TRequestStatus & aStatus |
IMPORT_C CMsvOperation * | DeleteFromL | ( | const CMsvEntrySelection & | aSelection, |
TRequestStatus & | aStatus | |||
) | [virtual] |
const CMsvEntrySelection & aSelection | |
TRequestStatus & aStatus |
IMPORT_C CMsvOperation * | DeleteServiceL | ( | const TMsvEntry & | aService, |
TRequestStatus & | aStatus | |||
) | [virtual] |
const TMsvEntry & aService | |
TRequestStatus & aStatus |
IMPORT_C TInt | DisplayProgressSummary | ( | const TDesC8 & | aProgress | ) | const [virtual] |
const TDesC8 & aProgress |
CMsvOperation * | EditL | ( | TRequestStatus & | aStatus | ) | [pure virtual] |
Edits an entry.
The behaviour that this implies is dependent on the current context:
1. for message contexts, this usually launches the appropriate message editor, or returns status KErrReadOnly if the message is not editable
2. for remote folder contexts, launches a settings dialog, for example to rename the folder, completing asynchronously
3. for service contexts, launches a service settings dialog, completing asynchronously
The returned CMsvOperation object completes when editing is complete.
Requirements:
Implementations should:
1. check aEntry.iType.iUid to ensure that they can edit the requested type of entry and leave with code KErrNotSupported if they cannot
2. return a CMsvOperation-derived object to provide asynchronous control and monitoring of the operation
3. for remote messages, typically, copy the messages to the Inbox
4. follow the leave protocols described in Leave considerations below
leave
KErrNotSupported The User Interface MTM does not support edit operations, or editing is inappropriate to the current context
leave
KErrReadOnly Context is read-only
leave
Other Dependent on implementation
If successful, this is an asynchronously completing edit operation. If failed, this is a completed operation, with status set to the relevant error code.
TRequestStatus & aStatus | The request status to be completed when the operation has finished |
CMsvOperation * | EditL | ( | TRequestStatus & | aStatus, |
const CMsvEntrySelection & | aSelection | |||
) | [pure virtual] |
Edits a selection of entries.
The behaviour that this implies is dependent on the current context:
1. for message contexts, this usually launches the appropriate message editor, or returns status KErrReadOnly if the message is not editable
2. for remote folder contexts, launches a settings dialog, for example to rename the folder, completing asynchronously
3. for service contexts, launches a service settings dialog, completing asynchronously
The returned CMsvOperation object completes when editing is complete.
Requirements:
Implementations should:
1. check aEntry.iType.iUid to ensure that they can edit the requested type of entry and leave with code KErrNotSupported if they cannot
2. return a CMsvOperation-derived object to provide asynchronous control and monitoring of the operation
3. for remote messages, typically, copy the messages to the Inbox
4. follow the leave protocols described in Leave considerations below
leave
KErrNotSupported The User Interface MTM does not support edit operations, or editing is inappropriate to the current context
leave
KErrReadOnly Context is read-only
leave
Other Dependent on implementation
If successful, this is an asynchronously completing edit operation. If failed, this is a completed operation, with status set to the relevant error code.
TRequestStatus & aStatus | The request status to be completed when the operation has finished |
const CMsvEntrySelection & aSelection | Selection of message entries |
CMsvOperation * | ForwardL | ( | TMsvId | aDestination, |
TMsvPartList | aPartList, | |||
TRequestStatus & | aCompletionStatus | |||
) | [pure virtual] |
Creates a forwarded message from the current message context, and allows the user to edit it through a message-type specific editor.
Some MTMs may support inclusion of elements, specified by aPartlist, from the original message in the forwarded message. The parent for the new entry is specified in aDestination. The returned CMsvOperation object completes when editing the forwarded message is complete. On completion, the context is set to the forwarded message.
Requirements:
A typical implementation for this function would include the following steps:
1. create a new forwarded message entry by calling CBaseMtm::ForwardL()
2. call EditL() allow the user to edit the forwarded message
3. return a CMsvOperation-derived object to provide asynchronous control and monitoring of the operation
If forwarded messages are not supported, implementations should leave with KErrNotSupported.
If successful, this is an asynchronously completing forward message operation. If failed, this is a completed operation, with status set to the relevant error code.
leave
KErrNotSupported The User Interface MTM does not support message forwarding operations
leave
Other Dependent on implementation
TMsvId aDestination | The entry to which to assign the forwarded message |
TMsvPartList aPartList | Defines the parts which are to be copied from the original message into the forwarded message |
TRequestStatus & aCompletionStatus | The request status to be completed when the operation has finished |
IMPORT_C TInt | GetProgress | ( | const TDesC8 & | aProgress, |
TBuf< EProgressStringMaxLen > & | aReturnString, | |||
TInt & | aTotalEntryCount, | |||
TInt & | aEntriesDone, | |||
TInt & | aCurrentEntrySize, | |||
TInt & | aCurrentBytesTrans | |||
) | const [virtual] |
void | GetResourceFileName | ( | TFileName & | aFileName | ) | const [protected, pure virtual] |
Sets the full path and name of the resource file associated with the User Interface MTM.
Client applications do not use this function. It is relevant only to implementers of derived classes.
Requirements:
The function is called by CBaseMtmUi::ConstructL(), which then loads the resource file.
TFileName & aFileName | Filename buffer to be filled with the resource file path and name |
IMPORT_C CMsvOperation * | InvokeAsyncFunctionL | ( | TInt | aFunctionId, |
const CMsvEntrySelection & | aSelection, | |||
TRequestStatus & | aCompletionStatus, | |||
TDes8 & | aParameter | |||
) | [virtual] |
TInt aFunctionId | |
const CMsvEntrySelection & aSelection | |
TRequestStatus & aCompletionStatus | |
TDes8 & aParameter |
IMPORT_C void | InvokeSyncFunctionL | ( | TInt | aFunctionId, |
const CMsvEntrySelection & | aSelection, | |||
TDes8 & | aParameter | |||
) | [virtual] |
TInt aFunctionId | |
const CMsvEntrySelection & aSelection | |
TDes8 & aParameter |
IMPORT_C CMsvOperation * | MoveFromL | ( | const CMsvEntrySelection & | aSelection, |
TMsvId | aTargetId, | |||
TRequestStatus & | aStatus | |||
) | [virtual] |
const CMsvEntrySelection & aSelection | |
TMsvId aTargetId | |
TRequestStatus & aStatus |
IMPORT_C CMsvOperation * | MoveToL | ( | const CMsvEntrySelection & | aSelection, |
TRequestStatus & | aStatus | |||
) | [virtual] |
const CMsvEntrySelection & aSelection | |
TRequestStatus & aStatus |
CMsvOperation * | OpenL | ( | TRequestStatus & | aStatus | ) | [pure virtual] |
Opens an entry.
The behaviour that this implies is dependent on the current context:
1. for message contexts, OpenL() is the equivalent of EditL(), or for read-only messages, ViewL(). Whether opening of remote messages is allowed is MTM-specific.
2. for service contexts, the function may initiate a connection to obtain the service contents from the server, completing asynchronously
3. for remote folder contexts, dependent on implementation, the function may initiate a connection to obtain the folder contents from the server, completing asynchronously
The returned CMsvOperation object completes when opening is complete.
Requirements:
If opening entries is not supported, implementations should leave with KErrNotSupported. Otherwise, implementations should:
1. check aEntry.iType.iUid to ensure that they can open the requested type of entry and leave with code KErrNotSupported if they cannot
2. return a CMsvOperation-derived object to provide asynchronous control and monitoring of the operation
3. for remote messages, typically, copy the messages to the Inbox
leave
KErrNotSupported The User Interface MTM does not support open operations, or opening is inappropriate to the current context
leave
Other Dependent on implementation
If successful, this is an asynchronously completing open operation. If failed, this is a completed operation, with status set to the relevant error code.
TRequestStatus & aStatus | The request status to be completed when the operation has finished |
CMsvOperation * | OpenL | ( | TRequestStatus & | aStatus, |
const CMsvEntrySelection & | aSelection | |||
) | [pure virtual] |
Opens a selection of entries.
The behaviour that this implies is dependent on the current context:
1. for message contexts, OpenL() is the equivalent of EditL(), or for read-only messages, ViewL(). Whether opening of remote messages is allowed is MTM-specific.
2. for service contexts, the function may initiate a connection to obtain the service contents from the server, completing asynchronously
3. for remote folder contexts, dependent on implementation, the function may initiate a connection to obtain the folder contents from the server, completing asynchronously
The returned CMsvOperation object completes when opening is complete.
Requirements:
If opening entries is not supported, implementations should leave with KErrNotSupported. Otherwise, implementations should:
1. check aEntry.iType.iUid to ensure that they can open the requested type of entry and leave with code KErrNotSupported if they cannot
2. return a CMsvOperation-derived object to provide asynchronous control and monitoring of the operation
3. for remote messages, typically, copy the messages to the Inbox
leave
KErrNotSupported The User Interface MTM does not support open operations, or opening is inappropriate to the current context
leave
Other Dependent on implementation
If successful, this is an asynchronously completing open operation. If failed, this is a completed operation, with status set to the relevant error code.
TRequestStatus & aStatus | The request status to be completed when the operation has finished |
const CMsvEntrySelection & aSelection | Selection of message entries |
IMPORT_C TInt | QueryCapability | ( | TUid | aCapability, |
TInt & | aResponse | |||
) | [virtual] |
CMsvOperation * | ReplyL | ( | TMsvId | aDestination, |
TMsvPartList | aPartlist, | |||
TRequestStatus & | aCompletionStatus | |||
) | [pure virtual] |
Creates a reply message to the current message context, and allows the user to edit it through a message-type specific editor.
Some MTMs may support inclusion of elements, specified by aPartlist, from the original message in the reply. The parent for the new entry is specified in aDestination. The returned CMsvOperation object completes when editing the reply is complete. On completion, the context is set to the reply message.
Requirements:
A typical implementation for this function would include the following steps:
1. create a new reply entry by calling CBaseMtm::ReplyL()
2. call EditL() allow the user to edit the reply
3. return a CMsvOperation-derived object to provide asynchronous control and monitoring of the operation
If message replies are not supported, implementations should leave with KErrNotSupported.
leave
KErrNotSupported The User Interface MTM does not support reply operations
leave
Other Dependent on implementation
If successful, this is an asynchronously completing reply operation. If failed, this is a completed operation, with status set to the relevant error code.
TMsvId aDestination | The entry to which to assign the reply |
TMsvPartList aPartlist | Defines the parts which are to be copied from the original message into the reply. See CBaseMtm::ReplyL() for details. |
TRequestStatus & aCompletionStatus | The request status to be completed when the operation has finished |
IMPORT_C CMsvOperation * | UnDeleteFromL | ( | const CMsvEntrySelection & | aSelection, |
TRequestStatus & | aStatus | |||
) | [virtual] |
const CMsvEntrySelection & aSelection | |
TRequestStatus & aStatus |
CMsvOperation * | ViewL | ( | TRequestStatus & | aStatus | ) | [pure virtual] |
Views an entry.
For message contexts, this usually launches the appropriate message viewer. Other context types leave with KErrNotSupported. The returned CMsvOperation object completes when viewing is complete.
Requirements:
Implementations should:
1. check aEntry.iType.iUid to ensure that they can view the requested type of entry and leave with code KErrNotSupported if they cannot
2. return a CMsvOperation-derived object to provide asynchronous control and monitoring of the operation
leave
KErrNotSupported The User Interface MTM does not support view operations, or viewing is inappropriate to the current context
leave
Other Dependent on implementation
If successful, this is an asynchronously completing view operation. If failed, this is a completed operation, with status set to the relevant error code.
TRequestStatus & aStatus | The request status to be completed when the operation has finished |
CMsvOperation * | ViewL | ( | TRequestStatus & | aStatus, |
const CMsvEntrySelection & | aSelection | |||
) | [pure virtual] |
Views a selection of entries.
For message contexts, this usually launches the appropriate message viewer. Other context types leave with KErrNotSupported. The returned CMsvOperation object completes when viewing is complete.
Requirements:
Implementations should:
1. check aEntry.iType.iUid to ensure that they can view the requested type of entry and leave with code KErrNotSupported if they cannot
2. return a CMsvOperation-derived object to provide asynchronous control and monitoring of the operation
leave
KErrNotSupported The User Interface MTM does not support view operations, or viewing is inappropriate to the current context
leave
Other Dependent on implementation
If successful, this is an asynchronously completing view operation. If failed, this is a completed operation, with status set to the relevant error code.
TRequestStatus & aStatus | The request status to be completed when the operation has finished |
const CMsvEntrySelection & aSelection | Selection of message entries |
Progress information buffer length.
EProgressStringMaxLen = 255 |
Defines the maximum buffer length used in GetProgress() to hold progress information. |
CBaseMtm & | iBaseMtm | [protected] |
The CBaseMtm-derived object (Client-side MTM) that requested the User Interface MTM. It is set by the constructor.