1 // Copyright (c) 1998-2009 Nokia Corporation and/or its subsidiary(-ies).
2 // All rights reserved.
3 // This component and the accompanying materials are made available
4 // under the terms of "Eclipse Public License v1.0"
5 // which accompanies this distribution, and is available
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".
8 // Initial Contributors:
9 // Nokia Corporation - initial contribution.
16 #if !defined(__MTMUIBAS_H__)
17 #define __MTMUIBAS_H__
19 #if !defined(__MSVSTD_H__)
22 #if !defined(__MTCLBASE_H__)
32 // CBaseMtmUi - MTMUi base API //
34 class CBaseMtmUi : public CBase
35 /** Provides MTM-specific user interaction, such as editing, viewing, deleting,
36 and copying of message entries.
38 Message client applications use the class to access such functionality polymorphically.
39 MTM implementers implement a derived class to provide such functionality for
40 their message protocol.
42 The base class is largely an interface definition: it implements little important
43 functionality itself. For implementers, this documentation defines conditions
44 that any implementation must fulfil, plus suggested semantics for behaviour.
45 This still leaves many decisions in the hands of the implementer. A key design
46 time activity is to define how the particular characteristics of the implemented
47 protocol are best mapped to the interface. As this class is concerned with
48 user interfaces, implementers should be sensitive to the look and feel of
51 Many functions are required to return an instance of a CMsvOperation-derived
52 class to provide asynchronous control and monitoring to the caller of the
53 operation being performed.
55 The following are some significant groups of functions:
57 Entry manipulation functions: OpenL(), CloseL(), EditL(), and ViewL() are
58 all available in two overloaded versions. The first version operates on the
59 current context. The second version operates upon groups of entries specified
60 by a CMsvEntrySelection argument. All entries must be in same folder and all
61 of the correct MTM type. The context may change after calling these functions.
62 Concrete User Interface MTMs can legally ignore any of the entries within
63 the selection - many may, for example, simply open the first entry.
65 Copying and moving functions: the CopyToL(), CopyFromL(), MoveToL(), and MoveFromL()
66 functions are concerned with copying and moving entries to and from remote
67 servers. MTMs can implement these functions to provide any user interaction
68 needed before copying or moving can proceed, such as dialogs to confirm settings;
69 and, any protocol-specific setup steps that can be done at this stage: for
70 example, a fax MTM could render messages into the required image format.
72 Progress information functions: DisplayProgressSummary() and GetProgress()
73 convert MTM-specific progress information about some asynchronous operation,
74 such as message sending, to a human-readable form. The progress information
75 to pass into these functions is, in general, obtained from an on-going CMsvOperation
76 by calling CMsvOperation::Progress(). The nature of any information provided
79 MTM-specific UI functions: MTM components can offer protocol-specific functionality
80 not provided by base class interface functions. MTM components define IDs
81 that correspond to each protocol-specific operation offered, and implement
82 the InvokeSyncFunctionL() and InvokeAsyncFunctionL() functions to allow clients
83 to access these operations by passing in the appropriate ID. Two functions
84 are provided to allow the MTM component to offer both synchronous and asynchronous
85 functionality. Message client applications can dynamically add user-interface
86 features for these operations using CBaseMtmUiData::MtmSpecificFunctions().
87 MTM developers should document the IDs if they wish to make the operations
95 /** Progress information buffer length. */
97 /** Defines the maximum buffer length used in GetProgress() to hold progress information. */
98 EProgressStringMaxLen=255};
100 // --- Set up functionality ---
101 IMPORT_C void SetPreferences(TUint aFlags);
102 IMPORT_C TUint Preferences() const;
104 // --- Destruction ---
105 IMPORT_C virtual ~CBaseMtmUi();
107 // --- Accessor functions ---
108 IMPORT_C TUid Type() const;
109 IMPORT_C CBaseMtm& BaseMtm() const;
111 // --- Functions NOT dependent on the current context ---
112 IMPORT_C virtual CMsvOperation* CreateL(const TMsvEntry& aEntry, CMsvEntry& aParent, TRequestStatus& aStatus);
114 // --- Functions dependent on the current context ---
117 The behaviour that this implies is dependent on the current context:
119 1. for message contexts, OpenL() is the equivalent of EditL(), or for read-only
120 messages, ViewL(). Whether opening of remote messages is allowed is MTM-specific.
122 2. for service contexts, the function may initiate a connection to obtain the
123 service contents from the server, completing asynchronously
125 3. for remote folder contexts, dependent on implementation, the function may
126 initiate a connection to obtain the folder contents from the server, completing
129 The returned CMsvOperation object completes when opening is complete.
133 If opening entries is not supported, implementations should leave with KErrNotSupported.
134 Otherwise, implementations should:
136 1. check aEntry.iType.iUid to ensure that they can open the requested type of
137 entry and leave with code KErrNotSupported if they cannot
139 2. return a CMsvOperation-derived object to provide asynchronous control and
140 monitoring of the operation
142 3. for remote messages, typically, copy the messages to the Inbox
144 @param aStatus The request status to be completed when the operation has finished
146 @leave KErrNotSupported The User Interface MTM does not support open operations,
147 or opening is inappropriate to the current context
148 @leave Other Dependent on implementation
149 @return If successful, this is an asynchronously completing open operation.
150 If failed, this is a completed operation, with status set to the relevant
152 virtual CMsvOperation* OpenL(TRequestStatus& aStatus) = 0;
153 /** Closes an entry. The behaviour that this implies is dependent on the current
156 1. for message contexts, this usually closes any launched editors or viewers
158 2. for folder contexts, leaves with KErrNotSupported
160 3. for service contexts, causes closure of a connection to a server
162 The returned CMsvOperation object completes when closing is complete.
166 Implementations should:
168 1. check aEntry.iType.iUid to ensure that they can close the requested type of
169 entry and leave with code KErrNotSupported if they cannot
171 2. return a CMsvOperation-derived object to provide asynchronous control and
172 monitoring of the operation
174 @param aStatus The request status to be completed when the operation has finished
176 @leave KErrNotSupported The User Interface MTM does not support close operations,
177 or closing is inappropriate to the current context
178 @leave Other Dependent on implementation
179 @return If successful, this is an asynchronously completing close operation.
180 If failed, this is a completed operation, with status set to the relevant
182 virtual CMsvOperation* CloseL(TRequestStatus& aStatus) = 0;
185 The behaviour that this implies is dependent on the current
188 1. for message contexts, this usually launches the appropriate message editor,
189 or returns status KErrReadOnly if the message is not editable
191 2. for remote folder contexts, launches a settings dialog, for example to rename
192 the folder, completing asynchronously
194 3. for service contexts, launches a service settings dialog, completing asynchronously
196 The returned CMsvOperation object completes when editing is complete.
200 Implementations should:
202 1. check aEntry.iType.iUid to ensure that they can edit the requested type of
203 entry and leave with code KErrNotSupported if they cannot
205 2. return a CMsvOperation-derived object to provide asynchronous control and
206 monitoring of the operation
208 3. for remote messages, typically, copy the messages to the Inbox
210 4. follow the leave protocols described in Leave considerations below
212 @param aStatus The request status to be completed when the operation has finished
213 @leave KErrNotSupported The User Interface MTM does not support edit operations,
214 or editing is inappropriate to the current context
215 @leave KErrReadOnly Context is read-only
216 @leave Other Dependent on implementation
217 @return If successful, this is an asynchronously completing edit operation.
218 If failed, this is a completed operation, with status set to the relevant
220 virtual CMsvOperation* EditL(TRequestStatus& aStatus) = 0;// Launches editor/settings dialog as appropriate
223 For message contexts, this usually launches the appropriate
224 message viewer. Other context types leave with KErrNotSupported. The returned
225 CMsvOperation object completes when viewing is complete.
229 Implementations should:
231 1. check aEntry.iType.iUid to ensure that they can view the requested type of
232 entry and leave with code KErrNotSupported if they cannot
234 2. return a CMsvOperation-derived object to provide asynchronous control and
235 monitoring of the operation
237 @param aStatus The request status to be completed when the operation has finished
238 @leave KErrNotSupported The User Interface MTM does not support view operations,
239 or viewing is inappropriate to the current context
240 @leave Other Dependent on implementation
241 @return If successful, this is an asynchronously completing view operation.
242 If failed, this is a completed operation, with status set to the relevant
244 virtual CMsvOperation* ViewL(TRequestStatus& aStatus) = 0;// Launches viewer/settings dialog as appropriate
246 // --- Actions upon message selections ---
247 // --- Selections must be in same folder and all of the correct MTM type ---
248 // --- Context may change after calling these functions ---
249 /** Opens a selection of entries.
251 The behaviour that this implies is dependent on the current context:
253 1. for message contexts, OpenL() is the equivalent of EditL(), or for read-only
254 messages, ViewL(). Whether opening of remote messages is allowed is MTM-specific.
256 2. for service contexts, the function may initiate a connection to obtain the
257 service contents from the server, completing asynchronously
259 3. for remote folder contexts, dependent on implementation, the function may
260 initiate a connection to obtain the folder contents from the server, completing
263 The returned CMsvOperation object completes when opening is complete.
267 If opening entries is not supported, implementations should leave with KErrNotSupported.
268 Otherwise, implementations should:
270 1. check aEntry.iType.iUid to ensure that they can open the requested type of
271 entry and leave with code KErrNotSupported if they cannot
273 2. return a CMsvOperation-derived object to provide asynchronous control and
274 monitoring of the operation
276 3. for remote messages, typically, copy the messages to the Inbox
278 @param aStatus The request status to be completed when the operation has finished
279 @param aSelection Selection of message entries
280 @leave KErrNotSupported The User Interface MTM does not support open operations,
281 or opening is inappropriate to the current context
282 @leave Other Dependent on implementation
283 @return If successful, this is an asynchronously completing open operation.
284 If failed, this is a completed operation, with status set to the relevant
286 virtual CMsvOperation* OpenL(TRequestStatus& aStatus, const CMsvEntrySelection& aSelection) = 0;
287 /** Closes a selection of entries.
289 The behaviour that this implies is dependent on the current context:
291 1. for message contexts, this usually closes any launched editors or viewers
293 2. for folder contexts, leaves with KErrNotSupported
295 3. for service contexts, causes closure of a connection to a server
297 The returned CMsvOperation object completes when closing is complete.
301 Implementations should:
303 1. check aEntry.iType.iUid to ensure that they can close the requested type of
304 entry and leave with code KErrNotSupported if they cannot
306 2. return a CMsvOperation-derived object to provide asynchronous control and
307 monitoring of the operation
309 @param aStatus The request status to be completed when the operation has finished
310 @param aSelection Selection of message entries
311 @leave KErrNotSupported The User Interface MTM does not support close operations,
312 or closing is inappropriate to the current context
313 @leave Other Dependent on implementation
314 @return If successful, this is an asynchronously completing close operation.
315 If failed, this is a completed operation, with status set to the relevant
317 virtual CMsvOperation* CloseL(TRequestStatus& aStatus, const CMsvEntrySelection& aSelection) = 0;
318 /** Edits a selection of entries.
320 The behaviour that this implies is dependent on the current context:
322 1. for message contexts, this usually launches the appropriate message editor,
323 or returns status KErrReadOnly if the message is not editable
325 2. for remote folder contexts, launches a settings dialog, for example to rename
326 the folder, completing asynchronously
328 3. for service contexts, launches a service settings dialog, completing asynchronously
330 The returned CMsvOperation object completes when editing is complete.
334 Implementations should:
336 1. check aEntry.iType.iUid to ensure that they can edit the requested type of
337 entry and leave with code KErrNotSupported if they cannot
339 2. return a CMsvOperation-derived object to provide asynchronous control and
340 monitoring of the operation
342 3. for remote messages, typically, copy the messages to the Inbox
344 4. follow the leave protocols described in Leave considerations below
346 @param aStatus The request status to be completed when the operation has finished
347 @param aSelection Selection of message entries
348 @leave KErrNotSupported The User Interface MTM does not support edit operations,
349 or editing is inappropriate to the current context
350 @leave KErrReadOnly Context is read-only
351 @leave Other Dependent on implementation
352 @return If successful, this is an asynchronously completing edit operation.
353 If failed, this is a completed operation, with status set to the relevant
355 virtual CMsvOperation* EditL(TRequestStatus& aStatus, const CMsvEntrySelection& aSelection) = 0;// Launches editor/settings dialog as appropriate
356 /** Views a selection of entries.
358 For message contexts, this usually launches the appropriate
359 message viewer. Other context types leave with KErrNotSupported. The returned
360 CMsvOperation object completes when viewing is complete.
364 Implementations should:
366 1. check aEntry.iType.iUid to ensure that they can view the requested type of
367 entry and leave with code KErrNotSupported if they cannot
369 2. return a CMsvOperation-derived object to provide asynchronous control and
370 monitoring of the operation
372 @param aStatus The request status to be completed when the operation has finished
373 @param aSelection Selection of message entries
374 @leave KErrNotSupported The User Interface MTM does not support view operations,
375 or viewing is inappropriate to the current context
376 @leave Other Dependent on implementation
377 @return If successful, this is an asynchronously completing view operation.
378 If failed, this is a completed operation, with status set to the relevant
380 virtual CMsvOperation* ViewL(TRequestStatus& aStatus, const CMsvEntrySelection& aSelection) = 0;// Launches viewer/settings dialog as appropriate
381 /** Cancels the sending of specified messages.
383 @param aStatus The request status to be completed when the operation has finished
384 @param aSelection Selection of message entries
385 @leave KErrNotSupported The User Interface MTM does not support cancel operations,
386 or cancelling is inappropriate to the current context
387 @leave Other Dependent on implementation
388 @return If successful, this is an asynchronously completing cancel operation.
389 If failed, this is a completed operation, with status set to the relevant
391 virtual CMsvOperation* CancelL(TRequestStatus& aStatus, const CMsvEntrySelection& aSelection) = 0;
394 // --- Deletes entries from the current context, which must be a folder or service of the relevant MTM ---
395 IMPORT_C virtual CMsvOperation* DeleteFromL(const CMsvEntrySelection& aSelection, TRequestStatus& aStatus);//Deletes selection from current context
396 // --- Un-deletes entries from the current context, which must be a folder or service of the relevant MTM ---
397 IMPORT_C virtual CMsvOperation* UnDeleteFromL(const CMsvEntrySelection& aSelection, TRequestStatus& aStatus);//Un-deletes selection from current context
398 // --- Deletes service, which need not be the current context ---
399 IMPORT_C virtual CMsvOperation* DeleteServiceL(const TMsvEntry& aService, TRequestStatus& aStatus); // default implementation simply delegates to the server
401 // --- Message responding ---
402 /** Creates a reply message to the current message context, and allows the user
403 to edit it through a message-type specific editor.
405 Some MTMs may support inclusion of elements, specified by aPartlist, from the original message in the reply.
406 The parent for the new entry is specified in aDestination. The returned CMsvOperation
407 object completes when editing the reply is complete. On completion, the context
408 is set to the reply message.
412 A typical implementation for this function would include the following steps:
414 1. create a new reply entry by calling CBaseMtm::ReplyL()
416 2. call EditL() allow the user to edit the reply
418 3. return a CMsvOperation-derived object to provide asynchronous control and
419 monitoring of the operation
421 If message replies are not supported, implementations should leave with KErrNotSupported.
423 @param aDestination The entry to which to assign the reply
424 @param aPartlist Defines the parts which are to be copied from the original
425 message into the reply. See CBaseMtm::ReplyL() for details.
426 @param aCompletionStatus The request status to be completed when the operation
428 @leave KErrNotSupported The User Interface MTM does not support reply operations
429 @leave Other Dependent on implementation
430 @return If successful, this is an asynchronously completing reply operation.
431 If failed, this is a completed operation, with status set to the relevant
433 virtual CMsvOperation* ReplyL(TMsvId aDestination, TMsvPartList aPartlist, TRequestStatus& aCompletionStatus) = 0;
435 Creates a forwarded message from the current message context, and allows the user to edit it through a message-type
438 Some MTMs may support inclusion of elements, specified by aPartlist, from the original message in the
439 forwarded message. The parent for the new entry is specified in aDestination. The returned CMsvOperation
440 object completes when editing the forwarded message is complete. On completion, the context is set to the forwarded message.
444 A typical implementation for this function would include the following steps:
446 1. create a new forwarded message entry by calling CBaseMtm::ForwardL()
448 2. call EditL() allow the user to edit the forwarded message
450 3. return a CMsvOperation-derived object to provide asynchronous control and monitoring of the operation
452 If forwarded messages are not supported, implementations should leave with KErrNotSupported.
454 @return If successful, this is an asynchronously completing forward message operation. If failed,
455 this is a completed operation, with status set to the relevant error code.
456 @param aDestination The entry to which to assign the forwarded message
457 @param aPartList Defines the parts which are to be copied from the original message into the forwarded message
458 @param aCompletionStatus The request status to be completed when the operation has finished
459 @leave KErrNotSupported The User Interface MTM does not support message forwarding operations
460 @leave Other Dependent on implementation
462 virtual CMsvOperation* ForwardL(TMsvId aDestination, TMsvPartList aPartList, TRequestStatus& aCompletionStatus) = 0;
465 // --- Copy and move functions ---
466 // --- Context should be set to folder or entry of this MTM ---
467 // --- Default implementations imply call the relevant CMsvEntry functions ---
468 IMPORT_C virtual CMsvOperation* CopyToL(const CMsvEntrySelection& aSelection, TRequestStatus& aStatus);// Context should be MTM folder/service to copy to
469 IMPORT_C virtual CMsvOperation* MoveToL(const CMsvEntrySelection& aSelection, TRequestStatus& aStatus);// Context should be MTM folder/service to move to
470 IMPORT_C virtual CMsvOperation* CopyFromL(const CMsvEntrySelection& aSelection, TMsvId aTargetId, TRequestStatus& aStatus);// Context should be MTM folder/service to copy from
471 IMPORT_C virtual CMsvOperation* MoveFromL(const CMsvEntrySelection& aSelection, TMsvId aTargetId, TRequestStatus& aStatus);// Context should be MTM folder/service to move from
473 // --- Interpret transfer progress ---
474 IMPORT_C virtual TInt DisplayProgressSummary(const TDesC8& aProgress) const;// Used for display operation summary (usually completed operations). Default implementation returns KErrNotSupported.
475 IMPORT_C virtual TInt GetProgress(const TDesC8& aProgress, TBuf<EProgressStringMaxLen>& aReturnString, TInt& aTotalEntryCount, TInt& aEntriesDone,
476 TInt& aCurrentEntrySize, TInt& aCurrentBytesTrans) const;// Default implementation returns KErrNotSupported
478 // --- RTTI functions ---
479 IMPORT_C virtual TInt QueryCapability(TUid aCapability, TInt& aResponse);
480 IMPORT_C virtual void InvokeSyncFunctionL(TInt aFunctionId, const CMsvEntrySelection& aSelection, TDes8& aParameter);
481 IMPORT_C virtual CMsvOperation* InvokeAsyncFunctionL(TInt aFunctionId, const CMsvEntrySelection& aSelection, TRequestStatus& aCompletionStatus,
485 // --- Construction ---
486 IMPORT_C CBaseMtmUi(CBaseMtm& aBaseMtm, CRegisteredMtmDll& aRegisteredMtmDll);
487 IMPORT_C virtual void ConstructL();
488 /** Sets the full path and name of the resource file associated with the User Interface MTM.
490 Client applications do not use this function. It is relevant only to implementers of derived classes.
494 The function is called by CBaseMtmUi::ConstructL(), which then loads the resource
497 @param aFileName Filename buffer to be filled with the resource file path
499 virtual void GetResourceFileName(TFileName& aFileName) const = 0;
501 // --- Utility functions ---
502 IMPORT_C CMsvSession& Session() const;
504 // Method used for extension: called by non virtual methods that need
505 // to have a polymorphic behaviour.
506 IMPORT_C virtual TAny* GetInterface(TUid aUid);
510 /** The CBaseMtm-derived object (Client-side MTM) that requested the User Interface
511 MTM. It is set by the constructor. */
513 /** Control environment object. It is set by the constructor. */
515 /** This flag records the preferences as set by SetPreferences(). */
520 CRegisteredMtmDll& iRegisteredMtmDll;
521 TInt iResourceFileOffset;
522 // Extra data member to allow for future extensions
523 TAny* iExtensionData;
527 #endif // __MTMUIBAS_H__