/*

* Copyright (c) 2002-2007 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:  MMsgMailOpObserver

*

*/

#ifndef CMSGMAILBASEOP_H

#define CMSGMAILBASEOP_H

//  INCLUDES

#include <e32base.h>

#include <AknWaitDialog.h>

// DATA TYPES

// FORWARD DECLARATIONS

class CMsgMailEditorDocument;

class CMsgMailBaseOp;

// CLASS DECLARATION

/**

* Observer interface for operations.

*/

NONSHARABLE_CLASS( MMsgMailOpObserver )

    {    

    public:

        /**

        * Method for observing operation completion. Intentionally

        * non-leaving since any problem in observer should not affect the

        * operation.

        * @param aOp operation instance reference

        * @param aResult result code

        */

        virtual void HandleOpCompleted( const CMsgMailBaseOp& aOp,

                                        TInt aResult ) = 0;    

    };

/**

* Base class for state machine -based long-running operations.

* Operations are divided to steps by the implementing subclass, and

* these steps are performed as individual CActive requests. The requests

* may either be truly asynchronous, or self-completing synchronous steps.

*

* Due to existing tight coupling with MsgMailEditorAppUi and UI

* in general the subclass may need to delegate some tasks to the UI via

* MMsgMailOpDelegate interface.

*

* Two alternative observation mechanisms for operations are available:

* either via MMsgMailOpObserver interface or using TRequestStatus completion.

*

* The base class does not cancel the operation in it's destructor

* since subclass destructors are called before base class destructor

* and that would lead to access violations. Subclasses must call Cancel()

* by themselves in their destructors if they want to cancel in destruction.

*/

NONSHARABLE_CLASS( CMsgMailBaseOp ) : public CActive, 

                                      public MProgressDialogCallback 

    {

    protected:

        // subclasses add their own states

        enum TState

            {

            EIdleState, // initial and final state of operation

            EFirstFreeState // a marker for subclasses, not a real state

            };

    public:  // Constructors and destructor

        /**

        * Destructor.

        */

        ~CMsgMailBaseOp();

    public: // API

        /**

        * Method for the class user to start the entire operation. Possibly

        * already ongoing operation is cancelled.

        * @param aObserver observer which is notified when operation completes

        */

        void StartOp( MMsgMailOpObserver& aObserver );

        /**

        * Method for the class user to start the entire operation. Possibly

        * already ongoing operation is cancelled.

        * @param aStatus request status, completed along with the operation

        */

        void StartOp( TRequestStatus& aStatus );

    protected: // From CActive

        // From CActive

        void DoCancel();

        void RunL();

        TInt RunError( TInt aError );

    protected: // From MProgressDialogCallback

        /**

         * Callback method is called when a dialog is dismissed.

         * @param aButtonId Cancel button id.

         */

        void DialogDismissedL( TInt aButtonId );

    protected:  // Implementation

        /**

        * Template method for implementing state switching logic.

        */

        virtual void SetNextState() = 0;

        /**

        * Template method for handling action for latest state transition.

        */

        virtual void HandleStateActionL() = 0;

        /**

        * Template method for handling operation cancellation. This is called

        * from DoCancel to allow subclass to cancel any outstanding request.

        */

        virtual void HandleOperationCancel() = 0;

        /**

        * Optional template method for handling an error occurred during

        * current state action. This method is called from RunError().

        * Return value determines whether the entire operation is continued

        * (ETrue returned) or stopped (EFalse returned). The base class

        * implementation always returns EFalse.

        * @param aError error code

        * @retval ETrue if error was handled and operation can continue

        */

        virtual TBool HandleStateActionError( TInt aError );

        /**

        * Helper method for completing non-asynchronous steps and

        * continuing with next iteration. If action is completed with an

        * error code, then RunError will get executed.

        * @param aError completion code, by default KErrNone

        */

        void CompleteStateAction( TInt aError = KErrNone );

        /**

        * Helper method for starting a wait note.

        * @param aTextResourceId wait note text

        * @param aDelayOff wait note delay on/off

        * @param aResourceId wait dialog resource

        */

        void StartWaitNoteL( TInt aTextResourceId,

                             TBool aDelayOff,

                             TInt aResouceID );

        /**

        * Helper method for stopping a wait note. If not called, then

        * wait note will be closed when operation is stopped.

        */

        void StopWaitNote();

    private:  // Implementation

        /**

        * Resets state machine, closes and waits possibly open wait note.

        * Calls NotifyObservers if wait note is not visible, otherwise the

        * operation handling continues in DialogDismissedL.

        * @param aError error code

        */

        void CompleteOperation( TInt aError );

        /**

        * Notifies observer with the given error code

        * @param aError error code

        */

        void NotifyObservers( TInt aError );

    protected:

        /**

        * Constructor.

        * @param aDocument Editor's document reference

        */

        CMsgMailBaseOp( CMsgMailEditorDocument& aDocument );                     

    protected:    // Data

        // Wait dialog, own

        CAknWaitDialog* iWaitDialog;

        // Editor's document, not own

        CMsgMailEditorDocument& iDocument;   

        // Operation observer, not own

        MMsgMailOpObserver* iObserver;

        // Operation obeserver's request status, not own

        TRequestStatus* iExtRequestStatus;

        // Current state

        TInt iState;

        // Pending operation result (waiting wait dialog).

        TInt iWaitingError;

    };

#endif      // CMSGMAILBASEOP_H

// End of File