FCL/sf/app/commonemail: comparison emailservices/emailframework/inc/MFSMailPlugin.h

equal deleted inserted replaced

-:578830873419
+:ecc8def7944a
 /*
 * Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies).
 * All rights reserved.
 * This component and the accompanying materials are made available
 * under the terms of "Eclipse Public License v1.0"
 * which accompanies this distribution, and is available
 * at the URL "http://www.eclipse.org/legal/epl-v10.html".
 *  to be called back.
 *
 *  API allows Symbian leaves from plugins and will trap them, error codes are
 *  expected to be symbian error codes.
 *  @since ...
 */
 class MFSMailPlugin
 	{
 public: // Data
 public: // Methods
 * returns plugin capabilities
 *
 * @return plugin capabilities data structure
 */
 	 virtual const TFSMailPluginCapabilities ReadPluginCapabilitiesL() = 0;
 	// MAILBOX HANDLING
 /**
 * lists existing mailboxes implemented by given plugin
 *
 * @param aPlugin defines which plugin request is accessed to
 *               - mailbox name
 *               - branding id
 *               - mailbox capabilities
 *
 * @param aMailBoxId defines mailbox id
 * @return mailBox object ( CFSMailBox ) to be owned by user
 */
 	 virtual CFSMailBox* GetMailBoxByUidL( const TFSMailMsgId& aMailBoxId) = 0;
 /**
 * removes mailbox
 *
 * @param aMailBoxId defines id of the mailbox to be removed
 */
 	 virtual void DeleteMailBoxByUidL(const TFSMailMsgId& aMailBoxId) = 0;
 * @param aMailBoxId defines mailbox id
 * @param aMessageIds ids of the messages to be transferred
 * @param aSourceFolderId id of the folder where messages are located
 * @param aDestinationFolderId destination folder id
 *
 */
 virtual void MoveMessagesL( 	const TFSMailMsgId& aMailBoxId,
 							 	const RArray<TFSMailMsgId>& aMessageIds,
 	const TFSMailMsgId& aSourceFolderId,
 	const TFSMailMsgId& aDestinationFolderId ) = 0;
 /**
 * Copies a messages from one folder to another.
 * This function copies a messages to the given folder,
 * including the properties, content, and all attachments.
 * (note Only works if the store is in an authenticated state,
 *  otherwise this function leaves with KErrNotReady)
 *
 * @param aMailBoxId defines mailbox id
 * @param aMessageIds ids of the messages to be copied
 * @param aNewMessages ids of the copied messages.
 * @param aSourceFolderId id of the folder where messages are located
 * @param aDestinationFolderId destination folder id
 */
 virtual void CopyMessagesL( const TFSMailMsgId& aMailBoxId,
 							 const RArray<TFSMailMsgId>& aMessageIds,
 							 RArray<TFSMailMsgId>& aNewMessages,
 const TFSMailMsgId& aSourceFolderId,
 const TFSMailMsgId& aDestinationFolderId ) = 0;
 *  not contain a name at all then a KNullDesC is found in place of
 *  the name.
 *
 *  The function will leave with KErrNotFound if a mailbox with
 *  given id is not found.
 *
 * @param aMailBoxId defines mailbox id
 * @return Array of descriptors containing MRUs. Ownership
 *         is transferred. Empty if no entries are found.
 */
 virtual MDesCArray* GetMrusL( const TFSMailMsgId& aMailBoxId ) = 0;
 *  not contain a name at all then a KNullDesC is found in place of
 *  the name.
 *
 *  The function will leave with KErrNotFound if a mailbox with
 *  given id is not found.
 *
 * @param aMailBoxId defines mailbox id
 * @param aNewMruList Array of descriptors containing MRUs. Empty if no entries are found.
 */
 virtual void SetMrusL( const TFSMailMsgId& aMailBoxId,
 						MDesCArray* aNewMruList ) = 0;
 	// MAILBOX SYNC
 /**
 * DEPRECATED
 *
 	 */
 virtual void GoOnlineL( ) = 0;
 /**
 * DEPRECATED
 *
 	 */
 virtual void GoOfflineL( ) = 0;
 /**
 * DEPRECATED
 *
 	 */
 virtual  TFSProgress GetLastSyncStatusL( ) = 0;
 /**
 * DEPRECATED
 *
 	 */
 virtual TInt RefreshNowL( ) = 0;
 /**
 * Enables synchronization of identified mailbox. This means
 * that the plugin can connect toserver to do synchronization
 * of the mailbox when necessary or stay connected all the time.
 * The actual functionality depends on user settings and plugin
 * Connection is set offline normally by using specific function
 * for this purpose. There are also other reasons for ending up
 * in offline state like network error or scheduling.
 *
 * @param aMailBoxId defines mailbox
 *
 	 */
 virtual void GoOnlineL( const TFSMailMsgId& aMailBoxId ) = 0;
 /**
 * Disables mailbox synchronization. Connection by the plugin
 * If GoOnlineL has effect on other mailboxes of the
 * same plugin then this function has effect on those
 * mailboxes also.
 *
 * @param aMailBoxId defines mailbox
 *
 	 */
 virtual void GoOfflineL( const TFSMailMsgId& aMailBoxId ) = 0;
 /**
 * Returns last sync operation status.
 *
 * @param aMailBoxId defines mailbox
 * @return Last sync operation status
 *
 	 */
 virtual const TFSProgress GetLastSyncStatusL( const TFSMailMsgId& aMailBoxId ) = 0;
 /**
 * Forces synchronization of mailbox. This can be called
 * case the mailbox is offline in the beginning, connection
 * is made up for the time of the synchronization.
 *
 * All collections (mail etc.) supported by the plugin and
 * enabled by user settings are synchronized.
 *
 * This is an asynchronous operation and the request id
 * is returned for cancelling purpose.
 *
 * Observer is given as a parameter to enable callbacks
 * related to this operation. Alternatively user can use
 * empty implementation of the observer function and rely
 * only on events. Notice that the event system is not as
 * comprehensive as the observing way do this.
 * @param aRequestId identifies asynchronous request
 	 */
 virtual void RefreshNowL(	const TFSMailMsgId& aMailBoxId,
 						MFSMailRequestObserver& aOperationObserver,
 						TInt aRequestId ) = 0;
 	// FOLDER HANDLING
 /**
 * returns email folder object related to given folder id
 * folder data set by plugin :
 *				 - folder id
 *               - folder name
 *				 - folder type ; Inbox, Outbox, Sent, Drafts, Deleted, Other
 *               - message count
 *               - unread message count
 *               - mailbox id
 	 *				 - parent folder
 * @param aMailBoxId defines mailbox id
 * @param aFolderId defines folder id
 * @return folder object (CFSMailFolder) to be owned by user
 */
 	 virtual CFSMailFolder* GetFolderByUidL( const TFSMailMsgId& aMailBoxId,
 	 										 const TFSMailMsgId& aFolderId ) = 0;
 /**
 * creates new folder
 *
 * @param aMailBoxId defines mailbox where folder is created
 * @param aFolderId defines id of the parent folder
 * @param aFolderName defines name of the new folder
 * @param aSync defines if new folder is local only (false)
 * or if it also should sync to server (true)
 	 virtual void DeleteFolderByUidL(	const TFSMailMsgId& aMailBoxId,
 	 									const TFSMailMsgId& aFolderId) = 0;
 	/**
 	 * List subfolders of given folder. Only direct subfolders of given folder are returned.
 	 * Folder data :
 	 * - folder id
 	 * - folder name
 	 * - folder type ; Inbox, Outbox, Sent, Drafts, Deleted, Other
 	 * - message count
 	 * - unread message count
 	 * - mailbox id
 	 * - parent folder
 	 * - subfolder count
 	 *
 	 * @param aMailBoxId defines mailbox where parent folder is
 	 * @param aFolderId defines parent folder id. TFSMailId::NullId() for root level list.
 	 * @param aFolderList plugin writes results in this array given by user
 	 */
 	virtual void ListFoldersL(	const TFSMailMsgId& aMailBoxId,
 	    						const TFSMailMsgId& aParentFolderId,
 	    						RPointerArray<CFSMailFolder>& aFolderList) = 0;
 	/**
 	 * List all subfolders of given mailbox.
 	 * folder data :
 	 * - folder id
 	 * - folder name
 	 * - folder type ; Inbox, Outbox, Sent, Drafts, Deleted, Other
 	 * - message count
 	 * - unread message count
 	 * - mailbox id
 	 * - parent folder
 	 * - subfolder count
 	 *
 	 * @param aMailBoxId defines mailbox
 	 * @param aFolderList plugin writes results in this array given by user.
 	 * Caller must determine tree structure by examining parent id of each returned folder.
 	 */
 	 virtual void ListFoldersL(	const TFSMailMsgId& aMailBoxId,
 	    						RPointerArray<CFSMailFolder>& aFolderList) = 0;
 /**
 * return folder id of given folder type
 *
 * @param aMailBoxId defines mailbox where folder is
 * @param aFolderType folder type
 virtual MFSMailIterator* ListMessagesL( const TFSMailMsgId& aMailBoxId,
 									 const TFSMailMsgId& aFolderId,
 									 const TFSMailDetails aDetails,
 									 const RArray<TFSMailSortCriteria>& aSorting ) = 0;
 /**
 * returns email message object related to given message id
 *
 * message info set by plugin :
 *				  - message id
 * @param aMessages defines ids of messages to be deleted
 */
 	 virtual void DeleteMessagesByUidL( const TFSMailMsgId& aMailBoxId,
 	 									const TFSMailMsgId& aFolderId,
 	 									const RArray<TFSMailMsgId>& aMessages ) = 0;
 /**
 * creates new message template into drafts folder
 *
 * @param aMailBoxId defines mailbox where message is created
 * @return message object to be modified by user (ownership is transferred to user)
 */
 	 virtual CFSMailMessage* CreateMessageToSendL( const TFSMailMsgId& aMailBoxId ) = 0;
 /**
 * creates new message template to drafts folder to be forwarded
 *
 * @param aMailBoxId defines mailbox where message is created
 * @param aOriginalMessageId defines original message,which is forwarded
 * @return message object to be modified by user (ownership is transferred to user)
 */
 	 virtual CFSMailMessage* CreateForwardMessageL( const TFSMailMsgId& aMailBoxId,
 	 												const TFSMailMsgId& aOriginalMessageId ) = 0;
 /**
 * creates new reply message template to drafts folder
 * @param aMailBoxId defines mailbox where message is created
 * @param aOriginalMessageId defines id of original message,which is replied to
 * @param aReplyToAll
 * @return message object to be modified by user (ownership is transferred to user)
 */
 	 virtual CFSMailMessage* CreateReplyMessageL( const TFSMailMsgId& aMailBoxId,
 	 											  const TFSMailMsgId& aOriginalMessageId,
 	 											  const TBool aReplyToAll ) = 0;
 /**
 * stores message data to message store after modifications (commit)
 *
 * @param aMailBoxId defines mailbox where message is stored
 * @param aMessage message data to be stored by plugin
 							 	const TFSMailMsgId& aParentFolderId,
 							 	const RArray<TFSMailMsgId>& aMessageIds,
 							 	TFSMailDetails aDetails,
 							 	MFSMailRequestObserver& aObserver,
 							 	TInt aRequestId) = 0;
 /**
 * DEPRECATED
 * Fetches message part contents from server asynchronously.
 *
 * @param aMessagePartIds define message part ids of message parts that are asked to be fetched
 */
 virtual void FetchMessagePartsL( 	const RArray<TFSMailMsgId>& aMessagePartIds,
 								MFSMailRequestObserver& aOperationObserver,
 										const TInt aRequestId,
 								const TUint aPreferredByteCount) = 0;
 /* synchronous message accessor
 	 *
 * @param aMailBoxId defines mailbox where message is located
 * @param aParentFolderId defines parent folder where message is located
 virtual void GetMessagesL(	const TFSMailMsgId& aMailBoxId,
 							const TFSMailMsgId& aParentFolderId,
 							const RArray<TFSMailMsgId>& aMessageIds,
 							RPointerArray<CFSMailMessage>& aMessageList,
 							const TFSMailDetails aDetails ) = 0;
 /**
 * Returns child part objects for given message part. Ownership of objects
 * is transferred to caller.
 *
 * @param aMailBoxId defines mailbox where message is located
 						 	RPointerArray<CFSMailMessagePart>& aParts) = 0;
 /**
 * Creates and adds a new child part to this part.
 * If aInsertBefore is NULL id then new part is added as last.
 *
 * @param aMailBoxId defines mailbox where message is located
 * @param aParentFolderId defines parent folder where message is located
 * @param aMessageId gives the id of the message that message part belongs to
 * @param aParentPartId parent of the new part
 * @param aInsertBefore id of existing part that new part should precede.
 * If NULL id then new part is added as last.
 */
 virtual CFSMailMessagePart* NewChildPartL( const TFSMailMsgId& aMailBoxId,
 				     							const TFSMailMsgId& aParentFolderId,
 												const TFSMailMsgId& aMessageId,
 											const TFSMailMsgId& aParentPartId,
 										const TFSMailMsgId& aInsertBefore,
 												const TDesC& aContentType) = 0;
 /**
 * Copies given message as new child part to this part.
 *
 * @param aMailBoxId defines mailbox where message is located
 * @param aParentFolderId defines parent folder where message is located
 * @param aMessageId gives the id of the message that message part belongs to
 * @param aParentPartId parent of the new part
 * @param aInsertBefore id of existing part that new part should precede.
 * If NULL id then new part is added as last.
 * @param aMessage specifies the message that is copied
 */
 virtual CFSMailMessagePart* CopyMessageAsChildPartL(const TFSMailMsgId& aMailBoxId,
 						     							 const TFSMailMsgId& aParentFolderId,
 														 const TFSMailMsgId& aMessageId,
 												 const TFSMailMsgId& aParentPartId,
 												 const TFSMailMsgId& aInsertBefore,
 												 const CFSMailMessage& aMessage) = 0;
 /**
 * Removes child part (and its children, if any) from this part
 *
 * @param aMailBoxId defines mailbox where message is located
 * @param aParentFolderId defines parent folder where message is located
 * @param aMessageId gives the id of the message that message part belongs to
 * @param aParentPartId parent of the part
 * @param aPartId part to remove
 */
 virtual void RemoveChildPartL(	const TFSMailMsgId& aMailBoxId,
 	     							const TFSMailMsgId& aParentFolderId,
 								 	const TFSMailMsgId& aMessageId,
 							const TFSMailMsgId& aParentPartId,
 							const TFSMailMsgId& aPartId) = 0;
 									const TFSMailMsgId& aMessagePartId,
 									RFile& aFileHandle) = 0;
 /**
 * copies message part to given location
 *
 *
 * @param aMailBoxId defines mailbox where message is located
 * @param aParentFolderId defines parent folder where message is located
 * @param aMessageId gives the id of the message that message part belongs to
 * @param aMessagePartId gives the id of the message part
 									const TDesC& aFilePath) = 0;
 /**
 * gets message part content to given buffer
 *
 *
 * @param aMailBoxId defines mailbox where message is located
 * @param aParentFolderId defines parent folder where message is located
 * @param aMessageId gives the id of the message that message part belongs to
 * @param aMessagePartId gives the id of the message part
 * @param aBuffer
 * @param aStartOffset
 */
 	 virtual void GetContentToBufferL(	const TFSMailMsgId& aMailBoxId,
 	 	     							const TFSMailMsgId& aParentFolderId,
 								 		const TFSMailMsgId& aMessageId,
 	 							 		const TFSMailMsgId& aMessagePartId,
 	 							 		TDes& aBuffer,
 	 							 		const TUint aStartOffset) = 0;
 /**
 * stores message part content
 *
 *
 * @param aBuffer message part content
 * @param aMailBoxId defines mailbox where message is located
 * @param aParentFolderId defines parent folder where message is located
 * @param aMessageId gives the id of the message that message part belongs to
 */
 	 virtual void SetContentL(	const TDesC& aBuffer,
 	 						  	const TFSMailMsgId& aMailBoxId,
 							const TFSMailMsgId& aParentFolderId,
 								const TFSMailMsgId& aMessageId,
 	 							const TFSMailMsgId& aMessagePartId) = 0;
 /**
 * Removes fetched contents of these parts.
 *
 * @param aMailBoxId defines mailbox where message is located
 * @param aParentFolderId defines parent folder where message is located
 * @param aMessageId gives the id of the message that message part belongs to
 * @param aPartIds Array of message part ids.
 */
 virtual void RemovePartContentL( 	const TFSMailMsgId& aMailBoxId,
 	     							const TFSMailMsgId& aParentFolderId,
 									  	const TFSMailMsgId& aMessageId,
 								  	const RArray<TFSMailMsgId>& aPartIds) = 0;
 /**
 * Sets contents from given file. Possible old contents are replaced.
 *
 *
 * @param aMailBoxId defines mailbox where message is located
 * @param aParentFolderId defines parent folder where message is located
 * @param aMessageId gives the id of the message that message part belongs to
 * @param aMessagePartId gives the id of the message part
 	     							 const TFSMailMsgId& aParentFolderId,
 									 const TFSMailMsgId& aMessageId,
 							 CFSMailMessagePart& aMessagePart) = 0;
 /**
 * unregisters plugin request observer to cancel pending events
 *
 * @param aRequestId request id of the pending asynchronous request
 */
 	 virtual void UnregisterRequestObserver(TInt aRequestId) = 0;
 // MESSAGE SENDING
 /**
 * DEPRECATED
 *
 * starts message sending done by plugin
 * cancellation is deleting the message from outbox
 *
 * @param aMessageId defines message id to be sent
 */
 virtual void SendL( TFSMailMsgId aMessageId ) = 0;
 /**
 * starts message sending done by plugin
 * cancellation is deleting the message from outbox
 *
 * @param aMessage message to be sent
 */
 virtual void SendMessageL( CFSMailMessage& aMessage ) = 0;
 /**
 * method for canceling pending request
 * @param aRequestId identifies request if parallel requests exists
 	 */
 virtual void CancelL( const TInt aRequestId ) = 0;
 	// Search API
 	// OPEN: IDS plugin nippets?
 /**
 * Asyncronous call for starting search for given string. Only one search can be
 * performed at a time.
 *
 *
 * This function will search for message's containing the given search string.
 * The search will be performed on the all message fields: To, Cc, Bcc, subject, body.
 * The search client will be notified of each found message,
 * and upon completion of the search.  Only one search can be performed at a time.
 *
 * To change the sort order in the search result, use the same search string in the
 * but change the aSortCriteria parameter.  The store "caches" the search
 * results generated by the same search string.
 *
 * The function will leave with KErrInUse if a search is already in progress.
 	 *
 * /note Only works if the store is in an authenticated state,
 *  otherwise this function leaves with KErrNotReady
 *
 * @param aFolderIds list of folders where messages are to be searched
 * @param aSearchStrings text strings that will be searched from different message fields.
 	 * @param aSortCriteria sort criteria for the results
 * @param aSearchObserver client observer that will be notified about search status.
 *
 */
 	virtual void SearchL( const TFSMailMsgId& aMailBoxId,
 						  const RArray<TFSMailMsgId>& aFolderIds,
 						  const RPointerArray<TDesC>& aSearchStrings,
 						  const TFSMailSortCriteria& aSortCriteria,
 					      MFSMailBoxSearchObserver& aSearchObserver ) = 0;
 /**
 * Cancels current search. Does nothing if there is not any search.
 * The search client will not be called back after this function is called.
 	 *
 * \note CancelSearch() method does NOT clear the search result cached in the store.
 *       A different sort order can be used for the same search string, and the
 *       cache will be utilized.  Only by using a different search string can the
 *       cache be cleaned.
 	 *
 * @paran aMailBoxId mailbox where the search should be cancelled
 	 *
 */
 	virtual void CancelSearch( const TFSMailMsgId& aMailBoxId ) = 0;
 /** Inform the store to clean up its cache for search results.
 *
 *  This method cancels the the ongoing search (if exists), and then clean ups store's cache.
 *
 *  This function should be called when search results are no longer in display.
 	 *
 * @paran aMailBoxId mailbox where the search cache should be cleared
 	 *
 */
 /**
 * Returns the current sync state for this mailbox.
 *
 * @param aMailboxId id of target mailbox
 */
-virtual const TSSMailSyncState CurrentSyncState(const TFSMailMsgId& aMailboxId) = 0;
+virtual TSSMailSyncState CurrentSyncState(const TFSMailMsgId& aMailboxId) = 0;
 /**
 * Sets the mailbox name for this mailbox.
 *
 * @param aMailboxId id of target mailbox
 * @param aMailboxName new name for the mailbox
 */
 virtual void SetMailboxName(const TFSMailMsgId& aMailboxId, const TDesC& aMailboxName );
 	};
 #endif  // M_FSMAILPLUGIN_H

changeset 20	ecc8def7944a
parent 18	578830873419
child 62	a8c646b56683