sl@0: /**
sl@0: * Copyright (c) 2008-2010 Nokia Corporation and/or its subsidiary(-ies).
sl@0: * All rights reserved.
sl@0: * This component and the accompanying materials are made available
sl@0: * under the terms of "Eclipse Public License v1.0"
sl@0: * which accompanies this distribution, and is available
sl@0: * at the URL "http://www.eclipse.org/legal/epl-v10.html".
sl@0: *
sl@0: * Initial Contributors:
sl@0: * Nokia Corporation - initial contribution.
sl@0: *
sl@0: * Contributors:
sl@0: *
sl@0: * Description:
sl@0: * Declarations for the multi-threaded Symbian OS porting layer.
sl@0: * 
sl@0: *
sl@0: */
sl@0: 
sl@0: 
sl@0: 
sl@0: /**
sl@0:  @file
sl@0: */
sl@0: #ifndef OS_SYMBIAN_H
sl@0: #define OS_SYMBIAN_H
sl@0: 
sl@0: #include <sqlite3.h>
sl@0: #include "FileBuf64.h"
sl@0: 
sl@0: #ifdef SQLITE_OS_SYMBIAN
sl@0: 
sl@0: ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
sl@0: //////////////////////////  TStaticFs  /////////////////////////////////////////////////////////////////////////////////////////
sl@0: ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
sl@0: 
sl@0: /**
sl@0: This class encapsulates a RFs object. 
sl@0: Only one RFs object is created per process.
sl@0: The class has a build dependent implementation:
sl@0:  - a single global static TStaticFs variable is defined for the hardware builds;
sl@0:  - the process local storage (TPls) is used for storing TStaticFs object for the emulator builds;
sl@0: 
sl@0: @see TPls
sl@0: 
sl@0: @internalComponent
sl@0: */
sl@0: NONSHARABLE_CLASS(TStaticFs)
sl@0: 	{
sl@0: public:	
sl@0: 	TStaticFs();		//Build dependent implementation
sl@0: 	TInt Connect();
sl@0: 	static RFs& Fs();	//Build dependent implementation
sl@0: private:
sl@0: 	RFs	iFs;	
sl@0: 	};
sl@0: 
sl@0: ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
sl@0: //////////////////////////  sqlite3_mutex  /////////////////////////////////////////////////////////////////////////////////////            
sl@0: ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
sl@0: 
sl@0: const TInt KStaticMutexCount = SQLITE_MUTEX_STATIC_LRU2 - 1;//"-1": excluding fast and recoursive mutex types
sl@0: 
sl@0: /**
sl@0: This class describes a mutex object. 
sl@0: SQLite uses three mutex types: static, fast and recursive.
sl@0: 
sl@0: The static mutexes are expected to be created prior first SQLite function call.
sl@0: The OS porting layer provides build dependent implementation for the static mutextes:
sl@0:  - The static mutexes are defined as global variables for the hardware builds.
sl@0:    The mutex creation is performed in the global variable's constructor. 
sl@0:    If the mutex creation fails, the program will be terminated;
sl@0:  - The static mutexes are stored in the process local storage for the emulator builds.
sl@0:    If the mutex creation fails, the program will be terminated;
sl@0: 
sl@0: The difference between fast and recursive mutextes is that the recursive mutexes can be entered mutiple times
sl@0: by the same thread. The OS porting layer makes no difference between fast and recursive mutexes at the moment.
sl@0: Whether the SQLite requests fast or ecursive mutex, a recursive mutex will be created.
sl@0: The recursive mutex creation can fail, in which case the error will be reported back to the caller.
sl@0: 
sl@0: Note that even though sqlite3_mutex has virtual methods, it is not declared as a standard Symbian OS "C" class 
sl@0: because sqlite3_mutex is an abstract type, externally declared and used by SQLite (SQLite is a C library).
sl@0: SQLite deals only with pointers to sqlite3_mutex objects. See the declaration in sqlite3.h file. 
sl@0: 
sl@0: @see TPls
sl@0: @see CRecursiveMutex
sl@0: @see TStaticMutex
sl@0: 
sl@0: @internalComponent
sl@0: */
sl@0: NONSHARABLE_CLASS(sqlite3_mutex)
sl@0: 	{
sl@0: public:
sl@0: 	sqlite3_mutex();
sl@0: 	TInt 	Create();
sl@0: 	virtual ~sqlite3_mutex();
sl@0: 	void 	Enter();
sl@0: 	void	Leave();
sl@0: 	TBool	IsHeld() const;
sl@0: private:	
sl@0: 	TInt		iRefCount;
sl@0: 	TThreadId	iOwnerThreadId;
sl@0: 	RMutex		iMutex;
sl@0: 	};
sl@0: 
sl@0: /**
sl@0: sqlite3_mutex derived class. Describes a recursive mutex.
sl@0: The mutex creation can fail, the error will be reported back to the caller.
sl@0: 
sl@0: This is not a standard Symbian OS "C" class, not derived from CBase.
sl@0: CRecursiveMutex is a specialization of the sqlite3_mutex class, used for recursive mutexes. 
sl@0: 
sl@0: @see sqlite3_mutex
sl@0: 
sl@0: @internalComponent
sl@0: */
sl@0: NONSHARABLE_CLASS(CRecursiveMutex) : public sqlite3_mutex
sl@0: 	{
sl@0: public:	
sl@0: 	static CRecursiveMutex* New();
sl@0: 	virtual ~CRecursiveMutex();
sl@0: 	
sl@0: private:
sl@0: 	CRecursiveMutex()
sl@0: 		{
sl@0: 		}
sl@0: 	};
sl@0: 
sl@0: /**
sl@0: sqlite3_mutex derived class. Describes a static mutex.
sl@0: If the mutex creation fails, the program will be terminated.
sl@0: 
sl@0: @see sqlite3_mutex
sl@0: 
sl@0: @internalComponent
sl@0: */
sl@0: NONSHARABLE_CLASS(TStaticMutex) : public sqlite3_mutex
sl@0: 	{
sl@0: public:	
sl@0: 	TStaticMutex();						//Build dependent implementation
sl@0: 	};
sl@0: 	
sl@0: /**
sl@0: Returns a pointer to already created static mutex.
sl@0: The function has build dependet implementation:
sl@0:  - The static mutexes are defined as global objects for the hardware builds;
sl@0:  - The static mutexes are stored in th eprocess local storage for the emulator builds;
sl@0:  
sl@0: @see TPls
sl@0: @see sqlite3_mutex
sl@0: 
sl@0: @param  aType The static mutex type
sl@0: @return sqlite3_mutex pointer
sl@0: 
sl@0: @panic SqliteMt  6 Process local storage initialization failure (the emulator builds only)
sl@0: @panic SqliteMt 22 The mutex type is bigger than SQLITE_MUTEX_STATIC_LRU2
sl@0: 
sl@0: @internalComponent
sl@0: */
sl@0: sqlite3_mutex* StaticMutex(TInt aType);	//Build dependent implementation
sl@0: 
sl@0: ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
sl@0: //////////////////////////  TMutexApi  ////////////////////////////////////////////////////////////////////////////////////////
sl@0: ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
sl@0: 
sl@0: /**
sl@0: Defines mutex API, that is needed by SQLite.
sl@0: 
sl@0: SQLite creates a mutex using the TMutexApi::Alloc() method.
sl@0: Depending on aType parameter value, either existing static mutex will be used or a new recursive mutex will be created.
sl@0: 
sl@0: @see TheMutexMethods
sl@0: @see sqlite3_mutex
sl@0: @see CRecursiveMutex
sl@0: @see TStaticMutex
sl@0: 
sl@0: @internalComponent
sl@0: */
sl@0: NONSHARABLE_CLASS(TMutexApi)
sl@0: 	{
sl@0: public:		
sl@0: 	static int Init();
sl@0: 	static int End();
sl@0: 	static sqlite3_mutex* Alloc(int aType);
sl@0: 	static void Free(sqlite3_mutex* aMutex);
sl@0: 	static void Enter(sqlite3_mutex* aMutex);
sl@0: 	static int Try(sqlite3_mutex* aMutex);
sl@0: 	static void Leave(sqlite3_mutex* aMutex);
sl@0: 	static int Held(sqlite3_mutex* aMutex);
sl@0: 	static int Notheld(sqlite3_mutex* aMutex);
sl@0: 	};
sl@0: 
sl@0: ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
sl@0: //////////////////////////  TDbFile  //////////////////////////////////////////////////////////////////////////////////////////
sl@0: ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
sl@0: 
sl@0: /**
sl@0: TDbFile derives from the sqlite3_file structure, adding data members needed for processing the SQLite requests to the OS layer.
sl@0: When SQLite needs an access to a file, SQLite allocates memory for a new TDbFile instance and passes a pointer to that 
sl@0: instance to TVfs::Open(). TVfs::Open() creates/opens the file and initializes the TDbFile instance. 
sl@0: SQLite uses the initialized TDbFile instance (actually SQLite knows and uses the sqlite3_file, the base structure) 
sl@0: every time when needs to read or write from/to the file, using for that an appropriate TFileIo method.
sl@0: 
sl@0: No virtual methods here! sqlite3_file contains data members. If a virtual method is added, that will shift the offset of the
sl@0: data members from the beginning of the sqlite3_file  object by 4 bytes. This is not what SQLite (C code) expects.
sl@0: 
sl@0: @internalComponent
sl@0: 
sl@0: @see TVfs
sl@0: @see TFileIo
sl@0: @see TVfs::Open()
sl@0: */
sl@0: NONSHARABLE_STRUCT(TDbFile) : public sqlite3_file 
sl@0: 	{
sl@0: 	inline TDbFile();
sl@0: 	RFileBuf64	iFileBuf;
sl@0: 	HBufC*		iFullName;				//Used for the "delete file" operation
sl@0: 	TInt 		iSharedLockByte;
sl@0: 	TInt		iLockType;
sl@0: 	TBool		iReadOnly;
sl@0: 	TInt		iSectorSize;
sl@0: 	TInt		iDeviceCharacteristics;
sl@0: 	};
sl@0: 
sl@0: ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
sl@0: //////////////////////////  TFileIo  //////////////////////////////////////////////////////////////////////////////////////////
sl@0: ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
sl@0: 
sl@0: /**
sl@0: TFileIo class offers static methods for performing operations on a file.
sl@0: Every TFileIo method has a pointer to a sqlite3_file instance (so, a TDbFile instance) as its first argument.
sl@0: 
sl@0: SQLite never accesses the file system directly, only through function pointers, data members of the sqlite3_io_methods structure.
sl@0: The OS porting layer defines a single instance of sqlite3_io_methods structure, TheFileIoApi, and uses the TFileIo to initialize the 
sl@0: sqlite3_io_methods data members (function pointers).
sl@0: Every time when SQLite creates/opens a file using TVfs::Open(), TVfs::Open() will pass back to SQLite a pointer to the single
sl@0: initialized sqlite3_io_methods instance (TheFileIoApi) that will be used later by SQLite for accessing the file.
sl@0: 
sl@0: @internalComponent
sl@0: 
sl@0: @see TVfs
sl@0: @see TVfs::Open()
sl@0: @see TDbFile
sl@0: */
sl@0: NONSHARABLE_CLASS(TFileIo)
sl@0: 	{
sl@0: public:	
sl@0: 	static int Close(sqlite3_file* aDbFile);
sl@0: 	static int Read(sqlite3_file* aDbFile, void* aBuf, int aAmt, sqlite3_int64 aOffset);
sl@0: 	static int Write(sqlite3_file* aDbFile, const void* aData, int aAmt, sqlite3_int64 aOffset);
sl@0: 	static int Truncate(sqlite3_file* aDbFile, sqlite3_int64 aLength);
sl@0: 	static int Sync(sqlite3_file* aDbFile, int aFlags);
sl@0: 	static int FileSize(sqlite3_file* aDbFile, sqlite3_int64* aSize);
sl@0: 	static int Lock(sqlite3_file* aDbFile, int aLockType);
sl@0: 	static int Unlock(sqlite3_file* aDbFile, int aLockType);
sl@0: 	static int CheckReservedLock(sqlite3_file* aDbFile, int *aResOut);
sl@0: 	static int FileControl(sqlite3_file* aDbFile, int aOp, void* aArg);
sl@0: 	static int SectorSize(sqlite3_file* aDbFile);
sl@0: 	static int DeviceCharacteristics(sqlite3_file* aDbFile);
sl@0: private:
sl@0: 	static TInt GetReadLock(TDbFile& aDbFile);	
sl@0: 	static TInt UnlockReadLock(TDbFile& aDbFile);	
sl@0: 	};
sl@0: 
sl@0: ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
sl@0: //////////////////////////  TVfs     //////////////////////////////////////////////////////////////////////////////////////////
sl@0: ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
sl@0: 
sl@0: /**
sl@0: @return Pointer to the sqlite3_vfs interface
sl@0: 
sl@0: @see TVfs
sl@0: 
sl@0: @panic SqliteMt 7 Process local storage initialization failure (the emulator builds only)
sl@0: 
sl@0: @internalComponent
sl@0: */
sl@0: sqlite3_vfs* VfsApi();//Platform dependend implementation
sl@0: 
sl@0: /**
sl@0: TVfs ("VFS" - virtual file system) class offers methods for creating/openning a file, deleting a file,
sl@0: a "sleep" method, a "time" method, a "rand" method, etc.
sl@0: SQLite never accesses the OS API directly, only through the API offered by TVfs and TFileIo classes.
sl@0: 
sl@0: @internalComponent
sl@0: 
sl@0: @see TFileIo
sl@0: */
sl@0: NONSHARABLE_CLASS(TVfs)
sl@0: 	{
sl@0: public:		
sl@0: 	static int Open(sqlite3_vfs* aVfs, const char* aFileName, sqlite3_file* aDbFile, int aFlags, int* aOutFlags);
sl@0: 	static int Delete(sqlite3_vfs* aVfs, const char* aFileName, int aSyncDir);	
sl@0: 	static int Access(sqlite3_vfs* aVfs, const char* aFileName, int aFlags, int* aResOut);
sl@0: 	static int FullPathName(sqlite3_vfs* aVfs, const char* aRelative, int aBufLen, char* aBuf);
sl@0: 	static int Randomness(sqlite3_vfs* aVfs, int aBufLen, char* aBuf);
sl@0: 	static int Sleep(sqlite3_vfs* aVfs, int aMicrosec);
sl@0: 	static int CurrentTime(sqlite3_vfs* aVfs, double* aNow);
sl@0: 	static int GetLastError(sqlite3_vfs *sVfs, int aBufLen, char* aBuf);
sl@0: private:
sl@0: 	static inline TInt DoGetVolumeIoParamInfo(RFs& aFs, TInt aDriveNo, TVolumeIOParamInfo& aVolumeInfo);
sl@0: 	static TInt DoGetDeviceCharacteristics(const TDriveInfo& aDriveInfo, const TVolumeIOParamInfo& aVolumeInfo);
sl@0: 	static TInt DoGetSectorSize(const TDriveInfo& aDriveInfo, const TVolumeIOParamInfo& aVolumeInfo);
sl@0: 	static TInt DoGetDeviceCharacteristicsAndSectorSize(TDbFile& aDbFile, TInt& aRecReadBufSize);
sl@0: 	static TInt DoFileSizeCorruptionCheck(TDbFile& aDbFile, const TDesC& aFname, TInt aFmode);
sl@0: 	};
sl@0: 	
sl@0: ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
sl@0: ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
sl@0: 
sl@0: #endif//SQLITE_OS_SYMBIAN
sl@0: 
sl@0: #endif//OS_SYMBIAN_H