/*
* Copyright (c) 2004 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: Implements one store entry of the storage server
*
*/
#ifndef __CPENGDATAENTRY_H__
#define __CPENGDATAENTRY_H__
// INCLUDES
#include <e32base.h>
#include "PEngStorageGlobals.h"
// FORWARD DECLARATIONS
class RFs;
class MPEngHandlerListenSIDs;
/**
* Implements one store entry of the storage server
* Store entries are collected by the Storage folders
* @since 3.0
*/
class CPEngDataEntry
: public CBase
{
public: // Constructors and destructor
/**
* Two-phased constructor.
*/
static CPEngDataEntry* NewL( RFs& aFs,
const TDesC& aTempFolder,
const TDesC& aKey,
TPEngStorageType aType );
/**
* Two-phased constructor.
*/
static CPEngDataEntry* NewLC( RFs& aFs,
const TDesC& aTempFolder,
const TDesC& aKey,
TPEngStorageType aType );
/**
* Destructor.
*/
virtual ~CPEngDataEntry();
public: // New functions of the base class
/**
* Returns the data of this entry
* Function leaves with KErrNotFound if data is NULL pointer
* Otherwise not other leave is allowed
*
* @since 3.0
* @return descriptor with data of store entry.
*/
const TDesC8& DataL() const;
/**
* Returns the key of this entry.
*
* @since 3.0
* @return descriptor with the key
*/
const TDesC& Key() const;
/**
* Return pointer to key buffer, needed when ordering entries in B-tree.
*
* @since 3.0
* @return pointer to key buffer.
*/
HBufC** KeyBuffer();
/**
* Get Lock Status
*
* @since 3.0
* @param aPriority priority of the lock status to check
* @return lock status
*/
TBool LockStatus( TPengStorageLockPriority aPriority ) const;
/**
* Get lock count
* Get lock count, no matter the priority of the lock
*
* @since 3.0
* @return count
*/
TInt LockCount() const;
/**
* Increase Lock count of if client is allowed
*
* @since 3.0
* @param aSessionID ID of the Session command came from
* @param aSubSessionID ID of the Sub-session command came from
* @param aPriority priority of the lock command
*
*/
TInt IncreaseLockCountL( TInt32 aSessionID,
TInt aSubSessionID,
TPengStorageLockPriority aPriority );
/**
* Decrease Lock count of if client is allowed
*
* @since 3.0
* @param aSessionID ID of the Session command came from
* @param aSubSessionID ID of the Sub-session command came from
*/
TInt DecreaseLockCountL( TBool aNotifyActive,
TInt32 aSessionID,
TInt aSubSessionID,
CPEngDataEntry*& aNotifEntry );
/**
* Returns Current version of the store entry
*
* @since 3.0
* @return current version number
*/
TInt Version() const;
/**
* Returns Time of the last modification
*
* @since 3.0
* @return time
*/
const TTime& LastModification() const;
/**
* Asserts that store entry's storage type is required one.
* If not, leaves with KErrArgument.
*
* @since 3.0
* @param aType The supposed storage type.
*/
void AssertStorageTypeL( TPEngStorageType aType ) const;
public: // New functions of the base class with default implementation
/**
* Set entry data, owner ship of the passed buffer is called by
* the function. Descriptor buffer is in the clean up stack
* and should be poped/destroyed when when it is not needed.
* If derived class defines own implementation of this function
* CheckVersionNumberL() should be called before any operation
* and UpdateVersionNumber() on the end of the new implementation
* before function returns to caller. See CheckVersionNumberL()
* and UpdateVersionNumber() description
*
* Default implementation check Version, deletes old buffer,
* adopts new buffer, and updates version number
*
* @since 3.0
* @param aData data buffer to be set to store entry
* function takes ownership of the buffer descriptor
* @param aType data type for check it, also Version check
* is determined from the type
* @return if notification needs to be scheduled, return valid pointer
*/
virtual const CPEngDataEntry*
SetDataLX( HBufC8* aNewData,
TPEngStorageType aType,
TBool aNotifyActive,
TInt32 aSessionID,
TInt aSubSessionID );
/**
* Deletes store entry from storage
* Derived version can do additional cleaning if needed
*
* Default implementation removes permanent part of the store
* entry, if there is, from the file system
* @since 3.0
*/
virtual void DeleteStoreEntry();
/**
* Set hashed path of the store entry
* Function takes ownership of the passed des buffer
*
* @since 3.0
* @param aPath new hached path
*/
virtual void SetHashedPath( HBufC* aPath );
/**
* Initializes store entry. This function checks the type
* of thes store entry and load data from disc if needed
* This call always follows construction of the store entry
* before store entry si added to the tree.
* If store entry does not exists (for example for permanents entry)
* , function returns EFalse, so caller is informed that
* this entry has not meaning to be held if some data will not be
* stored into it
*
* @return ETrue if store entry has content
* @since 3.0
*/
virtual TBool InitializeStoreEntryL();
public: // new functions for observing support
/**
*
* @since 3.0
*/
void AddObserverL( MPEngHandlerListenSIDs& aObserver );
/**
*
* @since 3.0
*/
void RemoveObserver( MPEngHandlerListenSIDs& aObserver );
protected: // help functions of base class
/**
* Checks version number of passed data and internal buffer
* if they do not match.
* and function leave with KErrAccessDenied
* Version control flag is taken in account
*
* @since 3.0
* @param aNewData data buffer.
* @param aVersionControl flag is version if checked ETrue = yes
*/
void CheckVersionNumberL( const TDesC8& aNewData, TPEngStorageType aType );
/**
* Checks if passed sub-session is correct or not, in case lock
* is active. Function leave with KErrLocked if passed information
* does not match if lock was activated from passed sub-session,
* function does nothing
*
* @since 3.0
* @param aSessionID session
* @param aSubSessionID sub-session
*/
void CheckLockSubSessionL( TInt32 aSessionID, TInt aSubSessionID );
/**
* Updates version number of the Store Entry
* This suppose to be called when SetDataL function is called
*
* @since 3.0
* @param aData is data buffer.
*/
void UpdateVersionNumber();
protected: // private constructors
/**
* C++ default constructor.
*/
CPEngDataEntry( RFs& aFs,
const TDesC& aTempFolder,
TPEngStorageType aType );
/**
* Symbian second phase constructor
*/
void BaseConstructL( const TDesC& aKey );
private: // new private functions
void UpdatePermanentPartL( const TDesC8& aNewData );
void TrySeekPermanentPartL( RReadStream& aStream, TInt& aPermanentDataLength ) const;
HBufC8* PermanentFromFileOrNullL() const;
void NotifyUpdate();
protected: // Protected Data to allow derivation
/// REF: File server reference
RFs& iFs;
/// REF: Temp folder of the storage
const TDesC& iTempFolder;
/// OWN: Storage Type
const TPEngStorageType iType;
/// OWN: Storage ID of the Storage Entry
HBufC* iKey;
/// OWN: Hashed Store ID with the path
HBufC* iHashedPath;
/// OWN: Data of the stored entry
HBufC8* iData;
/// OWN: Last time entry was modified
TTime iModified;
/// OWN: Version count of the the entry ( used for confirmation)
TInt32 iVersion;
/// OWN: Flag if entry is locked, ETrue = Entry locked
TInt iLockCount;
/// OWN: Lock Session
TInt iLockSession;
/// OWN: Lock Sub-session
TInt iLockSubSession;
/// OWN: Lock Priority
TPengStorageLockPriority iLockPriority;
/// OWN: List of observers
/// Entries not owned
RPointerArray<MPEngHandlerListenSIDs> iObservers;
};
#endif