Class RStoreReclaim

RStoreReclaim

Support

Supported from 5.0

Description

Performs space reclamation or compaction on a permanent file store in incremental steps.

Reclaiming unused space makes it available for re-use by the store. Compacting makes unused space available for re-use by the relevant system pool — for example, the filing system in the case of file-based stores.

Once compaction is complete, the store must be committed.

Notes:

• Space reclamation and compaction are only supported by the file store CPermanentFileStore and are not supported by embedded or direct file stores.

• Use active objects when implementing space reclamation or compaction asynchronously.

• This class performs incremental compaction/reclamation. These operations can be performed in a — possibly long running — single step using CStreamStore functions.

Defined in RStoreReclaim:
Available(), Close(), CompactL(), CompactLC(), Next(), NextL(), OpenL(), OpenLC(), Release(), ResetL()

void OpenL(CStreamStore& aStore,TInt& aCount);

Description

Prepares the object to perform space reclamation.

Parameters

CStreamStore& aStore A reference to the store on which space reclamation or compaction is to be performed. TInt& aCount A reference to a control value set by these functions. This value is required by all variants of Next() and NextL() (and ResetL(), if used).

void OpenLC(CStreamStore& aStore,TInt& aCount);

Description

Prepares the object to perform space reclamation and puts a pointer onto the cleanup stack.

Placing a cleanup item for the object onto the cleanup stack allows allocated resources to be cleaned up if a subsequent leave occurs.

Parameters

CStreamStore& aStore A reference to the store on which space reclamation or compaction is to be performed. TInt& aCount A reference to a control value set by these functions. This value is required by all variants of Next() and NextL() (and ResetL(), if used).

void CompactL(CStreamStore& aStore,TInt& aCount);

Description

Prepares the object to perform compaction.

Streams must be closed before calling this function.

Parameters

CStreamStore& aStore A reference to the store on which space reclamation or compaction is to be performed. TInt& aCount A reference to a control value set by these functions. This value is required by all variants of Next() and NextL() (and ResetL(), if used).

void CompactLC(CStreamStore& aStore,TInt& aCount);

Description

Prepares the object to perform compaction, putting a cleanup item onto the cleanup stack.

Placing a cleanup item for the object onto the cleanup stack allows allocated resources to be cleaned up if a subsequent leave occurs.

Streams must be closed before calling this function.

Parameters

CStreamStore& aStore A reference to the store on which space reclamation or compaction is to be performed. TInt& aCount A reference to a control value set by these functions. This value is required by all variants of Next() and NextL() (and ResetL(), if used).

TInt Available() const;

Description

Returns the amount of free space currently available within the store. The function may be called at any time during space reclamation or compaction.

Return value

TInt The amount of free space currently available within the store.

void Close();

Description

Stops space reclamation or compaction. All allocated resources are freed.

Notes:

• If a cleanup item was placed on the cleanup stack when the RStoreReclaim object was prepared for space reclamation or compaction (i.e. by a call to OpenLC() or CompactLC()), then this function need not be called explicitly; clean up is implicitly done by CleanupStack::PopAndDestroy().

• The ResetL() member function can be used to restart abandoned space reclamation or compaction activity.

void Next(TPckgBuf<TInt>& aStep,TRequestStatus& aStatus);

Description

Initiates the next space reclamation or compaction step — asynchronous, non-leaving. The function updates the value in aStep, and should only be called while aStep is non-zero. Once this value is zero, no further calls should be made.

The step itself is performed asynchronously.

Note:

• The RStoreReclaim object should be made part of an active object to simplify the handling of the step completion event.

Parameters

TPckgBuf<TInt>& aStep A reference to a control value constructed from a TInt value originally set by OpenL(), OpenLC(), CompactL() or CompactLC().aStep is updated by calls to Next() or NextL(). TRequestStatus& aStatus On completion, contains the request status. If successful contains KErrNone. If the function fails during the initiation phase, the failure is reported as if the step had started successfully but completed with that error.

TInt Next(TInt& aStep);

Description

Performs the next space reclamation or compaction step — synchronous, non-leaving. The function updates the value in aStep, and should only be called while aStep is non-zero. Once this value is zero, no further calls should be made.

The step is performed synchronously, i.e. the function does not return until the step is complete.

Parameters

TInt& aStep A reference to a control value originally set by OpenL(), OpenLC(), CompactL() or CompactLC() and updated by calls to Next() or NextL().

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

void NextL(TPckgBuf<TInt>& aStep,TRequestStatus& aStatus);

Description

Initiates the next space reclamation or compaction step — asynchronous, leaving. The function updates the value in aStep, and should only be called while aStep is non-zero. Once this value is zero, no further calls should be made.

The step itself is performed asynchronously.

Note:

• The RStoreReclaim object should be made part of an active object to simplify the handling of the step completion event.

Parameters

TPckgBuf<TInt>& aStep A reference to a control value constructed from a TInt value originally set by OpenL(), OpenLC(), CompactL() or CompactLC().aStep is updated by calls to Next() or NextL(). TRequestStatus& aStatus On completion, contains the request status. If successful contains KErrNone. If the function fails during the initiation phase, the failure is reported as if the step had started successfully but completed with that error.

Leave codes

The function leaves if it fails during the initiation phase, in which case no asynchronous request will have been made.

void NextL(TInt& aStep);

Description

Performs the next space reclamation or compaction step — synchronous, leaves. The function updates the value in aStep, and should only be called while aStep is non-zero. Once this value is zero, no further calls should be made.

The step is performed synchronously, i.e. the function does not return until the step is complete.

Parameters

TInt& aStep A reference to a control value originally set by OpenL(), OpenLC(), CompactL() or CompactLC() and updated by calls to Next() or NextL().

Leave codes

The function leaves on failure with one of the system-wide error codes (e.g. KErrNone ).

void Release();

Description

Releases allocated resources. Any space reclamation or compaction in progress is abandoned.

Notes:

• If a cleanup item was placed on the cleanup stack when the RStoreReclaim object was prepared for space reclamation or compaction (i.e. by a call to OpenLC() or CompactLC()), then this function need not be called explicitly; clean up is implicitly done by CleanupStack::PopAndDestroy().

• The ResetL() member function can be used to restart abandoned space reclamation or compaction activity.

void ResetL(TInt& aCount);

Description

Restarts space reclamation or compaction.

The value in aCount must be:

• that which was set by the most recent call to Next() or NextL(), if space reclamation or compaction had been started.

• that which was set by OpenL(), OpenLC(), CompactL() or CompactLC(), if space reclamation or compaction had not been started.

Parameters

TInt& aCount A reference to a control value originally set by OpenL(), OpenLC(), CompactL() or CompactLC() and updated by subsequent calls to Next() or NextL().