1 /*

     2 * Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  common mailbox object

    15 *

    16 */

    17 

    18 

    19 #ifndef __CFSMAILBOX_H

    20 #define __CFSMAILBOX_H

    21 

    22 

    23 // <qmail>

    24 #include <badesca.h>

    25 // </qmail>

    26 #include "CFSMailBoxBase.h"

    27 

    28 // forward declarations

    29 class CFSMailPlugin;

    30 class MFSMailBoxSearchObserver;

    31 class MFSMailEventObserver;

    32 class MFSMailRequestObserver;

    33 

    34 // <qmail>

    35 class CFSMailFolder;

    36 class CFSMailMessage;

    37 class CFSMailRequestHandler;

    38 // </qmail>

    39 

    40 /**

    41  *  mailbox data handling

    42  *

    43  *  @lib FSFWCommonLib

    44  */

    45 NONSHARABLE_CLASS ( CFSMailBox ) : public CFSMailBoxBase

    46 {

    47  public:

    48   

    49     /**

    50      * Destructor.

    51      */  

    52     IMPORT_C  ~CFSMailBox();

    53 

    54     /**

    55      * two based constructor

    56      *

    57      * @param aMailBoxId mailbox id in plugin containing mailbox

    58      */

    59   	 IMPORT_C static CFSMailBox* NewL( TFSMailMsgId aMailBoxId	);

    60   	

    61     /**

    62      * two based constructor

    63      *

    64      * @param aMailBoxId mailbox id in plugin containing mailbox

    65      */

    66   	 IMPORT_C static CFSMailBox* NewLC( TFSMailMsgId aMailBoxId );

    67   	

    68     /**

    69      * Enables synchronization of the mailbox. This means

    70      * that the framework can connect to server to do synchronization

    71      * of the mailbox when necessary or stay connected all the time.

    72      * The actual functionality depends on user settings and

    73      * connection implementation.

    74      *

    75      * All collections (mail etc.) supported by the connection and

    76      * enabled by user settings are synchronized.

    77      *

    78      * This function sets the mailbox online but it may

    79      * have a side effect that also other mailboxes provided

    80      * through the same connection are set online too.

    81      *

    82      * Connection is set offline normally by using specific function

    83      * for this purpose. There are also other reasons for ending up

    84      * in offline state like network error or scheduling.

    85      * 

    86 	 */

    87      IMPORT_C void GoOnlineL();

    88 

    89     /**

    90      * Disables mailbox synchronization. Connection to server

    91      * in order to synchronize the mailbox is not allowed

    92      * after this.

    93      *

    94      * If GoOnlineL has effect on other mailboxes using the

    95      * same connection then this function has effect on those

    96      * mailboxes also.

    97      * 

    98 	 */

    99      IMPORT_C void GoOfflineL();

   100 

   101     /**

   102      * Returns last synchronizing operation progress status.

   103      *

   104      * @return last sync operation progress status

   105      * 

   106 	 */

   107      IMPORT_C TFSProgress GetLastSyncStatusL();

   108 

   109     /**

   110      * Forces synchronization of mailbox. This can be called

   111      * whether the mailbox is currently offline or online. In the

   112      * case the mailbox is offline in the beginning, connection

   113      * is made up for the time of the synchronization.

   114      *

   115      * All collections (mail etc.) supported by the connection and

   116      * enabled by user settings are synchronized.

   117      *     

   118      * This is an asynchronous operation and the request id

   119      * is returned for cancelling purpose.

   120      * 

   121      * User can provide an observer as a parameter,

   122      * which will pass progress notifications during the operation

   123      * as callbacks related to this operation.

   124      *

   125      * Alternatively user can use overloaded parallel implementation

   126      * of function without an observer function and rely only on

   127      * general events. Notice that the general event system is not

   128      * as comprehensive as the observing using dedicated observer.

   129      *

   130      * @param aOperationObserver optional observer given by user

   131      *

   132      * @return asynchronous request id

   133 	 */

   134      IMPORT_C TInt RefreshNowL( MFSMailRequestObserver& aOperationObserver );

   135 

   136      IMPORT_C TInt RefreshNowL( );

   137   	

   138     /**

   139      * cancels all ongoing synchronizations in this mailbox regardless

   140      * of initiator, by user or by plugin itself

   141      *

   142 	 */

   143      IMPORT_C void CancelSyncL();

   144 

   145     /**

   146      * creates into this mailbox new draft email 

   147      *

   148      * @return new draft email object, ownership is transferred to user

   149      */

   150   	 IMPORT_C CFSMailMessage* CreateMessageToSend( );

   151 

   152 // <qmail>  	 

   153     /**

   154      * Creates a new draft email into this mailbox asynchronously. When the operation

   155      * finishes, RequestResponseL is called on the observer and the created message is 

   156      * passed along with the TFSProgress data. UI should not use this method directly

   157      * but via an NmMessageCreationOperation-derived object.

   158      *

   159      * @param aOperationObserver Observer for the operation 

   160      * 

   161      * @return id of the request, KErrFSMailPluginNotSupported if the protocol plugin this

   162      * instance is attached to does not support the async method.

   163      */

   164      IMPORT_C TInt CreateMessageToSendL( MFSMailRequestObserver& aOperationObserver );

   165 // </qmail>       

   166 

   167 // <qmail> 

   168     /**

   169     * update message flags

   170     * 

   171     * ownership of message pointers is transferred

   172     * 

   173     */

   174     IMPORT_C int UpdateMessageFlagsL( 

   175         const TFSMailMsgId aMailboxId,

   176         RPointerArray<CFSMailMessage> &messages,

   177         MFSMailRequestObserver& aOperationObserver );

   178 // </qmail> 

   179     

   180     /**

   181      * creates into this mailbox new draft email to be forwarded 

   182      *

   183      * @param aOriginalMessageId message id of the original message to be forwarded

   184      * @param aHeaderDescriptor user can give quote headers data to plugin as

   185      *  parameter if needed

   186      *

   187      * @return new draft email object, ownership is transferred to user

   188      */

   189   	 IMPORT_C CFSMailMessage* CreateForwardMessage( const TFSMailMsgId aOriginalMessageId,

   190   	 												const TDesC& aHeaderDescriptor = KNullDesC  );

   191 

   192 // <qmail>       

   193     /**

   194      * creates into this mailbox new draft email to be forwarded asynchronously

   195      * When the operation finishes, RequestResponseL is called on the observer and 

   196      * the created message is passed along with the TFSProgress data.

   197      *

   198      * @param aOriginalMessageId message id of the original message to be forwarded

   199      * @param aOperationObserver Observer for the operation 

   200      * @param aHeaderDescriptor user can give quote headers data to plugin as

   201      *  parameter if needed

   202      *

   203      * @return id of the request

   204      */

   205     IMPORT_C TInt CreateForwardMessageL( const TFSMailMsgId aOriginalMessageId,

   206                             MFSMailRequestObserver& aOperationObserver,

   207                             const TDesC& aHeaderDescriptor = KNullDesC );

   208 // </qmail>       

   209 

   210     /**

   211      * creates into this mailbox new email for reply

   212      *

   213      * @param aOriginalMessageId id of the original message to be replied

   214      * @param aReplyToAll is set true if reply to all is requested

   215      * @param aHeaderDescriptor user can give quote headers data to plugin as

   216      *  parameter if needed

   217      *

   218      * @return new draft email object, ownership is transferred to user

   219      */

   220   	 IMPORT_C CFSMailMessage* CreateReplyMessage(	const TFSMailMsgId aOriginalMessageId,

   221   	 							 					const TBool aReplyToAll,

   222   	 							 					const TDesC& aHeaderDescriptor = KNullDesC  );

   223 

   224 // <qmail>       

   225     /**

   226      * creates into this mailbox new email for reply

   227      *

   228      * @param aOriginalMessageId id of the original message to be replied

   229      * @param aReplyToAll is set true if reply to all is requested

   230      * @param aOperationObserver Observer for the operation 

   231      * @param aHeaderDescriptor user can give quote headers data to plugin as

   232      *  parameter if needed

   233      *

   234      * @return new draft email object, ownership is transferred to user

   235      */

   236     IMPORT_C TInt CreateReplyMessageL( const TFSMailMsgId aOriginalMessageId,

   237                                       const TBool aReplyToAll,

   238                                       MFSMailRequestObserver& aOperationObserver,

   239                                       const TDesC& aHeaderDescriptor = KNullDesC );

   240 // </qmail>       

   241 

   242     /**

   243      * sends email

   244      *

   245      * @param aMessage message to be sent

   246      */

   247 	 IMPORT_C void SendMessageL(CFSMailMessage& aMessage);

   248 

   249 // <qmail>

   250     /**

   251      * sends email

   252      *

   253      * @param aMessage message to be sent

   254      */

   255     IMPORT_C TInt SendMessageL( CFSMailMessage& aMessage,

   256                                 MFSMailRequestObserver& aOperationObserver );

   257 

   258 // </qmail>

   259 

   260     /**

   261 	 * List subfolders of given folder.

   262 	 * Only direct subfolders of given folder are returned.

   263 	 *

   264 	 * folder data : 

   265 	 * - folder id

   266 	 * - folder name

   267 	 * - folder type ; Inbox, Outbox, Sent, Drafts, Deleted, Other

   268 	 * - message count

   269 	 * - unread message count

   270 	 * - mailbox id 

   271 	 * - parent folder

   272 	 * - subfolder count

   273 	 *

   274 	 * @param aFolderId defines parent folder id. TFSMailId::NullId() for root level list.

   275 	 * @param aFolderList plugin writes results in this array owned by user

   276 	 */

   277 	 IMPORT_C void ListFolders( const TFSMailMsgId aFolderId, RPointerArray<CFSMailFolder>& aFolderList); 

   278 

   279 	/**

   280 	 * List all subfolders of mailbox.

   281 	 *

   282 	 * folder data : 

   283 	 * - folder id

   284 	 * - folder name

   285 	 * - folder type ; Inbox, Outbox, Sent Items, Drafts, Deleted Items, Other

   286 	 * - message count

   287 	 * - unread message count

   288 	 * - mailbox id 

   289 	 * - parent folder

   290 	 * - subfolder count

   291 	 *

   292 	 * @return results in this array owned by this object, caller must determine

   293 	 *         tree structure by examining parent id of each returned folder.

   294 	 */

   295 	 IMPORT_C RPointerArray<CFSMailFolder>& ListFolders(  ); 

   296 

   297     /**

   298      * Standard folder id accessor.

   299      *

   300      * @param aFolderType defines folder type

   301      * @return standard folder id

   302      */

   303 	 IMPORT_C TFSMailMsgId GetStandardFolderId( const TFSFolderType aFolderType );

   304 

   305 

   306     /**

   307      * Branding id accessor for this mailbox. This function is used by Branding Manager

   308      * to associate mailbox to a branding definition.

   309      *

   310      * @return branding id

   311      */

   312      IMPORT_C TDesC& GetBrandingIdL( );

   313 

   314 

   315     /**

   316      * Moves a messages between folders.

   317      *

   318      * @param aMessageIds ids of the messages to be transferred

   319      * @param aSourceFolderId source folder id

   320      * @param aDestinationFolderId destination folder id

   321      */    

   322      IMPORT_C void MoveMessagesL( const RArray<TFSMailMsgId>& aMessageIds, 

   323                                   const TFSMailMsgId aSourceFolderId, 

   324                                   const TFSMailMsgId aDestinationFolderId );

   325 

   326      /**

   327      * Moves a messages between folders. Async version.

   328      *                            

   329      * @param MFSMailRequestObserver& aOperationObserver for callback

   330      * @param aMessageIds ids of the messages to be transferred

   331      * @param aSourceFolderId source folder id

   332      * @param aDestinationFolderId destination folder id

   333      */    

   334 	 IMPORT_C TInt MoveMessagesL( MFSMailRequestObserver& aOperationObserver,

   335                                   const RArray<TFSMailMsgId>& aMessageIds, 

   336                                   const TFSMailMsgId aSourceFolderId, 

   337                                   const TFSMailMsgId aDestinationFolderId );

   338     /**

   339      * Copies a messages from one folder to another folder.

   340      * including the properties, content, and all attachments. 

   341      * (note only works if the store is in an authenticated state,

   342      *  otherwise this function leaves with KErrNotReady)

   343      *

   344      * @param aMessageIds ids of the messages to be copied

   345      * @param aCopiedMessages table containing (new) ids of the copied messages

   346      *        owned by user

   347      * @param aSourceFolderId source folder id

   348      * @param aDestinationFolderId destination folder id

   349      */    

   350      IMPORT_C void CopyMessagesL(	const RArray<TFSMailMsgId>& aMessageIds, 

   351 							  		RArray<TFSMailMsgId>& aCopiedMessages,

   352                               		const TFSMailMsgId aSourceFolderId, 

   353                               		const TFSMailMsgId aDestinationFolderId );

   354                               		

   355     /**

   356      * Asyncronous call for starting search for given string. Only one search can be

   357      * performed at a time.

   358      *

   359      * This function will search for message's containing the given search string.

   360      * The search will be performed on the all message fields: To, Cc, Bcc, subject, body.

   361      * The search client will be notified of each found message,

   362      * and upon completion of the search.  Only one search can be performed at a time.  

   363      *  

   364      * To change the sort order in the search result, use the same search string in the

   365      * but change the aSortCriteria parameter.  The store "caches" the search

   366      * results generated by the same search string.

   367      *    

   368      * The function will leave with KErrInUse if a search is already in progress.

   369 	 *

   370      * note only works if the store is in an authenticated state,

   371      * otherwise this function leaves with KErrNotReady

   372      *

   373      * @param aSearchStrings text strings that will be searched from different message fields.

   374 	 * @param aSortCriteria sort criteria for the results

   375 	 * @param aSortCriteria sort criteria for the results

   376      * @param aFolderIds user can give list of folders to be searched

   377      */    

   378 	 IMPORT_C void SearchL( const RPointerArray<TDesC>& aSearchStrings,

   379 						    const TFSMailSortCriteria& aSortCriteria,

   380 					 	    MFSMailBoxSearchObserver& aSearchObserver );

   381 

   382     /**

   383      * Cancels current search. Does nothing if there is not any search ongoing.

   384      * The search client will not be called back after this function is called.

   385 	 *

   386      * note CancelSearch() method does NOT clear the search result cached in the store. 

   387      *       A different sort order can be used for the same search string, and the 

   388      *       cache will be utilized.  Only by using a different search string can the

   389      *       cache be cleaned.

   390      */    

   391 	 IMPORT_C void CancelSearch();

   392 

   393     /**

   394      * Inform the store to clean up its cache for search results.

   395      *        

   396      *  This method cancels the the ongoing search (if exists), and then clean ups store's cache.

   397      * 

   398      *  This function should be called by the UI when search results are no longer in display.

   399      */

   400      IMPORT_C void ClearSearchResultCache();

   401 

   402 	/**

   403 	 * DEPRECATED

   404 	 *

   405      * @param aFolderId...

   406      * @param aObserver observer

   407      */    

   408 	 IMPORT_C void AddObserver(const TFSMailMsgId aFolderId, MFSMailEventObserver& aObserver);

   409 

   410     /**

   411      * Returns the current synchronizing state of this mailbox.

   412      *

   413      * @return mailbox synchronizing state data structure

   414      */

   415      IMPORT_C TSSMailSyncState CurrentSyncState() const;

   416 

   417     /**

   418      * mailbox connection status accessor

   419      *

   420      * @return connection status, online / offline

   421      */

   422 	    IMPORT_C TFSMailBoxStatus GetMailBoxStatus( );

   423 

   424 

   425 public: // from  CExtendableEmail

   426 

   427      /**

   428      * @see CExtendableEmail::ReleaseExtension()

   429      */

   430      IMPORT_C void ReleaseExtension( CEmailExtension* aExtension );

   431 

   432      /**

   433       * Returns extension by uid, leaves KErrNotSupported if extension is

   434       * not available.

   435       * @param aInterfaceUid extension interface uid

   436       * @return extension pointer. Ownership depends on extension.

   437       */

   438      IMPORT_C CEmailExtension* ExtensionL( const TUid& aInterfaceUid );

   439 

   440 private:

   441 

   442   	/**

   443      * Two-phased constructor

   444      */

   445   	 void ConstructL( TFSMailMsgId aMailBoxId );

   446 

   447     /**

   448      * C++ default constructor.

   449      */

   450   	 CFSMailBox();

   451 

   452 

   453  private: // data

   454  

   455     /**

   456      * request handler for plugin requests

   457      */

   458 	 CFSMailRequestHandler* 	iRequestHandler;	

   459 

   460 	/**

   461      * mailbox folder list

   462      */

   463 	 RPointerArray<CFSMailFolder> iFolders;

   464 

   465 };

   466 

   467 #endif