diff -r 000000000000 -r 8466d47a6819 emailservices/emailframework/inc/CFSMailClient.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/emailservices/emailframework/inc/CFSMailClient.h Thu Dec 17 08:39:21 2009 +0200 @@ -0,0 +1,438 @@ +/* +* Copyright (c) 2007-2008 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". +* +* Initial Contributors: +* Nokia Corporation - initial contribution. +* +* Contributors: +* +* Description: email framework user interface +* +*/ + + +#ifndef __FSMAILCLIENT_H +#define __FSMAILCLIENT_H + +#include +#include + +#include "CFSMailClient.hrh" +#include "cemailextensionbase.h" + +#include "mfsmailbrandmanager.h" +#include "cfsmailplugin.h" + + +class CFSFWImplementation; +class CFSMailPluginManager; + + /** + * @mainpage Freestyle Email API + * + * @section sec1 Introduction + * + * This is the mail API and framework used by the Freestyle email + * client. It provides access to the message store for reading email + * and to the sync engine for starting and stopping synchronizations. + * + * @section sec2 Typical Usage From UI + * + * // Initialize the access to the mail framework + * CFSMailClient* mail = CFSMailClient::NewL(); + * CleanupClosePushL(*mail); + * + * // List mailboxes for user to select which one to open + * RPointerArray mailBoxes; + * mailBoxes.Reset(); + * TFSMailMsgId plugin; // null id if all mailboxes required + * mail->ListMailBoxes(plugin,mailBoxes); + * // Lets select the first one this time + * CFSMailBox * currentMailbox = mailboxes[0]; + * + * // list all mailbox folders for user + * RPointerArray folders = currentMailBox->ListFolders( ); + * + * // or get default folder, for example inbox + * TFSMailMsgId folderId; + * folderId = mailBox->GetStandardFolderId( EFSInbox ); + * CFSMailFolder* inbox = mail->GetFolderByUid(currentMailBox->GetId(),folderId); + * + * // List messages in inbox + * // select message details to be listed + * TFSMailDetails details(EFSMsgDataStructure); + * + * // set sorting criteria + * TFSMailSortCriteria criteria; + * criteria.iField = EFSMailSortByDate; + * criteria.iOrder = EFSMailAscending; + * RArray sorting; + * sorting.Append(criteria); + * + * // get email list iterator from plugin + * MFSMailIterator* iterator = folder->ListMessagesL(details,sorting); + * + * // list all messages from folder + * TFSMailMsgId currentMessageId; // first call contains NULL id as begin id + * RPointerArray messages; + * messages.Reset(); + * iterator->NextL(currentMessageId, folder->GetMessageCount(), messages); + * + * // Show the first 5 messages to in the UI + * for(TInt i=0;iGetSender().GetEmailAddress(), + * messages[i]->GetSubject() + * messages[i]->GetDate()); + * + * // get email body + * CFSMailMessagePart* body = messages[i]->PlainTextBodyPartL(); + * if(body) + * { + * TBuf text; + * TInt startOffset = 0; + * body->GetContentToBufferL(text,startOffset); + * MyPlainTextBodyShowMethod(text); + * delete body; + * } + * + * //list email attachments + * RPointerArray attachments; + * attachments.Reset(); + * messages[i]->AttachmentListL(attachments); + * for(TInt i=0;iAttachmentName()); + * } + * attachments.ResetAndDestroy(); + * } + * + * // clean iterator and tables + * messages.ResetAndDestroy(); + * delete iterator; + * sorting.Reset(); + * delete folder; + * + * // User should call close when terminating mail framework usage + * // when shutting down application close mail client singleton + * CleanupStack::PopAndDestroy(mail); + * + * @section sec3 Observing Email Events. + * + * // To be able to observe events an user has to + * // implement MFSMailEventObserver interface. + * // Here the COwnMailObserver class implements the interface. + * COwnMailObserver* ownObserver = COwnMailObserver::NewL(); + * + * // Register to observe mail store events + * mail->AddObserverL(*ownObserver); + * + * // Now callbacks are done via the EventL function defined + * // in the MFSMailEventObserver and implemented in this case + * // by the COwnMailObserver + * + * // When user does not wish to observe events anymore + * // he has to unregister + * mail->RemoveObserver( *ownObserver ); + * + * // Remember that it must be done for each observer + * // in the end of the observation because the AddObserverL + * // does not replace the observer + * + * @section sec_groups Classes + * + * The following classes form the public API of the frame work. + * + * @section sec_info More Information + * + * Copyright © 2006 Nokia. All rights reserved. + * + * This material, including documentation and any related computer programs, + * is protected by copyright controlled by Nokia. All rights are reserved. + * Copying, including reproducing, storing, adapting or translating, any or + * all of this material requires the prior written consent of Nokia. This + * material also contains confidential information which may not be disclosed + * to others without the prior written consent of Nokia. + */ + +NONSHARABLE_CLASS(CFSMailClient) : public CExtendableEmail +{ + public: + + /** + * Creates a new CFSMailClient singleton instance or increments + * reference count if singleton already exists + * + * @return CFSMailClient pointer + */ + IMPORT_C static CFSMailClient* NewL(); + + /** + * Creates a new CFSMailClient singleton instance or increments + * reference count if singleton already exists + * + * @return CFSMailClient pointer + */ + IMPORT_C static CFSMailClient* NewL( TInt aConfiguration ); + + /** + * Creates a new CFSMailClient singleton instance or increments + * reference count if singleton already exists + * + * @return CFSMailClient pointer + */ + IMPORT_C static CFSMailClient* NewLC( TInt aConfiguration ); + + /** + * CFSMailClient destructor, removes CFSMailClient singleton instance + * or decrements reference count if singleton is used by other applications + */ + IMPORT_C void Close(); + + /** + * plugin manager accessor + */ + IMPORT_C CFSMailPlugin* GetPluginManager(); + + /** + * if plugin id is null id, function goes through all plugins and lists existing + * mailboxes, otherwise lists existing mailboxes contained by given plugin + * + * @param aPluginId plugin id + * @param aMailBoxes table containing ids of existing mailboxes owned by user + */ + IMPORT_C TInt ListMailBoxes(const TFSMailMsgId aPluginId, RPointerArray& aMailboxes); + + /** + * returns email mailbox object related to given mailbox id + * + * @param aMailBoxId mailbox id + * @return mailbox object ( CFSMailBox ), ownership is transferred to user + */ + IMPORT_C CFSMailBox* GetMailBoxByUidL( const TFSMailMsgId aMailBoxId); + + /** + * returns email folder object related to given folder id + * + * @param aMailBoxId id of mailbox containing folder + * @param aFolderId folder id + * + * @return folder object (CFSMailFolder), ownership is transferred to user + */ + IMPORT_C CFSMailFolder* GetFolderByUidL( const TFSMailMsgId aMailBoxId, const TFSMailMsgId aFolderId ); + + /** + * returns email object related to given message id + * + * @param aMailBoxId id of mailbox containing email + * @param aFolderId id of folder containing email + * @param aMessageId message id + * @param aDetails defines which details are included in email object + * + * @return email object (CFSMailMessage), ownership is transferred to user + */ + IMPORT_C CFSMailMessage* GetMessageByUidL(const TFSMailMsgId aMailBoxId, const TFSMailMsgId aFolderId, + const TFSMailMsgId aMessageId, const TFSMailDetails aDetails ); + /** + * deletes emails defined in message id list + * + * @param aMailBoxId id of mailbox containing emails + * @param aFolderId id of folder containing email + * @param aMessageIds defines ids of email to be deleted + */ + IMPORT_C void DeleteMessagesByUidL( const TFSMailMsgId aMailBoxId, const TFSMailMsgId aFolderId, + const RArray& aMessageIds ); + + /** + * Deletes mail account. This asynchronous operation returns id that can + * be later used for cancelling the operation. + * + * @param aMailBoxId id of the mailbox to be deleted + * @param aOperationObserver observer to forward request events to user + */ + IMPORT_C TInt DeleteMailBoxByUidL( const TFSMailMsgId aMailBoxId, + MFSMailRequestObserver& aOperationObserver ); + + /** + * List emails. Returns iterator, which user can use to scroll email list + * forwards and backwards. + * + * @param aMailBoxId id of mailbox containing emails + * @param aFolderId id of folder containing emails + * @param aDetails defines which details are included in each email object + * (CFSMailMessage) returned by the iterator + * @param aSorting sort criteria requested by user. + * First item in array is primary sort criteria. + * + * @return email list iterator, ownership is transferred to user + */ + IMPORT_C MFSMailIterator* ListMessages( + const TFSMailMsgId aMailBoxId, + const TFSMailMsgId aFolderId, + const TFSMailDetails aDetails, + const RArray& aSorting); + + /** + * returns branding manager to handle branding elements + * + * @return branding manager (ownership in framework) + */ + IMPORT_C MFSMailBrandManager& GetBrandManagerL( void ); + + /** + * Adds a new event observer. There can be several observers active at + * the same time. Caller MUST call RemoveObserver before destroying given + * observer object. + * + * @param aObserver observer implementation + */ + IMPORT_C void AddObserverL(MFSMailEventObserver& aObserver); + + /** + * Removes event observer + * + * @param aObserver observer to be removed + */ + IMPORT_C void RemoveObserver(MFSMailEventObserver& aObserver); + + /** + * unregisters plugin request observer to cancel pending events + * + * @param aRequestId request id of the pending asynchronous request + */ + IMPORT_C void UnregisterRequestObserver(TInt aRequestId); + + /** + * Subscribes events from given mailbox + * + * @param aMailboxId id of target mailbox + * @param aObserver observer given by user + */ + IMPORT_C void SubscribeMailboxEventsL(TFSMailMsgId aMailboxId, MFSMailEventObserver& aObserver); + + /** + * Unsubscribes events from given mailbox + * UnsubscribeMailboxEvents MUST be called before destroying given observer object. + * + * @param aMailboxId id of target mailbox + * @param aObserver observer implementation + */ + IMPORT_C void UnsubscribeMailboxEvents(TFSMailMsgId aMailboxId, MFSMailEventObserver& aObserver); + + /** + * Sends notification to all protocol plugins that there is + * Email Wizard data available for some of them. + * + * Can return any of the standard Symbian error codes if + * one of the plugins reports failed mailbox configuration. + */ + IMPORT_C TInt WizardDataAvailableL(); + + /** + * Client can call this function to immediately initialize authentications that are mandatory + * to get services from protocol plugins. This means e.g. store authentications. FW will + * internally ask authentication from all existing plugins before this operations completes. + * + * @param aOperationObserver is client provided observer that will receive progress + * notifications during the operation. + */ + IMPORT_C TInt AuthenticateL(MFSMailRequestObserver& aOperationObserver); + + /** + * get framework temp directory + */ + IMPORT_C TDesC& GetTempDirL( ); + + /** + * clean framework temp directory + */ + IMPORT_C void CleanTempDirL( ); + + /** + * cancels single pending asynchronous request + * + * @param aRequestId identifies request + */ + IMPORT_C void CancelL( const TInt aRequestId ); + + /** + * cancels all pending asynchronous requests + */ + IMPORT_C void CancelAllL( ); + + /** + * Calls plugin to change the name of the mailbox + * + * @param aMailboxId mailbox id + * @param aMailboxName new name for the mailbox + */ + IMPORT_C void SetMailboxName( const TFSMailMsgId aMailboxId, const TDesC& aMailboxName ); + +public: // from CExtendableEmail + + /** + * @see CExtendableEmail::ReleaseExtension + */ + IMPORT_C virtual void ReleaseExtension( CEmailExtension* aExtension ); + + /** + * Requests extension. Default implementation performs lookup only and + * derived class should implement actual instantiation because it knows + * extensions it supports + * array but does not delete it. + * @param aExtension extension to release + */ + IMPORT_C virtual CEmailExtension* ExtensionL( const TUid& aInterfaceUid ); + + protected: + + private: + + /** + * C++ default constructor. + */ + CFSMailClient(); + + /** + * Destructor. + */ + ~CFSMailClient(); + + /** + * ConstructL + */ + void ConstructL( TInt aConfiguration ); + + /** + * returns framework singleton instance if exists + */ + static CFSMailClient* Instance(); + + /** + * increments reference count to framework singleton + */ + TInt IncReferenceCount(); + + /** + * decrements reference count to framework singleton + */ + TInt DecReferenceCount(); + + private: // data + + /** framework singleton reference count */ + TInt iReferenceCount; + + /** */ + CFSFWImplementation* iFWImplementation; + + /** branding manager pointer */ + MFSMailBrandManager* iBrandManager; +}; + +#endif // __FSMAILCLIENT_H