sl@0: // Copyright (c) 2006-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: //
sl@0: 
sl@0: /**
sl@0:  
sl@0:  Retrieves a reference to the textual description of the error returned by the
sl@0:  most recent call to any of the functions:
sl@0:  - CSqlSrvDatabase::ExecL();
sl@0:  - CSqlSrvStatement::NewLC();
sl@0:  - CSqlSrvStatement::Next();
sl@0:  - CSqlSrvStatement::Reset();
sl@0:  - CSqlSrvStatement::Exec();
sl@0:  
sl@0:  Note that the function can only return a reference to text for
sl@0:  database-specific type errors, i.e. those errors that are categorised as of
sl@0:  type ESqlDbError.
sl@0:  
sl@0:  @return A non-modifiable pointer descriptor representing the most recent error
sl@0:  message. Note that message may be NULL, i.e. the descriptor may have
sl@0:  zero length.
sl@0:  
sl@0:  @see CSqlSrvDatabase::ExecL()
sl@0:  @see CSqlSrvStatement::NewLC()
sl@0:  @see CSqlSrvStatement::Next()
sl@0:  @see CSqlSrvStatement::Reset()
sl@0:  @see CSqlSrvStatement::Exec()
sl@0: */
sl@0: inline TPtrC CSqlSrvDatabase::LastErrorMessage() const
sl@0: 	{
sl@0: 	const void* errMsg = sqlite3_errmsg16(iDbHandle);//"errMsg" - zero terminated string
sl@0: 	TPtrC msg(reinterpret_cast <const TUint16*> (errMsg));//terminating zero removed
sl@0: 	return msg;
sl@0: 	}
sl@0: 	
sl@0: /**
sl@0: Executes one or more 16-bit SQL statements.
sl@0: 
sl@0: SQL statements of any kind can be executed, but note the following points:
sl@0: - the function does not return any records if the SQL statement type is "SELECT".
sl@0: - if an SQL statement contains one or more parameters, then the function will execute it,
sl@0: giving the parameters default NULL values.
sl@0: 
sl@0: If the call to this function fails because of a database-specific type error 
sl@0: (i.e. the error is categorised as of type ESqlDbError), then a textual description of
sl@0: the error can be obtained calling CSqlSrvDatabase::LastErrorMessage().
sl@0: 
sl@0: @param aSqlStmt A zero-terminated string descriptor of 16-bit wide characters containing one or more 
sl@0:                 SQL statements. Each statement is separated by a ';' character.
sl@0:                 Note that the ExecL() call can modify the content of aSqlStmt parameter.
sl@0: 
sl@0: @leave  KErrNoMemory, an out of memory condition has occured;
sl@0:         KSqlErrGeneral, a syntax error has occurred - text describing the problem
sl@0:                         can be obtained by calling 	CSqlSrvDatabase::LastErrorMessage();
sl@0:         KErrPermissionDenied, the caller does not satisfy the relevant database security policies.
sl@0:                       Note that the function may also leave with some other database specific 
sl@0:                       errors categorised as ESqlDbError, and other system-wide error codes.
sl@0:                       
sl@0: @see CSqlSrvDatabase::LastErrorMessage()
sl@0: */
sl@0: inline void CSqlSrvDatabase::ExecL(TDes16& aSqlStmt)
sl@0: 	{
sl@0: 	__SQLLEAVE_IF_ERROR(::DbExecStmt16(iDbHandle, aSqlStmt));
sl@0: 	}
sl@0: 	
sl@0: /**
sl@0: Executes one or more 8-bit SQL statements.
sl@0: 
sl@0: SQL statements of any kind can be executed, but note the following points:
sl@0: - the function does not return any records if the SQL statement type is "SELECT".
sl@0: - if an SQL statement contains one or more parameters, then the function will execute it,
sl@0: giving the parameters default NULL values.
sl@0: 
sl@0: If the call to this function fails because of a database-specific type error 
sl@0: (i.e. the error is categorised as of type ESqlDbError), then a textual description of
sl@0: the error can be obtained calling CSqlSrvDatabase::LastErrorMessage().
sl@0: 
sl@0: @param aSqlStmt A zero-terminated string descriptor of 8-bit wide characters containing one or more 
sl@0:                 SQL statements. Each statement is separated by a ';' character.
sl@0: 
sl@0: @leave  KErrNoMemory, an out of memory condition has occured;
sl@0:         KSqlErrGeneral, a syntax error has occurred - text describing the problem
sl@0:                         can be obtained by calling 	CSqlSrvDatabase::LastErrorMessage();
sl@0:         KErrPermissionDenied, the caller does not satisfy the relevant database security policies.
sl@0:                       Note that the function may also leave with some other database specific 
sl@0:                       errors categorised as ESqlDbError, and other system-wide error codes.
sl@0:                       
sl@0: @see CSqlSrvDatabase::LastErrorMessage()
sl@0: */
sl@0: inline void CSqlSrvDatabase::ExecL(const TDesC8& aSqlStmt)
sl@0: 	{
sl@0: 	__SQLLEAVE_IF_ERROR(::DbExecStmt8(iDbHandle, aSqlStmt));
sl@0: 	}
sl@0: 	
sl@0: /**
sl@0: Sets the transaction isolation level for the database.
sl@0: 
sl@0: A transaction isolation level defines the way in which a transaction
sl@0: interacts with other transactions that may be in progress concurrently.
sl@0: 
sl@0: Transaction isolation levels are defined by the values of the
sl@0: RSqlDatabase::TIsolationLevel enum.
sl@0: 
sl@0: The default isolation level is RSqlDatabase::ESerializable
sl@0: 
sl@0: Note that the isolation level is not a persistent property of the database.
sl@0: It is set to the default value, i.e. RSqlDatabase::ESerializable,
sl@0: whenever the database is created or opened.
sl@0: 
sl@0: @param aLevel The isolation level to be set.
sl@0: 
sl@0: @leave KErrNotSupported, invalid (not supported) transaction isolation level.
sl@0: 						 Current implementation of CSqlSrvDatabase::SetIsolationLevelL()
sl@0: 						 does not support RSqlDatabase::EReadCommitted and RSqlDatabase::ERepeatableRead
sl@0: 						 transaction isolation levels.
sl@0: */
sl@0: inline void CSqlSrvDatabase::SetIsolationLevelL(RSqlDatabase::TIsolationLevel aLevel)
sl@0: 	{
sl@0: 	if(aLevel != RSqlDatabase::EReadUncommitted && aLevel != RSqlDatabase::ESerializable)
sl@0: 		{
sl@0: 		__SQLLEAVE(KErrNotSupported);
sl@0: 		}
sl@0: 	iAuthorizerDisabled = ETrue;
sl@0: 	TInt err = ::DbExecStmt8(iDbHandle, aLevel == RSqlDatabase::EReadUncommitted ? KReadUncommittedPragma() : KSerializablePragma());
sl@0: 	iAuthorizerDisabled = EFalse;
sl@0: 	__SQLLEAVE_IF_ERROR(err);
sl@0: 	}
sl@0: 	
sl@0: /**
sl@0: @return sqlite3 handle
sl@0: 
sl@0: @panic SqlDb 7 In _DEBUG mode. iDbHandle is NULL.
sl@0: */
sl@0: inline sqlite3* CSqlSrvDatabase::RawDbHandle() const
sl@0: 	{
sl@0: 	__ASSERT_DEBUG(iDbHandle != NULL, __SQLPANIC(ESqlPanicInternalError));
sl@0: 	return iDbHandle;	
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: @return A pointer to the database security policies object.
sl@0: 
sl@0: Note that there may be no security policies in force for this database (if it is not a secure database).
sl@0: 
sl@0: @see CSqlSecurityPolicy
sl@0: */	
sl@0: inline const CSqlSecurityPolicy* CSqlSrvDatabase::SecurityPolicy() const
sl@0: 	{
sl@0: 	return iSecurityPolicy;	
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: Installs user defined collations.
sl@0: 
sl@0: At the moment 5 user defined collations with the following names are installed:
sl@0: - CompareC0 - 16-bit strings collated comaprison at level 0;
sl@0: - CompareC1 - 16-bit strings collated comaprison at level 1;
sl@0: - CompareC2 - 16-bit strings collated comaprison at level 2;
sl@0: - CompareC3 - 16-bit strings collated comaprison at level 3;
sl@0: - CompareF  - 16-bit strings folded comaprison;
sl@0: 
sl@0: These user defined collations can be used in the following cases:
sl@0: 
sl@0: - as column constraint in "CREATE TABLE" SQL statements. For example:
sl@0: @code
sl@0:   CREATE TABLE A(Col1 TEXT COLLATE CompareC1)
sl@0: @endcode
sl@0: In this case every time when Col1 values have to be compared, the SQL server will use CompareC1 collation.
sl@0: 
sl@0: - as column constraint in "CREATE INDEX" SQL statements. For example:
sl@0: @code
sl@0:   CREATE INDEX I ON A(Col1 COLLATE CompareC2)
sl@0: @endcode
sl@0: In this case SQL server will use CompareC2 collation to compare Col1 values when using the index.
sl@0: 
sl@0: - In "ORDER BY" clause of "SELECT" SQL statements. For example:
sl@0: @code
sl@0:   SELECT * FROM A ORDER BY Col1 COLLATE CompareC3
sl@0: @endcode
sl@0: In this case SQL server will use CompareC3 collation to compare Col1 values when building the result set.
sl@0: 
sl@0: This function is part of CSqlSrvDatabase instance initialization.
sl@0: 
sl@0: @leave The function may leave with some database specific errors categorised as ESqlDbError.
sl@0: 
sl@0: @see TSqlCollate
sl@0: @see TSqlCollate::InstallCollationsL()
sl@0: */
sl@0: inline void CSqlSrvDatabase::InstallCollationsL()
sl@0: 	{
sl@0: 	TSqlCollationUtil collationUtil(iDbHandle);
sl@0: 	collationUtil.InstallCollationsL();
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: Stores the initial settings in the system settings table of a database. 
sl@0: The initial settings are the specified collation dll name and version 0
sl@0: of the database configuration file.
sl@0: The collation dll name is used to uniquely identify the collation 
sl@0: method which is used by the collation comparison methods: 
sl@0: TDesC16::CompareC(), TDesC16::MatchC(), TDesC16::FindC().
sl@0: This function is used when a new database is created.
sl@0: 
sl@0: @param aCollationDllName Collation dll name. It uniquely identifies the current collation method in use.
sl@0:                          If the default collation method changes later then the database will be reindexed 
sl@0:                          and the new collation dll name will replace the existing one in the settings table.
sl@0: @param aDbConfigFileVersion Current config file version or KSqlNullDbConfigFileVersion
sl@0: @param aCompactionMode Database compaction mode, one of TSqlCompactionMode enum item values (except ESqlCompactionNotSet)
sl@0: 
sl@0: @see TSqlCompactionMode
sl@0: 
sl@0: @panic SqlDb 4 In _DEBUG mode if aCompactionMode parameter value is invalid.
sl@0: */
sl@0: inline void CSqlSrvDatabase::StoreSettingsL(const TDesC& aCollationDllName, TInt aDbConfigFileVersion, TSqlCompactionMode aCompactionMode)
sl@0: 	{
sl@0: 	__ASSERT_DEBUG(aCompactionMode == ESqlCompactionManual || aCompactionMode == ESqlCompactionBackground || aCompactionMode == ESqlCompactionAuto, __SQLPANIC(ESqlPanicBadArgument));
sl@0: #if !defined(__SQL_DISABLE_SYMBIAN_SETTINGS_TABLE__)		
sl@0: 	TSqlDbSysSettings dbSettings(iDbHandle);
sl@0: 	dbSettings.StoreSettingsL(KMainDb16, aCollationDllName, aDbConfigFileVersion, aCompactionMode);
sl@0: #else
sl@0: 	aCollationDllName.Ptr(); // to avoid compile-time warning
sl@0: #endif // !(__SQL_DISABLE_SYMBIAN_SETTINGS_TABLE__)		
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: This function returns the number of database rows that were updated/inserted/deleted
sl@0: by the most recently completed INSERT, UPDATE, or DELETE statement.
sl@0: */
sl@0: inline TInt CSqlSrvDatabase::LastChangesCount()
sl@0: 	{
sl@0: 	return sqlite3_changes(iDbHandle);
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: @return Returns the ROWID of the most recent successful INSERT into the database from this database connection.
sl@0:         If no successful inserts have ever occurred on this database connection, zero is returned.
sl@0: */
sl@0: inline TInt64 CSqlSrvDatabase::LastInsertedRowId()
sl@0: 	{
sl@0: 	return sqlite3_last_insert_rowid(iDbHandle);
sl@0: 	}
sl@0: 
sl@0: //Check that the caller has at least one of {Read, Write, Schema} policies and leave with 
sl@0: //KErrPermissionDenied if it is not true.
sl@0: //The "schema" policy check should be evaluated last in order to prevent too many platsec warnings reported in the log files.
sl@0: //(It is very likely that the caller has either "read", "write" or both database security policies)
sl@0: inline void CSqlSrvDatabase::BasicSecurityPolicyCheckL(const CSqlSecurityPolicy& aSecurityPolicy)
sl@0: 	{
sl@0: 	MSqlPolicyInspector& inspector = ::SqlServer().SecurityInspector();
sl@0: 	if(!(inspector.Check(aSecurityPolicy.DbPolicy(RSqlSecurityPolicy::EReadPolicy)) ||
sl@0: 	     inspector.Check(aSecurityPolicy.DbPolicy(RSqlSecurityPolicy::EWritePolicy))||
sl@0: 	     inspector.Check(aSecurityPolicy.DbPolicy(RSqlSecurityPolicy::ESchemaPolicy))))
sl@0: 	     	{
sl@0: 	     	__SQLLEAVE(KErrPermissionDenied);		
sl@0: 	     	}
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: Current database connection transaction state.
sl@0: 
sl@0: @return True, the current database connection is in transaction, false otherwise.
sl@0: */
sl@0: inline TBool CSqlSrvDatabase::InTransaction() const
sl@0: 	{
sl@0: 	return !sqlite3_get_autocommit(iDbHandle);		
sl@0: 	}
sl@0: