/*
* Copyright (c) 2006-2006 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:  Common interface for preset handling
*
*/


#ifndef C_CPSPRESETINTERFACE_H
#define C_CPSPRESETINTERFACE_H

#include "pspresetobserver.h"
#include "pstransaction.h"

const TUid KPSPresetInterface = { 0x10281CB6 }; /**< The ECOM interface UID for preset plugins. */

class CPSPresetNotifier;
class CPSPresetTransaction;
class RReadStream;
class RPSServ;
class RPSServSession;
class RWriteStream;

/**
 * Common interface for preset handling.
 *
 * All preset plugins must inherit from this class, and implement the InternalizeL( RReadStream& aStream )
 * and ExternalizeL( RWriteStream& aStream ) methods.
 *
 */
class CPSPresetInterface : public CBase, public MPSPresetObserver, public MPSTransactionEntity
    {

public:

    /**
     * Destructor
     */
    IMPORT_C ~CPSPresetInterface();
    
    /**
     * Creates and starts an explicit transaction.
     *
     * If a transaction is not active when using the setters, they will panic with <code>KErrNotReady</code>.
     *
     * Creating a transaction leaves with <code>KErrLocked</code> if another transaction for the same preset is active.
	 *
     * Transactions are completed with either CommitL or RollbackL.
     */
    IMPORT_C CPSTransaction* CreateTransactionL();

    /**
     * Creates and starts explicit transaction leaving it on the cleanup stack.
     *
     * @see CPSPresetTramsaction::CreateTransactionL()
     */
    IMPORT_C CPSTransaction* CreateTransactionLC();

    /**
     * Sets the name of the preset.
     *
     * @param   aName       The name of the preset. 
     */
    IMPORT_C void SetNameL( const TDesC& aName );
    
    /**
     * Returns the name of the preset.
     *
     * @return  The name of the preset.
     */
    IMPORT_C const TDesC& Name() const;

    /**
     * Sets the index of the preset.
     *
     * @param   aIndex      The index of the preset.
     */
    IMPORT_C void SetIndex( TInt aIndex );
    
    /**
     * Returns the index of the preset.
     *
     * @return  The index of the preset.
     */
    IMPORT_C TInt Index() const;

    /**
     * Returns the id of the preset.
     *
     * @return  The id of the preset.
     */
    IMPORT_C TInt Id() const;

    /**
     * Returns the data handler of the preset.
     *
     * @return  The data handler of the preset.
     */
    IMPORT_C TUid DataHandler() const;

protected:

    /**
     * Completes the construction of the preset interface.
     *
     * All classes deriving from this class must call BaseConstructL( TAny* aParams ) before
     * trying to use any of the functionality provided.
     *
     * @param   aParams     The ECOM construction parameters, as supplied to the plugin's
     *                      <code>NewL( TAny* aParams )</code> by the ECOM framework.
     */
    IMPORT_C void BaseConstructL( TAny* aParams );

    /**
     * Validates the preset for data change.
     *
     * Implementing plugins must call this whenever any of their functions that modify the external
     * status of the preset are called before making any changes to the preset's values.
     *
     * Checks if there is a transaction open for this preset, and if not, panics the application as it
     * indicates a programming error.
     */
    IMPORT_C void ValidateDataChange();

    /**
     * Internalizes the preset.
     *
     * This is called when the preset's data is changed, and needs to be updated.
     *
     * @param   aStream     Read stream containing the preset's data.
     */
    virtual void InternalizeL( RReadStream& aStream ) = 0;

    /**
     * Externalizes the preset.
     *
     * Called when the preset is about to be committed, and the data provided by the plugin 
     * needs to be externalized.
     *
     * @param   aStream     Write stream to write the preset's data to.
     */
    virtual void ExternalizeL( RWriteStream& aStream ) const = 0;

private:

// from base class MPSPresetObserver

    /**
     * @see MPSPresetObserver::HandlePresetChangedL( TInt aId, TUid aDataHandler, MPSPresetObserver::TPSReason aReason )
     */
    IMPORT_C void HandlePresetChangedL( TInt aId, TUid aDataHandler, MPSPresetObserver::TPSReason aReason );

// from base class MPSTransactionEntity
    
    /**
     * @see MPSTransactionEntity::BeginTransactionL()
     */
    IMPORT_C void BeginTransactionL();

    /**
     * @see MPSTransactionEntity::CommitL()
     */
    IMPORT_C void CommitL();
    
    /**
     * @see MPSTransactionEntity::Rollback()
     */
    IMPORT_C void Rollback();

public:

    /**
     * Creates a new preset interface object.
     * 
     * @param   aServ           reference to session, used to communicate to server
     * @param   aId             id of the preset 
     * @param   aDataHandler    datahandler uid, used in preset creation
     */
    static CPSPresetInterface* CreateL( RPSServ& aServ, TInt aId, TUid aDataHandler );

private:

    /**
     * Updates the preset.
     */
    void UpdatePresetL();

private:

    /** The preset change notifier. */
    CPSPresetNotifier* iNotifier;
    /** Session to the preset server. */
    RPSServSession* iSession;
    /** <code>ETrue</code> if the preset is in transaction, <code>EFalse</code> otherwise. */
    TBool iTransaction;
    /** Name of the preset. */
    HBufC* iName;
    /** Index of the preset. */
    TInt iIndex;
    /** Identifier of the preset. */
    TInt iId;
    /** Data handler of the preset. */
    TUid iDataHandler;
    /** Destructor id. */
    TUid iDtor;
    /** Extension. */
    TAny* iExtension;

    };

#endif // C_CPSPRESETINTERFACE_H