1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/persistentdata/persistentstorage/store/UFILE/UF_STOR.CPP Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,539 @@
1.4 +// Copyright (c) 1998-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 +// All rights reserved.
1.6 +// This component and the accompanying materials are made available
1.7 +// under the terms of "Eclipse Public License v1.0"
1.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +//
1.18 +
1.19 +#include "UF_STD.H"
1.20 +
1.21 +const TFileStoreFactoryFunction KDefaultFileStoreFactory[]=
1.22 + {
1.23 + KDirectFileStoreFactoryFunction,
1.24 + KPermanentFileStoreFactoryFunction,
1.25 + NULL
1.26 + };
1.27 +
1.28 +EXPORT_C CFileStore* CFileStore::OpenL(RFs& aFs,const TDesC& aName,TUint aFileMode)
1.29 +/** Opens a file containing a store and constructs an appropriate file store object.
1.30 +
1.31 +The resulting file store object is of concrete type, i.e. either CDirectFileStore
1.32 +or CPermanentFileStore. The specific type is determined from the layout information
1.33 +held in the file store. Note that if the store object is CPermanentFileStore and the file is writable,
1.34 +it is strongly recommended to set EFileWriteDirectIO bit in aFileMode. This is because that
1.35 +when the file server write caching is enabled, the order of file write operations is not guaranteed.
1.36 +This could cause data inconsistency in some circumstances, for example, when the power is lost in
1.37 + the middle of database transaction. Therefore, the file write caching should be switched off to maintain integrity.
1.38 +
1.39 +
1.40 +@param aFs Handle to a file server session.
1.41 +@param aName The full path name of the file containing the store.
1.42 +@param aFileMode The mode in which the file is to be accessed. The mode is
1.43 +defined by the TFileMode type.
1.44 +@return A pointer to the new file store object.
1.45 +@see TFileMode
1.46 +@see CFileStore::Layout() */
1.47 + {
1.48 + return OpenL(aFs,aName,aFileMode,KDefaultFileStoreFactory);
1.49 + }
1.50 +
1.51 +EXPORT_C CFileStore* CFileStore::OpenLC(RFs& aFs,const TDesC& aName,TUint aFileMode)
1.52 +/** Opens a file containing a store, constructs an appropriate file store object
1.53 +and places the pointer onto the cleanup stack.
1.54 +
1.55 +The resulting file store object is of concrete type, i.e. either CDirectFileStore
1.56 +or CPermanentFileStore. The specific type is determined from the layout information
1.57 +held in the file store. Note that if the store object is CPermanentFileStore and the file is writable,
1.58 +it is strongly recommended to set EFileWriteDirectIO bit when opening the file. This is because that
1.59 +when the file server write caching is enabled, the order of file write operations is not guaranteed.
1.60 +This could cause data inconsistency in some circumstances, for example, when the power is lost in
1.61 + the middle of database transaction. Therefore, the file write caching should be switched off to maintain integrity.
1.62 +
1.63 +
1.64 +@param aFs Handle to a file server session.
1.65 +@param aName The full path name of the file containing the store.
1.66 +@param aFileMode The mode in which the file is to be accessed. The mode is
1.67 +defined by the TFileMode type.
1.68 +@return A pointer to the new file store object.
1.69 +@see TFileMode
1.70 +@see CFileStore::Layout() */
1.71 + {
1.72 + return OpenLC(aFs,aName,aFileMode,KDefaultFileStoreFactory);
1.73 + }
1.74 +
1.75 +EXPORT_C CFileStore* CFileStore::FromL(RFile& aFile)
1.76 +/** Constructs a file store object from an opened file.
1.77 +
1.78 +The file must already be open before calling this function.
1.79 +
1.80 +The resulting file store object is of concrete type, i.e. either CDirectFileStore
1.81 +or CPermanentFileStore. The specific type is determined from the layout information
1.82 +held in the file store.
1.83 +
1.84 +Note that ownership of the file passes to the store. The referenced RFile
1.85 +is cleared and is no longer valid:
1.86 +
1.87 +@param aFile A reference to the opened file.
1.88 +@return A pointer to the new file store object.
1.89 +@see CFileStore::Layout() */
1.90 + {
1.91 + return FromL(aFile,KDefaultFileStoreFactory);
1.92 + }
1.93 +
1.94 +EXPORT_C CFileStore* CFileStore::FromLC(RFile& aFile)
1.95 +/** Constructs a file store object from an opened file, and places the pointer
1.96 +onto the cleanup stack.
1.97 +
1.98 +The file must already be open before calling this function.
1.99 +
1.100 +The resulting file store object is of concrete type, i.e. either CDirectFileStore
1.101 +or CPermanentFileStore. The specific type is determined from the layout information
1.102 +held in the file store.
1.103 +
1.104 +Note that ownership of the file passes to the store. The referenced RFile
1.105 +is cleared and is no longer valid:
1.106 +
1.107 +@param aFile A reference to the opened file.
1.108 +@return A pointer to the new file store object.
1.109 +@see CFileStore::Layout() */
1.110 + {
1.111 + return FromLC(aFile,KDefaultFileStoreFactory);
1.112 + }
1.113 +
1.114 +/** Opens a file containing a store and constructs an appropriate file store object.
1.115 +
1.116 +The resulting file store object is of concrete type, i.e. either CDirectFileStore
1.117 +or CPermanentFileStore. The specific type is determined from the layout information
1.118 +held in the file store. Note that if the store object is CPermanentFileStore and the file is writable,
1.119 +it is strongly recommended to set EFileWriteDirectIO bit in aFileMode. This is because that
1.120 +when the file server write caching is enabled, the order of file write operations is not guaranteed.
1.121 +This could cause data inconsistency in some circumstances, for example, when the power is lost in
1.122 +the middle of database transaction. Therefore, the file write caching should be switched off to maintain integrity.
1.123 +
1.124 +
1.125 +@param aFs Handle to a file server session.
1.126 +@param aName The full path name of the file containing the store.
1.127 +@param aFileMode The mode in which the file is to be accessed. The mode is
1.128 +defined by the TFileMode type.
1.129 +@param TFileStoreFactoryFunction An array of file store factory function.
1.130 +@return A pointer to the new file store object.
1.131 +@see TFileMode
1.132 +@see TFileStoreFactoryFunction
1.133 +*/
1.134 +EXPORT_C CFileStore* CFileStore::OpenL(RFs& aFs,const TDesC& aName,TUint aFileMode,const TFileStoreFactoryFunction aFactory[])
1.135 +//
1.136 +// Open a file store of any of the types supported by aFactory.
1.137 +//
1.138 + {
1.139 + RFile file;
1.140 + __LEAVE_IF_ERROR(file.Open(aFs,aName,aFileMode));
1.141 + return FromL(file,aFactory);
1.142 + }
1.143 +
1.144 +/** Opens a file containing a store and constructs an appropriate file store object.
1.145 +
1.146 +The resulting file store object is of concrete type, i.e. either CDirectFileStore
1.147 +or CPermanentFileStore. The specific type is determined from the layout information
1.148 +held in the file store. Note that if the store object is CPermanentFileStore and the file is writable,
1.149 +it is strongly recommended to set EFileWriteDirectIO bit in aFileMode. This is because that
1.150 +when the file server write caching is enabled, the order of file write operations is not guaranteed.
1.151 +This could cause data inconsistency in some circumstances, for example, when the power is lost in
1.152 +the middle of database transaction. Therefore, the file write caching should be switched off to maintain integrity.
1.153 +
1.154 +
1.155 +@param aFs Handle to a file server session.
1.156 +@param aName The full path name of the file containing the store.
1.157 +@param aFileMode The mode in which the file is to be accessed. The mode is
1.158 +defined by the TFileMode type.
1.159 +@param TFileStoreFactoryFunction An array of file store factory function.
1.160 +@return A pointer to the new file store object.
1.161 +@see TFileMode
1.162 +@see TFileStoreFactoryFunction
1.163 +*/
1.164 +EXPORT_C CFileStore* CFileStore::OpenLC(RFs& aFs,const TDesC& aName,TUint aFileMode,const TFileStoreFactoryFunction aFactory[])
1.165 +//
1.166 +// Open and leave on cleanup stack.
1.167 +//
1.168 + {
1.169 + CFileStore* store=OpenL(aFs,aName,aFileMode,aFactory);
1.170 + CleanupStack::PushL(store);
1.171 + return store;
1.172 + }
1.173 +
1.174 +EXPORT_C CFileStore* CFileStore::FromL(RFile& aFile,const TFileStoreFactoryFunction aFactory[])
1.175 +//
1.176 +// Read the file header and let every factory function in turn try to open it.
1.177 +//
1.178 + {
1.179 + RFileBuf buf;
1.180 + buf.Attach(aFile);
1.181 + buf.PushL();
1.182 + RReadStream stream(&buf);
1.183 + TCheckedUid chk;
1.184 + stream>>chk;
1.185 + if (chk.UidType().IsValid())
1.186 + {
1.187 + const TFileStoreFactoryFunction* iter=&aFactory[0];
1.188 + TFileStoreFactoryFunction func;
1.189 + while ((func=*iter++)!=NULL)
1.190 + {
1.191 + CFileStore* store=(*func)(buf,chk.UidType());
1.192 + if (store!=NULL)
1.193 + {
1.194 + CleanupStack::Pop(2);
1.195 + return store;
1.196 + }
1.197 + }
1.198 + }
1.199 +//
1.200 + __LEAVE(KErrNotSupported);
1.201 + return NULL;
1.202 + }
1.203 +
1.204 +EXPORT_C CFileStore* CFileStore::FromLC(RFile& aFile,const TFileStoreFactoryFunction aFactory[])
1.205 +//
1.206 +// Open and leave on cleanup stack.
1.207 +//
1.208 + {
1.209 + CFileStore* store=FromL(aFile,aFactory);
1.210 + CleanupStack::PushL(store);
1.211 + return store;
1.212 + }
1.213 +
1.214 +EXPORT_C void CFileStore::SetTypeL(const TUidType& aType)
1.215 +/** Sets the UID type of the file store.
1.216 +
1.217 +The first UID, i.e. the first TUid component, of the TUidType must be the
1.218 +file store type as returned by CFileStore::Layout(), otherwise the function
1.219 +raises a STORE-File 9 panic.
1.220 +
1.221 +@param aType The UID type object containing the file store type.
1.222 +@see TUid */
1.223 + {
1.224 + __ASSERT_ALWAYS(aType[0]==Layout(),Panic(EFileStoreBadType));
1.225 + TCheckedUid chk(aType);
1.226 + if (iHost.IsActive())
1.227 + {
1.228 + RShareWriteStream stream(iHost);
1.229 + stream.PushL();
1.230 + stream<<chk; // failure may mean the file's type information is lost
1.231 + CleanupStack::PopAndDestroy();
1.232 + }
1.233 + else
1.234 + {
1.235 + TInt size=iBuf.SizeL();
1.236 + RWriteStream stream(&iBuf);
1.237 + stream<<chk;
1.238 + if (size==0)
1.239 + {
1.240 + ExternalizeL(stream);
1.241 + iHost.Share(&iBuf);
1.242 + }
1.243 + }
1.244 + iType=aType;
1.245 + }
1.246 +
1.247 +EXPORT_C void CFileStore::MarshalL()
1.248 +//
1.249 +// Second-phase construction for opening existing file stores.
1.250 +//
1.251 + {
1.252 + __ASSERT_DEBUG(!iHost.IsActive()&&(!iType.IsValid()||iType[0]==Layout()),User::Invariant());
1.253 + RReadStream stream(&iBuf);
1.254 + InternalizeL(stream);
1.255 + iHost.Share(&iBuf);
1.256 + }
1.257 +
1.258 +EXPORT_C CFileStore::~CFileStore()
1.259 +/** Frees resources owned by the object, prior to its destruction. In particular,
1.260 +it closes the associated file. */
1.261 + {
1.262 + Destruct();
1.263 + iBuf.Close();
1.264 + }
1.265 +
1.266 +/** Opens a file containing a store and constructs an appropriate file store object.
1.267 +
1.268 +The resulting file store object is of concrete type, i.e. either CDirectFileStore
1.269 +or CPermanentFileStore. The specific type is determined from the layout information
1.270 +held in the file store. Note that if the store object is CPermanentFileStore and the file is writable,
1.271 +it is strongly recommended to set EFileWriteDirectIO bit in aFileMode. This is because that
1.272 +when the file server write caching is enabled, the order of file write operations is not guaranteed.
1.273 +This could cause data inconsistency in some circumstances, for example, when the power is lost in
1.274 +the middle of database transaction. Therefore, the file write caching should be switched off to maintain integrity.
1.275 +
1.276 +
1.277 +@param aFs Handle to a file server session.
1.278 +@param aName The full path name of the file containing the store.
1.279 +@param aFileMode The mode in which the file is to be accessed. The mode is
1.280 +defined by the TFileMode type.
1.281 +@param TFileStoreFactoryFunction A file store factory function.
1.282 +@return A pointer to the new file store object.
1.283 +@see TFileMode
1.284 +@see TFileStoreFactoryFunction
1.285 +*/
1.286 +EXPORT_C CFileStore* CFileStore::OpenL(RFs& aFs,const TDesC& aName,TUint aFileMode,TFileStoreFactoryFunction aFunction)
1.287 +//
1.288 +// Open a file store using aFunction.
1.289 +//
1.290 + {
1.291 + RFile file;
1.292 + __LEAVE_IF_ERROR(file.Open(aFs,aName,aFileMode));
1.293 + return FromL(file,aFunction);
1.294 + }
1.295 +
1.296 +/** Opens a file containing a store and constructs an appropriate file store object.
1.297 +
1.298 +The resulting file store object is of concrete type, i.e. either CDirectFileStore
1.299 +or CPermanentFileStore. The specific type is determined from the layout information
1.300 +held in the file store. Note that if the store object is CPermanentFileStore and the file is writable,
1.301 +it is strongly recommended to set EFileWriteDirectIO bit in aFileMode. This is because that
1.302 +when the file server write caching is enabled, the order of file write operations is not guaranteed.
1.303 +This could cause data inconsistency in some circumstances, for example, when the power is lost in
1.304 +the middle of database transaction. Therefore, the file write caching should be switched off to maintain integrity.
1.305 +
1.306 +
1.307 +@param aFs Handle to a file server session.
1.308 +@param aName The full path name of the file containing the store.
1.309 +@param aFileMode The mode in which the file is to be accessed. The mode is
1.310 +defined by the TFileMode type.
1.311 +@param TFileStoreFactoryFunction A file store factory function.
1.312 +@return A pointer to the new file store object.
1.313 +@see TFileMode
1.314 +@see TFileStoreFactoryFunction
1.315 +*/
1.316 +EXPORT_C CFileStore* CFileStore::OpenLC(RFs& aFs,const TDesC& aName,TUint aFileMode,TFileStoreFactoryFunction aFunction)
1.317 +//
1.318 +// Open and leave on cleanup stack.
1.319 +//
1.320 + {
1.321 + CFileStore* store=OpenL(aFs,aName,aFileMode,aFunction);
1.322 + CleanupStack::PushL(store);
1.323 + return store;
1.324 + }
1.325 +
1.326 +EXPORT_C CFileStore* CFileStore::CreateL(RFs& aFs,const TDesC& aName,TUint aFileMode,TNewFunction aFunction)
1.327 +//
1.328 +// Create a file store using aFunction. Must not already exist.
1.329 +//
1.330 + {
1.331 + RFile file;
1.332 + __LEAVE_IF_ERROR(file.Create(aFs,aName,aFileMode));
1.333 + return DoNewL(file,aFunction);
1.334 + }
1.335 +
1.336 +EXPORT_C CFileStore* CFileStore::CreateLC(RFs& aFs,const TDesC& aName,TUint aFileMode,TNewFunction aFunction)
1.337 +//
1.338 +// Create and leave on cleanup stack.
1.339 +//
1.340 + {
1.341 + CFileStore* store=CreateL(aFs,aName,aFileMode,aFunction);
1.342 + CleanupStack::PushL(store);
1.343 + return store;
1.344 + }
1.345 +
1.346 +EXPORT_C CFileStore* CFileStore::ReplaceL(RFs& aFs,const TDesC& aName,TUint aFileMode,TNewFunction aFunction)
1.347 +//
1.348 +// Replace a file store using aFunction. May exist already.
1.349 +//
1.350 + {
1.351 + RFile file;
1.352 + __LEAVE_IF_ERROR(file.Replace(aFs,aName,aFileMode));
1.353 + return DoNewL(file,aFunction);
1.354 + }
1.355 +
1.356 +EXPORT_C CFileStore* CFileStore::ReplaceLC(RFs& aFs,const TDesC& aName,TUint aFileMode,TNewFunction aFunction)
1.357 +//
1.358 +// Replace and leave on cleanup stack.
1.359 +//
1.360 + {
1.361 + CFileStore* store=ReplaceL(aFs,aName,aFileMode,aFunction);
1.362 + CleanupStack::PushL(store);
1.363 + return store;
1.364 + }
1.365 +
1.366 +EXPORT_C CFileStore* CFileStore::TempL(RFs& aFs,const TDesC& aPath,TFileName& aName,TUint aFileMode,TNewFunction aFunction)
1.367 +//
1.368 +// Create a temporary file store using aFunction.
1.369 +//
1.370 + {
1.371 + RFile file;
1.372 + __LEAVE_IF_ERROR(file.Temp(aFs,aPath,aName,aFileMode));
1.373 + return DoNewL(file,aFunction);
1.374 + }
1.375 +
1.376 +EXPORT_C CFileStore* CFileStore::TempLC(RFs& aFs,const TDesC& aPath,TFileName& aName,TUint aFileMode,TNewFunction aFunction)
1.377 +//
1.378 +// Create temporary and leave on cleanup stack.
1.379 +//
1.380 + {
1.381 + CFileStore* store=TempL(aFs,aPath,aName,aFileMode,aFunction);
1.382 + CleanupStack::PushL(store);
1.383 + return store;
1.384 + }
1.385 +
1.386 +EXPORT_C CFileStore* CFileStore::FromL(RFile& aFile,TFileStoreFactoryFunction aFunction)
1.387 +//
1.388 +// Open a file store using aFunction, given its file handle.
1.389 +//
1.390 + {
1.391 + RFileBuf buf;
1.392 + buf.Attach(aFile);
1.393 + buf.PushL();
1.394 + RReadStream stream(&buf);
1.395 + TCheckedUid chk;
1.396 + stream>>chk;
1.397 + CFileStore* store=(*aFunction)(buf,chk.UidType());
1.398 + if (store==NULL)
1.399 + {
1.400 + aFile.Close();
1.401 + __LEAVE(KErrNotSupported);
1.402 + }
1.403 +//
1.404 + CleanupStack::Pop(2);
1.405 + return store;
1.406 + }
1.407 +
1.408 +EXPORT_C CFileStore* CFileStore::FromLC(RFile& aFile,TFileStoreFactoryFunction aFunction)
1.409 +//
1.410 +// Open and leave on cleanup stack.
1.411 +//
1.412 + {
1.413 + CFileStore* store=FromL(aFile,aFunction);
1.414 + CleanupStack::PushL(store);
1.415 + return store;
1.416 + }
1.417 +
1.418 +EXPORT_C CFileStore* CFileStore::NewL(RFile& aFile,TNewFunction aFunction)
1.419 +//
1.420 +// Create a file store using aFunction, given its file handle.
1.421 +//
1.422 + {
1.423 + TInt r=aFile.SetSize(0);
1.424 + if (r!=KErrNone)
1.425 + {
1.426 + aFile.Close();
1.427 + __LEAVE(r);
1.428 + }
1.429 + return DoNewL(aFile,aFunction);
1.430 + }
1.431 +
1.432 +EXPORT_C CFileStore* CFileStore::NewLC(RFile& aFile,TNewFunction aFunction)
1.433 +//
1.434 +// Create and leave on cleanup stack.
1.435 +//
1.436 + {
1.437 + CFileStore* store=NewL(aFile,aFunction);
1.438 + CleanupStack::PushL(store);
1.439 + return store;
1.440 + }
1.441 +
1.442 +EXPORT_C CFileStore::CFileStore(RFile& aFile)
1.443 +//
1.444 +// Constructor creating a new file store.
1.445 +//
1.446 + {
1.447 + iBuf.Attach(aFile);
1.448 + iBuf.iExt = 0;
1.449 + }
1.450 +
1.451 +EXPORT_C CFileStore::CFileStore(RFileBuf& aBuf,const TUidType& aType)
1.452 +//
1.453 +// Constructor opening an existing file store.
1.454 +//
1.455 + : iBuf(Capture(aBuf)),iType(aType)
1.456 + {}
1.457 +
1.458 +EXPORT_C void CFileStore::Destruct()
1.459 +//
1.460 +// Early destruction, for derived classes overriding DoRevertL().
1.461 +//
1.462 + {
1.463 + if (iHost.IsActive())
1.464 + {
1.465 + iHost.Release();
1.466 + }
1.467 + }
1.468 +
1.469 +EXPORT_C void CFileStore::SynchL()
1.470 +//
1.471 +// Synchronise this file store's file buffer.
1.472 +//
1.473 + {
1.474 + TStreamExchange& host=iHost;
1.475 + if (host.IsActive())
1.476 + {
1.477 + MStreamBuf* buf=host.HostL();
1.478 + __ASSERT_DEBUG(IsHost(buf),User::Invariant());
1.479 + host.Release(); // make sure no writes fail silently by shutting down on failure
1.480 + buf->SynchL();
1.481 + host.Share(buf);
1.482 + }
1.483 + else
1.484 + iBuf.SynchL();
1.485 + }
1.486 +
1.487 +EXPORT_C void CFileStore::ChangedL()
1.488 +//
1.489 +// Re-write this file store's structure.
1.490 +//
1.491 + {
1.492 + __ASSERT_DEBUG(iHost.IsActive(),User::Invariant());
1.493 + RShareWriteStream stream(iHost,KFileStoreStart);
1.494 + stream.PushL();
1.495 + ExternalizeL(stream);
1.496 + CleanupStack::PopAndDestroy();
1.497 + }
1.498 +
1.499 +EXPORT_C void CFileStore::RefreshL()
1.500 +//
1.501 +// Re-read this file store's structure.
1.502 +//
1.503 + {
1.504 + if (iHost.IsActive())
1.505 + {
1.506 + RShareReadStream stream(iHost,KFileStoreStart);
1.507 + stream.PushL();
1.508 + InternalizeL(stream);
1.509 + CleanupStack::PopAndDestroy();
1.510 + }
1.511 + else
1.512 + {
1.513 + iBuf.SeekL(iBuf.ERead,KFileStoreStart);
1.514 + MarshalL();
1.515 + }
1.516 + }
1.517 +
1.518 +EXPORT_C void CFileStore::DoCommitL()
1.519 +//
1.520 +// Default implementation just synchronising.
1.521 +//
1.522 + {
1.523 + SynchL();
1.524 + }
1.525 +
1.526 +EXPORT_C void CFileStore::DoRevertL()
1.527 +//
1.528 +// Default implementation failing after synchronisation.
1.529 +//
1.530 + {
1.531 + SynchL();
1.532 + __LEAVE(KErrNotSupported);
1.533 + }
1.534 +
1.535 +CFileStore* CFileStore::DoNewL(RFile& aFile,TNewFunction aFunction)
1.536 + {
1.537 + CleanupClosePushL(aFile);
1.538 + CFileStore* store=(*aFunction)(aFile);
1.539 + CleanupStack::Pop();
1.540 + return store;
1.541 + }
1.542 +