1 /*

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

    15 *

    16 */

    17 

    18 

    19 

    20 

    21 #ifndef IAUPDATECONTROLLER_H

    22 #define IAUPDATECONTROLLER_H

    23 

    24 

    25 #include <e32cmn.h>

    26 

    27 #include "iaupdatecontrollerobserver.h"

    28 #include "iaupdateconnectionmethod.h"

    29 

    30 class MIAUpdateNode;

    31 class MIAUpdateHistory;

    32 class CIAUpdateRestartInfo;

    33 class CIAUpdaterIdentifier;

    34 

    35 

    36 /**

    37  * 

    38  *

    39  * @since S60 v3.2

    40  */

    41 class MIAUpdateController

    42     {

    43     

    44 public:

    45 

    46     /**

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

    48      *

    49      * @since S60 v3.2

    50      */        

    51     virtual ~MIAUpdateController()

    52         {

    53         }

    54 

    55 

    56     /**

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

    58      *

    59      * @note MIAUpdateControllerObserver::StartupComplete function is called when

    60      * this operation has finished.

    61      *

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

    63      * and no callback is called.

    64      *

    65      * @return TInt System wide error code.

    66      * KErrInUse if the startup operation is already going on.

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

    68      *

    69      * @since S60 v3.2

    70      **/

    71     virtual TInt Startup() = 0;

    72    

    73     

    74     /**

    75      * Issues a refresh operation. 

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

    77      * until previous operation has completed.

    78      *

    79      * @param aAllowNetConnection ETrue means that information can be refreshed

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

    81      * is allowed to be used.

    82      *

    83      * @note MIAUpdateControllerObserver::RefreshComplete function is called when

    84      * this operation has finished.

    85      *

    86      * @since S60 v3.2

    87      **/

    88     virtual void StartRefreshL( TBool aAllowNetConnection ) = 0;

    89   

    90         

    91     /**

    92      * Cancel an ongoing refresh operation

    93      *

    94      * @since S60 v3.2

    95      **/

    96     virtual void CancelRefresh() = 0;

    97 

    98 

    99     /**

   100      * Cancel a possible ongoing reporting operation. 

   101      *

   102      * Reporting may have been started if FinishedUpdatesL function is called 

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

   104      * job in the background.

   105      *

   106      * @since S60 v3.2

   107      **/

   108     virtual void CancelReporting() = 0;

   109    

   110     

   111     /**

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

   113      *

   114      * @since S60 v3.2

   115      */

   116     virtual MIAUpdateHistory& HistoryL() = 0;

   117 

   118 

   119     /**

   120      * Sets the default connection method used for network access.

   121      *

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

   123      * creates the controller.

   124      * 

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

   126      *

   127      * @since S60 v3.2

   128      */    

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

   130 

   131 

   132     /**

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

   134      * If this function returns EFalse, then StartPossibleSelfUpdateL function will 

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

   136      *

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

   138      * EFalse if no self update item has been set.

   139      */

   140     virtual TBool SelfUpdateDataExists() const = 0;    

   141 

   142 

   143     /**

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

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

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

   147      * function does not do anything.

   148      *

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

   150      * 

   151      * @param aIndex Index information that informs how many other

   152      * items have already been installed.

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

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

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

   156      * when restarting the iaupdate after self update.

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

   158      * If EFalse, then operation can show dialogs. 

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

   160      * @exception Leaves with system wide error code.

   161      *

   162      * @since S60 v3.2

   163      */

   164     virtual TBool StartPossibleSelfUpdateL( TInt aIndex, 

   165                                             TInt aTotalCount,

   166                                             const RPointerArray< MIAUpdateNode >& aPendingNodes,

   167                                             TBool aSilent ) = 0;

   168     

   169             

   170     /**

   171      * Resets the self updater infos.

   172      * This only resets the object data.

   173      *

   174      * @since S60 v3.2     

   175      */         

   176     virtual void ResetSelfUpdate() = 0;

   177 

   178 

   179     /**

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

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

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

   183      * or if the UI should not continue updates.

   184      *

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

   186      * CIAUpdateRestartInfo information. Files can be deleted by calling

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

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

   189      *

   190      * @return CIAUpdateRestartInfo* NULL if required files were

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

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

   193      * the pending node updates. Ownership is transferred.

   194      */

   195     virtual CIAUpdateRestartInfo* SelfUpdateRestartInfo() = 0;    

   196 

   197 

   198     /**

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

   200      * identifier.

   201      * 

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

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

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

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

   206      * function.

   207      *

   208      * @param aIdentifier Identifies the node uniquely.

   209      * @return MIAUpdateNode& Node.

   210      */

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

   212 

   213 

   214     /**

   215      * This function should be called when updates are started.

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

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

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

   219      * process is finished.

   220      *

   221      * @see MIAUpdateController::FinishedUpdatesL

   222      */

   223     virtual void StartingUpdatesL() = 0;

   224     

   225     

   226     /**

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

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

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

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

   231      * is finsihed.

   232      * 

   233      * @note If parameter aOperationsAllowed is given as ETrue, 

   234      * this function starts an asynchronous server report sending and 

   235      * MIAUpdateServerReportObserver::ServerReportOperationComplete is 

   236      * called when the operation is finished.

   237      

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

   239      * given for aMaxWaitTime, one asynchronous loop is done before 

   240      * MIAUpdateServerReportObserver::ServerReportOperationComplete is called.

   241      *

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

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

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

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

   246      * If maximum time is reached, then timer will call 

   247      * MIAUpdateServerReportObserver::ServerReportOperationComplete.

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

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

   250      * 

   251      * @see MIAUpdateServerReportObserver::ServerReportOperationComplete

   252      * @see MIAUpdateController::StartingUpdatesL

   253      */

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

   255 

   256     };

   257 

   258 

   259 #endif  //  IAUPDATECONTROLLER_H