1 /*

     2 * Copyright (c) 2007-2008 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  *  @since S60 v3.1

    45  */

    46 NONSHARABLE_CLASS ( CFSMailBox ) : public CFSMailBoxBase

    47 {

    48  public:

    49   

    50     /**

    51      * Destructor.

    52      */  

    53     IMPORT_C  ~CFSMailBox();

    54 

    55     /**

    56      * two based constructor

    57      *

    58      * @param aMailBoxId mailbox id in plugin containing mailbox

    59      */

    60     IMPORT_C static CFSMailBox* NewL( TFSMailMsgId aMailBoxId );

    61     

    62     /**

    63      * two based constructor

    64      *

    65      * @param aMailBoxId mailbox id in plugin containing mailbox

    66      */

    67      IMPORT_C static CFSMailBox* NewLC( TFSMailMsgId aMailBoxId );

    68     

    69     /**

    70      * Enables synchronization of the mailbox. This means

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

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

    73      * The actual functionality depends on user settings and

    74      * connection implementation.

    75      *

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

    77      * enabled by user settings are synchronized.

    78      *

    79      * This function sets the mailbox online but it may

    80      * have a side effect that also other mailboxes provided

    81      * through the same connection are set online too.

    82      *

    83      * Connection is set offline normally by using specific function

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

    85      * in offline state like network error or scheduling.

    86      * 

    87      */

    88     IMPORT_C void GoOnlineL();

    89 

    90     /**

    91      * Disables mailbox synchronization. Connection to server

    92      * in order to synchronize the mailbox is not allowed

    93      * after this.

    94      *

    95      * If GoOnlineL has effect on other mailboxes using the

    96      * same connection then this function has effect on those

    97      * mailboxes also.

    98      * 

    99      */

   100     IMPORT_C void GoOfflineL();

   101 

   102     /**

   103      * Returns last synchronizing operation progress status.

   104      *

   105      * @return last sync operation progress status

   106      * 

   107      */

   108     IMPORT_C TFSProgress GetLastSyncStatusL();

   109 

   110     /**

   111      * Forces synchronization of mailbox. This can be called

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

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

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

   115      *

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

   117      * enabled by user settings are synchronized.

   118      *     

   119      * This is an asynchronous operation and the request id

   120      * is returned for cancelling purpose.

   121      * 

   122      * User can provide an observer as a parameter,

   123      * which will pass progress notifications during the operation

   124      * as callbacks related to this operation.

   125      *

   126      * Alternatively user can use overloaded parallel implementation

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

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

   129      * as comprehensive as the observing using dedicated observer.

   130      *

   131      * @param aOperationObserver optional observer given by user

   132      *

   133      * @return asynchronous request id

   134      */

   135     IMPORT_C TInt RefreshNowL( MFSMailRequestObserver& aOperationObserver );

   136 

   137     IMPORT_C TInt RefreshNowL();

   138     

   139     /**

   140      * cancels all ongoing synchronizations in this mailbox regardless

   141      * of initiator, by user or by plugin itself

   142      *

   143      */

   144     IMPORT_C void CancelSyncL();

   145 

   146     /**

   147      * creates into this mailbox new draft email 

   148      *

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

   150      */

   151     IMPORT_C CFSMailMessage* CreateMessageToSend();

   152 

   153 // <qmail>  	 

   154     /**

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

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

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

   158      * but via an NmMessageCreationOperation-derived object.

   159      *

   160      * @param aOperationObserver Observer for the operation 

   161      * 

   162      * @return id of the request, KErrNotSupported if the protocol plugin this

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

   164      */

   165      IMPORT_C TInt CreateMessageToSendL( MFSMailRequestObserver& aOperationObserver );

   166 // </qmail>       

   167 

   168 // <qmail> 

   169     /**

   170     * update message flags

   171     * 

   172     * ownership of message pointers is transferred

   173     * 

   174     */

   175     IMPORT_C int UpdateMessageFlagsL( 

   176         const TFSMailMsgId aMailboxId,

   177         RPointerArray<CFSMailMessage> &messages,

   178         MFSMailRequestObserver& aOperationObserver );

   179 // </qmail> 

   180     

   181      /**

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

   183      *

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

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

   186      *  parameter if needed

   187      *

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

   189      */

   190     IMPORT_C CFSMailMessage* CreateForwardMessage( const TFSMailMsgId aOriginalMessageId,

   191                             const TDesC& aHeaderDescriptor = KNullDesC );

   192 

   193 // <qmail>       

   194     /**

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

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

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

   198      *

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

   200      * @param aOperationObserver Observer for the operation 

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

   202      *  parameter if needed

   203      *

   204      * @return id of the request

   205      */

   206     IMPORT_C TInt CreateForwardMessageL( const TFSMailMsgId aOriginalMessageId,

   207                             MFSMailRequestObserver& aOperationObserver,

   208                             const TDesC& aHeaderDescriptor = KNullDesC );

   209 // </qmail>       

   210 

   211     /**

   212      * creates into this mailbox new email for reply

   213      *

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

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

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

   217      *  parameter if needed

   218      *

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

   220      */

   221     IMPORT_C CFSMailMessage* CreateReplyMessage( const TFSMailMsgId aOriginalMessageId,

   222                             const TBool aReplyToAll,

   223                             const TDesC& aHeaderDescriptor = KNullDesC );

   224 

   225 // <qmail>       

   226     /**

   227      * creates into this mailbox new email for reply

   228      *

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

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

   231      * @param aOperationObserver Observer for the operation 

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

   233      *  parameter if needed

   234      *

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

   236      */

   237     IMPORT_C TInt CreateReplyMessageL( const TFSMailMsgId aOriginalMessageId,

   238                                       const TBool aReplyToAll,

   239                                       MFSMailRequestObserver& aOperationObserver,

   240                                       const TDesC& aHeaderDescriptor = KNullDesC );

   241 // </qmail>       

   242 

   243     /**

   244      * sends email

   245      *

   246      * @param aMessage message to be sent

   247      */

   248     IMPORT_C void SendMessageL( CFSMailMessage& aMessage );

   249 

   250 // <qmail>

   251     /**

   252      * sends email

   253      *

   254      * @param aMessage message to be sent

   255      */

   256     IMPORT_C TInt SendMessageL( CFSMailMessage& aMessage,

   257                                 MFSMailRequestObserver& aOperationObserver );

   258 

   259 // </qmail>

   260 

   261     /**

   262      * List subfolders of given folder.

   263      * Only direct subfolders of given folder are returned.

   264        *

   265        * folder data : 

   266        * - folder id

   267        * - folder name

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

   269        * - message count

   270        * - unread message count

   271        * - mailbox id 

   272        * - parent folder

   273        * - subfolder count

   274        *

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

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

   277        */

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

   279 

   280       /**

   281        * List all subfolders of mailbox.

   282        *

   283        * folder data : 

   284        * - folder id

   285        * - folder name

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

   287        * - message count

   288        * - unread message count

   289        * - mailbox id 

   290        * - parent folder

   291        * - subfolder count

   292        *

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

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

   295        */

   296     IMPORT_C RPointerArray<CFSMailFolder>& ListFolders(); 

   297 

   298     /**

   299      * Standard folder id accessor.

   300      *

   301      * @param aFolderType defines folder type

   302      * @return standard folder id

   303      */

   304     IMPORT_C TFSMailMsgId GetStandardFolderId( const TFSFolderType aFolderType );

   305 

   306 

   307     /**

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

   309      * to associate mailbox to a branding definition.

   310      *

   311      * @return branding id

   312      */

   313     IMPORT_C TDesC& GetBrandingIdL( );

   314 

   315 

   316     /**

   317      * Moves a messages between folders.

   318      *

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

   320      * @param aSourceFolderId source folder id

   321      * @param aDestinationFolderId destination folder id

   322      */    

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

   324                                  const TFSMailMsgId aSourceFolderId, 

   325                                  const TFSMailMsgId aDestinationFolderId );

   326 

   327     /**

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

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

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

   331      *  otherwise this function leaves with KErrNotReady)

   332      *

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

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

   335      *        owned by user

   336      * @param aSourceFolderId source folder id

   337      * @param aDestinationFolderId destination folder id

   338      */    

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

   340                                  RArray<TFSMailMsgId>& aCopiedMessages,

   341                                  const TFSMailMsgId aSourceFolderId, 

   342                                  const TFSMailMsgId aDestinationFolderId );

   343                                   

   344     /**

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

   346      * performed at a time.

   347      *

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

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

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

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

   352      *  

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

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

   355      * results generated by the same search string.

   356      *    

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

   358    *

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

   360      * otherwise this function leaves with KErrNotReady

   361      *

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

   363    * @param aSortCriteria sort criteria for the results

   364    * @param aSortCriteria sort criteria for the results

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

   366      */    

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

   368                            const TFSMailSortCriteria& aSortCriteria,

   369                            MFSMailBoxSearchObserver& aSearchObserver );

   370 

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

   372                            const TFSMailSortCriteria& aSortCriteria,

   373                            MFSMailBoxSearchObserver& aSearchObserver,

   374                            RArray<TFSMailMsgId> aFolderIds );

   375     /**

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

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

   378      *

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

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

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

   382      *       cache be cleaned.

   383      */    

   384     IMPORT_C void CancelSearch();

   385 

   386     /**

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

   388      *        

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

   390      * 

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

   392      */

   393     IMPORT_C void ClearSearchResultCache();

   394 

   395     /**

   396      * DEPRECATED

   397      *

   398      * @param aFolderId...

   399      * @param aObserver observer

   400      */    

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

   402 

   403     /** 

   404      *  Get a list of most recently used addresses of this mailbox.

   405      *  Each MRU entry consists of two descriptors placed sequentially

   406      *  in the array. First one is the display name and the second

   407      *  one is the actual email address. If for example some entry does

   408      *  not contain a name at all then a KNullDesC is found in place of

   409      *  the name.

   410      *        

   411      * @return Array of descriptors containing MRUs. Ownership

   412      *         is transferred. Empty if no entries are found.

   413      */

   414     IMPORT_C MDesCArray* ListMrusL() const;

   415 

   416     /**

   417      * Returns the current synchronizing state of this mailbox.

   418      *

   419      * @return mailbox synchronizing state data structure

   420      */

   421     IMPORT_C TSSMailSyncState CurrentSyncState() const;

   422 

   423     /**

   424      * mailbox capability check for user

   425      *

   426      * @param aCapa mailbox capability to be checked

   427      */

   428     IMPORT_C TBool HasCapability( const TFSMailBoxCapabilities aCapability ) const; 

   429 

   430     /**

   431      * mailbox connection status accessor

   432      *

   433      * @return connection status, online / offline

   434      */

   435     IMPORT_C TFSMailBoxStatus GetMailBoxStatus( );

   436 

   437     /**

   438      * mailbox authentication data mutator

   439      *

   440      * @param aUsername account user name

   441      * @param aPassword account password

   442      */

   443      IMPORT_C void SetCredentialsL( const TDesC& aUsername, const TDesC& aPassword );

   444 

   445      /**

   446       * removes downloaded attachments from local/terminal memory 

   447       */

   448      IMPORT_C void RemoveDownLoadedAttachmentsL();

   449    

   450      /**

   451       * reads connection id from plugin

   452       *

   453       * @param  aConnectionId reference to connection id

   454       * @return KErrNone or error code

   455       */

   456      IMPORT_C TInt GetConnectionId( TUint32& aConnectionId );

   457 

   458      /**

   459       * checks from plugin if connection is allowed when roaming

   460       *

   461       * @param  aConnectionAllowed 

   462       * @return KErrNone or error code

   463       */

   464      IMPORT_C TInt IsConnectionAllowedWhenRoaming( TBool& aConnectionAllowed ) ;

   465    

   466 private:

   467 

   468     /**

   469      * Two-phased constructor

   470      */

   471      void ConstructL( TFSMailMsgId aMailBoxId );

   472 

   473     /**

   474      * C++ default constructor.

   475      */

   476      CFSMailBox();

   477 

   478     /**

   479      * Function used internally to inform that Mru list related to this

   480      * mailbox should now be updated using the given recipient info. In

   481      * other words this function makes sure that the given recipients are

   482      * found from the mru list in which the mrus of this mailbox are stored.

   483      * Mrus are stored in the plugin.

   484      *

   485      * @param aRecipients email recipients in TO-field

   486      * @param aCCRecipients email recipients in CC-field

   487      * @param aBCCRecipients email recipients in BCC-field

   488      */

   489     void UpdateMrusL(

   490         const RPointerArray<CFSMailAddress>& aRecipients,

   491         const RPointerArray<CFSMailAddress>& aCCRecipients,

   492         const RPointerArray<CFSMailAddress>& aBCCRecipients ) const;

   493     

   494     /**

   495      * Function used to copy array contents to another array.

   496      *

   497      * @param aArrayToBeCopied Array that should be copied. 

   498      * @return Copy of the given array.

   499      */

   500     CDesCArraySeg* CopyArrayL( MDesCArray& aArrayToBeCopied ) const;

   501 

   502 

   503     /**

   504      * Function used to update given mru list with

   505      * recently used address info. If this info is already found

   506      * from the mru list then it is moved to the end of the mru list.

   507      * This way the most recent ones are found from the end

   508      * of the list.

   509      *

   510      * @param aMruList Mru list that should be updated.

   511      * @param aNewRecentlyUsedOnes Addresses that should be used

   512      *                             to update the given mru list.

   513      */

   514     void UpdateMruListL(

   515         CDesCArraySeg& aMruList,

   516         const RPointerArray<CFSMailAddress>& aNewRecentlyUsedOnes ) const;

   517 

   518 

   519     /**

   520      * Function used to search an address from given mru list.

   521      * Fucntion goes through the addresses in the mru list

   522      * and returns the first one matching the given address.

   523      *

   524      * @param aMruList Mru list that is searched through.

   525      * @param searchedAddress Address that is searched from the

   526      *                        given mru list.

   527      * @param aPos Reference parameter used to return the position

   528      *             of a matching address if such was found.

   529      * @return Integer value to indicate whether the searched address

   530      *         was found or not. Zero is returned if the address was found.

   531      *         Otherwise 1 is returned.

   532      */

   533     TInt FindAddressFromMruList( CDesCArraySeg& aMruList,

   534                              TDesC& searchedAddress,

   535                              TInt& aPos ) const;

   536 

   537     /**

   538      * Removes the oldest entry from the mru list and adds

   539      * given address info to the mru list. 

   540      *

   541      * @param aMruList Mru list.

   542      * @param aToBeAdded Address info to be added into the mru list.

   543      */

   544     void AddAndRemoveExcessMruL( CDesCArraySeg& aMruList,

   545                                  CFSMailAddress& aToBeAdded ) const;

   546 

   547     /**

   548      * Function to append mru entry to the mru list. This implementation

   549      * adds display name and then the address in this order into the

   550      * mru list.

   551      *

   552      * @param aMruList Mru list.

   553      * @param aToBeAdded Address info to be added into the mru list.

   554      */

   555     void AppendMruItemL( CDesCArraySeg& aMruList,

   556                          CFSMailAddress& aToBeAppended ) const;

   557 

   558     /**

   559      * Function to set the already existing entry in the mru list

   560      * as the most recent one.

   561      *

   562      * @param aMruList Mru list that should be edited.

   563      * @param aPosition Position where from the address element of

   564      *                  the most recent address is found. The display

   565      *                  name of the address is found with index one less

   566      *                  from the mru list.

   567      * @param aMostRecent After removal of the mru entry with given index,

   568      *                    this entry is added into the mru list as the

   569      *                    most recently used one.

   570      */

   571     void SetAsMostRecentMruL( CDesCArraySeg& aMruList,

   572                               TInt aPosition,

   573                               CFSMailAddress& aMostRecent ) const;

   574 

   575  private: // data

   576  

   577     /**

   578      * request handler for plugin requests

   579      */

   580     CFSMailRequestHandler*   iRequestHandler;  

   581 

   582     /**

   583      * mailbox folder list

   584      */

   585     RPointerArray<CFSMailFolder> iFolders;

   586 

   587 };

   588 

   589 #endif