/*

* Copyright (c) 2002 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:  Store entry abstract class

*

*/

#ifndef __CPENGSTOREENTRY_H__

#define __CPENGSTOREENTRY_H__

//  INCLUDES

#include <e32base.h>

#include <s32strm.h>

#include "PEngStorageGlobals.h"

#include "MPEngSIDChangeObserver.h"

// FORWARD DECLARATIONS

class MPEngStorageManagerWatcher;

class MPEngStorageManager;

class CPEngStorageManager;

// CLASS DECLARATION

/**

 *  One store entry template

 *  Each store entry of the storage manager has to be derived from

 *	this abstract class.

 *	Pure virtual function must be implemented by derived class.

 *	However virtual functions have default implementation.

 *

 *  @lib PEngStoreMan2.dll

 *  @since 3.0

 */

class CPEngStoreEntry :

            public CBase,

            public MPEngSIDChangeObserver

    {

    public:  // Constructors and destructor

        /**

         * Destructor.

         */

        IMPORT_C virtual ~CPEngStoreEntry();

    protected:	// Protected constructor to allow derivation

        /**

         * C++ default constructor.

         *

         * @param aStoragetype	storage type of the Store Entry

         */

        IMPORT_C CPEngStoreEntry( TPEngStorageType aStorageType );

        /**

         * Base constructor of the Base class

         * It registeres store entry to listen its changes

         *

         * @since 3.0

         * @param aStorageManager Storage manager

         * @param aRegister register store entry to observer its updates

         */

        IMPORT_C void BaseConstructL(

            MPEngStorageManager& aStorageManager,

            TBool aRegister = ETrue  );

        /**

         * Base constructor of the Base class

         * Overloaded version which does not register to listen changes

         *

         * @since 3.0

         */

        IMPORT_C void BaseConstructL();

    public:	// Clean up support for the Lock of the Entry

        /**

         * Release lock of the store entry

         * It is also used for clean up stack of the entry's lock support

         *

         * @since 3.0

         */

        IMPORT_C virtual void Release();

        /**

         * Lock store entry and leave lock on the clean up stack

         *

         * @since 3.0

         * @return count of the lock on the server side or KErrDisconected

         */

        IMPORT_C TInt LockLC();

        /**

         * Locks store entry

         *

         * @since 3.0

         * @param aPriority priority of the Lock to be done

         * @param aCreateEntry if store entry does not exists, it is created

         *         default value is ETrue = store entry is created if needed

         * @return count of the lock on the server side, KErrDisconected or

         *       KErrNotFound if aCreateEntry = EFalse and entry does not exist.

         */

        IMPORT_C TInt Lock( TPengStorageLockPriority

                            aPriority = EStorageLockLevelBasic,

                            TBool aCreateEntry = ETrue ) const;

        /**

         * Unlocks store entry

         *

         * @since 3.0

         * @return count of the lock on the server side or KErrDisconected

         */

        IMPORT_C TInt Unlock() const;

        /*

         * Stops sending of SID changes done through Storage Manager

         * More in <MPEngStorageManager.h>

         *

         * @since 3.0

         * @return positive number represents number on the server side

         *		counter, negative some system wide error

         */

        IMPORT_C TInt BufferServerSideNotifications();

        /*

         * Decreases counter of the Server Side Notification buffering,

          * More in <MPEngStorageManager.h>

         *

         * @since 3.0

         * @return positive number represents number on the server side

         *		counter, negative some system wide error

         */

        IMPORT_C TInt ReleaseServerSideBuffering();

        /**

         * Store this store entry

         *

         * @since 3.0

         */

        IMPORT_C void StoreL();

    public: // New functions of the base class

        /**

         * ExternalizeL provides way to externalize data from store entry.

         * For behavior of this function based on the different

         * storage type check <PEngStorageGlobals.h>

         *

         * @since 3.0

         * @param aStream stream to write to

         * @param aStorageType storage type to externalized

         */

        virtual void ExternalizeL( RWriteStream& aStream,

                                   TPEngStorageType aStorageType ) const = 0;

        /**

         * InternalizeL provides way to internalise data to store entry.

         * For behavior of this function based on the different

         * storage type check <PEngStorageGlobals.h>

         *

         * @since 3.0

         * @param aStream stream to read from

         * @param aStorageType storage type to internalized

         */

        virtual void InternalizeL( RReadStream& aStream,

                                   TPEngStorageType aStorageType ) = 0;

        /**

         * This method is used to retrieve ID for storing.

         *

         * @since 3.0

         * @return Store Id

         */

        virtual const TDesC& StorageId() const = 0;

        /*

         * This method is used to ask entry size in bytes.

         * It is called before actual call of the InternalizeL and

         * ExternalizeL to get estimation of the buffer needed for the

         * operation. If Size is incorrect before the ExternalizeL,

         * externalize operation will fail to fit data in the stream.

         * If size is incorrect before InternalizeL, operation will

         * be more time consuming (extra client/server)call involved

         *

         * For more behavior of this function based on the different

         * storage type check <PEngStorageGlobals.h>

         *

         * @since 3.0

         * @return size as TInt

         */

        virtual TUint32 EntrySize() const = 0;

    public: // Storage type support

        /**

         * Returns storage type

         *

         * @since 3.0

         * @return one of the enum values of type TPEngStorageType

         */

        IMPORT_C TPEngStorageType StorageType() const;

        /**

         * Change storage type

         * When storage type is changes, this store entry should be

         * valid. Fisrt data are clean from the storage server and

         * then storage entry is stored with new type.

         * This function is available when

         * BaseConstructL( MPEngStorageManager& aStorageManager  )

         * was called.

         *

         * @since 3.0

         * @param aNewType ne storage type

         */

        IMPORT_C void ChangeStorageTypeL( TPEngStorageType aNewType );

    public: // New functions of MPEngSIDChangeObserver with default implementation

        /**

         * Handle change of the Storage IDs

         * More information can be found in <MPEngSIDChangeObserver.h>

         *

         * @since 3.0

         */

        IMPORT_C virtual void HandleSIDsChangeL( CPtrCArray& aChangedSIDs );

        /**

         * Called when SIDs notifier fails

         * More information can be found in <MPEngSIDChangeObserver.h>

         *

         * @since 3.0

         */

        IMPORT_C virtual void HandleSIDNotifyError( TInt aError );

    protected:  // Data protected to allow derivation

        /// OWN: Reference accessed Storage Manager

        MPEngStorageManager*					iStorageManager;

        /// OWN: Size of the store entry, updated by the storage manager

        TInt									iSize;

    private:    // Data, not visible to derived classes

        /// OWN: Storage Type, cannot be modified by derived class

        TPEngStorageType						iStorageType;

        /// Last Version of the Store retrieved from Storage Manager

        TInt32									iEntryVersion;

        friend class CPEngStorageManager;       // CSI: 36 #

    };

#endif      // __CPENGSTOREENTRY_H__

// End of File