1 // Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // under the terms of "Eclipse Public License v1.0"

     5 // which accompanies this distribution, and is available

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

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 //

    15 

    16 /**

    17  

    18  Retrieves a reference to the textual description of the error returned by the

    19  most recent call to any of the functions:

    20  - CSqlSrvDatabase::ExecL();

    21  - CSqlSrvStatement::NewLC();

    22  - CSqlSrvStatement::Next();

    23  - CSqlSrvStatement::Reset();

    24  - CSqlSrvStatement::Exec();

    25  

    26  Note that the function can only return a reference to text for

    27  database-specific type errors, i.e. those errors that are categorised as of

    28  type ESqlDbError.

    29  

    30  @return A non-modifiable pointer descriptor representing the most recent error

    31  message. Note that message may be NULL, i.e. the descriptor may have

    32  zero length.

    33  

    34  @see CSqlSrvDatabase::ExecL()

    35  @see CSqlSrvStatement::NewLC()

    36  @see CSqlSrvStatement::Next()

    37  @see CSqlSrvStatement::Reset()

    38  @see CSqlSrvStatement::Exec()

    39 */

    40 inline TPtrC CSqlSrvDatabase::LastErrorMessage() const

    41 	{

    42 	const void* errMsg = sqlite3_errmsg16(iDbHandle);//"errMsg" - zero terminated string

    43 	TPtrC msg(reinterpret_cast <const TUint16*> (errMsg));//terminating zero removed

    44 	return msg;

    45 	}

    46 	

    47 /**

    48 Executes one or more 16-bit SQL statements.

    49 

    50 SQL statements of any kind can be executed, but note the following points:

    51 - the function does not return any records if the SQL statement type is "SELECT".

    52 - if an SQL statement contains one or more parameters, then the function will execute it,

    53 giving the parameters default NULL values.

    54 

    55 If the call to this function fails because of a database-specific type error 

    56 (i.e. the error is categorised as of type ESqlDbError), then a textual description of

    57 the error can be obtained calling CSqlSrvDatabase::LastErrorMessage().

    58 

    59 @param aSqlStmt A zero-terminated string descriptor of 16-bit wide characters containing one or more 

    60                 SQL statements. Each statement is separated by a ';' character.

    61                 Note that the ExecL() call can modify the content of aSqlStmt parameter.

    62 

    63 @leave  KErrNoMemory, an out of memory condition has occured;

    64         KSqlErrGeneral, a syntax error has occurred - text describing the problem

    65                         can be obtained by calling 	CSqlSrvDatabase::LastErrorMessage();

    66         KErrPermissionDenied, the caller does not satisfy the relevant database security policies.

    67                       Note that the function may also leave with some other database specific 

    68                       errors categorised as ESqlDbError, and other system-wide error codes.

    69                       

    70 @see CSqlSrvDatabase::LastErrorMessage()

    71 */

    72 inline void CSqlSrvDatabase::ExecL(TDes16& aSqlStmt)

    73 	{

    74 	__SQLLEAVE_IF_ERROR(::DbExecStmt16(iDbHandle, aSqlStmt));

    75 	}

    76 	

    77 /**

    78 Executes one or more 8-bit SQL statements.

    79 

    80 SQL statements of any kind can be executed, but note the following points:

    81 - the function does not return any records if the SQL statement type is "SELECT".

    82 - if an SQL statement contains one or more parameters, then the function will execute it,

    83 giving the parameters default NULL values.

    84 

    85 If the call to this function fails because of a database-specific type error 

    86 (i.e. the error is categorised as of type ESqlDbError), then a textual description of

    87 the error can be obtained calling CSqlSrvDatabase::LastErrorMessage().

    88 

    89 @param aSqlStmt A zero-terminated string descriptor of 8-bit wide characters containing one or more 

    90                 SQL statements. Each statement is separated by a ';' character.

    91 

    92 @leave  KErrNoMemory, an out of memory condition has occured;

    93         KSqlErrGeneral, a syntax error has occurred - text describing the problem

    94                         can be obtained by calling 	CSqlSrvDatabase::LastErrorMessage();

    95         KErrPermissionDenied, the caller does not satisfy the relevant database security policies.

    96                       Note that the function may also leave with some other database specific 

    97                       errors categorised as ESqlDbError, and other system-wide error codes.

    98                       

    99 @see CSqlSrvDatabase::LastErrorMessage()

   100 */

   101 inline void CSqlSrvDatabase::ExecL(const TDesC8& aSqlStmt)

   102 	{

   103 	__SQLLEAVE_IF_ERROR(::DbExecStmt8(iDbHandle, aSqlStmt));

   104 	}

   105 	

   106 /**

   107 Sets the transaction isolation level for the database.

   108 

   109 A transaction isolation level defines the way in which a transaction

   110 interacts with other transactions that may be in progress concurrently.

   111 

   112 Transaction isolation levels are defined by the values of the

   113 RSqlDatabase::TIsolationLevel enum.

   114 

   115 The default isolation level is RSqlDatabase::ESerializable

   116 

   117 Note that the isolation level is not a persistent property of the database.

   118 It is set to the default value, i.e. RSqlDatabase::ESerializable,

   119 whenever the database is created or opened.

   120 

   121 @param aLevel The isolation level to be set.

   122 

   123 @leave KErrNotSupported, invalid (not supported) transaction isolation level.

   124 						 Current implementation of CSqlSrvDatabase::SetIsolationLevelL()

   125 						 does not support RSqlDatabase::EReadCommitted and RSqlDatabase::ERepeatableRead

   126 						 transaction isolation levels.

   127 */

   128 inline void CSqlSrvDatabase::SetIsolationLevelL(RSqlDatabase::TIsolationLevel aLevel)

   129 	{

   130 	if(aLevel != RSqlDatabase::EReadUncommitted && aLevel != RSqlDatabase::ESerializable)

   131 		{

   132 		__SQLLEAVE(KErrNotSupported);

   133 		}

   134 	iAuthorizerDisabled = ETrue;

   135 	TInt err = ::DbExecStmt8(iDbHandle, aLevel == RSqlDatabase::EReadUncommitted ? KReadUncommittedPragma() : KSerializablePragma());

   136 	iAuthorizerDisabled = EFalse;

   137 	__SQLLEAVE_IF_ERROR(err);

   138 	}

   139 	

   140 /**

   141 @return sqlite3 handle

   142 

   143 @panic SqlDb 7 In _DEBUG mode. iDbHandle is NULL.

   144 */

   145 inline sqlite3* CSqlSrvDatabase::RawDbHandle() const

   146 	{

   147 	__SQLASSERT(iDbHandle != NULL, ESqlPanicInternalError);

   148 	return iDbHandle;	

   149 	}

   150 

   151 /**

   152 @return A pointer to the database security policies object.

   153 

   154 Note that there may be no security policies in force for this database (if it is not a secure database).

   155 

   156 @see CSqlSecurityPolicy

   157 */	

   158 inline const CSqlSecurityPolicy* CSqlSrvDatabase::SecurityPolicy() const

   159 	{

   160 	return iSecurityPolicy;	

   161 	}

   162 

   163 /**

   164 Installs user defined collations.

   165 

   166 At the moment 5 user defined collations with the following names are installed:

   167 - CompareC0 - 16-bit strings collated comaprison at level 0;

   168 - CompareC1 - 16-bit strings collated comaprison at level 1;

   169 - CompareC2 - 16-bit strings collated comaprison at level 2;

   170 - CompareC3 - 16-bit strings collated comaprison at level 3;

   171 - CompareF  - 16-bit strings folded comaprison;

   172 

   173 These user defined collations can be used in the following cases:

   174 

   175 - as column constraint in "CREATE TABLE" SQL statements. For example:

   176 @code

   177   CREATE TABLE A(Col1 TEXT COLLATE CompareC1)

   178 @endcode

   179 In this case every time when Col1 values have to be compared, the SQL server will use CompareC1 collation.

   180 

   181 - as column constraint in "CREATE INDEX" SQL statements. For example:

   182 @code

   183   CREATE INDEX I ON A(Col1 COLLATE CompareC2)

   184 @endcode

   185 In this case SQL server will use CompareC2 collation to compare Col1 values when using the index.

   186 

   187 - In "ORDER BY" clause of "SELECT" SQL statements. For example:

   188 @code

   189   SELECT * FROM A ORDER BY Col1 COLLATE CompareC3

   190 @endcode

   191 In this case SQL server will use CompareC3 collation to compare Col1 values when building the result set.

   192 

   193 This function is part of CSqlSrvDatabase instance initialization.

   194 

   195 @leave The function may leave with some database specific errors categorised as ESqlDbError.

   196 

   197 @see TSqlCollate

   198 @see TSqlCollate::InstallCollationsL()

   199 */

   200 inline void CSqlSrvDatabase::InstallCollationsL()

   201 	{

   202 	TSqlCollationUtil collationUtil(iDbHandle);

   203 	collationUtil.InstallCollationsL();

   204 	}

   205 

   206 /**

   207 Stores the initial settings in the system settings table of a database. 

   208 The initial settings are the specified collation dll name and version 0

   209 of the database configuration file.

   210 The collation dll name is used to uniquely identify the collation 

   211 method which is used by the collation comparison methods: 

   212 TDesC16::CompareC(), TDesC16::MatchC(), TDesC16::FindC().

   213 This function is used when a new database is created.

   214 

   215 @param aCollationDllName Collation dll name. It uniquely identifies the current collation method in use.

   216                          If the default collation method changes later then the database will be reindexed 

   217                          and the new collation dll name will replace the existing one in the settings table.

   218 @param aDbConfigFileVersion Current config file version or KSqlNullDbConfigFileVersion

   219 @param aCompactionMode Database compaction mode, one of TSqlCompactionMode enum item values (except ESqlCompactionNotSet)

   220 

   221 @see TSqlCompactionMode

   222 

   223 @panic SqlDb 4 In _DEBUG mode if aCompactionMode parameter value is invalid.

   224 */

   225 inline void CSqlSrvDatabase::StoreSettingsL(const TDesC& aCollationDllName, TInt aDbConfigFileVersion, TSqlCompactionMode aCompactionMode)

   226 	{

   227 	__SQLASSERT(aCompactionMode == ESqlCompactionManual || aCompactionMode == ESqlCompactionBackground || aCompactionMode == ESqlCompactionAuto, ESqlPanicBadArgument);

   228 #if !defined(__SQL_DISABLE_SYMBIAN_SETTINGS_TABLE__)		

   229 	TSqlDbSysSettings dbSettings(iDbHandle);

   230 	dbSettings.StoreSettingsL(KMainDb16, aCollationDllName, aDbConfigFileVersion, aCompactionMode);

   231 #else

   232 	aCollationDllName.Ptr(); // to avoid compile-time warning

   233 #endif // !(__SQL_DISABLE_SYMBIAN_SETTINGS_TABLE__)		

   234 	}

   235 

   236 /**

   237 This function returns the number of database rows that were updated/inserted/deleted

   238 by the most recently completed INSERT, UPDATE, or DELETE statement.

   239 */

   240 inline TInt CSqlSrvDatabase::LastChangesCount()

   241 	{

   242 	return sqlite3_changes(iDbHandle);

   243 	}

   244 

   245 /**

   246 @return Returns the ROWID of the most recent successful INSERT into the database from this database connection.

   247         If no successful inserts have ever occurred on this database connection, zero is returned.

   248 */

   249 inline TInt64 CSqlSrvDatabase::LastInsertedRowId()

   250 	{

   251 	return sqlite3_last_insert_rowid(iDbHandle);

   252 	}

   253 

   254 //Check that the caller has at least one of {Read, Write, Schema} policies and leave with 

   255 //KErrPermissionDenied if it is not true.

   256 //The "schema" policy check should be evaluated last in order to prevent too many platsec warnings reported in the log files.

   257 //(It is very likely that the caller has either "read", "write" or both database security policies)

   258 inline void CSqlSrvDatabase::BasicSecurityPolicyCheckL(const CSqlSecurityPolicy& aSecurityPolicy)

   259 	{

   260 	MSqlPolicyInspector& inspector = ::SqlServer().SecurityInspector();

   261 	if(!(inspector.Check(aSecurityPolicy.DbPolicy(RSqlSecurityPolicy::EReadPolicy)) ||

   262 	     inspector.Check(aSecurityPolicy.DbPolicy(RSqlSecurityPolicy::EWritePolicy))||

   263 	     inspector.Check(aSecurityPolicy.DbPolicy(RSqlSecurityPolicy::ESchemaPolicy))))

   264 	     	{

   265 	     	__SQLLEAVE(KErrPermissionDenied);		

   266 	     	}

   267 	}

   268 

   269 /**

   270 Current database connection transaction state.

   271 

   272 @return True, the current database connection is in transaction, false otherwise.

   273 */

   274 inline TBool CSqlSrvDatabase::InTransaction() const

   275 	{

   276 	return !sqlite3_get_autocommit(iDbHandle);		

   277 	}

   278