1 /**

     2 * Copyright (c) 2008-2009 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 */

    19 

    20 

    21 

    22 /**

    23  @file

    24 */

    25 #ifndef OS_SYMBIAN_H

    26 #define OS_SYMBIAN_H

    27 

    28 #include <sqlite3.h>

    29 #include "FileBuf64.h"

    30 

    31 #ifdef SQLITE_OS_SYMBIAN

    32 

    33 /**

    34 Multi-threaded Symbian OS porting layer panic category.

    35 

    36 @see TPanicCodes

    37 

    38 @internalComponent

    39 */

    40 _LIT(KPanicCategory, "SqliteMt");

    41 

    42 /**

    43 Panic codes - used by asserts in the multi-threaded OS porting layer.

    44 

    45 @see KPanicCategory

    46 

    47 @internalComponent

    48 */

    49 enum TPanicCodes

    50 	{

    51 	EPanicFsCreationError		= 1,

    52 	EPanicMutexCreationError	= 2,

    53 	EPanicInvalidFs				= 3,

    54 	EPanicNullPls1				= 4,

    55 	EPanicNullPls2				= 5,

    56 	EPanicNullPls3				= 6,

    57 	EPanicNullPls4				= 7,

    58 	EPanicAssert				= 8,

    59 	EPanicMaxKeysExceeded		= 9,

    60 	EPanicBufferSizeExceeded	=10,

    61 	EPanicNullKey				=11,

    62 	EPanicWsdBufSize			=12,

    63 	EPanicWsdEntryCount			=13,

    64 	EPanicInternalError			=19,

    65 	EPanicNullDbFilePtr			=20,

    66 	EPanicInvalidLock			=21,

    67 	EPanicInvalidMutexType		=22,

    68 	EPanicMutexLockCounter		=23,

    69 	EPanicMutexOwner			=24

    70 	};

    71 

    72 ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

    73 //////////////////////////  TStaticFs  /////////////////////////////////////////////////////////////////////////////////////////

    74 ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

    75 

    76 /**

    77 This class encapsulates a RFs object. 

    78 Only one RFs object is created per process.

    79 The class has a build dependent implementation:

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

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

    82 

    83 @see TPls

    84 

    85 @internalComponent

    86 */

    87 NONSHARABLE_CLASS(TStaticFs)

    88 	{

    89 public:	

    90 	TStaticFs();		//Build dependent implementation

    91 	TInt Connect();

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

    93 private:

    94 	RFs	iFs;	

    95 	};

    96 

    97 ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

    98 //////////////////////////  sqlite3_mutex  /////////////////////////////////////////////////////////////////////////////////////            

    99 ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

   100 

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

   102 

   103 /**

   104 This class describes a mutex object. 

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

   106 

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

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

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

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

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

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

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

   114 

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

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

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

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

   119 

   120 Note that even though sqlite3_mutex has vritual methods, it is not declared as a "C" class because sqlite3_mutex

   121 is an externally defined type by SQLite.

   122 

   123 @see TPls

   124 @see CRecursiveMutex

   125 @see TStaticMutex

   126 

   127 @internalComponent

   128 */

   129 NONSHARABLE_CLASS(sqlite3_mutex)

   130 	{

   131 public:

   132 	sqlite3_mutex();

   133 	TInt 	Create();

   134 	virtual ~sqlite3_mutex();

   135 	void 	Enter();

   136 	void	Leave();

   137 	TBool	IsHeld() const;

   138 private:	

   139 	TInt		iRefCount;

   140 	TThreadId	iOwnerThreadId;

   141 	RMutex		iMutex;

   142 	};

   143 

   144 /**

   145 sqlite3_mutex derived class. Describes a recursive mutex.

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

   147 

   148 @see sqlite3_mutex

   149 

   150 @internalComponent

   151 */

   152 NONSHARABLE_CLASS(CRecursiveMutex) : public sqlite3_mutex

   153 	{

   154 public:	

   155 	static CRecursiveMutex* New();

   156 	virtual ~CRecursiveMutex();

   157 	

   158 private:

   159 	CRecursiveMutex()

   160 		{

   161 		}

   162 	};

   163 

   164 /**

   165 sqlite3_mutex derived class. Describes a static mutex.

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

   167 

   168 @see sqlite3_mutex

   169 

   170 @internalComponent

   171 */

   172 NONSHARABLE_CLASS(TStaticMutex) : public sqlite3_mutex

   173 	{

   174 public:	

   175 	TStaticMutex();						//Build dependent implementation

   176 	};

   177 	

   178 /**

   179 Returns a pointer to already created static mutex.

   180 The function has build dependet implementation:

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

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

   183  

   184 @see TPls

   185 @see sqlite3_mutex

   186 

   187 @param  aType The static mutex type

   188 @return sqlite3_mutex pointer

   189 

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

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

   192 

   193 @internalComponent

   194 */

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

   196 

   197 ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

   198 //////////////////////////  TMutexApi  ////////////////////////////////////////////////////////////////////////////////////////

   199 ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

   200 

   201 /**

   202 Defines mutex API, that is needed by SQLite.

   203 

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

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

   206 

   207 @see TheMutexMethods

   208 @see sqlite3_mutex

   209 @see CRecursiveMutex

   210 @see TStaticMutex

   211 

   212 @internalComponent

   213 */

   214 NONSHARABLE_CLASS(TMutexApi)

   215 	{

   216 public:		

   217 	static int Init();

   218 	static int End();

   219 	static sqlite3_mutex* Alloc(int aType);

   220 	static void Free(sqlite3_mutex* aMutex);

   221 	static void Enter(sqlite3_mutex* aMutex);

   222 	static int Try(sqlite3_mutex* aMutex);

   223 	static void Leave(sqlite3_mutex* aMutex);

   224 	static int Held(sqlite3_mutex* aMutex);

   225 	static int Notheld(sqlite3_mutex* aMutex);

   226 	};

   227 

   228 ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

   229 //////////////////////////  TDbFile  //////////////////////////////////////////////////////////////////////////////////////////

   230 ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

   231 

   232 /**

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

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

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

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

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

   238 

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

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

   241 

   242 @internalComponent

   243 

   244 @see TVfs

   245 @see TFileIo

   246 @see TVfs::Open()

   247 */

   248 NONSHARABLE_STRUCT(TDbFile) : public sqlite3_file 

   249 	{

   250 	inline TDbFile();

   251 	RFileBuf64	iFileBuf;

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

   253 	TInt 		iSharedLockByte;

   254 	TInt		iLockType;

   255 	TBool		iReadOnly;

   256 	TInt		iSectorSize;

   257 	TInt		iDeviceCharacteristics;

   258 	};

   259 

   260 ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

   261 //////////////////////////  TFileIo  //////////////////////////////////////////////////////////////////////////////////////////

   262 ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

   263 

   264 /**

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

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

   267 

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

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

   270 sqlite3_io_methods data members (function pointers).

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

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

   273 

   274 @internalComponent

   275 

   276 @see TVfs

   277 @see TVfs::Open()

   278 @see TDbFile

   279 */

   280 NONSHARABLE_CLASS(TFileIo)

   281 	{

   282 public:	

   283 	static int Close(sqlite3_file* aDbFile);

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

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

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

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

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

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

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

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

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

   293 	static int SectorSize(sqlite3_file* aDbFile);

   294 	static int DeviceCharacteristics(sqlite3_file* aDbFile);

   295 private:

   296 	static TInt GetReadLock(TDbFile& aDbFile);	

   297 	static TInt UnlockReadLock(TDbFile& aDbFile);	

   298 	};

   299 

   300 ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

   301 //////////////////////////  TVfs     //////////////////////////////////////////////////////////////////////////////////////////

   302 ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

   303 

   304 /**

   305 @return Pointer to the sqlite3_vfs interface

   306 

   307 @see TVfs

   308 

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

   310 

   311 @internalComponent

   312 */

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

   314 

   315 /**

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

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

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

   319 

   320 @internalComponent

   321 

   322 @see TFileIo

   323 */

   324 NONSHARABLE_CLASS(TVfs)

   325 	{

   326 public:		

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

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

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

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

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

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

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

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

   335 private:

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

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

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

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

   340 	};

   341 	

   342 ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

   343 ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

   344 

   345 #endif//SQLITE_OS_SYMBIAN

   346 

   347 #endif//OS_SYMBIAN_H