sl@0: // Copyright (c) 1998-2009 Nokia Corporation and/or its subsidiary(-ies).
sl@0: // All rights reserved.
sl@0: // This component and the accompanying materials are made available
sl@0: // under the terms of "Eclipse Public License v1.0"
sl@0: // which accompanies this distribution, and is available
sl@0: // at the URL "http://www.eclipse.org/legal/epl-v10.html".
sl@0: //
sl@0: // Initial Contributors:
sl@0: // Nokia Corporation - initial contribution.
sl@0: //
sl@0: // Contributors:
sl@0: //
sl@0: // Description:
sl@0: //
sl@0: 
sl@0: #include "UT_STD.H"
sl@0: 
sl@0: #define UNUSED_VAR(a) a = a
sl@0: 
sl@0: LOCAL_C TInt runL(MIncrementalCollector* aCollector)
sl@0: //
sl@0: // Collect synchronously until finished.
sl@0: //
sl@0: 	{
sl@0: 	TInt total=0;
sl@0: 	TInt step=0;
sl@0: 	CleanupReleasePushL(*aCollector);
sl@0: 	aCollector->ResetL(step);
sl@0: 	while (step>0)
sl@0: 		aCollector->NextL(step,total);
sl@0: 	CleanupStack::PopAndDestroy();
sl@0: 	return total;
sl@0: 	}
sl@0: 
sl@0: EXPORT_C void CStreamStore::Delete(TStreamId anId)
sl@0: /** Deletes the specified stream from this store.
sl@0: 
sl@0: This function is deprecated.
sl@0: 
sl@0: If unsuccessful, the function fails silently with no way to return information 
sl@0: to the user.
sl@0: 
sl@0: The function is not supported by the direct file store, CDirectFileStore.
sl@0: 
sl@0: @param anId The id of the stream to be deleted. */
sl@0: 	{
sl@0: 	TRAPD(ignore,DeleteL(anId));
sl@0:     UNUSED_VAR(ignore);
sl@0: 	}
sl@0: 
sl@0: EXPORT_C void CStreamStore::DeleteL(TStreamId anId)
sl@0: /** Deletes the specified stream from this store, leaving if unsuccessful.
sl@0: 
sl@0: The function is not supported by the direct file store, CDirectFileStore.
sl@0: 
sl@0: @param anId The id of the stream to be deleted from this store.
sl@0: @see CDirectFileStore */
sl@0: 	{
sl@0: 	if (anId!=KNullStreamId)
sl@0: 		DoDeleteL(anId);
sl@0: 	}
sl@0: 
sl@0: EXPORT_C TInt CStreamStore::Commit()
sl@0: /** Commits changes.
sl@0: 
sl@0: This function establishes a new commit point. Typically, this is done after 
sl@0: changes to new or existing streams are complete and the streams themselves 
sl@0: have been committed.
sl@0: 
sl@0: Establishing a new commit point makes changes to the store permanent. Until 
sl@0: such changes are committed, they can be rolled back or reverted, effectively 
sl@0: causing the store to revert back to its state before the changes were made.
sl@0: 
sl@0: This ensures that persistent data moves from one consistent state to another 
sl@0: and guarantees the integrity of persistent store data in the event of failures. 
sl@0: In particular, if a process terminates or a media failure occurs, the store 
sl@0: reverts automatically to its state at the last successful commit point.
sl@0: 
sl@0: Note that this function is not implemented by the direct file store CDirectFileStore 
sl@0: and the non-persistent in-memory store CBufStore.
sl@0: 
sl@0: @return KErrNone if successful, otherwise another of the system-wide error 
sl@0: codes.
sl@0: @see CDirectFileStore
sl@0: @see CBufStore */
sl@0: 	{
sl@0: 	TRAPD(r,CommitL());
sl@0: 	return r;
sl@0: 	}
sl@0: 
sl@0: EXPORT_C void CStreamStore::Revert()
sl@0: /** Rolls back the store to its state at the last commit point. 
sl@0: 
sl@0: This function is deprecated; use RevertL() instead.
sl@0: 
sl@0: If unsuccessful, the function fails silently with no way to return information 
sl@0: to the user.
sl@0: 
sl@0: The function is not supported by the direct file store CDirectFileStore and 
sl@0: the non-persistent in-memory store CBufStore.
sl@0: 
sl@0: @see CDirectFileStore
sl@0: @see CBufStore */
sl@0: 	{
sl@0: 	TRAPD(ignore,RevertL());
sl@0:     UNUSED_VAR(ignore);
sl@0: 	}
sl@0: 
sl@0: EXPORT_C TInt CStreamStore::ReclaimL()
sl@0: /** Reclaims space within a store, returning the total amount of free space available 
sl@0: within that store.
sl@0: 
sl@0: The function does not return until the reclamation process is complete. This 
sl@0: can take an extended amount of time.
sl@0: 
sl@0: The function is only supported by the permanent file store, CPermanentFileStore, 
sl@0: but not by other derived classes, e.g., CDirectFileStore or CBufStore.
sl@0: 
sl@0: @return The amount of free space available within the store.
sl@0: @see CPermanentFileStore */
sl@0: 	{
sl@0: 	return runL(DoReclaimL());
sl@0: 	}
sl@0: 
sl@0: EXPORT_C TInt CStreamStore::CompactL()
sl@0: /** Compacts the store. This returns free space to the appropriate system pool, 
sl@0: for example, the filing system in the case of file-based stores.
sl@0: 
sl@0: On completion, the function returns the total amount of free space available 
sl@0: within the store.
sl@0: 
sl@0: The function does not return until the compaction process is complete. This 
sl@0: can take an extended amount of time.
sl@0: 
sl@0: Note:
sl@0: 
sl@0: this function is only supported by the permanent file store, CPermanentFileStore, 
sl@0: and not by CDirectFileStore or CBufStore.
sl@0: 
sl@0: Streams must be closed before calling this function.
sl@0: 
sl@0: @return The amount of free space available within the store.
sl@0: @see CPermanentFileStore */
sl@0: 	{
sl@0: 	return runL(DoCompactL());
sl@0: 	}
sl@0: 
sl@0: EXPORT_C TStreamId CStreamStore::DoExtendL()
sl@0: /** Generates a new stream within this store, and returns its id. This function 
sl@0: is intended to create a new stream in advance of being written to.
sl@0: 
sl@0: This is called by ExtendL().
sl@0: 
sl@0: @return The new stream id.
sl@0: @see CStreamStore::ExtendL() */
sl@0: 	{
sl@0: 	__LEAVE(KErrNotSupported);
sl@0: 	return KNullStreamId;
sl@0: 	}
sl@0: 
sl@0: EXPORT_C void CStreamStore::DoDeleteL(TStreamId)
sl@0: //
sl@0: // Default implementation failing.
sl@0: //
sl@0: 	{
sl@0: 	__LEAVE(KErrNotSupported);
sl@0: 	}
sl@0: 
sl@0: EXPORT_C MStreamBuf* CStreamStore::DoWriteL(TStreamId)
sl@0: //
sl@0: // Default implementation failing.
sl@0: //
sl@0: 	{
sl@0: 	__LEAVE(KErrNotSupported);
sl@0: 	return NULL;
sl@0: 	}
sl@0: 
sl@0: EXPORT_C MStreamBuf* CStreamStore::DoReplaceL(TStreamId)
sl@0: //
sl@0: // Default implementation failing.
sl@0: //
sl@0: 	{
sl@0: 	__LEAVE(KErrNotSupported);
sl@0: 	return NULL;
sl@0: 	}
sl@0: 
sl@0: EXPORT_C void CStreamStore::DoCommitL()
sl@0: /** Commits any changes to the store. For a store that provides atomic updates, 
sl@0: this writes all of the pending updates to the to the permanent storage medium. 
sl@0: After committing the store contains all or none of the updates since the last 
sl@0: commit/revert.
sl@0: 
sl@0: This function provides the implementation for the public CommitL() function. */
sl@0: 	{}
sl@0: 
sl@0: EXPORT_C void CStreamStore::DoRevertL()
sl@0: /** Discards any pending changes to the store. This includes all changes which 
sl@0: have not been committed to a permanent storage medium. 
sl@0: 
sl@0: This function provides the implementation for the public Revert() function.
sl@0: 
sl@0: Note:
sl@0: 
sl@0: The function need only be implemented by stores that provide atomic updates, 
sl@0: as revert has no meaning for other implementations. */
sl@0: 	{
sl@0: 	__LEAVE(KErrNotSupported);
sl@0: 	}
sl@0: 
sl@0: EXPORT_C MIncrementalCollector* CStreamStore::DoReclaimL()
sl@0: /** Initialises an object for reclaiming space in the store. This function provides 
sl@0: the direct implementation for RStoreReclaim::OpenL(). 
sl@0: 
sl@0: Note:
sl@0: 
sl@0: Actually reclaiming the space is done by repeated calls to MIncrementalCollector::Next(), 
sl@0: before releasing the object.
sl@0: 
sl@0: @return Pointer to an incremental collector, which implements the interface 
sl@0: for reclaiming store space. */
sl@0: 	{
sl@0: 	__LEAVE(KErrNotSupported);
sl@0: 	return NULL;
sl@0: 	}
sl@0: 
sl@0: EXPORT_C MIncrementalCollector* CStreamStore::DoCompactL()
sl@0: /** Initialises an object for compacting space in the store. This function provides 
sl@0: the direct implementation for RStoreReclaim::CompactL(). 
sl@0: 
sl@0: Note:
sl@0: 
sl@0: Actually compacting the space is done by repeated calls to MIncrementalCollector::Next() 
sl@0: before releasing the object.
sl@0: 
sl@0: @return Pointer to an incremental collector, which implements the interface 
sl@0: for compacting store space. */
sl@0: 	{
sl@0: 	__LEAVE(KErrNotSupported);
sl@0: 	return NULL;
sl@0: 	}
sl@0: 
sl@0: EXPORT_C void CPersistentStore::DoSetRootL(TStreamId anId)
sl@0: /** Implements the setting of theroot stream.
sl@0: 
sl@0: This function is called by SetRootL()
sl@0: 
sl@0: @param anId The id of the stream which is to be the root stream of the store.
sl@0: @see CPersistentStore::SetRootL() */
sl@0: 	{
sl@0: 	iRoot=anId;
sl@0: 	}
sl@0: 
sl@0: EXPORT_C void RStoreReclaim::OpenL(CStreamStore& aStore,TInt& aCount)
sl@0: /** Prepares the object to perform space reclamation.
sl@0: 
sl@0: @param aStore A reference to the store on which space reclamation or compaction 
sl@0: is to be performed.
sl@0: @param aCount A reference to a control value set by these functions. This value 
sl@0: is required by all variants of Next() and NextL() (and ResetL(), if used). */
sl@0: 	{
sl@0: 	OpenLC(aStore,aCount);
sl@0: 	CleanupStack::Pop();
sl@0: 	}
sl@0: 
sl@0: EXPORT_C void RStoreReclaim::OpenLC(CStreamStore& aStore,TInt& aCount)
sl@0: /** Prepares the object to perform space reclamation and puts a pointer onto the 
sl@0: cleanup stack.
sl@0: 
sl@0: Placing a cleanup item for the object onto the cleanup stack allows allocated 
sl@0: resources to be cleaned up if a subsequent leave occurs.
sl@0: 
sl@0: @param aStore A reference to the store on which space reclamation or compaction 
sl@0: is to be performed.
sl@0: @param aCount A reference to a control value set by these functions. This value 
sl@0: is required by all variants of Next() and NextL() (and ResetL(), if used). */
sl@0: 	{
sl@0: 	iCol=aStore.DoReclaimL();
sl@0: 	CleanupReleasePushL(*this);
sl@0: 	ResetL(aCount);
sl@0: 	}
sl@0: 
sl@0: EXPORT_C void RStoreReclaim::CompactL(CStreamStore& aStore,TInt& aCount)
sl@0: /** Prepares the object to perform compaction.
sl@0: 
sl@0: Streams must be closed before calling this function.
sl@0: 
sl@0: @param aStore A reference to the store on which space reclamation or compaction 
sl@0: is to be performed.
sl@0: @param aCount A reference to a control value set by these functions. This value 
sl@0: is required by all variants of Next() and NextL() (and ResetL(), if used). */
sl@0: 	{
sl@0: 	CompactLC(aStore,aCount);
sl@0: 	CleanupStack::Pop();
sl@0: 	}
sl@0: 
sl@0: EXPORT_C void RStoreReclaim::CompactLC(CStreamStore& aStore,TInt& aCount)
sl@0: /** Prepares the object to perform compaction, putting a cleanup item onto the 
sl@0: cleanup stack. 
sl@0: 
sl@0: P lacing a cleanup item for the object onto the cleanup stack allows allocated 
sl@0: resources to be cleaned up if a subsequent leave occurs.
sl@0: 
sl@0: Streams must be closed before calling this function.
sl@0: 
sl@0: @param aStore A reference to the store on which space reclamation or compaction 
sl@0: is to be performed.
sl@0: @param aCount A reference to a control value set by these functions. This value 
sl@0: is required by all variants of Next() and NextL() (and ResetL(), if used). */
sl@0: 	{
sl@0: 	iCol=aStore.DoCompactL();
sl@0: 	CleanupReleasePushL(*this);
sl@0: 	ResetL(aCount);
sl@0: 	}
sl@0: 
sl@0: EXPORT_C void RStoreReclaim::Release()
sl@0: /** Releases allocated resources. Any space reclamation or compaction in progress 
sl@0: is abandoned.
sl@0: 
sl@0: Notes:
sl@0: 
sl@0: If a cleanup item was placed on the cleanup stack when the RStoreReclaim object 
sl@0: was prepared for space reclamation or compaction (i.e. by a call to OpenLC() 
sl@0: or CompactLC()), then this function need not be called explicitly; clean up 
sl@0: is implicitly done by CleanupStack::PopAndDestroy().
sl@0: 
sl@0: The ResetL() member function can be used to restart abandoned space reclamation 
sl@0: or compaction activity. */
sl@0: 	{
sl@0: 	if (iCol!=NULL)
sl@0: 		{
sl@0: 		iCol->Release();
sl@0: 		iCol=NULL;
sl@0: 		}
sl@0: 	}
sl@0: 
sl@0: EXPORT_C void RStoreReclaim::ResetL(TInt& aCount)
sl@0: /** Restarts space reclamation or compaction.
sl@0: 
sl@0: The value in aCount must be:
sl@0: 
sl@0: that which was set by the most recent call to Next() or NextL(), if space 
sl@0: reclamation or compaction had been started.
sl@0: 
sl@0: that which was set by OpenL(), OpenLC(), CompactL() or CompactLC(), if space 
sl@0: reclamation or compaction had not been started.
sl@0: 
sl@0: @param aCount A reference to a control value originally set by OpenL(), OpenLC(), 
sl@0: CompactL() or CompactLC() and updated by subsequent calls to Next() or NextL(). */
sl@0: 	{
sl@0: 	__ASSERT_DEBUG(iCol!=NULL,Panic(EStoreNotOpen));
sl@0: 	iCol->ResetL(aCount);
sl@0: 	iAvail()=0;
sl@0: 	}
sl@0: 
sl@0: EXPORT_C void RStoreReclaim::NextL(TInt& aStep)
sl@0: /** Performs the next space reclamation or compaction step synchronous, leaves. 
sl@0: The function updates the value in aStep, and should only be called while aStep 
sl@0: is non-zero. Once this value is zero, no further calls should be made.
sl@0: 
sl@0: The step is performed synchronously, i.e. the function does not return until 
sl@0: the step is complete.
sl@0: 
sl@0: @param aStep A reference to a control value originally set by OpenL(), OpenLC(), 
sl@0: CompactL() or CompactLC() and updated by calls to Next() or NextL(). */
sl@0: 	{
sl@0: 	__ASSERT_DEBUG(iCol!=NULL,Panic(EStoreNotOpen));
sl@0: 	iCol->NextL(aStep,iAvail());
sl@0: 	}
sl@0: 
sl@0: EXPORT_C void RStoreReclaim::Next(TPckgBuf<TInt>& aStep,TRequestStatus& aStatus)
sl@0: //
sl@0: // Perform a reclamation step with guaranteed completion.
sl@0: //
sl@0: /** Initiates the next space reclamation or compaction step asynchronous, 
sl@0: non-leaving. The function updates the value in aStep, and should only be called 
sl@0: while aStep is non-zero. Once this value is zero, no further calls should 
sl@0: be made.
sl@0: 
sl@0: The step itself is performed asynchronously.
sl@0: 
sl@0: Note:
sl@0: 
sl@0: The RStoreReclaim object should be made part of an active object to simplify 
sl@0: the handling of the step completion event.
sl@0: 
sl@0: @param aStep A reference to a control value constructed from a TInt value 
sl@0: originally set by OpenL(), OpenLC(), CompactL() or CompactLC().aStep is updated 
sl@0: by calls to Next() or NextL().
sl@0: @param aStatus On completion, contains the request status. If successful contains 
sl@0: KErrNone. If the function fails during the initiation phase, the failure is 
sl@0: reported as if the step had started successfully but completed with that error. */
sl@0: 	{
sl@0: 	__ASSERT_DEBUG(iCol!=NULL,Panic(EStoreNotOpen));
sl@0: 	TRAPD(r,iCol->NextL(aStep,aStatus,iAvail));
sl@0: 	if (r!=KErrNone)
sl@0: 		{
sl@0: 		TRequestStatus* stat=&aStatus;
sl@0: 		User::RequestComplete(stat,r);
sl@0: 		}
sl@0: 	}
sl@0: 
sl@0: EXPORT_C void RStoreReclaim::NextL(TPckgBuf<TInt>& aStep,TRequestStatus& aStatus)
sl@0: /** Initiates the next space reclamation or compaction step asynchronous, 
sl@0: leaving. The function updates the value in aStep, and should only be called 
sl@0: while aStep is non-zero. Once this value is zero, no further calls should 
sl@0: be made.
sl@0: 
sl@0: The step itself is performed asynchronously.
sl@0: 
sl@0: Note:
sl@0: 
sl@0: The RStoreReclaim object should be made part of an active object to simplify 
sl@0: the handling of the step completion event.
sl@0: 
sl@0: @param aStep A reference to a control value constructed from a TInt value 
sl@0: originally set by OpenL(), OpenLC(), CompactL() or CompactLC().aStep is updated 
sl@0: by calls to Next() or NextL().
sl@0: @param aStatus On completion, contains the request status. If successful contains 
sl@0: KErrNone. If the function fails during the initiation phase, the failure is 
sl@0: reported as if the step had started successfully but completed with that error. */
sl@0: 	{
sl@0: 	__ASSERT_DEBUG(iCol!=NULL,Panic(EStoreNotOpen));
sl@0: 	iCol->NextL(aStep,aStatus,iAvail);
sl@0: 	}
sl@0: 
sl@0: EXPORT_C TInt RStoreReclaim::Next(TInt& aStep)
sl@0: /** Performs the next space reclamation or compaction step synchronous, non-leaving. 
sl@0: The function updates the value in aStep, and should only be called while aStep 
sl@0: is non-zero. Once this value is zero, no further calls should be made.
sl@0: 
sl@0: The step is performed synchronously, i.e. the function does not return until 
sl@0: the step is complete.
sl@0: 
sl@0: @param aStep A reference to a control value originally set by OpenL(), OpenLC(), 
sl@0: CompactL() or CompactLC() and updated by calls to Next() or NextL().
sl@0: @return KErrNone if successful, otherwise another of the system-wide error 
sl@0: codes. */
sl@0: 	{
sl@0: 	__ASSERT_DEBUG(iCol!=NULL,Panic(EStoreNotOpen));
sl@0: 	TRAPD(r,iCol->NextL(aStep,iAvail()));
sl@0: 	return r;
sl@0: 	}
sl@0: