/*

* 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:   This file contains the header file of the CIAUpdate class 

*

*/

#ifndef IA_UPDATE_H

#define IA_UPDATE_H

#include <e32base.h>

#include <e32std.h>

class MIAUpdateObserver;

class CIAUpdateManager;

class CIAUpdateParameters;

/**

 * CIAUpdate object provides methods to handle update actions.

 * Updating will be targeted to the update items that qualify the requirements

 * given in CIAUpdateParameters objects. In asynchronous actions, the callback 

 * functions of MIAUpdateObserver object will be informed about the progress 

 * of update actions.

 * 

 * @see MIAUpdateObserver

 * @see CIAUpdateParameters

 *

 * @since S60 v3.2

 */

class CIAUpdate : public CBase

    {

public:

    /**

     * @param aObserver Callback functions of the observer are called

     * when operations that are started from this interface progress.    

     * @return CIAUpdate* Pointer to the created CIAUpdate object that 

     * can be used for update actions.

     *

     * @since S60 v3.2

     */

    IMPORT_C static CIAUpdate* NewL( MIAUpdateObserver& aObserver );

    /**

     * @see NewL

     */

    IMPORT_C static CIAUpdate* NewLC( MIAUpdateObserver& aObserver );

    /**

     * Destructor

     *

     * @since S60 v3.2

     */

    IMPORT_C virtual ~CIAUpdate();

    /**

     * Checks if any updates are available.

     * This function is asynchronic.

     *

     * @note Update check is directed to items that match:

     *       - CIAUpdateParameters::Uid OR

     *       - CIAUpdateParameters::SearchCriteria

     * @note Uid describes either package UID or SID.

     *       UID is assumed to be SID if update items are not found 

     *       with the given UID. Then, corresponding package UID is 

     *       searched from the installed application registry. 

     *       If corresponding package UID is found, then update items 

     *       are rechecked. 

     * @note If Uid is given, then search criteria is omitted.

     * @note If none of the parameters that are mentioned above is not set, 

     * then all the updates are checked.

     *

     * @note CIAUpdateParameters::ShowProgress defines if a ready-made

     * wait dialog should be shown in case the operation takes longer time. 

     * This happens e.g. if the updates are refreshed from the server.

     *

     * @param aUpdateParameters Defines the update targets.

     *

     * @since S60 v3.2

     */

    IMPORT_C void CheckUpdates( const CIAUpdateParameters& aUpdateParameters );

    /** 

     * Starts IAD UI.

     *

     * UI will show the update items that qualify the requirements given

     * in aUpdateParameters.

     *

     * Even if the updating is handled in the IAD UI, the observer is informed

     * about the progression of operations. So, the calling application

     * may continue correctly after updates are finished.

     * 

     * @note IAD UI will show update items that match:

     *       - CIAUpdateParameters::Uid

     *       - CIAUpdateParameters::SearchCriteria

     * @note Uid describes either package UID or SID.

     *       UID is assumed to be SID if update items are not found 

     *       with the given UID. Then, corresponding package UID is 

     *       searched from the installed application registry. 

     *       If corresponding package UID is found, then update items 

     *       are rechecked. 

     * @note If Uid is given, then search criteria is omitted.

     * @note If none of the parameters that are mentioned above is not set, 

     * then all the updates are shown in the UI.

     *

     * @note When update finishes, the following values are used 

     * for command line execution:

     *      - CIAUpdateParameters::CommandLineExecutable

     *      - CIAUpdateParameters::CommandLineArguments

     * @note If CIAUpdateParameters::CommandLineExecutable is not set, 

     * then no command line execution is done.

     *

     * @param aUpdateParameters Defines the update targets.

     *

     * @since S60 v3.2

     */

    IMPORT_C void ShowUpdates( const CIAUpdateParameters& aUpdateParameters );

    /** 

     * All the items that qualify the requirements given in

     * aUpdateParameters will be updated without opening the IAD UI.

     * This function is asynchronic.

     *

     * @note Update is directed to items that match:

     *       - CIAUpdateParameters::Uid

     *       - CIAUpdateParameters::SearchCriteria

     * @note Uid describes either package UID or SID.

     *       UID is assumed to be SID if update items are not found 

     *       with the given UID. Then, corresponding package UID is 

     *       searched from the installed application registry. 

     *       If corresponding package UID is found, then update items 

     *       are rechecked. 

     * @note If Uid is given, then search criteria is omitted.

     * @note If none of the parameters that are mentioned above is not set, 

     * then everything is updated.

     *

     * @note When update finishes, the following values are used 

     * for command line execution:

     *      - CIAUpdateParameters::CommandLineExecutable

     *      - CIAUpdateParameters::CommandLineArguments

     * @note If CIAUpdateParameters::CommandLineExecutable is not set, 

     * then no command line execution is done.

     *

     * @param aUpdateParameters Defines the update targets.

     *

     * @since S60 v3.2

     */

    IMPORT_C void Update( const CIAUpdateParameters& aUpdateParameters );

    /** 

     * This function is provided as a convenience method 

     * that has localized texts for the query dialog. 

     * This function does not start any update. 

     * This function is asynchronic.

     *

     * @note The observer is informed when the update query operation has completed.

     *

     * @since S60 v3.2

     */

    IMPORT_C void UpdateQuery();

private:

    /**

     * Constructor is private because this class is not meant for

     * inheritance.

     *

     * @see NewL

     */

    CIAUpdate();

    /** 

     * @see NewL

     */

    void ConstructL( MIAUpdateObserver& aObserver );

    /** 

     * @return CIADUpdateManager& Manages update operations.

     */

    CIAUpdateManager& UpdateManager() const;

    // These are prevented

    CIAUpdate( const CIAUpdate& aObject );

    CIAUpdate& operator =( const CIAUpdate& aObject );

private: // data

    // Manages update operations.

    CIAUpdateManager* iUpdateManager;

    };

#endif // IA_UPDATE_H