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


#ifndef M_CFCONTEXTSOURCEUPGRADE_H
#define M_CFCONTEXTSOURCEUPGRADE_H

// CONSTANTS
const TInt KCFContextSourceUpgradeUidValue = 0x2001599D;
const TUid KCFContextSourceUpgradeUid = {KCFContextSourceUpgradeUidValue};

// FORWARD DECLARATIONS
class CCFContextSourceSettingArray;

/**
* Context Source Upgrade API.
*
* RAM based context source settings (configurations) are dynamically added and
* upgraded via this interface. RAM based settings never hide nor upgrage ROM
* based settings.
*
* CheckValidity is first called for RAM based settings before they are given to
* the plugin. The plugin should check that the settings are valid. It may also
* check client's permission to install the settings, if that is appropriate.
* CheckValidity is called when new settings are installed or the settings
* upgrade older ones. Note that the list of settings given for the validity
* check should not be stored by the plugin.
*
* UpdateSettingsL is called if the call to CheckValidity returned KErrNone or
* RAM based settings have been uninstalled. UpdateSettingsL includes all current
* settings for the plugin. The plugin must take the ownership of the settings
* before calling any code that might leave. Leaving for other reason than out of
* memory is not recommended because the settings are already stored by Context
* Framework, and thus the same list of setting block will be provided to the
* source plugin during next start-up of Context Framework.
*
* @since S60 5.0
* @lib None-
*/
class MCFContextSourceUpgrade
    {
    public: // New functions

        /**
        * Checks setting validity.
        * The settings are either new or upgrading existing RAM based settings.
        * The source plugin should check that the settings are valid (correct
        * attributes and parameters) and if necessary, check client's permission
        * to install the settings (security).
        *
        * @since S60 5.0
        * @param aClientThread Client thread installing new or upgrading
        *   existing RAM based settings.
        * @param aSettingList List of setting blocks, either new settings or
        *   settings upgrading older settings from the same client. Note that
        *   these settings should only be referenced for possible security check
        *   needs, they are not to be copied by the plugin.
        * @return KErrNone if the settings are valid, KErrNotSupported if
        *   settings are invalid, KErrPermissionDenied if client does not have
        *   permission to install the settings, otherwise any system-wide error
        *   error code.
        */
        virtual TInt CheckValidity( RThread& aClientThread,
                const CCFContextSourceSettingArray& aSettingList ) = 0;

        /**
        * Updates complete set of settings for the context source.
        * All current setting blocks defined with the plugin name in the XML
        * settings files will be given in an array. Called if CheckSecurity has
        * succeeded when installing new or upgrading RAM based settings, or RAM
        * based settings have been uninstalled. Ownership of the settings is
        * transferred to the plug-in who should take it before calling any code
        * that might leave.
        *
        * @since S60 5.0
        * @param aSettingList List of setting blocks, ownership is transferred.
        *   Note that the array may be empty (zero setting items) if all RAM
        *   based settings have been uninstalled and the source does not have
        *   any ROM based settings. However, the souce plugin has the
        *   ownership (responsibility) of the array.
        * @return None.
        */
        virtual void UpdateSettingsL(
                CCFContextSourceSettingArray* aSettingList ) = 0;

    protected:

        // Deny destruction through this interface.
        virtual ~MCFContextSourceUpgrade(){};
    };

#endif // M_CFCONTEXTSOURCEUPGRADE_H