1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/persistentdata/persistentstorage/sql/SRC/Server/SqlSrvDatabase.inl Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,278 @@
1.4 +// Copyright (c) 2006-2010 Nokia Corporation and/or its subsidiary(-ies).
1.5 +// All rights reserved.
1.6 +// This component and the accompanying materials are made available
1.7 +// under the terms of "Eclipse Public License v1.0"
1.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +//
1.18 +
1.19 +/**
1.20 +
1.21 + Retrieves a reference to the textual description of the error returned by the
1.22 + most recent call to any of the functions:
1.23 + - CSqlSrvDatabase::ExecL();
1.24 + - CSqlSrvStatement::NewLC();
1.25 + - CSqlSrvStatement::Next();
1.26 + - CSqlSrvStatement::Reset();
1.27 + - CSqlSrvStatement::Exec();
1.28 +
1.29 + Note that the function can only return a reference to text for
1.30 + database-specific type errors, i.e. those errors that are categorised as of
1.31 + type ESqlDbError.
1.32 +
1.33 + @return A non-modifiable pointer descriptor representing the most recent error
1.34 + message. Note that message may be NULL, i.e. the descriptor may have
1.35 + zero length.
1.36 +
1.37 + @see CSqlSrvDatabase::ExecL()
1.38 + @see CSqlSrvStatement::NewLC()
1.39 + @see CSqlSrvStatement::Next()
1.40 + @see CSqlSrvStatement::Reset()
1.41 + @see CSqlSrvStatement::Exec()
1.42 +*/
1.43 +inline TPtrC CSqlSrvDatabase::LastErrorMessage() const
1.44 + {
1.45 + const void* errMsg = sqlite3_errmsg16(iDbHandle);//"errMsg" - zero terminated string
1.46 + TPtrC msg(reinterpret_cast <const TUint16*> (errMsg));//terminating zero removed
1.47 + return msg;
1.48 + }
1.49 +
1.50 +/**
1.51 +Executes one or more 16-bit SQL statements.
1.52 +
1.53 +SQL statements of any kind can be executed, but note the following points:
1.54 +- the function does not return any records if the SQL statement type is "SELECT".
1.55 +- if an SQL statement contains one or more parameters, then the function will execute it,
1.56 +giving the parameters default NULL values.
1.57 +
1.58 +If the call to this function fails because of a database-specific type error
1.59 +(i.e. the error is categorised as of type ESqlDbError), then a textual description of
1.60 +the error can be obtained calling CSqlSrvDatabase::LastErrorMessage().
1.61 +
1.62 +@param aSqlStmt A zero-terminated string descriptor of 16-bit wide characters containing one or more
1.63 + SQL statements. Each statement is separated by a ';' character.
1.64 + Note that the ExecL() call can modify the content of aSqlStmt parameter.
1.65 +
1.66 +@leave KErrNoMemory, an out of memory condition has occured;
1.67 + KSqlErrGeneral, a syntax error has occurred - text describing the problem
1.68 + can be obtained by calling CSqlSrvDatabase::LastErrorMessage();
1.69 + KErrPermissionDenied, the caller does not satisfy the relevant database security policies.
1.70 + Note that the function may also leave with some other database specific
1.71 + errors categorised as ESqlDbError, and other system-wide error codes.
1.72 +
1.73 +@see CSqlSrvDatabase::LastErrorMessage()
1.74 +*/
1.75 +inline void CSqlSrvDatabase::ExecL(TDes16& aSqlStmt)
1.76 + {
1.77 + __SQLLEAVE_IF_ERROR(::DbExecStmt16(iDbHandle, aSqlStmt));
1.78 + }
1.79 +
1.80 +/**
1.81 +Executes one or more 8-bit SQL statements.
1.82 +
1.83 +SQL statements of any kind can be executed, but note the following points:
1.84 +- the function does not return any records if the SQL statement type is "SELECT".
1.85 +- if an SQL statement contains one or more parameters, then the function will execute it,
1.86 +giving the parameters default NULL values.
1.87 +
1.88 +If the call to this function fails because of a database-specific type error
1.89 +(i.e. the error is categorised as of type ESqlDbError), then a textual description of
1.90 +the error can be obtained calling CSqlSrvDatabase::LastErrorMessage().
1.91 +
1.92 +@param aSqlStmt A zero-terminated string descriptor of 8-bit wide characters containing one or more
1.93 + SQL statements. Each statement is separated by a ';' character.
1.94 +
1.95 +@leave KErrNoMemory, an out of memory condition has occured;
1.96 + KSqlErrGeneral, a syntax error has occurred - text describing the problem
1.97 + can be obtained by calling CSqlSrvDatabase::LastErrorMessage();
1.98 + KErrPermissionDenied, the caller does not satisfy the relevant database security policies.
1.99 + Note that the function may also leave with some other database specific
1.100 + errors categorised as ESqlDbError, and other system-wide error codes.
1.101 +
1.102 +@see CSqlSrvDatabase::LastErrorMessage()
1.103 +*/
1.104 +inline void CSqlSrvDatabase::ExecL(const TDesC8& aSqlStmt)
1.105 + {
1.106 + __SQLLEAVE_IF_ERROR(::DbExecStmt8(iDbHandle, aSqlStmt));
1.107 + }
1.108 +
1.109 +/**
1.110 +Sets the transaction isolation level for the database.
1.111 +
1.112 +A transaction isolation level defines the way in which a transaction
1.113 +interacts with other transactions that may be in progress concurrently.
1.114 +
1.115 +Transaction isolation levels are defined by the values of the
1.116 +RSqlDatabase::TIsolationLevel enum.
1.117 +
1.118 +The default isolation level is RSqlDatabase::ESerializable
1.119 +
1.120 +Note that the isolation level is not a persistent property of the database.
1.121 +It is set to the default value, i.e. RSqlDatabase::ESerializable,
1.122 +whenever the database is created or opened.
1.123 +
1.124 +@param aLevel The isolation level to be set.
1.125 +
1.126 +@leave KErrNotSupported, invalid (not supported) transaction isolation level.
1.127 + Current implementation of CSqlSrvDatabase::SetIsolationLevelL()
1.128 + does not support RSqlDatabase::EReadCommitted and RSqlDatabase::ERepeatableRead
1.129 + transaction isolation levels.
1.130 +*/
1.131 +inline void CSqlSrvDatabase::SetIsolationLevelL(RSqlDatabase::TIsolationLevel aLevel)
1.132 + {
1.133 + if(aLevel != RSqlDatabase::EReadUncommitted && aLevel != RSqlDatabase::ESerializable)
1.134 + {
1.135 + __SQLLEAVE(KErrNotSupported);
1.136 + }
1.137 + iAuthorizerDisabled = ETrue;
1.138 + TInt err = ::DbExecStmt8(iDbHandle, aLevel == RSqlDatabase::EReadUncommitted ? KReadUncommittedPragma() : KSerializablePragma());
1.139 + iAuthorizerDisabled = EFalse;
1.140 + __SQLLEAVE_IF_ERROR(err);
1.141 + }
1.142 +
1.143 +/**
1.144 +@return sqlite3 handle
1.145 +
1.146 +@panic SqlDb 7 In _DEBUG mode. iDbHandle is NULL.
1.147 +*/
1.148 +inline sqlite3* CSqlSrvDatabase::RawDbHandle() const
1.149 + {
1.150 + __ASSERT_DEBUG(iDbHandle != NULL, __SQLPANIC(ESqlPanicInternalError));
1.151 + return iDbHandle;
1.152 + }
1.153 +
1.154 +/**
1.155 +@return A pointer to the database security policies object.
1.156 +
1.157 +Note that there may be no security policies in force for this database (if it is not a secure database).
1.158 +
1.159 +@see CSqlSecurityPolicy
1.160 +*/
1.161 +inline const CSqlSecurityPolicy* CSqlSrvDatabase::SecurityPolicy() const
1.162 + {
1.163 + return iSecurityPolicy;
1.164 + }
1.165 +
1.166 +/**
1.167 +Installs user defined collations.
1.168 +
1.169 +At the moment 5 user defined collations with the following names are installed:
1.170 +- CompareC0 - 16-bit strings collated comaprison at level 0;
1.171 +- CompareC1 - 16-bit strings collated comaprison at level 1;
1.172 +- CompareC2 - 16-bit strings collated comaprison at level 2;
1.173 +- CompareC3 - 16-bit strings collated comaprison at level 3;
1.174 +- CompareF - 16-bit strings folded comaprison;
1.175 +
1.176 +These user defined collations can be used in the following cases:
1.177 +
1.178 +- as column constraint in "CREATE TABLE" SQL statements. For example:
1.179 +@code
1.180 + CREATE TABLE A(Col1 TEXT COLLATE CompareC1)
1.181 +@endcode
1.182 +In this case every time when Col1 values have to be compared, the SQL server will use CompareC1 collation.
1.183 +
1.184 +- as column constraint in "CREATE INDEX" SQL statements. For example:
1.185 +@code
1.186 + CREATE INDEX I ON A(Col1 COLLATE CompareC2)
1.187 +@endcode
1.188 +In this case SQL server will use CompareC2 collation to compare Col1 values when using the index.
1.189 +
1.190 +- In "ORDER BY" clause of "SELECT" SQL statements. For example:
1.191 +@code
1.192 + SELECT * FROM A ORDER BY Col1 COLLATE CompareC3
1.193 +@endcode
1.194 +In this case SQL server will use CompareC3 collation to compare Col1 values when building the result set.
1.195 +
1.196 +This function is part of CSqlSrvDatabase instance initialization.
1.197 +
1.198 +@leave The function may leave with some database specific errors categorised as ESqlDbError.
1.199 +
1.200 +@see TSqlCollate
1.201 +@see TSqlCollate::InstallCollationsL()
1.202 +*/
1.203 +inline void CSqlSrvDatabase::InstallCollationsL()
1.204 + {
1.205 + TSqlCollationUtil collationUtil(iDbHandle);
1.206 + collationUtil.InstallCollationsL();
1.207 + }
1.208 +
1.209 +/**
1.210 +Stores the initial settings in the system settings table of a database.
1.211 +The initial settings are the specified collation dll name and version 0
1.212 +of the database configuration file.
1.213 +The collation dll name is used to uniquely identify the collation
1.214 +method which is used by the collation comparison methods:
1.215 +TDesC16::CompareC(), TDesC16::MatchC(), TDesC16::FindC().
1.216 +This function is used when a new database is created.
1.217 +
1.218 +@param aCollationDllName Collation dll name. It uniquely identifies the current collation method in use.
1.219 + If the default collation method changes later then the database will be reindexed
1.220 + and the new collation dll name will replace the existing one in the settings table.
1.221 +@param aDbConfigFileVersion Current config file version or KSqlNullDbConfigFileVersion
1.222 +@param aCompactionMode Database compaction mode, one of TSqlCompactionMode enum item values (except ESqlCompactionNotSet)
1.223 +
1.224 +@see TSqlCompactionMode
1.225 +
1.226 +@panic SqlDb 4 In _DEBUG mode if aCompactionMode parameter value is invalid.
1.227 +*/
1.228 +inline void CSqlSrvDatabase::StoreSettingsL(const TDesC& aCollationDllName, TInt aDbConfigFileVersion, TSqlCompactionMode aCompactionMode)
1.229 + {
1.230 + __ASSERT_DEBUG(aCompactionMode == ESqlCompactionManual || aCompactionMode == ESqlCompactionBackground || aCompactionMode == ESqlCompactionAuto, __SQLPANIC(ESqlPanicBadArgument));
1.231 +#if !defined(__SQL_DISABLE_SYMBIAN_SETTINGS_TABLE__)
1.232 + TSqlDbSysSettings dbSettings(iDbHandle);
1.233 + dbSettings.StoreSettingsL(KMainDb16, aCollationDllName, aDbConfigFileVersion, aCompactionMode);
1.234 +#else
1.235 + aCollationDllName.Ptr(); // to avoid compile-time warning
1.236 +#endif // !(__SQL_DISABLE_SYMBIAN_SETTINGS_TABLE__)
1.237 + }
1.238 +
1.239 +/**
1.240 +This function returns the number of database rows that were updated/inserted/deleted
1.241 +by the most recently completed INSERT, UPDATE, or DELETE statement.
1.242 +*/
1.243 +inline TInt CSqlSrvDatabase::LastChangesCount()
1.244 + {
1.245 + return sqlite3_changes(iDbHandle);
1.246 + }
1.247 +
1.248 +/**
1.249 +@return Returns the ROWID of the most recent successful INSERT into the database from this database connection.
1.250 + If no successful inserts have ever occurred on this database connection, zero is returned.
1.251 +*/
1.252 +inline TInt64 CSqlSrvDatabase::LastInsertedRowId()
1.253 + {
1.254 + return sqlite3_last_insert_rowid(iDbHandle);
1.255 + }
1.256 +
1.257 +//Check that the caller has at least one of {Read, Write, Schema} policies and leave with
1.258 +//KErrPermissionDenied if it is not true.
1.259 +//The "schema" policy check should be evaluated last in order to prevent too many platsec warnings reported in the log files.
1.260 +//(It is very likely that the caller has either "read", "write" or both database security policies)
1.261 +inline void CSqlSrvDatabase::BasicSecurityPolicyCheckL(const CSqlSecurityPolicy& aSecurityPolicy)
1.262 + {
1.263 + MSqlPolicyInspector& inspector = ::SqlServer().SecurityInspector();
1.264 + if(!(inspector.Check(aSecurityPolicy.DbPolicy(RSqlSecurityPolicy::EReadPolicy)) ||
1.265 + inspector.Check(aSecurityPolicy.DbPolicy(RSqlSecurityPolicy::EWritePolicy))||
1.266 + inspector.Check(aSecurityPolicy.DbPolicy(RSqlSecurityPolicy::ESchemaPolicy))))
1.267 + {
1.268 + __SQLLEAVE(KErrPermissionDenied);
1.269 + }
1.270 + }
1.271 +
1.272 +/**
1.273 +Current database connection transaction state.
1.274 +
1.275 +@return True, the current database connection is in transaction, false otherwise.
1.276 +*/
1.277 +inline TBool CSqlSrvDatabase::InTransaction() const
1.278 + {
1.279 + return !sqlite3_get_autocommit(iDbHandle);
1.280 + }
1.281 +