1 // Copyright (c) 1998-2009 Nokia Corporation and/or its subsidiary(-ies).

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // under the terms of "Eclipse Public License v1.0"

     5 // which accompanies this distribution, and is available

     6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 //

    15 

    16 #include "UT_STD.H"

    17 

    18 #define UNUSED_VAR(a) a = a

    19 

    20 LOCAL_C TInt runL(MIncrementalCollector* aCollector)

    21 //

    22 // Collect synchronously until finished.

    23 //

    24 	{

    25 	TInt total=0;

    26 	TInt step=0;

    27 	CleanupReleasePushL(*aCollector);

    28 	aCollector->ResetL(step);

    29 	while (step>0)

    30 		aCollector->NextL(step,total);

    31 	CleanupStack::PopAndDestroy();

    32 	return total;

    33 	}

    34 

    35 EXPORT_C void CStreamStore::Delete(TStreamId anId)

    36 /** Deletes the specified stream from this store.

    37 

    38 This function is deprecated.

    39 

    40 If unsuccessful, the function fails silently with no way to return information 

    41 to the user.

    42 

    43 The function is not supported by the direct file store, CDirectFileStore.

    44 

    45 @param anId The id of the stream to be deleted. */

    46 	{

    47 	TRAPD(ignore,DeleteL(anId));

    48     UNUSED_VAR(ignore);

    49 	}

    50 

    51 EXPORT_C void CStreamStore::DeleteL(TStreamId anId)

    52 /** Deletes the specified stream from this store, leaving if unsuccessful.

    53 

    54 The function is not supported by the direct file store, CDirectFileStore.

    55 

    56 @param anId The id of the stream to be deleted from this store.

    57 @see CDirectFileStore */

    58 	{

    59 	if (anId!=KNullStreamId)

    60 		DoDeleteL(anId);

    61 	}

    62 

    63 EXPORT_C TInt CStreamStore::Commit()

    64 /** Commits changes.

    65 

    66 This function establishes a new commit point. Typically, this is done after 

    67 changes to new or existing streams are complete and the streams themselves 

    68 have been committed.

    69 

    70 Establishing a new commit point makes changes to the store permanent. Until 

    71 such changes are committed, they can be rolled back or reverted, effectively 

    72 causing the store to revert back to its state before the changes were made.

    73 

    74 This ensures that persistent data moves from one consistent state to another 

    75 and guarantees the integrity of persistent store data in the event of failures. 

    76 In particular, if a process terminates or a media failure occurs, the store 

    77 reverts automatically to its state at the last successful commit point.

    78 

    79 Note that this function is not implemented by the direct file store CDirectFileStore 

    80 and the non-persistent in-memory store CBufStore.

    81 

    82 @return KErrNone if successful, otherwise another of the system-wide error 

    83 codes.

    84 @see CDirectFileStore

    85 @see CBufStore */

    86 	{

    87 	TRAPD(r,CommitL());

    88 	return r;

    89 	}

    90 

    91 EXPORT_C void CStreamStore::Revert()

    92 /** Rolls back the store to its state at the last commit point. 

    93 

    94 This function is deprecated; use RevertL() instead.

    95 

    96 If unsuccessful, the function fails silently with no way to return information 

    97 to the user.

    98 

    99 The function is not supported by the direct file store CDirectFileStore and 

   100 the non-persistent in-memory store CBufStore.

   101 

   102 @see CDirectFileStore

   103 @see CBufStore */

   104 	{

   105 	TRAPD(ignore,RevertL());

   106     UNUSED_VAR(ignore);

   107 	}

   108 

   109 EXPORT_C TInt CStreamStore::ReclaimL()

   110 /** Reclaims space within a store, returning the total amount of free space available 

   111 within that store.

   112 

   113 The function does not return until the reclamation process is complete. This 

   114 can take an extended amount of time.

   115 

   116 The function is only supported by the permanent file store, CPermanentFileStore, 

   117 but not by other derived classes, e.g., CDirectFileStore or CBufStore.

   118 

   119 @return The amount of free space available within the store.

   120 @see CPermanentFileStore */

   121 	{

   122 	return runL(DoReclaimL());

   123 	}

   124 

   125 EXPORT_C TInt CStreamStore::CompactL()

   126 /** Compacts the store. This returns free space to the appropriate system pool, 

   127 for example, the filing system in the case of file-based stores.

   128 

   129 On completion, the function returns the total amount of free space available 

   130 within the store.

   131 

   132 The function does not return until the compaction process is complete. This 

   133 can take an extended amount of time.

   134 

   135 Note:

   136 

   137 this function is only supported by the permanent file store, CPermanentFileStore, 

   138 and not by CDirectFileStore or CBufStore.

   139 

   140 Streams must be closed before calling this function.

   141 

   142 @return The amount of free space available within the store.

   143 @see CPermanentFileStore */

   144 	{

   145 	return runL(DoCompactL());

   146 	}

   147 

   148 EXPORT_C TStreamId CStreamStore::DoExtendL()

   149 /** Generates a new stream within this store, and returns its id. This function 

   150 is intended to create a new stream in advance of being written to.

   151 

   152 This is called by ExtendL().

   153 

   154 @return The new stream id.

   155 @see CStreamStore::ExtendL() */

   156 	{

   157 	__LEAVE(KErrNotSupported);

   158 	return KNullStreamId;

   159 	}

   160 

   161 EXPORT_C void CStreamStore::DoDeleteL(TStreamId)

   162 //

   163 // Default implementation failing.

   164 //

   165 	{

   166 	__LEAVE(KErrNotSupported);

   167 	}

   168 

   169 EXPORT_C MStreamBuf* CStreamStore::DoWriteL(TStreamId)

   170 //

   171 // Default implementation failing.

   172 //

   173 	{

   174 	__LEAVE(KErrNotSupported);

   175 	return NULL;

   176 	}

   177 

   178 EXPORT_C MStreamBuf* CStreamStore::DoReplaceL(TStreamId)

   179 //

   180 // Default implementation failing.

   181 //

   182 	{

   183 	__LEAVE(KErrNotSupported);

   184 	return NULL;

   185 	}

   186 

   187 EXPORT_C void CStreamStore::DoCommitL()

   188 /** Commits any changes to the store. For a store that provides atomic updates, 

   189 this writes all of the pending updates to the to the permanent storage medium. 

   190 After committing the store contains all or none of the updates since the last 

   191 commit/revert.

   192 

   193 This function provides the implementation for the public CommitL() function. */

   194 	{}

   195 

   196 EXPORT_C void CStreamStore::DoRevertL()

   197 /** Discards any pending changes to the store. This includes all changes which 

   198 have not been committed to a permanent storage medium. 

   199 

   200 This function provides the implementation for the public Revert() function.

   201 

   202 Note:

   203 

   204 The function need only be implemented by stores that provide atomic updates, 

   205 as revert has no meaning for other implementations. */

   206 	{

   207 	__LEAVE(KErrNotSupported);

   208 	}

   209 

   210 EXPORT_C MIncrementalCollector* CStreamStore::DoReclaimL()

   211 /** Initialises an object for reclaiming space in the store. This function provides 

   212 the direct implementation for RStoreReclaim::OpenL(). 

   213 

   214 Note:

   215 

   216 Actually reclaiming the space is done by repeated calls to MIncrementalCollector::Next(), 

   217 before releasing the object.

   218 

   219 @return Pointer to an incremental collector, which implements the interface 

   220 for reclaiming store space. */

   221 	{

   222 	__LEAVE(KErrNotSupported);

   223 	return NULL;

   224 	}

   225 

   226 EXPORT_C MIncrementalCollector* CStreamStore::DoCompactL()

   227 /** Initialises an object for compacting space in the store. This function provides 

   228 the direct implementation for RStoreReclaim::CompactL(). 

   229 

   230 Note:

   231 

   232 Actually compacting the space is done by repeated calls to MIncrementalCollector::Next() 

   233 before releasing the object.

   234 

   235 @return Pointer to an incremental collector, which implements the interface 

   236 for compacting store space. */

   237 	{

   238 	__LEAVE(KErrNotSupported);

   239 	return NULL;

   240 	}

   241 

   242 EXPORT_C void CPersistentStore::DoSetRootL(TStreamId anId)

   243 /** Implements the setting of theroot stream.

   244 

   245 This function is called by SetRootL()

   246 

   247 @param anId The id of the stream which is to be the root stream of the store.

   248 @see CPersistentStore::SetRootL() */

   249 	{

   250 	iRoot=anId;

   251 	}

   252 

   253 EXPORT_C void RStoreReclaim::OpenL(CStreamStore& aStore,TInt& aCount)

   254 /** Prepares the object to perform space reclamation.

   255 

   256 @param aStore A reference to the store on which space reclamation or compaction 

   257 is to be performed.

   258 @param aCount A reference to a control value set by these functions. This value 

   259 is required by all variants of Next() and NextL() (and ResetL(), if used). */

   260 	{

   261 	OpenLC(aStore,aCount);

   262 	CleanupStack::Pop();

   263 	}

   264 

   265 EXPORT_C void RStoreReclaim::OpenLC(CStreamStore& aStore,TInt& aCount)

   266 /** Prepares the object to perform space reclamation and puts a pointer onto the 

   267 cleanup stack.

   268 

   269 Placing a cleanup item for the object onto the cleanup stack allows allocated 

   270 resources to be cleaned up if a subsequent leave occurs.

   271 

   272 @param aStore A reference to the store on which space reclamation or compaction 

   273 is to be performed.

   274 @param aCount A reference to a control value set by these functions. This value 

   275 is required by all variants of Next() and NextL() (and ResetL(), if used). */

   276 	{

   277 	iCol=aStore.DoReclaimL();

   278 	CleanupReleasePushL(*this);

   279 	ResetL(aCount);

   280 	}

   281 

   282 EXPORT_C void RStoreReclaim::CompactL(CStreamStore& aStore,TInt& aCount)

   283 /** Prepares the object to perform compaction.

   284 

   285 Streams must be closed before calling this function.

   286 

   287 @param aStore A reference to the store on which space reclamation or compaction 

   288 is to be performed.

   289 @param aCount A reference to a control value set by these functions. This value 

   290 is required by all variants of Next() and NextL() (and ResetL(), if used). */

   291 	{

   292 	CompactLC(aStore,aCount);

   293 	CleanupStack::Pop();

   294 	}

   295 

   296 EXPORT_C void RStoreReclaim::CompactLC(CStreamStore& aStore,TInt& aCount)

   297 /** Prepares the object to perform compaction, putting a cleanup item onto the 

   298 cleanup stack. 

   299 

   300 P lacing a cleanup item for the object onto the cleanup stack allows allocated 

   301 resources to be cleaned up if a subsequent leave occurs.

   302 

   303 Streams must be closed before calling this function.

   304 

   305 @param aStore A reference to the store on which space reclamation or compaction 

   306 is to be performed.

   307 @param aCount A reference to a control value set by these functions. This value 

   308 is required by all variants of Next() and NextL() (and ResetL(), if used). */

   309 	{

   310 	iCol=aStore.DoCompactL();

   311 	CleanupReleasePushL(*this);

   312 	ResetL(aCount);

   313 	}

   314 

   315 EXPORT_C void RStoreReclaim::Release()

   316 /** Releases allocated resources. Any space reclamation or compaction in progress 

   317 is abandoned.

   318 

   319 Notes:

   320 

   321 If a cleanup item was placed on the cleanup stack when the RStoreReclaim object 

   322 was prepared for space reclamation or compaction (i.e. by a call to OpenLC() 

   323 or CompactLC()), then this function need not be called explicitly; clean up 

   324 is implicitly done by CleanupStack::PopAndDestroy().

   325 

   326 The ResetL() member function can be used to restart abandoned space reclamation 

   327 or compaction activity. */

   328 	{

   329 	if (iCol!=NULL)

   330 		{

   331 		iCol->Release();

   332 		iCol=NULL;

   333 		}

   334 	}

   335 

   336 EXPORT_C void RStoreReclaim::ResetL(TInt& aCount)

   337 /** Restarts space reclamation or compaction.

   338 

   339 The value in aCount must be:

   340 

   341 that which was set by the most recent call to Next() or NextL(), if space 

   342 reclamation or compaction had been started.

   343 

   344 that which was set by OpenL(), OpenLC(), CompactL() or CompactLC(), if space 

   345 reclamation or compaction had not been started.

   346 

   347 @param aCount A reference to a control value originally set by OpenL(), OpenLC(), 

   348 CompactL() or CompactLC() and updated by subsequent calls to Next() or NextL(). */

   349 	{

   350 	__ASSERT_DEBUG(iCol!=NULL,Panic(EStoreNotOpen));

   351 	iCol->ResetL(aCount);

   352 	iAvail()=0;

   353 	}

   354 

   355 EXPORT_C void RStoreReclaim::NextL(TInt& aStep)

   356 /** Performs the next space reclamation or compaction step synchronous, leaves. 

   357 The function updates the value in aStep, and should only be called while aStep 

   358 is non-zero. Once this value is zero, no further calls should be made.

   359 

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

   361 the step is complete.

   362 

   363 @param aStep A reference to a control value originally set by OpenL(), OpenLC(), 

   364 CompactL() or CompactLC() and updated by calls to Next() or NextL(). */

   365 	{

   366 	__ASSERT_DEBUG(iCol!=NULL,Panic(EStoreNotOpen));

   367 	iCol->NextL(aStep,iAvail());

   368 	}

   369 

   370 EXPORT_C void RStoreReclaim::Next(TPckgBuf<TInt>& aStep,TRequestStatus& aStatus)

   371 //

   372 // Perform a reclamation step with guaranteed completion.

   373 //

   374 /** Initiates the next space reclamation or compaction step asynchronous, 

   375 non-leaving. The function updates the value in aStep, and should only be called 

   376 while aStep is non-zero. Once this value is zero, no further calls should 

   377 be made.

   378 

   379 The step itself is performed asynchronously.

   380 

   381 Note:

   382 

   383 The RStoreReclaim object should be made part of an active object to simplify 

   384 the handling of the step completion event.

   385 

   386 @param aStep A reference to a control value constructed from a TInt value 

   387 originally set by OpenL(), OpenLC(), CompactL() or CompactLC().aStep is updated 

   388 by calls to Next() or NextL().

   389 @param aStatus On completion, contains the request status. If successful contains 

   390 KErrNone. If the function fails during the initiation phase, the failure is 

   391 reported as if the step had started successfully but completed with that error. */

   392 	{

   393 	__ASSERT_DEBUG(iCol!=NULL,Panic(EStoreNotOpen));

   394 	TRAPD(r,iCol->NextL(aStep,aStatus,iAvail));

   395 	if (r!=KErrNone)

   396 		{

   397 		TRequestStatus* stat=&aStatus;

   398 		User::RequestComplete(stat,r);

   399 		}

   400 	}

   401 

   402 EXPORT_C void RStoreReclaim::NextL(TPckgBuf<TInt>& aStep,TRequestStatus& aStatus)

   403 /** Initiates the next space reclamation or compaction step asynchronous, 

   404 leaving. The function updates the value in aStep, and should only be called 

   405 while aStep is non-zero. Once this value is zero, no further calls should 

   406 be made.

   407 

   408 The step itself is performed asynchronously.

   409 

   410 Note:

   411 

   412 The RStoreReclaim object should be made part of an active object to simplify 

   413 the handling of the step completion event.

   414 

   415 @param aStep A reference to a control value constructed from a TInt value 

   416 originally set by OpenL(), OpenLC(), CompactL() or CompactLC().aStep is updated 

   417 by calls to Next() or NextL().

   418 @param aStatus On completion, contains the request status. If successful contains 

   419 KErrNone. If the function fails during the initiation phase, the failure is 

   420 reported as if the step had started successfully but completed with that error. */

   421 	{

   422 	__ASSERT_DEBUG(iCol!=NULL,Panic(EStoreNotOpen));

   423 	iCol->NextL(aStep,aStatus,iAvail);

   424 	}

   425 

   426 EXPORT_C TInt RStoreReclaim::Next(TInt& aStep)

   427 /** Performs the next space reclamation or compaction step synchronous, non-leaving. 

   428 The function updates the value in aStep, and should only be called while aStep 

   429 is non-zero. Once this value is zero, no further calls should be made.

   430 

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

   432 the step is complete.

   433 

   434 @param aStep A reference to a control value originally set by OpenL(), OpenLC(), 

   435 CompactL() or CompactLC() and updated by calls to Next() or NextL().

   436 @return KErrNone if successful, otherwise another of the system-wide error 

   437 codes. */

   438 	{

   439 	__ASSERT_DEBUG(iCol!=NULL,Panic(EStoreNotOpen));

   440 	TRAPD(r,iCol->NextL(aStep,iAvail()));

   441 	return r;

   442 	}

   443