/*

* Copyright (c) 2009 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:   ?Description

*

*/

#ifndef IAUPDATECONTROLLER_H

#define IAUPDATECONTROLLER_H

#include <e32cmn.h>

#include "iaupdatecontrollerobserver.h"

#include "iaupdateconnectionmethod.h"

class MIAUpdateNode;

class MIAUpdateHistory;

class CIAUpdateRestartInfo;

class CIAUpdaterIdentifier;

/**

 * 

 *

 * @since S60 v3.2

 */

class MIAUpdateController

    {

public:

    /**

     * Virtual destructor of an interface can be used for deletion.

     *

     * @since S60 v3.2

     */        

    virtual ~MIAUpdateController()

        {

        }

    /**

     * Issue an asynchronous operation for controller to start up and ready for operations

     *

     * @note MIAUpdateControllerObserver::StartupComplete function is called when

     * this operation has finished.

     *

     * @note If returned error code is not KErrNone, then operation is not started 

     * and no callback is called.

     *

     * @return TInt System wide error code.

     * KErrInUse if the startup operation is already going on.

     * KErrAlreadyExists if the startup operation has already been successfully done.

     *

     * @since S60 v3.2

     **/

    virtual TInt Startup() = 0;

    /**

     * Issues a refresh operation. 

     * Only one operation can be in progress at a time; user has to always wait

     * until previous operation has completed.

     *

     * @param aAllowNetConnection ETrue means that information can be refreshed

     * from the network if required. EFalse means that only local information

     * is allowed to be used.

     *

     * @note MIAUpdateControllerObserver::RefreshComplete function is called when

     * this operation has finished.

     *

     * @since S60 v3.2

     **/

    virtual void StartRefreshL( TBool aAllowNetConnection ) = 0;

    /**

     * Cancel an ongoing refresh operation

     *

     * @since S60 v3.2

     **/

    virtual void CancelRefresh() = 0;

    /**

     * Cancel a possible ongoing reporting operation. 

     *

     * Reporting may have been started if FinishedUpdatesL function is called 

     * and operations are allowed there. Then, reporting operation handles its 

     * job in the background.

     *

     * @since S60 v3.2

     **/

    virtual void CancelReporting() = 0;

    /**

     * @return MIAUpdateHistory& The history of the update items.

     *

     * @since S60 v3.2

     */

    virtual MIAUpdateHistory& HistoryL() = 0;

    /**

     * Sets the default connection method used for network access.

     *

     * @note Not stored persistently. A client needs to set this again every time it

     * creates the controller.

     * 

     * @param aMethod Identifier of the connection method to use by default.

     *

     * @since S60 v3.2

     */    

    virtual void SetDefaultConnectionMethodL( const TIAUpdateConnectionMethod& aMethod ) = 0;

    /**

     * This function can be used to check if any items have been set for self update.

     * If this function returns EFalse, then StartPossibleSelfUpdateL function will 

     * not start self updater because there is nothing to update.

     *

     * @return TBool ETrue if at least one self update item has been set.

     * EFalse if no self update item has been set.

     */

    virtual TBool SelfUpdateDataExists() const = 0;    

    /**

     * If there exists self updater items that are waiting permission to 

     * be updated, this function starts the self updater which handles the

     * updating of those items. If no updater items are waiting, then this

     * function does not do anything.

     *

     * @note Self updater most likely shuts down this UI.

     * 

     * @param aIndex Index information that informs how many other

     * items have already been installed.

     * @param aTotalCount The total number of items that will be installed.

     * @param aPendingNodes The UIDs of these nodes will be saved to a temporary file

     * and this information can be gotten by calling SelfUpdateRestartInfoL, for example,

     * when restarting the iaupdate after self update.

     * @param aSilent If ETrue, the operation should be silent and no dialogs should be shown.

     * If EFalse, then operation can show dialogs. 

     * @return TBool ETrue if self updater was started. Else EFalse.

     * @exception Leaves with system wide error code.

     *

     * @since S60 v3.2

     */

    virtual TBool StartPossibleSelfUpdateL( TInt aIndex, 

                                            TInt aTotalCount,

                                            const RPointerArray< MIAUpdateNode >& aPendingNodes,

                                            TBool aSilent ) = 0;

    /**

     * Resets the self updater infos.

     * This only resets the object data.

     *

     * @since S60 v3.2     

     */         

    virtual void ResetSelfUpdate() = 0;

    /**

     * Function provides objects that can be used to check if the self updater was started. 

     * This function can be used, for example, when UI is started. Then, the results values 

     * can be used to check if the UI should continue updates after successfull self installation

     * or if the UI should not continue updates.

     *

     * @notice It is up to the user to decide when to delete the files that contain

     * CIAUpdateRestartInfo information. Files can be deleted by calling

     * CIAUpdateRestartInfo::DeleteFiles function. This way the UI may check

     * the data and release memory when it suits UIs purposes.

     *

     * @return CIAUpdateRestartInfo* NULL if required files were

     * not available. Else pointer to CIAUpdateRestartInfo object that can be

     * used to check the results of the self update and to get the information about

     * the pending node updates. Ownership is transferred.

     */

    virtual CIAUpdateRestartInfo* SelfUpdateRestartInfo() = 0;    

    /**

     * This function will return the latest version of the node that corresponds to the given 

     * identifier.

     * 

     * @note This function can return the nodes that are not given for the controller observer when

     * refresh is called. These hidden nodes have already been installed. So, this function is mainly

     * meant for the self update purposes, when already installed nodes should be gotten for some

     * extra handling in the UI side. The required identifier can be gotten from SelfUpdateRestartInfo

     * function.

     *

     * @param aIdentifier Identifies the node uniquely.

     * @return MIAUpdateNode& Node.

     */

    virtual MIAUpdateNode& NodeL( const CIAUpdaterIdentifier& aIdentifier ) = 0;

    /**

     * This function should be called when updates are started.

     * The purpose of this function is to set engine ready for the whole update process

     * that may contain multiple update items. For example, this way the engine knows

     * that data for the server reports can be start collecting until the whole update

     * process is finished.

     *

     * @see MIAUpdateController::FinishedUpdatesL

     */

    virtual void StartingUpdatesL() = 0;

    /**

     * This function should be called when updates have been completed.

     * The purpose of this function is to inform engine that the whole update process 

     * that may contain multiple update items has finished. For example, this way the engine

     * knows that the collected server reports can be sent because the whole update process

     * is finsihed.

     * 

     * @note If parameter aOperationsAllowed is given as ETrue, 

     * this function starts an asynchronous server report sending and 

     * MIAUpdateServerReportObserver::ServerReportOperationComplete is 

     * called when the operation is finished.

     * @note Even if aOperationsAllowed is given as EFalse and a negative value is

     * given for aMaxWaitTime, one asynchronous loop is done before 

     * MIAUpdateServerReportObserver::ServerReportOperationComplete is called.

     *

     * @param aOperationsAllowed ETrue if new operations can be created and started.

     * Else EFalse. If ETrue is given, then for example, server report operation is started.

     * @param aMaxWaitTime The maximum time in microseconds that completion of server reports

     * is waited. Negative value means that timer should not be used if operation is created.

     * If maximum time is reached, then timer will call 

     * MIAUpdateServerReportObserver::ServerReportOperationComplete.

     * Notice, that the server reporting still continues in the background until operation

     * is cancelled, for example, when the application is closed.

     * 

     * @see MIAUpdateServerReportObserver::ServerReportOperationComplete

     * @see MIAUpdateController::StartingUpdatesL

     */

    virtual void FinishedUpdatesL( TBool aOperationsAllowed, TInt aMaxWaitTime ) = 0;

    };

#endif  //  IAUPDATECONTROLLER_H