Symaptic: os/persistentdata/persistentstorage/sqlite3api/OsLayer/os

     1 /**

     2 * Copyright (c) 2008-2010 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

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

8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:

    15 * Declarations for the multi-threaded Symbian OS porting layer.

    16 *

    17 *

    18 */

    22 /**

    23  @file

    24 */

    25 #ifndef OS_SYMBIAN_H

    26 #define OS_SYMBIAN_H

    28 #include <sqlite3.h>

    29 #include "FileBuf64.h"

    31 #ifdef SQLITE_OS_SYMBIAN

    33 ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

    34 //////////////////////////  TStaticFs  /////////////////////////////////////////////////////////////////////////////////////////

    35 ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

    37 /**

    38 This class encapsulates a RFs object.

    39 Only one RFs object is created per process.

    40 The class has a build dependent implementation:

    41  - a single global static TStaticFs variable is defined for the hardware builds;

    42  - the process local storage (TPls) is used for storing TStaticFs object for the emulator builds;

    44 @see TPls

    46 @internalComponent

    47 */

    48 NONSHARABLE_CLASS(TStaticFs)

    49 	{

    50 public:

    51 	TStaticFs();		//Build dependent implementation

    52 	TInt Connect();

    53 	static RFs& Fs();	//Build dependent implementation

    54 private:

    55 	RFs	iFs;

    56 	};

    58 ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

    59 //////////////////////////  sqlite3_mutex  /////////////////////////////////////////////////////////////////////////////////////

    60 ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

    62 const TInt KStaticMutexCount = SQLITE_MUTEX_STATIC_LRU2 - 1;//"-1": excluding fast and recoursive mutex types

    64 /**

    65 This class describes a mutex object.

    66 SQLite uses three mutex types: static, fast and recursive.

    68 The static mutexes are expected to be created prior first SQLite function call.

    69 The OS porting layer provides build dependent implementation for the static mutextes:

    70  - The static mutexes are defined as global variables for the hardware builds.

    71    The mutex creation is performed in the global variable's constructor.

    72    If the mutex creation fails, the program will be terminated;

    73  - The static mutexes are stored in the process local storage for the emulator builds.

    74    If the mutex creation fails, the program will be terminated;

    76 The difference between fast and recursive mutextes is that the recursive mutexes can be entered mutiple times

    77 by the same thread. The OS porting layer makes no difference between fast and recursive mutexes at the moment.

    78 Whether the SQLite requests fast or ecursive mutex, a recursive mutex will be created.

    79 The recursive mutex creation can fail, in which case the error will be reported back to the caller.

    81 Note that even though sqlite3_mutex has virtual methods, it is not declared as a standard Symbian OS "C" class

    82 because sqlite3_mutex is an abstract type, externally declared and used by SQLite (SQLite is a C library).

    83 SQLite deals only with pointers to sqlite3_mutex objects. See the declaration in sqlite3.h file.

    85 @see TPls

    86 @see CRecursiveMutex

    87 @see TStaticMutex

    89 @internalComponent

    90 */

    91 NONSHARABLE_CLASS(sqlite3_mutex)

    92 	{

    93 public:

    94 	sqlite3_mutex();

    95 	TInt 	Create();

    96 	virtual ~sqlite3_mutex();

    97 	void 	Enter();

    98 	void	Leave();

    99 	TBool	IsHeld() const;

   100 private:

   101 	TInt		iRefCount;

   102 	TThreadId	iOwnerThreadId;

   103 	RMutex		iMutex;

   104 	};

   106 /**

   107 sqlite3_mutex derived class. Describes a recursive mutex.

   108 The mutex creation can fail, the error will be reported back to the caller.

   110 This is not a standard Symbian OS "C" class, not derived from CBase.

   111 CRecursiveMutex is a specialization of the sqlite3_mutex class, used for recursive mutexes.

   113 @see sqlite3_mutex

   115 @internalComponent

   116 */

   117 NONSHARABLE_CLASS(CRecursiveMutex) : public sqlite3_mutex

   118 	{

   119 public:

   120 	static CRecursiveMutex* New();

   121 	virtual ~CRecursiveMutex();

   123 private:

   124 	CRecursiveMutex()

   125 		{

   126 		}

   127 	};

   129 /**

   130 sqlite3_mutex derived class. Describes a static mutex.

   131 If the mutex creation fails, the program will be terminated.

   133 @see sqlite3_mutex

   135 @internalComponent

   136 */

   137 NONSHARABLE_CLASS(TStaticMutex) : public sqlite3_mutex

   138 	{

   139 public:

   140 	TStaticMutex();						//Build dependent implementation

   141 	};

   143 /**

   144 Returns a pointer to already created static mutex.

   145 The function has build dependet implementation:

   146  - The static mutexes are defined as global objects for the hardware builds;

   147  - The static mutexes are stored in th eprocess local storage for the emulator builds;

   149 @see TPls

   150 @see sqlite3_mutex

   152 @param  aType The static mutex type

   153 @return sqlite3_mutex pointer

   155 @panic SqliteMt  6 Process local storage initialization failure (the emulator builds only)

   156 @panic SqliteMt 22 The mutex type is bigger than SQLITE_MUTEX_STATIC_LRU2

   158 @internalComponent

   159 */

   160 sqlite3_mutex* StaticMutex(TInt aType);	//Build dependent implementation

   162 ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

   163 //////////////////////////  TMutexApi  ////////////////////////////////////////////////////////////////////////////////////////

   164 ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

   166 /**

   167 Defines mutex API, that is needed by SQLite.

   169 SQLite creates a mutex using the TMutexApi::Alloc() method.

   170 Depending on aType parameter value, either existing static mutex will be used or a new recursive mutex will be created.

   172 @see TheMutexMethods

   173 @see sqlite3_mutex

   174 @see CRecursiveMutex

   175 @see TStaticMutex

   177 @internalComponent

   178 */

   179 NONSHARABLE_CLASS(TMutexApi)

   180 	{

   181 public:

   182 	static int Init();

   183 	static int End();

   184 	static sqlite3_mutex* Alloc(int aType);

   185 	static void Free(sqlite3_mutex* aMutex);

   186 	static void Enter(sqlite3_mutex* aMutex);

   187 	static int Try(sqlite3_mutex* aMutex);

   188 	static void Leave(sqlite3_mutex* aMutex);

   189 	static int Held(sqlite3_mutex* aMutex);

   190 	static int Notheld(sqlite3_mutex* aMutex);

   191 	};

   193 ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

   194 //////////////////////////  TDbFile  //////////////////////////////////////////////////////////////////////////////////////////

   195 ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

   197 /**

   198 TDbFile derives from the sqlite3_file structure, adding data members needed for processing the SQLite requests to the OS layer.

   199 When SQLite needs an access to a file, SQLite allocates memory for a new TDbFile instance and passes a pointer to that

   200 instance to TVfs::Open(). TVfs::Open() creates/opens the file and initializes the TDbFile instance.

   201 SQLite uses the initialized TDbFile instance (actually SQLite knows and uses the sqlite3_file, the base structure)

   202 every time when needs to read or write from/to the file, using for that an appropriate TFileIo method.

   204 No virtual methods here! sqlite3_file contains data members. If a virtual method is added, that will shift the offset of the

   205 data members from the beginning of the sqlite3_file  object by 4 bytes. This is not what SQLite (C code) expects.

   207 @internalComponent

   209 @see TVfs

   210 @see TFileIo

   211 @see TVfs::Open()

   212 */

   213 NONSHARABLE_STRUCT(TDbFile) : public sqlite3_file

   214 	{

   215 	inline TDbFile();

   216 	RFileBuf64	iFileBuf;

   217 	HBufC*		iFullName;				//Used for the "delete file" operation

   218 	TInt 		iSharedLockByte;

   219 	TInt		iLockType;

   220 	TBool		iReadOnly;

   221 	TInt		iSectorSize;

   222 	TInt		iDeviceCharacteristics;

   223 	};

   225 ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

   226 //////////////////////////  TFileIo  //////////////////////////////////////////////////////////////////////////////////////////

   227 ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

   229 /**

   230 TFileIo class offers static methods for performing operations on a file.

   231 Every TFileIo method has a pointer to a sqlite3_file instance (so, a TDbFile instance) as its first argument.

   233 SQLite never accesses the file system directly, only through function pointers, data members of the sqlite3_io_methods structure.

   234 The OS porting layer defines a single instance of sqlite3_io_methods structure, TheFileIoApi, and uses the TFileIo to initialize the

   235 sqlite3_io_methods data members (function pointers).

   236 Every time when SQLite creates/opens a file using TVfs::Open(), TVfs::Open() will pass back to SQLite a pointer to the single

   237 initialized sqlite3_io_methods instance (TheFileIoApi) that will be used later by SQLite for accessing the file.

   239 @internalComponent

   241 @see TVfs

   242 @see TVfs::Open()

   243 @see TDbFile

   244 */

   245 NONSHARABLE_CLASS(TFileIo)

   246 	{

   247 public:

   248 	static int Close(sqlite3_file* aDbFile);

   249 	static int Read(sqlite3_file* aDbFile, void* aBuf, int aAmt, sqlite3_int64 aOffset);

   250 	static int Write(sqlite3_file* aDbFile, const void* aData, int aAmt, sqlite3_int64 aOffset);

   251 	static int Truncate(sqlite3_file* aDbFile, sqlite3_int64 aLength);

   252 	static int Sync(sqlite3_file* aDbFile, int aFlags);

   253 	static int FileSize(sqlite3_file* aDbFile, sqlite3_int64* aSize);

   254 	static int Lock(sqlite3_file* aDbFile, int aLockType);

   255 	static int Unlock(sqlite3_file* aDbFile, int aLockType);

   256 	static int CheckReservedLock(sqlite3_file* aDbFile, int *aResOut);

   257 	static int FileControl(sqlite3_file* aDbFile, int aOp, void* aArg);

   258 	static int SectorSize(sqlite3_file* aDbFile);

   259 	static int DeviceCharacteristics(sqlite3_file* aDbFile);

   260 private:

   261 	static TInt GetReadLock(TDbFile& aDbFile);

   262 	static TInt UnlockReadLock(TDbFile& aDbFile);

   263 	};

   265 ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

   266 //////////////////////////  TVfs     //////////////////////////////////////////////////////////////////////////////////////////

   267 ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

   269 /**

   270 @return Pointer to the sqlite3_vfs interface

   272 @see TVfs

   274 @panic SqliteMt 7 Process local storage initialization failure (the emulator builds only)

   276 @internalComponent

   277 */

   278 sqlite3_vfs* VfsApi();//Platform dependend implementation

   280 /**

   281 TVfs ("VFS" - virtual file system) class offers methods for creating/openning a file, deleting a file,

   282 a "sleep" method, a "time" method, a "rand" method, etc.

   283 SQLite never accesses the OS API directly, only through the API offered by TVfs and TFileIo classes.

   285 @internalComponent

   287 @see TFileIo

   288 */

   289 NONSHARABLE_CLASS(TVfs)

   290 	{

   291 public:

   292 	static int Open(sqlite3_vfs* aVfs, const char* aFileName, sqlite3_file* aDbFile, int aFlags, int* aOutFlags);

   293 	static int Delete(sqlite3_vfs* aVfs, const char* aFileName, int aSyncDir);

   294 	static int Access(sqlite3_vfs* aVfs, const char* aFileName, int aFlags, int* aResOut);

   295 	static int FullPathName(sqlite3_vfs* aVfs, const char* aRelative, int aBufLen, char* aBuf);

   296 	static int Randomness(sqlite3_vfs* aVfs, int aBufLen, char* aBuf);

   297 	static int Sleep(sqlite3_vfs* aVfs, int aMicrosec);

   298 	static int CurrentTime(sqlite3_vfs* aVfs, double* aNow);

   299 	static int GetLastError(sqlite3_vfs *sVfs, int aBufLen, char* aBuf);

   300 private:

   301 	static inline TInt DoGetVolumeIoParamInfo(RFs& aFs, TInt aDriveNo, TVolumeIOParamInfo& aVolumeInfo);

   302 	static TInt DoGetDeviceCharacteristics(const TDriveInfo& aDriveInfo, const TVolumeIOParamInfo& aVolumeInfo);

   303 	static TInt DoGetSectorSize(const TDriveInfo& aDriveInfo, const TVolumeIOParamInfo& aVolumeInfo);

   304 	static TInt DoGetDeviceCharacteristicsAndSectorSize(TDbFile& aDbFile, TInt& aRecReadBufSize);

   305 	static TInt DoFileSizeCorruptionCheck(TDbFile& aDbFile, const TDesC& aFname, TInt aFmode);

   306 	};

   308 ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

   309 ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

   311 #endif//SQLITE_OS_SYMBIAN

   313 #endif//OS_SYMBIAN_H

author	sl
	Tue, 10 Jun 2014 14:32:02 +0200
changeset 1	260cb5ec6c19
permissions	-rw-r--r--