1 /*

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

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

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

     6 * which accompanies this distribution, and is available

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

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  email framework user interface

    15 *

    16 */

    17 

    18 

    19 #ifndef __FSMAILCLIENT_H

    20 #define __FSMAILCLIENT_H

    21 

    22 #include <e32std.h>

    23 #include <e32base.h>

    24 

    25 #include "CFSMailClient.hrh"

    26 #include "cemailextensionbase.h"

    27 

    28 #include "mfsmailbrandmanager.h"

    29 #include "cfsmailplugin.h"

    30 

    31 

    32 class CFSFWImplementation;

    33 class CFSMailPluginManager;

    34 

    35 	/**

    36 	* @mainpage Freestyle Email API

    37 	*

    38 	* @section sec1 Introduction

    39 	*

    40 	*    This is the mail API and framework used by the Freestyle email

    41 	*    client. It provides access to the message store for reading email

    42 	*    and to the sync engine for starting and stopping synchronizations.

    43 	*

    44 	* @section sec2 Typical Usage From UI

    45 	*

    46 	*  	// Initialize the access to the mail framework

    47 	*  	CFSMailClient* mail = CFSMailClient::NewL();

    48 	*  	CleanupClosePushL(*mail);

    49     * 

    50 	*  	// List mailboxes for user to select which one to open

    51 	*	RPointerArray<CFSMailBox> mailBoxes;

    52 	*	mailBoxes.Reset();

    53 	*	TFSMailMsgId plugin; // null id if all mailboxes required

    54 	*	mail->ListMailBoxes(plugin,mailBoxes);

    55     *   // Lets select the first one this time

    56 	*  	CFSMailBox * currentMailbox = mailboxes[0]; 

    57     * 

    58 	*   // list all mailbox folders for user

    59 	*   RPointerArray<CFSMailFolder> folders = currentMailBox->ListFolders( );

    60 	*

    61 	*   // or get default folder, for example inbox

    62 	*	TFSMailMsgId folderId;

    63 	*	folderId = mailBox->GetStandardFolderId( EFSInbox );

    64 	*  	CFSMailFolder* inbox = mail->GetFolderByUid(currentMailBox->GetId(),folderId);

    65 	*

    66 	*   // List messages in inbox

    67 	*   // select message details to be listed

    68 	*   TFSMailDetails details(EFSMsgDataStructure);

    69     *	

    70 	*   // set sorting criteria

    71     *   TFSMailSortCriteria criteria;

    72     *   criteria.iField = EFSMailSortByDate;

    73     *   criteria.iOrder = EFSMailAscending;

    74     *   RArray<TFSMailSortCriteria> sorting;

    75     *   sorting.Append(criteria);

    76     *

    77     *   // get email list iterator from plugin

    78 	*   MFSMailIterator* iterator = folder->ListMessagesL(details,sorting);

    79     *

    80     *   //  list all messages from folder

    81     *   TFSMailMsgId currentMessageId; // first call contains NULL id as begin id

    82     *   RPointerArray<CFSMailMessage> messages;

    83     *   messages.Reset();

    84     *   iterator->NextL(currentMessageId, folder->GetMessageCount(), messages);

    85     *		

    86 	*   // Show the first 5 messages to in the UI

    87 	*   for(TInt i=0;i<messages.Count() && i<5;i++)

    88 	*   {

    89     *       MyHeaderShowMethod(messages[i]->GetSender().GetEmailAddress(),

    90     *                          messages[i]->GetSubject()

    91     *                          messages[i]->GetDate());

    92     *

    93     *       // get email body

    94 	*       CFSMailMessagePart* body = messages[i]->PlainTextBodyPartL();

    95     *       if(body)

    96     *       {

    97     *           TBuf<n> text;

    98     *           TInt startOffset = 0;

    99     *           body->GetContentToBufferL(text,startOffset);

   100     *           MyPlainTextBodyShowMethod(text);

   101     *           delete body;		

   102     *       }

   103     *

   104     *       //list email attachments

   105     *       RPointerArray<CFSMailMessagePart> attachments;

   106     *       attachments.Reset();

   107     *       messages[i]->AttachmentListL(attachments);

   108     *       for(TInt i=0;i<attachments.Count();i++)

   109     *       {

   110     *           MyShowAttachmentNameMethod(attachments[i]->AttachmentName());

   111     *       }

   112     *       attachments.ResetAndDestroy();

   113     *   }

   114 	*

   115     *   // clean iterator and tables

   116     *   messages.ResetAndDestroy();

   117     *   delete iterator;

   118     *   sorting.Reset();

   119     *   delete folder;

   120     *

   121 	*   // User should call close when terminating mail framework usage

   122 	*   // when shutting down application close mail client singleton

   123 	*   CleanupStack::PopAndDestroy(mail);

   124 	*

   125 	* @section sec3 Observing Email Events.

   126 	*

   127 	*   // To be able to observe events an user has to

   128 	*   // implement MFSMailEventObserver interface.

   129 	*   // Here the COwnMailObserver class implements the interface.

   130 	*   COwnMailObserver* ownObserver = COwnMailObserver::NewL();

   131 	*

   132 	*   // Register to observe mail store events

   133 	*   mail->AddObserverL(*ownObserver);

   134 	*

   135 	*   // Now callbacks are done via the EventL function defined

   136 	*   // in the MFSMailEventObserver and implemented in this case

   137 	*   // by the COwnMailObserver

   138 	*

   139 	*   // When user does not wish to observe events anymore

   140 	*   // he has to unregister

   141 	*   mail->RemoveObserver( *ownObserver );

   142 	*

   143 	*   // Remember that it must be done for each observer

   144 	*   // in the end of the observation because the AddObserverL

   145 	*   // does not replace the observer

   146 	*

   147 	* @section sec_groups Classes

   148 	*

   149 	* The following classes form the public API of the frame work.

   150 	*

   151 	* @section sec_info More Information

   152 	*

   153 	* Copyright © 2006 Nokia.  All rights reserved.

   154 	*

   155 	* This material, including documentation and any related computer programs, 

   156 	* is protected by copyright controlled by Nokia.  All rights are reserved.  

   157 	* Copying, including reproducing, storing, adapting or translating, any or 

   158 	* all of this material requires the prior written consent of Nokia.  This 

   159 	* material also contains confidential information which may not be disclosed 

   160 	* to others without the prior written consent of Nokia.

   161 	*/

   162 

   163 NONSHARABLE_CLASS(CFSMailClient) : public CExtendableEmail

   164 {

   165  public:

   166     

   167     /**

   168      * Creates a new CFSMailClient singleton instance or increments

   169      * reference count if singleton already exists

   170      *

   171      * @return CFSMailClient pointer

   172      */

   173      IMPORT_C static CFSMailClient* NewL();

   174 

   175     /**

   176      * Creates a new CFSMailClient singleton instance or increments

   177      * reference count if singleton already exists

   178      *

   179      * @return CFSMailClient pointer

   180      */

   181      IMPORT_C static CFSMailClient* NewL( TInt aConfiguration );

   182   	

   183     /**

   184      * Creates a new CFSMailClient singleton instance or increments

   185      * reference count if singleton already exists

   186      *

   187      * @return CFSMailClient pointer

   188      */

   189      IMPORT_C static CFSMailClient* NewLC( TInt aConfiguration );

   190 

   191     /**

   192      * CFSMailClient destructor, removes CFSMailClient singleton instance

   193      * or decrements reference count if singleton is used by other applications

   194      */

   195      IMPORT_C void Close();

   196 

   197     /**

   198      * plugin manager accessor

   199      */

   200      IMPORT_C CFSMailPlugin* GetPluginManager();

   201 

   202     /**

   203      * if plugin id is null id, function goes through all plugins and lists existing

   204      * mailboxes, otherwise lists existing mailboxes contained by given plugin

   205      *

   206      * @param aPluginId plugin id

   207      * @param aMailBoxes table containing ids of existing mailboxes owned by user

   208      */

   209      IMPORT_C TInt ListMailBoxes(const TFSMailMsgId aPluginId, RPointerArray<CFSMailBox>& aMailboxes);

   210 

   211     /**

   212      * returns email mailbox object related to given mailbox id

   213      *

   214      * @param aMailBoxId mailbox id

   215      * @return mailbox object ( CFSMailBox ), ownership is transferred to user

   216      */

   217      IMPORT_C CFSMailBox* GetMailBoxByUidL( const TFSMailMsgId aMailBoxId);

   218       	  		

   219     /**

   220      * returns email folder object related to given folder id

   221      *

   222      * @param aMailBoxId id of mailbox containing folder

   223      * @param aFolderId folder id

   224      *

   225      * @return folder object (CFSMailFolder), ownership is transferred to user

   226      */

   227      IMPORT_C CFSMailFolder* GetFolderByUidL( const TFSMailMsgId aMailBoxId, const TFSMailMsgId aFolderId );

   228 

   229     /**

   230      * returns email object related to given message id

   231      *

   232      * @param aMailBoxId id of mailbox containing email

   233      * @param aFolderId id of folder containing email

   234      * @param aMessageId message id

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

   236      *

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

   238      */

   239 	 IMPORT_C CFSMailMessage* GetMessageByUidL(const TFSMailMsgId aMailBoxId, const TFSMailMsgId aFolderId,

   240 	 										  const TFSMailMsgId aMessageId, const TFSMailDetails aDetails );	 										  

   241     /**

   242      * deletes emails defined in message id list

   243      *

   244      * @param aMailBoxId id of mailbox containing emails

   245      * @param aFolderId id of folder containing email

   246      * @param aMessageIds defines ids of email to be deleted

   247      */

   248      IMPORT_C void DeleteMessagesByUidL( const TFSMailMsgId aMailBoxId, const TFSMailMsgId aFolderId, 

   249 	 									 const RArray<TFSMailMsgId>& aMessageIds );

   250 

   251     /**

   252      * Deletes mail account. This asynchronous operation returns id that can

   253      * be later used for cancelling the operation.

   254      *

   255      * @param aMailBoxId id of the mailbox to be deleted

   256      * @param aOperationObserver observer to forward request events to user

   257      */

   258      IMPORT_C TInt DeleteMailBoxByUidL( const TFSMailMsgId aMailBoxId,

   259                                         MFSMailRequestObserver& aOperationObserver );

   260 

   261     /**

   262      * List emails. Returns iterator, which user can use to scroll email list

   263      * forwards and backwards.

   264      *

   265      * @param aMailBoxId id of mailbox containing emails

   266      * @param aFolderId id of folder containing emails

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

   268      * (CFSMailMessage) returned by the iterator

   269      * @param aSorting sort criteria requested by user.

   270      * First item in array is primary sort criteria.

   271      *

   272      * @return email list iterator, ownership is transferred to user

   273      */

   274      IMPORT_C MFSMailIterator* ListMessages(

   275         						const TFSMailMsgId aMailBoxId,

   276         						const TFSMailMsgId  aFolderId,

   277         						const TFSMailDetails  aDetails,

   278         						const RArray<TFSMailSortCriteria>& aSorting);

   279 

   280     /**

   281      * returns branding manager to handle branding elements

   282      *

   283      * @return branding manager (ownership in framework)

   284      */

   285      IMPORT_C MFSMailBrandManager& GetBrandManagerL( void );

   286 

   287     /**

   288      * Adds a new event observer. There can be several observers active at

   289      * the same time. Caller MUST call RemoveObserver before destroying given

   290      * observer object.

   291      *

   292      * @param aObserver observer implementation

   293      */

   294      IMPORT_C void AddObserverL(MFSMailEventObserver& aObserver);

   295      

   296     /**

   297      * Removes event observer

   298      *

   299      * @param aObserver observer to be removed

   300      */

   301      IMPORT_C void RemoveObserver(MFSMailEventObserver& aObserver);

   302 

   303     /**

   304      * unregisters plugin request observer to cancel pending events  

   305      *

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

   307      */

   308      IMPORT_C void UnregisterRequestObserver(TInt aRequestId);

   309 

   310     /**

   311      * Subscribes events from given mailbox

   312      *

   313      * @param aMailboxId id of target mailbox

   314      * @param aObserver observer given by user

   315      */

   316      IMPORT_C void SubscribeMailboxEventsL(TFSMailMsgId aMailboxId, MFSMailEventObserver& aObserver);

   317 

   318     /**

   319      * Unsubscribes events from given mailbox

   320      * UnsubscribeMailboxEvents MUST be called before destroying given observer object.

   321      *

   322      * @param aMailboxId id of target mailbox

   323      * @param aObserver observer implementation

   324      */

   325      IMPORT_C void UnsubscribeMailboxEvents(TFSMailMsgId aMailboxId, MFSMailEventObserver& aObserver);

   326 

   327     /**

   328      * Sends notification to all protocol plugins that there is

   329      * Email Wizard data available for some of them.

   330      *

   331      * Can return any of the standard Symbian error codes if

   332      * one of the plugins reports failed mailbox configuration.

   333      */

   334      IMPORT_C TInt WizardDataAvailableL();

   335 

   336     /**

   337      * Client can call this function to immediately initialize authentications that are mandatory

   338      * to get services from protocol plugins. This means e.g. store authentications. FW will

   339      * internally ask authentication from all existing plugins before this operations completes.

   340      *

   341      * @param aOperationObserver is client provided observer that will receive progress

   342      * notifications during the operation.

   343      */

   344      IMPORT_C TInt AuthenticateL(MFSMailRequestObserver& aOperationObserver);

   345 

   346     /**

   347      * get framework temp directory

   348 	 */

   349      IMPORT_C TDesC& GetTempDirL( );

   350 

   351     /**

   352      * clean framework temp directory

   353 	 */

   354      IMPORT_C void CleanTempDirL( );

   355 

   356     /**

   357      * cancels single pending asynchronous request

   358      *

   359      * @param aRequestId identifies request

   360 	 */

   361      IMPORT_C void CancelL( const TInt aRequestId );

   362 

   363     /**

   364      * cancels all pending asynchronous requests

   365 	 */

   366      IMPORT_C void CancelAllL( );

   367 

   368      /**

   369       * Calls plugin to change the name of the mailbox

   370       *

   371       * @param aMailboxId mailbox id

   372       * @param aMailboxName new name for the mailbox

   373       */

   374      IMPORT_C void SetMailboxName( const TFSMailMsgId aMailboxId, const TDesC& aMailboxName );

   375 

   376 public: // from  CExtendableEmail

   377 

   378     /**

   379 	 * @see CExtendableEmail::ReleaseExtension

   380 	 */

   381     IMPORT_C virtual void ReleaseExtension( CEmailExtension* aExtension );

   382 

   383     /**

   384     * Requests extension. Default implementation performs lookup only and

   385     * derived class should implement actual instantiation because it knows

   386     * extensions it supports

   387     * array but does not delete it.

   388     * @param aExtension extension to release

   389     */

   390     IMPORT_C virtual CEmailExtension* ExtensionL( const TUid& aInterfaceUid );

   391         

   392  protected:

   393 

   394  private:

   395 

   396     /**

   397      * C++ default constructor.

   398      */

   399      CFSMailClient();

   400 

   401     /**

   402      * Destructor.

   403      */

   404      ~CFSMailClient();

   405 

   406     /**

   407      * ConstructL

   408      */

   409 	 void ConstructL( TInt aConfiguration );

   410 

   411     /**

   412      * returns framework singleton instance if exists

   413      */

   414 	 static CFSMailClient* Instance();

   415 

   416     /**

   417      * increments reference count to framework singleton

   418      */

   419      TInt IncReferenceCount();

   420 

   421     /**

   422      * decrements reference count to framework singleton

   423      */

   424      TInt DecReferenceCount();

   425 

   426  private: // data

   427 

   428 	/** framework singleton reference count */

   429     TInt                     iReferenceCount;

   430 

   431 	/** */

   432     CFSFWImplementation*     iFWImplementation;

   433 	 

   434 	/** branding manager pointer  */

   435     MFSMailBrandManager*     iBrandManager;

   436 };

   437 

   438 #endif // __FSMAILCLIENT_H