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:  email framework plugin interface

    15 *

    16 */

    17 

    18 #ifndef CFSFWMAILPLUGIN_H

    19 #define CFSFWMAILPLUGIN_H

    20 

    21 #include <ecom/ecom.h>

    22 

    23 #include "mfsmailrequestobserver.h"

    24 #include "mfsmaileventobserver.h"

    25 #include "cfsmailbox.h"

    26 #include "cfsmailplugin.hrh"

    27 #include "cemailextensionbase.h"

    28 // constants

    29 const TUid KFSMailPluginInterface = { FSMAILPLUGININTERFACE };

    30 _LIT8( KFSPluginInterfaceImplementationType, "Plug-In Interface / Freestyle Email Framework");

    31 

    32 /**

    33  *  Freestyle Email Framework Plugin Interface

    34  *

    35  *  class MFSMailPlugin defines functions used by email framework

    36  *  and implemented by plugin implementor.

    37  *

    38  *  Plugin implementor inherits from class CFSMailPlugin,

    39  *  but plugin load medhods are provided by framework in file CFSMailPlugin.inl

    40  *  CFSMailPlugin,CFSMailPlugin.inl are exported by framework

    41  *

    42  *  @lib FSFWCommonLib

    43  *

    44  */

    45 class CFSMailPlugin : public CExtendableEmail

    46     {

    47 

    48 public: // Methods

    49 

    50     /**

    51      * destructor

    52      */

    53      inline virtual ~CFSMailPlugin();

    54 

    55     /**

    56      * two-phased constructor

    57      */

    58      static CFSMailPlugin* NewL(TUid aUid);

    59 

    60     /**

    61      * close ecom session

    62      */

    63      static void Close( );

    64 

    65     /**

    66      * list plugin implementations

    67      *

    68      * @param aInfo plugin implementation info

    69      */

    70      static void ListImplementationsL( RPointerArray<CImplementationInformation>& aInfo );

    71 

    72 	/** MAILBOX HANDLING API */

    73 

    74     /**

    75      * Enables synchronization of identified mailbox. This means

    76      * that the plugin can connect to server to do synchronization

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

    78      * The actual functionality depends on user settings and plugin

    79      * implementation.

    80      *

    81      * All collections (mail etc.) supported by the plugin and

    82      * enabled by user settings are synchronized.

    83      *

    84      * This function sets identified mailbox online but it may

    85      * have a side effect that also other mailboxes of the same

    86      * plugin are set online.

    87      *

    88      * Connection is set offline normally by using specific function

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

    90      * in offline state like network error or scheduling.

    91      *

    92      * @param aMailBoxId mailbox id request is accessed to

    93 	 */

    94      virtual void GoOnlineL( const TFSMailMsgId& aMailBoxId ) = 0;

    95 

    96     /**

    97      * Disables mailbox synchronization. Connection by the plugin

    98      * to synchronize identified mailbox is not allowed after this.

    99      *

   100      * If GoOnlineL has effect on other mailboxes of the

   101      * same plugin then this function has effect on those

   102      * mailboxes also.

   103      *

   104      * @param aMailBoxId mailbox id request is accessed to

   105 	 */

   106      virtual void GoOfflineL( const TFSMailMsgId& aMailBoxId ) = 0;

   107 

   108     /**

   109      * Forces synchronization of mailbox. This can be called

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

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

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

   113      *

   114      * All collections (mail etc.) supported by the plugin and

   115      * enabled by user settings are synchronized.

   116      *

   117      * This is an asynchronous operation and the request id

   118      * is returned for cancelling purpose.

   119      *

   120      * Observer is given as a parameter to enable callbacks

   121      * related to this operation. Alternatively user can use

   122      * empty implementation of the observer function and rely

   123      * only on events. Notice that the event system is not as

   124      * comprehensive as the observing way do this.

   125      *

   126      * @param aMailBoxId defines mailbox

   127      * @param aOperationObserver is client provided observer that

   128      *        will receive progress notifications during the operation.

   129      * @param aRequestId identifies asynchronous request if parallel

   130      * requests exist

   131 	 */

   132      virtual void RefreshNowL( const TFSMailMsgId& aMailBoxId,

   133                                MFSMailRequestObserver& aOperationObserver,

   134                                TInt aRequestId ) = 0;

   135 

   136     /**

   137      * Returns last synchronization operation status.

   138      *

   139      * @param aMailBoxId mailbox id

   140      *

   141      * @return last sync operation status

   142      *

   143      */

   144      virtual const TFSProgress GetLastSyncStatusL( const TFSMailMsgId& aMailBoxId ) = 0;

   145 

   146     /**

   147      * cancels all ongoing synchronizations in given mailbox regardless if initiated

   148      * by email framework or plugin itself

   149      *

   150      * @return error code

   151      */

   152      virtual TInt CancelSyncL( const TFSMailMsgId& aMailBoxId ) = 0;

   153 

   154     /**

   155      * Returns the current synchronization state of mailbox.

   156      *

   157      * @param aMailboxId id of the target mailbox

   158      *

   159      * @return mailbox synchronizing state data structure

   160      */

   161      virtual TSSMailSyncState CurrentSyncState( const TFSMailMsgId& aMailboxId ) = 0;

   162 

   163     /**

   164      * returns mailbox online status

   165      *

   166      * @param aMailboxId id of target mailbox

   167      *

   168      * @return online / offline

   169      */

   170      virtual TFSMailBoxStatus GetMailBoxStatus( const TFSMailMsgId& aMailBoxId ) = 0;

   171 

   172     /**

   173      * checks if mailbox supports given capability

   174      *

   175      * @param aCapability capability to be checked

   176      * @param aMailBoxId id of the target mailbox

   177      *

   178      * @return true/false

   179      */

   180      virtual TBool MailboxHasCapabilityL( 	TFSMailBoxCapabilities aCapability,

   181 	 										TFSMailMsgId aMailBoxId ) = 0;

   182 

   183     /**

   184      * lists existing mailboxes contained by plugin

   185      *

   186      * @param aMailBoxes plugin writes list of existing mailboxes into this

   187      *        table owned by user

   188      * to this table owned by framework

   189      */

   190   	 virtual void ListMailBoxesL( RArray<TFSMailMsgId>& aMailboxes) = 0;

   191 

   192     /**

   193      * returns email mailbox object related to given mailbox id

   194      * mailbox data set by plugin :

   195      *				 - mailbox id

   196      *               - mailbox name

   197      *               - branding id

   198      *               - mailbox capabilities

   199      *

   200      * @param aMailBoxId mailbox id

   201      *

   202      * @return mailBox object ( CFSMailBox ) to be owned by user

   203      */

   204      virtual CFSMailBox* GetMailBoxByUidL( const TFSMailMsgId& aMailBoxId) = 0;

   205 

   206     /**

   207      * removes mailbox

   208      *

   209      * @param aMailBoxId id of the mailbox to be removed

   210      * @param aOperationObserver is FW provided observer that should be

   211      * used to report progress notifications during the operation.

   212      * @param aRequestId asynchronous request id

   213      */

   214      virtual void DeleteMailBoxByUidL(	const TFSMailMsgId& aMailBoxId,

   215 	                                    MFSMailRequestObserver& aOperationObserver,

   216 	                                    const TInt aRequestId ) = 0;

   217 

   218     /**

   219      * Returns branding id of this mailbox.

   220      * This function is used by Branding Manager to associate mailbox to a branding

   221      * definition. Plugin should return incoming mail server associated with this mailbox.

   222      *

   223      * @param aMailBoxId defines the target mailbox

   224      * @return branding id

   225      */

   226      virtual TDesC& GetBrandingIdL(const TFSMailMsgId& aMailboxId) = 0;

   227 

   228     /**

   229      * Subscribes events coming from given mailbox. UnsubscribeMailboxEvents

   230      * MUST be called before destroying given observer object.

   231      *

   232      * @param aMailboxId id of target mailbox

   233      * @param aObserver event observer implementation

   234      */

   235      virtual void SubscribeMailboxEventsL(const TFSMailMsgId& aMailboxId,

   236                                           MFSMailEventObserver& aObserver) = 0;

   237 

   238     /**

   239      * Unsubscribes events from given mailbox

   240      *

   241      * @param aMailboxId id of target mailbox

   242      * @param aObserver event observer

   243      */

   244      virtual void UnsubscribeMailboxEvents(const TFSMailMsgId& aMailboxId,

   245                                            MFSMailEventObserver& aObserver) = 0;

   246 

   247     /**

   248      * Gives notification that new account data may be available from Email Wizard.

   249      * Plugin must check if there is Wizard Data available for it and create

   250      * new account if necessary. If plugin does not support Email Wizard this

   251      * function can just return immediately.

   252      *

   253      * Should return KErrNone if no data found or configuration was successful.

   254      * otherwise any of the standard Symbian error codes.

   255      */

   256      virtual TInt WizardDataAvailableL() = 0;

   257 

   258     /**

   259      * reads connection id from plugin

   260      *

   261      * @param  aConnectionId reference to connection id

   262      * @return KErrNone or error code

   263      */

   264      virtual TInt GetConnectionId( TFSMailMsgId aMailBoxId, TUint32& aConnectionId );

   265 

   266     /**

   267      * checks from plugin if connection is allowed when roaming

   268      *

   269      * @param  aConnectionAllowed

   270      * @return KErrNone or error code

   271      */

   272      virtual TInt IsConnectionAllowedWhenRoaming( TFSMailMsgId aMailBoxId, TBool& aConnectionAllowed );

   273 

   274 

   275     /**

   276       * Reads email from file stream and converts it to class CFSMailMessage

   277       *

   278       * @param  aMailBoxId mailbox where email exists

   279       * @param  aFile input file given by user

   280       * @return CFSMailMessage

   281       */

   282      virtual CFSMailMessage* CreateMessageFromFileL( const TFSMailMsgId /*aMailboxId*/,

   283                                                      const RFile& /*aFile*/ )

   284                                                      { return NULL; };

   285 

   286     /**

   287      * Moves a messages between the given folders.

   288      *

   289      * @param aMailBoxId id of the target mailbox

   290      * @param aMessageIds ids of the messages to be transferred owned by user

   291      * @param aSourceFolderId source folder id

   292      * @param aDestinationFolderId destination folder id

   293      *

   294      */

   295      virtual void MoveMessagesL( const TFSMailMsgId& aMailBoxId,

   296                                  const RArray<TFSMailMsgId>& aMessageIds,

   297                                  const TFSMailMsgId& aSourceFolderId,

   298                                  const TFSMailMsgId& aDestinationFolderId ) = 0;

   299 

   300     /**

   301      * Moves a messages between the given folders. Async version.

   302      * @param aMailBoxId id of the target mailbox

   303      * @param aMessageIds ids of the messages to be transferred owned by user

   304      * @param aSourceFolderId source folder id

   305      * @param aDestinationFolderId destination folder id

   306      */

   307      virtual TInt MoveMessagesL( const TFSMailMsgId& /*aMailBoxId*/,

   308                                  const RArray<TFSMailMsgId>& /*aMessageIds*/,

   309                                  const TFSMailMsgId& /*aSourceFolderId*/,

   310                                  const TFSMailMsgId& /*aDestinationFolderId*/,

   311                                  MFSMailRequestObserver& /*aOperationObserver*/,

   312                                  TInt /*aRequestId*/ ){return KErrNotSupported;}

   313 

   314     /**

   315      * Copies a messages from folder to another.

   316      * This function copies a messages to the given folder,

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

   318      * (note Only works if the store is in an authenticated state,

   319      *  otherwise this function leaves with KErrNotReady)

   320      *

   321      * @param aMailBoxId target mailbox id

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

   323      * @param aNewMessages ids of the copied new messages owned by user

   324      * @param aSourceFolderId source folder id

   325      * @param aDestinationFolderId destination folder id

   326      */

   327      virtual void CopyMessagesL( const TFSMailMsgId& aMailBoxId,

   328                                  const RArray<TFSMailMsgId>& aMessageIds,

   329                                  RArray<TFSMailMsgId>& aNewMessages,

   330                                  const TFSMailMsgId& aSourceFolderId,

   331                                  const TFSMailMsgId& aDestinationFolderId ) = 0;

   332 

   333     /** Get a list of most recently used addresses of desired mailbox.

   334      *  Each MRU entry consists of two descriptors placed sequentially

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

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

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

   338      *  the name.

   339      *

   340      *  The function will leave with KErrNotFound if a mailbox with

   341      *  given id is not found.

   342      *

   343      * @param aMailBoxId target mailbox id

   344      *

   345      * @return Array of descriptors containing MRUs. Ownership

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

   347      */

   348      virtual MDesCArray* GetMrusL( const TFSMailMsgId& aMailBoxId ) = 0;

   349 

   350     /** Set a list of most recently used addresses for given mailbox.

   351      *  Each MRU entry consists of two descriptors placed sequentially

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

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

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

   355      *  the name.

   356      *

   357      *  The function will leave with KErrNotFound if a mailbox with

   358      *  given id is not found.

   359      *

   360      * @param aMailBoxId target mailbox id

   361      * @param aNewMruList Array of descriptors containing MRUs.

   362      * Empty if no entries are found.

   363      */

   364      virtual void SetMrusL( const TFSMailMsgId& aMailBoxId,

   365                             MDesCArray* aNewMruList ) = 0;

   366 

   367 	/** FOLDER HANDLING API */

   368     /**

   369      * returns email folder object related to given folder id

   370      * folder data set by plugin :

   371      *				 - folder id

   372      *               - folder name

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

   374      *               - message count

   375      *               - unread message count

   376      *               - mailbox id

   377 	 *				 - parent folder

   378 	 *

   379      * @param aMailBoxId id of mailbox containing folder

   380      * @param aFolderId folder id

   381      *

   382      * @return folder object (CFSMailFolder) to be owned by user

   383      */

   384      virtual CFSMailFolder* GetFolderByUidL( const TFSMailMsgId& aMailBoxId,

   385                                              const TFSMailMsgId& aFolderId ) = 0;

   386 

   387     /**

   388      * create new folder

   389      *

   390      * @param aMailBoxId id of the mailbox where folder is created

   391      * @param aFolderId id of the parent folder where folder is created

   392      * @param aFolderName name of the new folder

   393      * @param aSync defines if new folder is local only (false)

   394      * or if it also should sync to server (true)

   395      *

   396      * @return new folder object CFSMailFolder to be owned by user

   397      */

   398      virtual CFSMailFolder* CreateFolderL( 	const TFSMailMsgId& aMailBoxId,

   399                                             const TFSMailMsgId& aParentFolderId,

   400                                             const TDesC& aFolderName,

   401                                             const TBool aSync ) = 0;

   402 

   403     /**

   404      * deletes folder related to given folder id

   405      *

   406      * @param aMailBoxId mailbox where deleted folder is located

   407      * @param aFolderId defines id of the folder to be deleted

   408      */

   409      virtual void DeleteFolderByUidL( const TFSMailMsgId& aMailBoxId,

   410                                       const TFSMailMsgId& aFolderId) = 0;

   411 

   412 	/**

   413 	 * Lists subfolders of given folder.

   414 	 * Only direct subfolders of given folder are returned.

   415 	 * Folder data :

   416 	 * - folder id

   417 	 * - folder name

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

   419 	 * - message count

   420 	 * - unread message count

   421 	 * - mailbox id

   422 	 * - parent folder

   423 	 * - subfolder count

   424 	 *

   425 	 * @param aMailBoxId id of the mailbox where parent folder is located

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

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

   428 	 */

   429 	 virtual void ListFoldersL(	const TFSMailMsgId& aMailBoxId,

   430 	                            const TFSMailMsgId& aParentFolderId,

   431 	                            RPointerArray<CFSMailFolder>& aFolderList) = 0;

   432 

   433    /**

   434      * List all subfolders of given mailbox.

   435      * folder data :

   436      * - folder id

   437      * - folder name

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

   439      * - message count

   440      * - unread message count

   441      * - mailbox id

   442      * - parent folder

   443      * - subfolder count

   444      *

   445      * @param aMailBoxId mailbox id

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

   447 	 * Caller must determine tree structure by examining parent id of each

   448      * returned folder.

   449      */

   450      virtual void ListFoldersL(	const TFSMailMsgId& aMailBoxId,

   451                                 RPointerArray<CFSMailFolder>& aFolderList) = 0;

   452 

   453     /**

   454      * returns folder id of given standard folder

   455      *

   456      * @param aMailBoxId id of the mailbox where folder is located

   457      * @param aFolderType folder type

   458      *

   459      * return folder id

   460      */

   461      virtual TFSMailMsgId GetStandardFolderIdL( const TFSMailMsgId& aMailBoxId,

   462 	 											const TFSFolderType aFolderType ) = 0;

   463 

   464 	/** MESSAGE FETCH AND STORE */

   465     /**

   466      * List messages contained by given folder.

   467      * Returns email list iterator to user.

   468      *

   469      * @param aMailBoxId id of the mailbox where parent folder is located

   470      * @param aFolderId folder id of given folder

   471      * @param aDetails defines which message details are included in messages

   472 	 * EFSMsgDataIdOnly  -> Doesn't get any data. The object just contains the ID.

   473 	 * EFSMsgDataDate    -> Get received date only. To be used when showing messages sorted by date.

   474      *                      The rest would be retreived when needed but date is needed to build the list.

   475 	 * EFSMsgDataSubject -> Like above but when sorting by subject

   476 	 * EFSMsgDataSender  -> Likewise for sender address.

   477 	 * EFSMsgDataEnvelope, EFSMsgDataStructure -> email content type is returned by plugin

   478      * @param aSorting describes requested sort criteria (owned by user).

   479      *        First item in array is primary sort criteria.

   480      *

   481      * @return Email list iterator, ownership is transferred to user.

   482 	 */

   483 	 virtual MFSMailIterator* ListMessagesL( const TFSMailMsgId& aMailBoxId,

   484 	                                         const TFSMailMsgId& aFolderId,

   485 	                                         const TFSMailDetails aDetails,

   486 	                                         const RArray<TFSMailSortCriteria>& aSorting ) = 0;

   487 

   488     /**

   489      * returns email object related to given message id

   490      *

   491      * message info set by plugin :

   492      *				  - message id

   493      *                - mailbox

   494      *				  - parent folder

   495      *                - message size

   496 	 *                - the rest is defined by message attributes ;

   497      * @param aMailBoxId id of the mailbox containing email

   498      * @param aFolderId parent folder id containing email

   499      * @param aMessageId email message id

   500      *

   501      * @param aDetails defines which message parts are included in message

   502 	 * EFSMsgDataIdOnly  -> Doesn't get any data. The object just contains the ID.

   503 	 * EFSMsgDataDate    -> Get received date only. To be used when showing messages sorted by date.

   504      *                      The rest would be retreived when needed but date is needed to build the list.

   505 	 * EFSMsgDataSubject -> Like above but when sorting by subject

   506 	 * EFSMsgDataSender  -> Likewise for sender address.

   507 	 * EFSMsgDataEnvelope, EFSMsgDataStructure ->

   508 	 * email content type is evaluated and returned by plugin

   509      *

   510      * @return email object (CFSMailMessage), ownership is transferred to user

   511      */

   512      virtual CFSMailMessage* GetMessageByUidL( 	const TFSMailMsgId& aMailBoxId,

   513                                                 const TFSMailMsgId& aParentFolderId,

   514                                                 const TFSMailMsgId& aMessageId,

   515                                                 const TFSMailDetails aDetails) = 0;

   516 

   517     /**

   518      * deletes email defined by message id

   519      *

   520      * @param aMailBoxId id of the mailbox containing email

   521      * @param aFolderId email parent folder id

   522      * @param aMessages ids of messages to be deleted

   523      */

   524      virtual void DeleteMessagesByUidL( const TFSMailMsgId& aMailBoxId,

   525                                         const TFSMailMsgId& aFolderId,

   526                                         const RArray<TFSMailMsgId>& aMessages ) = 0;

   527 

   528     /**

   529      * creates new email template into drafts folder

   530      *

   531      * @param aMailBoxId id of the mailbox where new email is created

   532      * @return email object to be modified by user, ownership is transferred to user

   533      */

   534      virtual CFSMailMessage* CreateMessageToSendL( const TFSMailMsgId& aMailBoxId ) = 0;

   535 

   536     /**

   537      * creates new email template to drafts folder to be forwarded

   538      *

   539      * @param aMailBoxId id of the mailbox where new email is created

   540      * @param aOriginalMessageId if of the (original) message,which is forwarded

   541      * @return email object to be modified by user, ownership is transferred to user

   542      */

   543      virtual CFSMailMessage* CreateForwardMessageL( const TFSMailMsgId& aMailBoxId,

   544                                                     const TFSMailMsgId& aOriginalMessageId,

   545                                                     const TDesC& aHeaderDescriptor = KNullDesC ) = 0;

   546 

   547     /**

   548      * creates new email template to drafts folder to be replied

   549      *

   550      * @param aMailBoxId id of the mailbox where new email is created

   551      * @param aOriginalMessageId id of original email,which is replied to

   552      * @param aReplyToAll true if reply to all is wanted

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

   554      *        parameter if needed

   555      *

   556      * @return email object to be modified by user, ownership is transferred to user

   557      */

   558      virtual CFSMailMessage* CreateReplyMessageL( const TFSMailMsgId& aMailBoxId,

   559                                                   const TFSMailMsgId& aOriginalMessageId,

   560                                                   const TBool aReplyToAll,

   561                                                   const TDesC& aHeaderDescriptor = KNullDesC) = 0;

   562 

   563     /**

   564      * stores email object data to message store after modifications (commit)

   565      *

   566      * @param aMailBoxId id of the mailbox where email is stored

   567      * @param aMessage email data to be stored by plugin

   568      */

   569      virtual void StoreMessageL( const TFSMailMsgId& aMailBoxId,

   570                                  CFSMailMessage& aMessage ) = 0;

   571 

   572     /**

   573      * starts email fetching from email server

   574 	 *

   575      * @param aMailBoxId id of the mailbox where email is located

   576      * @param aFolderId id of the parent folder containing email

   577      * @param aMessageIds ids of email to be fetched

   578      * @param aDetails defines which details are included in email

   579 	 * EFSMsgDataIdOnly  -> Doesn't get any data. The object just contains the ID.

   580 	 * EFSMsgDataDate    -> Get received date only. To be used when showing messages sorted by date.

   581      *                      The rest would be retreived when needed but date is needed to build the list.

   582 	 * EFSMsgDataSubject -> Like above but when sorting by subject

   583 	 * EFSMsgDataSender  -> Likewise for sender address.

   584 	 * EFSMsgDataEnvelope -> Date, subject, Sender, To, Cc at least.

   585 	 * EFSMsgDataStructure -> the part structure including mime type, size and name headers.

   586 	 *

   587      * @param aObserver observer (callback medhod), which plugin calls to pass progress

   588      *        events to user (like fetching has completed)

   589      * @param aRequestId asynchronous request id

   590      */

   591      virtual void FetchMessagesL( const TFSMailMsgId& aMailBoxId,

   592                                   const TFSMailMsgId& aParentFolderId,

   593                                   const RArray<TFSMailMsgId>& aMessageIds,

   594                                   TFSMailDetails aDetails,

   595                                   MFSMailRequestObserver& aObserver,

   596                                   TInt aRequestId) = 0;

   597 

   598     /**

   599      * starts email parts fetching from email server

   600 	 *

   601      * @param aMailBoxId id of the mailbox where email is located

   602      * @param aFolderId id of the parent folder containing email

   603      * @param aMessagePartIds part ids of email parts, which are to be fetched

   604      * @param aOperationObserver observer that plugin uses to report

   605      *        progress notifications during the operation.

   606      * @param aRequestId asynchronous request id

   607      * @param aPreferredByteCount indicates how much more content for part(s)

   608      *        user wants to fetch. Default value zero indicates that all content

   609      *        should be fetched. Actual amount of data fetched may differ from

   610      *        requested (possibly all fetched in any case).

   611      */

   612      virtual void FetchMessagePartsL( const TFSMailMsgId& aMailBoxId,

   613                                       const TFSMailMsgId& aFolderId,

   614                                       const TFSMailMsgId& aMessageId,

   615                                       const RArray<TFSMailMsgId>& aMessagePartIds,

   616                                       MFSMailRequestObserver& aOperationObserver,

   617                                       const TInt aRequestId,

   618                                       const TUint aPreferredByteCount) = 0;

   619 

   620 

   621     /* reads email objects from plugin store

   622 	 *

   623      * @param aMailBoxId id of the mailbox where email are located

   624      * @param aParentFolderId parent folder id containing emails

   625      * @param aMessageIds ids of emails to be read from plugin store

   626  	 * @param aMessageList plugin writes results into this table owned by user

   627      * @param aDetails defines which email details are included in each email object

   628 	 *        EFSMsgDataIdOnly  -> Doesn't get any data. The object just contains the ID.

   629 	 *        EFSMsgDataDate    -> Get received date only. To be used when showing

   630 	 *        messages sorted by date. The rest would be retreived when needed but

   631 	 *        date is needed to build the list.

   632 	 *        EFSMsgDataSubject -> Like above but when sorting by subject

   633 	 *        EFSMsgDataSender  -> Likewise for sender address.

   634 	 *        EFSMsgDataEnvelope -> Date, subject, Sender, To, Cc at least.

   635 	 *        EFSMsgDataStructure -> the part structure including mime type,

   636 	 *        size and name headers.

   637 	 */

   638 	 virtual void GetMessagesL(	const TFSMailMsgId& aMailBoxId,

   639 	                            const TFSMailMsgId& aParentFolderId,

   640 	                            const RArray<TFSMailMsgId>& aMessageIds,

   641 	                            RPointerArray<CFSMailMessage>& aMessageList,

   642 	                            const TFSMailDetails aDetails ) = 0;

   643 

   644     /**

   645      * Returns child part objects for given email part. Ownership of objects

   646      * is transferred to user.

   647      *

   648      * @param aMailBoxId id of the mailbox where email is located

   649      * @param aParentFolderId id of the parent folder containing email

   650      * @param aMessageId id of the email part belongs to

   651      * @param aParentId id of the parent email part

   652      * @param aParts plugin lists child parts into this table owned by user

   653      */

   654      virtual void ChildPartsL( const TFSMailMsgId& aMailBoxId,

   655                                const TFSMailMsgId& aParentFolderId,

   656                                const TFSMailMsgId& aMessageId,

   657                                const TFSMailMsgId& aParentId,

   658                                RPointerArray<CFSMailMessagePart>& aParts) = 0;

   659 

   660     /**

   661      * Creates and adds a new child part to given email part.

   662      *

   663      * @param aMailBoxId id of the mailbox where email is located

   664      * @param aParentFolderId id of the parent folder where email is located

   665      * @param aMessageId id of the email email belongs to

   666      * @param aParentPartId id of the parent part of the new part

   667      * @param aInsertBefore id of existing part that new part should precede.

   668      * If aInsertBefore is NULL id then new part is added as last.

   669      * @param aContentType content type of the new message part

   670      *

   671      * return new child part object, ownership is transferred to user

   672      */

   673      virtual CFSMailMessagePart* NewChildPartL( const TFSMailMsgId& aMailBoxId,

   674                                                 const TFSMailMsgId& aParentFolderId,

   675                                                 const TFSMailMsgId& aMessageId,

   676                                                 const TFSMailMsgId& aParentPartId,

   677                                                 const TFSMailMsgId& aInsertBefore,

   678                                                 const TDesC& aContentType) = 0;

   679 

   680     /**

   681      * Creates and adds a new child part from file to given email part.

   682      *

   683      * @param aMailBoxId id of the mailbox where parent part is located

   684      * @param aParentFolderId id of the parent folder where email is located

   685      * @param aMessageId id of the email parent part belongs to

   686      * @param aParentPartId id of the parent part of the new part

   687      * @param aInsertBefore id of existing part that new part should precede.

   688      * If aInsertBefore is NULL id then new part is added as last.

   689      * @param aContentType content type of the new message part

   690      * @param aFilePath file containing new child part contents

   691      *

   692      * return new child part object, ownership is transferred to user

   693      */

   694 	 virtual CFSMailMessagePart* NewChildPartFromFileL( const TFSMailMsgId& aMailBoxId,

   695 	                                                    const TFSMailMsgId& aParentFolderId,

   696 	                                                    const TFSMailMsgId& aMessageId,

   697 	                                                    const TFSMailMsgId& aParentPartId,

   698 	                                                    const TDesC& aContentType,

   699 	                                                    const TDesC& aFilePath) = 0;

   700 

   701 

   702 	 /**

   703 	  * Creates and adds a new child part from file to given email part.

   704 	  *

   705 	  * @param aMailBoxId id of the mailbox where parent part is located

   706 	  * @param aParentFolderId id of the parent folder where email is located

   707 	  * @param aMessageId id of the email parent part belongs to

   708 	  * @param aParentPartId id of the parent part of the new part

   709 	  * @param aInsertBefore id of existing part that new part should precede.

   710 	  * If aInsertBefore is NULL id then new part is added as last.

   711 	  * @param aContentType content type of the new message part

   712 	  * @param aFile access to file containing new child part contents,

   713 	  *  ownership is transferred

   714 	  *

   715 	  * return new child part object, ownership is transferred to user

   716 	  */

   717 	  virtual CFSMailMessagePart* NewChildPartFromFileL( const TFSMailMsgId& aMailBoxId,

   718 	                                                     const TFSMailMsgId& aParentFolderId,

   719 	                                                     const TFSMailMsgId& aMessageId,

   720 	                                                     const TFSMailMsgId& aParentPartId,

   721 	                                                     const TDesC& aContentType,

   722 	                                                     RFile& aFile ) = 0;

   723 

   724 

   725     /**

   726      * Copies given email as new child part to given email part.

   727      *

   728      * @param aMailBoxId id of the mailbox where email is located

   729      * @param aParentFolderId id of the parent folder where email is located

   730      * @param aMessageId id of the email parent part belongs to

   731      * @param aParentPartId id of the parent part of the new part

   732      * @param aInsertBefore id of existing part that new part should precede.

   733      *        If NULL id then new part is added as last.

   734      * @param aMessage id of the email that is copied as child part

   735      *

   736      * return new child part object, ownership is transferred to user

   737      */

   738      virtual CFSMailMessagePart* CopyMessageAsChildPartL( const TFSMailMsgId& aMailBoxId,

   739                                                           const TFSMailMsgId& aParentFolderId,

   740                                                           const TFSMailMsgId& aMessageId,

   741                                                           const TFSMailMsgId& aParentPartId,

   742                                                           const TFSMailMsgId& aInsertBefore,

   743                                                           const CFSMailMessage& aMessage) = 0;

   744 

   745     /**

   746      * Removes child part (and its children, if any) from given email part

   747      *

   748      * @param aMailBoxId id of the mailbox where email is located

   749      * @param aParentFolderId id of the parent folder where email is located

   750      * @param aMessageId id of the email parent part belongs to

   751      * @param aParentPartId id of the parent of the part

   752      * @param aPartId id of the part to removed

   753      */

   754      virtual void RemoveChildPartL(	const TFSMailMsgId& aMailBoxId,

   755                                     const TFSMailMsgId& aParentFolderId,

   756                                     const TFSMailMsgId& aMessageId,

   757                                     const TFSMailMsgId& aParentPartId,

   758                                     const TFSMailMsgId& aPartId) = 0;

   759 

   760     /**

   761      * Returns given message part. Ownership of object is transferred to caller.

   762      *

   763      * @param aMailBoxId id of the mailbox where email is located

   764      * @param aParentFolderId id of the parent folder where email is located

   765      * @param aMessageId id of the email part belongs to

   766      * @param aMessagePartId id of the message part

   767      *

   768      * return email part object, ownership is transferred to user

   769      */

   770      virtual CFSMailMessagePart* MessagePartL( const TFSMailMsgId& aMailBoxId,

   771                                                const TFSMailMsgId& aParentFolderId,

   772                                                const TFSMailMsgId& aMessageId,

   773                                                const TFSMailMsgId& aMessagePartId) = 0;

   774 

   775     /**

   776      * Retrieves a read-only file handle for the content file of this message part.

   777      * Should return KErrNotSupported if handle can not be given directly. In that case

   778      * FW will next ask to copy file to a temporary location so that FW can open the RFile

   779      * itself. Ownership of the handle is transferred. Caller is responsible for closing the

   780      * handle.

   781      *

   782      * @param aMailBoxId id of the mailbox where email is located

   783      * @param aParentFolderId id of the parent folder where email is located

   784      * @param aMessageId id of the email part belongs to

   785      * @param aMessagePartId id of the message part

   786      * @param aFileHandle returns the opened read-only file handle

   787      */

   788      virtual TInt GetMessagePartFileL( const TFSMailMsgId& aMailBoxId,

   789                                        const TFSMailMsgId& aParentFolderId,

   790                                        const TFSMailMsgId& aMessageId,

   791                                        const TFSMailMsgId& aMessagePartId,

   792                                        RFile& aFileHandle) = 0;

   793 

   794     /**

   795      * copies contents of this message part to given file

   796      *

   797      * @param aMailBoxId id of the mailbox where email is located

   798      * @param aParentFolderId id of the parent folder where email is located

   799      * @param aMessageId id of the email part belongs to

   800      * @param aMessagePartId id of the message part

   801      * @param aContentLocation defines file location as

   802      * a) directory, when plugin finds out corresponding file name

   803      *    related to this part id, in this case last character should

   804      *    be '/'

   805      * b) directory & filename, when both directory and file name

   806      *    are given by user

   807      */

   808      virtual void CopyMessagePartFileL( const TFSMailMsgId& aMailBoxId,

   809                                         const TFSMailMsgId& aParentFolderId,

   810                                         const TFSMailMsgId& aMessageId,

   811                                         const TFSMailMsgId& aMessagePartId,

   812                                         const TDesC& aContentLocation) = 0;

   813 

   814     /**

   815      * copies email part content to user given buffer

   816      *

   817      * @param aMailBoxId id of the mailbox where email is located

   818      * @param aParentFolderId id of the parent folder where email is located

   819      * @param aMessageId id of the email part belongs to

   820      * @param aMessagePartId id of the message part

   821      * @param aBuffer user buffer

   822      * @param aStartOffset offset from content beginning

   823      */

   824      virtual void GetContentToBufferL( const TFSMailMsgId& aMailBoxId,

   825                                        const TFSMailMsgId& aParentFolderId,

   826                                        const TFSMailMsgId& aMessageId,

   827                                        const TFSMailMsgId& aMessagePartId,

   828                                        TDes& aBuffer,

   829                                        const TUint aStartOffset) = 0;

   830 

   831     /**

   832      * stores email part content

   833      *

   834      * @param aBuffer contain email part content

   835      * @param aMailBoxId id of the mailbox where email is located

   836      * @param aParentFolderId id of the parent folder where email is located

   837      * @param aMessageId id of the email part belongs to

   838      * @param aMessagePartId id of the message part

   839      */

   840 	 virtual void SetContentL(	const TDesC& aBuffer,

   841 	 						  	const TFSMailMsgId& aMailBoxId,

   842      							const TFSMailMsgId& aParentFolderId,

   843 								const TFSMailMsgId& aMessageId,

   844 	 							const TFSMailMsgId& aMessagePartId) = 0;

   845 

   846     /**

   847      * Removes fetched contents of these parts.

   848      *

   849      * @param aMailBoxId defines mailbox where message is located

   850      * @param aParentFolderId defines parent folder where message is located

   851      * @param aMessageId gives the id of the message that message part belongs to

   852      * @param aPartIds message part ids to be removed

   853      */

   854      virtual void RemovePartContentL( 	const TFSMailMsgId& aMailBoxId,

   855      	     							const TFSMailMsgId& aParentFolderId,

   856 									  	const TFSMailMsgId& aMessageId,

   857      								  	const RArray<TFSMailMsgId>& aPartIds) = 0;

   858 

   859     /**

   860      * Sets email part contents from given file.

   861      * Possible old contents are replaced.

   862      *

   863      * @param aMailBoxId id of the mailbox where email is located

   864      * @param aParentFolderId id of the parent folder where email is located

   865      * @param aMessageId id of the email part belongs to

   866      * @param aMessagePartId id of the message part

   867      * @param aFilePath source file path

   868      */

   869      virtual void SetPartContentFromFileL( const TFSMailMsgId& aMailBoxId,

   870                                            const TFSMailMsgId& aParentFolderId,

   871                                            const TFSMailMsgId& aMessageId,

   872                                            const TFSMailMsgId& aMessagePartId,

   873                                            const TDesC& aFilePath) = 0;

   874 

   875     /**

   876      * stores email part object data to message store after modifications (commit)

   877      *

   878      * @param aMailBoxId id of the mailbox where email is located

   879      * @param aParentFolderId id of the parent folder where email is located

   880      * @param aMessageId id of the email part belongs to

   881      * @param aMessagePart email part data to be stored

   882      */

   883      virtual void StoreMessagePartL( const TFSMailMsgId& aMailBoxId,

   884    	     							 const TFSMailMsgId& aParentFolderId,

   885 									 const TFSMailMsgId& aMessageId,

   886          							 CFSMailMessagePart& aMessagePart) = 0;

   887 

   888     /**

   889      * unregisters request observer to cancel pending events

   890      *

   891      * @param aRequestId request id of the pending asynchronous request

   892      */

   893      virtual void UnregisterRequestObserver(TInt aRequestId) = 0;

   894 

   895     /**

   896      * Launches email sending in plugin,

   897      * cancellation is deleting the message from outbox.

   898      *

   899      * @param aMessage email to be sent

   900      */

   901      virtual void SendMessageL( CFSMailMessage& aMessage ) = 0;

   902 

   903     /**

   904      * Returns pending asynchronous request status, request is identified

   905 	 * by request id if parallel requests exists

   906 	 *

   907      * @param aRequestId request id

   908      *

   909      * @return pending request status

   910      */

   911      virtual TFSProgress StatusL( const TInt aRequestId ) = 0;

   912 

   913     /**

   914      * cancels pending request

   915      *

   916      * @param aRequestId identifies request if parallel requests exists

   917 	 */

   918      virtual void CancelL( const TInt aRequestId ) = 0;

   919 

   920 	/** Search API */

   921 

   922     /**

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

   924      * performed at a time.

   925      *

   926      *

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

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

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

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

   931      *

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

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

   934      * results generated by the same search string.

   935      *

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

   937 	 *

   938      * /note Only works if the store is in an authenticated state,

   939      *  otherwise this function leaves with KErrNotReady

   940      *

   941      * @paran aMailBoxId id of the mailbox where messages are to be searched

   942      * @param aFolderIds list of folders where messages are to be searched

   943 	 * 	      global or folder specific search depends on the size of array is 0 or not.

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

   945 	 * @param aSortCriteria sort criteria for the results

   946      * @param aSearchObserver client observer that will be notified about search status.

   947      *

   948      */

   949      virtual void SearchL( const TFSMailMsgId& aMailBoxId,

   950                            const RArray<TFSMailMsgId>& aFolderIds,

   951                            const RPointerArray<TDesC>& aSearchStrings,

   952                            const TFSMailSortCriteria& aSortCriteria,

   953                            MFSMailBoxSearchObserver& aSearchObserver ) = 0;

   954 

   955 

   956     /**

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

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

   959 	 *

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

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

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

   963      *       cache be cleaned.

   964 	 *

   965      * @paran aMailBoxId id of the mailbox where the search should be cancelled

   966      */

   967      virtual void CancelSearch( const TFSMailMsgId& aMailBoxId ) = 0;

   968 

   969     /**

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

   971      *

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

   973      *

   974      * This function should be called when search results are no longer in display.

   975 	 *

   976      * @paran aMailBoxId id of the mailbox where the search cache should be cleared

   977 	 */

   978      virtual void ClearSearchResultCache( const TFSMailMsgId& aMailBoxId ) = 0;

   979 

   980     /**

   981      * Adds a new event observer. There can be several observers active at the same time.

   982      * Caller MUST call RemoveObserver before destroying given observer object.

   983      *

   984      * @param aObserver observer implementation

   985      */

   986      virtual void AddObserverL(MFSMailEventObserver& aObserver) = 0;

   987 

   988     /**

   989      * Removes event observer

   990      *

   991      * @param aObserver observer implementation

   992      */

   993      virtual void RemoveObserver(MFSMailEventObserver& aObserver) = 0;

   994 

   995     /**

   996      * Plugins is asked to immediaty execute all authentications that are mandatory to get

   997      * services from the plugin. This means e.g. store authentication.

   998      *

   999      * @param aOperationObserver is FW provided observer that should be used

  1000      *        to report progress notifications during the operation.

  1001      * @param aRequestId asynchronous request id

  1002      */

  1003      virtual void AuthenticateL(MFSMailRequestObserver& aOperationObserver, TInt aRequestId) = 0;

  1004 

  1005     /**

  1006 	 * sets authentication popup data

  1007      * @param aMailBoxId id of the mailbox

  1008      * @param aUsername email account user name

  1009      * @param aPassword email account password

  1010      */

  1011     virtual void SetCredentialsL( const TFSMailMsgId& aMailBoxId,

  1012                                   const TDesC& aUsername,

  1013                                   const TDesC& aPassword )  = 0;

  1014 

  1015     /**

  1016       * Sets the mailbox name for this mailbox.

  1017       *

  1018       * @param aMailboxId id of target mailbox

  1019       * @param aMailboxName new name for the mailbox

  1020       */

  1021     virtual void SetMailboxName(const TFSMailMsgId& aMailboxId, const TDesC& aMailboxName ) = 0;

  1022 

  1023 protected:

  1024 

  1025     /**

  1026      * C++ default constructor.

  1027      */

  1028      CFSMailPlugin();

  1029 

  1030 private:

  1031 

  1032   	/**

  1033      * Two-phased constructor

  1034      */

  1035      void ConstructL();

  1036 

  1037 private: // data

  1038 

  1039     /**

  1040      * instance identifier key for destructor

  1041      */

  1042     TUid		iDtor_ID_Key;

  1043 

  1044     };

  1045 

  1046 //<cmail>

  1047 #include "cfsmailplugin.inl"

  1048 //</cmail>

  1049 

  1050 #endif // CFSFW_MAIL_PLUGIN_H

  1051 

  1052 // End of File