/*

* 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:  Storage Manager interface

*

*/

#ifndef __MPENGSTORAGEMANAGER_H__

#define __MPENGSTORAGEMANAGER_H__

//class CPEngStoreEntry;

#include <badesca.h>

#include "CPEngStoreEntry.h"

// FORWARD DECLARATIONS

class MPEngStorageManagerWatcher;

class CPEngSessionSlotId;

// CLASS DECLARATION

/**

*  MPEngStorageManager defines the interface for Storing / Retrieving.

*  Through this interface Storage Entries can be stored / retrieved.

*  Storage entries implement CPENGSTOREENTRY interface. For more

*  information about storage entries see CPEngStoreEntry class.

*

*  @lib PEngStorMan.lib

*  @since 3.0

*/

class MPEngStorageManager

    {

        // Storage Manager can be deleted by this interface

    public:

        virtual ~MPEngStorageManager() {};

    public: // New functions

        /**

        *	Opens one more reference to this storage Manager

        *

        *	@since 3.0

        */

        virtual void Open() = 0;

        /**

        *	Closes one reference to this storage manager and deletes

        *	if it is no more needed

        *

        *	@since 3.0

        */

        virtual void Close() = 0;

        /**

         *	Stores StoreEntry given as an argument.

         *	If StoreEntry has been locked, lock is obeyed

         *

         *	@since 3.0

         *	@param aStoreEntry Store entry to store.

         */

        virtual void StoreL( const CPEngStoreEntry& aStoreEntry ) = 0;

        /**

         *	Stores Exclusively StoreEntry given as an argument.

         *	This store function does NOT obey Lock of the store entry

         *

         *	@since 3.0

         *	@param aStoreEntry Store entry to store.

         */

        virtual void StoreExclusiveL(

            const CPEngStoreEntry& aStoreEntry ) = 0;

        /**

         *	Retrieves the state of Storage Entry given as an argument.

         *  If obey version flag is on, before InternalizeL is called

         *  on the Store Entry, version is checked, if version from

         *  store and one Store Entry was already internalized with

         *  is same, InternalizeL is not called on the Store Entry.

         *  This feature is by default on.

         *

         *	@since 3.0

         *	@param aStoreEntry Store entry to retrieve.

         *  @param aObeyVersion flag to obey version numbers

         *	@return KErrNone if successful or KErrNotFound if store

         *		entry does not exists in the storage

         */

        virtual TInt RetrieveL( CPEngStoreEntry& aStoreEntry,

                                TBool aObeyVersion = ETrue ) = 0;

        /**

         *	Deletes Storage Entry from store.

         *

         *	@since 3.0

         *	@param aId id of Store entry to delete.

         *	@param aStorageType storage type of Store entry to delete.

         *	@return KErrNone if successful.

         */

        virtual TInt Delete( const CPEngStoreEntry& aStoreEntry ) = 0;

        /**

         *	Deletes Storage Entry from store.

         *

         *	@since 3.0

         *	@param aStoreEntryId Storage ID of entry to delete

         *	@return KErrNone if successful.

         */

        virtual TInt Delete( const TDesC& aStoreEntryId ) = 0;

        /*

         *	Used to check if certain storage entry is locked

         *  Function leaves if some error while communicating with

         *  server occures.

         *

         *	@since 3.0

         *	@param aStoreEntry store entry to be locked

         *  @param aPriority lock priority

         *	@return ETrue if entry is locked

         */

        virtual TBool LockedL( const CPEngStoreEntry& aStoreEntry,

                               TPengStorageLockPriority aPriority =

                                   EStorageLockLevelBasic ) const = 0;

        /**

         *	Used to check if certain storage entry is locked

         *  Function returns EFalse if some error while communicating with

         *  server occures.

         *

         *	@since 3.0

         *	@param aStoreID is id of the storage entry

         *  @param aPriority lock priority

         *	@return ETrue if entry is locked

         *          EFalse if not entry is not locked or error has occured

         *          while communicating with the server.

         */

        virtual TBool Locked( const CPEngStoreEntry& aStoreEntry,

                              TPengStorageLockPriority aPriority =

                                  EStorageLockLevelBasic ) const = 0;

        /*

         *	Used to lock certain storage entry

         *	Lock is reference counted, so in order to release lock

         *	same number of Unlock() calls needs to be done as Lock()

         *	If Store Entry is already locked with lower priority, no matter

         *	by which client, previous lock is removed and replaced by

         *	the new lock with the new higher priority.

         *	If passed priority is lower or same as already active of the

         *	store entry, this will fail with KErrLocked

         *

         *	@since 3.0

         *	@param aStoreEntry store entry to be locked

         *	@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.

         */

        virtual TInt Lock( const CPEngStoreEntry& aStoreEntry,

                           TPengStorageLockPriority aPriority =

                               EStorageLockLevelBasic,

                           TBool aCreateEntry = ETrue  ) const = 0;

        /*

         *	Used to unlock certain storage entry

         *	UnLock is reference counted and need to be called as many

         *	times ad Lock was called

         *

         *	@since 3.0

         *	@param aStoreEntry store entry to be un-locked

         *	@return Reference count of the lock, or if negative

         *			then some system wide error code

         */

        virtual TInt Unlock( const CPEngStoreEntry& aStoreEntry ) const = 0;

        /**

         *  Notifies about storage IDs change

         *  This call returns without waiting if notification was delivered

         *  to the Presence Server.

         *  Only one SID can be notified at the time, when same function

         *  is called in sequence multiple times client shall keep passed

         *  descriptors valid, if those descriptors will be deleted after

         *  call, notification will not be delivered to the listeners,

         *  Since Storage server was not able to read Store Id from client

         *

         *	@since 3.0

         *	@param aChangedSId changed Store Id to be notified,

         *  @param aSidStorageType storage type of the storage entry

         *	@return KErrDisconnected if there is not any observer registered

         *			KErrNone if it went OK

         */

        virtual TInt NotifyChangedSId( const TDesC& aChangedSId,

                                       TPEngStorageType aSidStorageType ) = 0;

        /*

         *	Stops sending of SID changes done through this Storage Manager

         *	Instance, how ever all notification will be buffered on the

         *	server side and will be sent all when ReleaseServerSideBuffering

         *	is called

         *	Multiple calling of this function increases counter on the

         *	client side and by specified counter

         *	Notifications are resumbed by the ReleaseServerSideBuffering()

         *

         *	@since 3.0

         *	@param	aCount count by which counter of the server will be

         *			increased, by default set to 1

         *	@return positive number represents number on the server side

         *		counter, negative some system wide error

         */

        virtual TInt BufferServerSideNotifications( TInt aCount = 1 ) = 0;

        /*

         *	Decreases counter of the Server Side Notification buffering,

         *	when counter reaches zero, all buffered notifications are

         *	notified to the listeners.

         *	If Bufferering of the SID changes is not active, this function

         *	Does nothing

         *

         *	@since 3.0

         *	@param	aCount count by which counter of the server will be

         *			decreased, by default set to 1

         *	@return positive number represents number on the server side

         *		ounter, negative some system wide error

         */

        virtual TInt ReleaseServerSideBuffering( TInt aCount = 1 ) = 0 ;

        /*

         *	Used to unlock certain storage entry

         *

         *	@since 3.0

         *	@return reference to the Storage Manager Watcher

         */

        virtual MPEngStorageManagerWatcher& StorageManagerWatcher() = 0;

        /*

         *	Get Session slot Id class

         *	Returned class carries information about the session of this

         *	instance of the storage manager

         *

         *	@since 3.0

         *	@return CPEngSessionSlotId& Session ID slot reference

         */

        virtual const CPEngSessionSlotId& SessionSlotId() const = 0;

    };

#endif      // __MPENGSTORAGEMANAGER_H__

// End of File