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 #include "cfsmailboxbase.h"

    23 

    24 // forward declarations

    25 class CFSMailPlugin;

    26 class MFSMailBoxSearchObserver;

    27 class MFSMailEventObserver;

    28 class MFSMailRequestObserver;

    29 

    30 /**

    31  *  mailbox data handling

    32  *

    33  *  @lib FSFWCommonLib

    34 

    35  */

    36 class CFSMailBox : public CFSMailBoxBase

    37 {

    38  public:

    39   

    40     /**

    41      * Destructor.

    42      */  

    43   	 ~CFSMailBox();

    44 

    45     /**

    46      * two based constructor

    47      *

    48      * @param aMailBoxId mailbox id in plugin containing mailbox

    49      */

    50   	 IMPORT_C static CFSMailBox* NewL( TFSMailMsgId aMailBoxId	);

    51   	

    52     /**

    53      * two based constructor

    54      *

    55      * @param aMailBoxId mailbox id in plugin containing mailbox

    56      */

    57   	 IMPORT_C static CFSMailBox* NewLC( TFSMailMsgId aMailBoxId );

    58   	

    59     /**

    60      * Enables synchronization of the mailbox. This means

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

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

    63      * The actual functionality depends on user settings and

    64      * connection implementation.

    65      *

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

    67      * enabled by user settings are synchronized.

    68      *

    69      * This function sets the mailbox online but it may

    70      * have a side effect that also other mailboxes provided

    71      * through the same connection are set online too.

    72      *

    73      * Connection is set offline normally by using specific function

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

    75      * in offline state like network error or scheduling.

    76      * 

    77 	 */

    78      IMPORT_C void GoOnlineL();

    79 

    80     /**

    81      * Disables mailbox synchronization. Connection to server

    82      * in order to synchronize the mailbox is not allowed

    83      * after this.

    84      *

    85      * If GoOnlineL has effect on other mailboxes using the

    86      * same connection then this function has effect on those

    87      * mailboxes also.

    88      * 

    89 	 */

    90      IMPORT_C void GoOfflineL();

    91 

    92     /**

    93      * Returns last synchronizing operation progress status.

    94      *

    95      * @return last sync operation progress status

    96      * 

    97 	 */

    98      IMPORT_C TFSProgress GetLastSyncStatusL();

    99 

   100     /**

   101      * Forces synchronization of mailbox. This can be called

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

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

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

   105      *

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

   107      * enabled by user settings are synchronized.

   108      *     

   109      * This is an asynchronous operation and the request id

   110      * is returned for cancelling purpose.

   111      * 

   112      * User can provide an observer as a parameter,

   113      * which will pass progress notifications during the operation

   114      * as callbacks related to this operation.

   115      *

   116      * Alternatively user can use overloaded parallel implementation

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

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

   119      * as comprehensive as the observing using dedicated observer.

   120      *

   121      * @param aOperationObserver optional observer given by user

   122      *

   123      * @return asynchronous request id

   124 	 */

   125      IMPORT_C TInt RefreshNowL( MFSMailRequestObserver& aOperationObserver );

   126 

   127      IMPORT_C TInt RefreshNowL( );

   128   	

   129     /**

   130      * cancels all ongoing synchronizations in this mailbox regardless

   131      * of initiator, by user or by plugin itself

   132      *

   133 	 */

   134      IMPORT_C void CancelSyncL();

   135 

   136     /**

   137      * creates into this mailbox new draft email 

   138      *

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

   140      */

   141   	 IMPORT_C CFSMailMessage* CreateMessageToSend( );

   142 

   143     /**

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

   145      *

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

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

   148      *  parameter if needed

   149      *

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

   151      */

   152   	 IMPORT_C CFSMailMessage* CreateForwardMessage( const TFSMailMsgId aOriginalMessageId,

   153   	 												const TDesC& aHeaderDescriptor = KNullDesC  );

   154 

   155     /**

   156      * creates into this mailbox new email for reply

   157      *

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

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

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

   161      *  parameter if needed

   162      *

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

   164      */

   165   	 IMPORT_C CFSMailMessage* CreateReplyMessage(	const TFSMailMsgId aOriginalMessageId,

   166   	 							 					const TBool aReplyToAll,

   167   	 							 					const TDesC& aHeaderDescriptor = KNullDesC  );

   168     /**

   169      * sends email

   170      *

   171      * @param aMessage message to be sent

   172      */

   173 	 IMPORT_C void SendMessageL(CFSMailMessage& aMessage);

   174 

   175 	/**

   176 	 * List subfolders of given folder.

   177 	 * Only direct subfolders of given folder are returned.

   178 	 *

   179 	 * folder data : 

   180 	 * - folder id

   181 	 * - folder name

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

   183 	 * - message count

   184 	 * - unread message count

   185 	 * - mailbox id 

   186 	 * - parent folder

   187 	 * - subfolder count

   188 	 *

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

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

   191 	 */

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

   193 

   194 	/**

   195 	 * List all subfolders of mailbox.

   196 	 *

   197 	 * folder data : 

   198 	 * - folder id

   199 	 * - folder name

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

   201 	 * - message count

   202 	 * - unread message count

   203 	 * - mailbox id 

   204 	 * - parent folder

   205 	 * - subfolder count

   206 	 *

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

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

   209 	 */

   210 	 IMPORT_C RPointerArray<CFSMailFolder>& ListFolders(  ); 

   211 

   212     /**

   213      * Standard folder id accessor.

   214      *

   215      * @param aFolderType defines folder type

   216      * @return standard folder id

   217      */

   218 	 IMPORT_C TFSMailMsgId GetStandardFolderId( const TFSFolderType aFolderType );

   219 

   220 

   221     /**

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

   223      * to associate mailbox to a branding definition.

   224      *

   225      * @return branding id

   226      */

   227      IMPORT_C TDesC& GetBrandingIdL( );

   228 

   229 

   230     /**

   231      * Moves a messages between folders.

   232      *

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

   234      * @param aSourceFolderId source folder id

   235      * @param aDestinationFolderId destination folder id

   236      */    

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

   238                                   const TFSMailMsgId aSourceFolderId, 

   239                                   const TFSMailMsgId aDestinationFolderId );

   240 

   241      /**

   242      * Moves a messages between folders. Async version.

   243      *                            

   244      * @param MFSMailRequestObserver& aOperationObserver for callback

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

   246      * @param aSourceFolderId source folder id

   247      * @param aDestinationFolderId destination folder id

   248      */    

   249 	 IMPORT_C TInt MoveMessagesL( MFSMailRequestObserver& aOperationObserver,

   250                                   const RArray<TFSMailMsgId>& aMessageIds, 

   251                                   const TFSMailMsgId aSourceFolderId, 

   252                                   const TFSMailMsgId aDestinationFolderId );

   253     /**

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

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

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

   257      *  otherwise this function leaves with KErrNotReady)

   258      *

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

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

   261      *        owned by user

   262      * @param aSourceFolderId source folder id

   263      * @param aDestinationFolderId destination folder id

   264      */    

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

   266 							  		RArray<TFSMailMsgId>& aCopiedMessages,

   267                               		const TFSMailMsgId aSourceFolderId, 

   268                               		const TFSMailMsgId aDestinationFolderId );

   269                               		

   270     /**

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

   272      * performed at a time.

   273      *

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

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

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

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

   278      *  

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

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

   281      * results generated by the same search string.

   282      *    

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

   284 	 *

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

   286      * otherwise this function leaves with KErrNotReady

   287      *

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

   289 	 * @param aSortCriteria sort criteria for the results

   290 	 * @param aSortCriteria sort criteria for the results

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

   292      */    

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

   294 						    const TFSMailSortCriteria& aSortCriteria,

   295 					 	    MFSMailBoxSearchObserver& aSearchObserver );

   296 

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

   298 						    const TFSMailSortCriteria& aSortCriteria,

   299 					 	    MFSMailBoxSearchObserver& aSearchObserver,

   300                             RArray<TFSMailMsgId> aFolderIds );

   301     /**

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

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

   304 	 *

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

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

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

   308      *       cache be cleaned.

   309      */    

   310 	 IMPORT_C void CancelSearch();

   311 

   312     /**

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

   314      *        

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

   316      * 

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

   318      */

   319      IMPORT_C void ClearSearchResultCache();

   320 

   321 	/**

   322 	 * DEPRECATED

   323 	 *

   324      * @param aFolderId...

   325      * @param aObserver observer

   326      */    

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

   328 

   329     /** 

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

   331      *  Each MRU entry consists of two descriptors placed sequentially

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

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

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

   335      *  the name.

   336      *        

   337      * @return Array of descriptors containing MRUs. Ownership

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

   339      */

   340      IMPORT_C MDesCArray* ListMrusL() const;

   341 

   342     /**

   343      * Returns the current synchronizing state of this mailbox.

   344      *

   345      * @return mailbox synchronizing state data structure

   346      */

   347      IMPORT_C TSSMailSyncState CurrentSyncState() const;

   348 

   349     /**

   350      * mailbox capability check for user

   351      *

   352      * @param aCapa mailbox capability to be checked

   353      */

   354 	 IMPORT_C TBool HasCapability(const TFSMailBoxCapabilities aCapability) const; 

   355 

   356     /**

   357      * mailbox connection status accessor

   358      *

   359      * @return connection status, online / offline

   360      */

   361 	 IMPORT_C TFSMailBoxStatus GetMailBoxStatus( );

   362 

   363     /**

   364      * mailbox authentication data mutator

   365      *

   366      * @param aUsername account user name

   367      * @param aPassword account password

   368      */

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

   370 

   371      /**

   372       * removes downloaded attachments from local/terminal memory 

   373       */

   374      IMPORT_C void RemoveDownLoadedAttachmentsL();

   375 	 

   376      /**

   377       * reads connection id from plugin

   378       *

   379       * @param  aConnectionId reference to connection id

   380       * @return KErrNone or error code

   381       */

   382      IMPORT_C TInt GetConnectionId( TUint32& aConnectionId );

   383 

   384      /**

   385       * checks from plugin if connection is allowed when roaming

   386       *

   387       * @param  aConnectionAllowed 

   388       * @return KErrNone or error code

   389       */

   390      IMPORT_C TInt IsConnectionAllowedWhenRoaming( TBool& aConnectionAllowed) ;

   391 

   392      /**

   393       * creates email from RFC822 format data stream located

   394       * in given attachment file

   395       *

   396       * @param  aFile access to file containing data stream contents

   397       *         given by user

   398       *

   399       * return new email object, ownership is transferred to user

   400       */

   401       IMPORT_C CFSMailMessage* CreateMessageFromFileL( const RFile& aFile );

   402 

   403 public: // from  CExtendableEmail

   404 

   405      /**

   406      * @see CExtendableEmail::ReleaseExtension()

   407      */

   408      IMPORT_C void ReleaseExtension( CEmailExtension* aExtension );

   409 

   410      /**

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

   412       * not available.

   413       * @param aInterfaceUid extension interface uid

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

   415       */

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

   417 

   418 private:

   419 

   420   	/**

   421      * Two-phased constructor

   422      */

   423   	 void ConstructL( TFSMailMsgId aMailBoxId );

   424 

   425     /**

   426      * C++ default constructor.

   427      */

   428   	 CFSMailBox();

   429 

   430     /**

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

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

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

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

   435      * Mrus are stored in the plugin.

   436      *

   437      * @param aRecipients email recipients in TO-field

   438      * @param aCCRecipients email recipients in CC-field

   439      * @param aBCCRecipients email recipients in BCC-field

   440      */

   441     void UpdateMrusL(

   442         const RPointerArray<CFSMailAddress>& aRecipients,

   443         const RPointerArray<CFSMailAddress>& aCCRecipients,

   444         const RPointerArray<CFSMailAddress>& aBCCRecipients ) const;

   445     

   446     /**

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

   448      *

   449      * @param aArrayToBeCopied Array that should be copied. 

   450      * @return Copy of the given array.

   451      */

   452     CDesCArraySeg* CopyArrayL( MDesCArray& aArrayToBeCopied ) const;

   453 

   454 

   455     /**

   456      * Function used to update given mru list with

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

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

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

   460      * of the list.

   461      *

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

   463      * @param aNewRecentlyUsedOnes Addresses that should be used

   464      *                             to update the given mru list.

   465      */

   466     void UpdateMruListL(

   467         CDesCArraySeg& aMruList,

   468         const RPointerArray<CFSMailAddress>& aNewRecentlyUsedOnes ) const;

   469 

   470 

   471     /**

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

   473      * Fucntion goes through the addresses in the mru list

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

   475      *

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

   477      * @param searchedAddress Address that is searched from the

   478      *                        given mru list.

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

   480      *             of a matching address if such was found.

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

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

   483      *         Otherwise 1 is returned.

   484      */

   485     TInt FindAddressFromMruList( CDesCArraySeg& aMruList,

   486                              TDesC& searchedAddress,

   487                              TInt& aPos ) const;

   488 

   489     /**

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

   491      * given address info to the mru list. 

   492      *

   493      * @param aMruList Mru list.

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

   495      */

   496     void AddAndRemoveExcessMruL( CDesCArraySeg& aMruList,

   497                                  CFSMailAddress& aToBeAdded ) const;

   498 

   499     /**

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

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

   502      * mru list.

   503      *

   504      * @param aMruList Mru list.

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

   506      */

   507     void AppendMruItemL( CDesCArraySeg& aMruList,

   508                          CFSMailAddress& aToBeAppended ) const;

   509 

   510     /**

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

   512      * as the most recent one.

   513      *

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

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

   516      *                  the most recent address is found. The display

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

   518      *                  from the mru list.

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

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

   521      *                    most recently used one.

   522      */

   523     void SetAsMostRecentMruL( CDesCArraySeg& aMruList,

   524                               TInt aPosition,

   525                               CFSMailAddress& aMostRecent ) const;

   526 

   527  private: // data

   528  

   529     /**

   530      * request handler for plugin requests

   531      */

   532 	 CFSMailRequestHandler* 	iRequestHandler;	

   533 

   534 	/**

   535      * mailbox folder list

   536      */

   537 	 RPointerArray<CFSMailFolder> iFolders;

   538 

   539 };

   540 

   541 #endif