1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/persistentdata/persistentstorage/sql/SRC/Client/SQLDatabase.cpp Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,1084 @@
1.4 +// Copyright (c) 2005-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 +#include "SqlAssert.h" //ESqlPanicInvalidObj, ESqlPanicObjExists
1.20 +#include "SqlDatabaseImpl.h" //CSqlDatabaseImpl
1.21 +#include "OstTraceDefinitions.h"
1.22 +#ifdef OST_TRACE_COMPILER_IN_USE
1.23 +#include "SqlDatabaseTraces.h"
1.24 +#endif
1.25 +#include "SqlTraceDef.h"
1.26 +
1.27 +/**
1.28 +Gets the category of the return code value that is returned by
1.29 +a call to the SQL API.
1.30 +
1.31 +A call to the SQL API may complete with a non-zero return code indicating that some
1.32 +unexpected behaviour has occurred. This can be categorised in a number of ways,
1.33 +for example, as a Symbian OS error, or as a database error etc etc.
1.34 +
1.35 +This function takes the return code value and gets the category associated with
1.36 +that value. The categories are defined by the enum values of
1.37 +the TSqlRetCodeClass enum.
1.38 +
1.39 +@param aSqlRetCode The return code value returned from a call to any (member)
1.40 + function that forms part of the SQL interface.
1.41 +
1.42 +@return The category associated with the specified return code value. This is
1.43 + one of the TSqlRetCodeClass enum values.
1.44 +
1.45 +@see TSqlRetCodeClass
1.46 +
1.47 +@capability None
1.48 +
1.49 +@publishedAll
1.50 +@released
1.51 +*/
1.52 +EXPORT_C TSqlRetCodeClass SqlRetCodeClass(TInt aSqlRetCode)
1.53 + {
1.54 + if(aSqlRetCode >= 0)
1.55 + {
1.56 + return ESqlInformation;
1.57 + }
1.58 + else if(aSqlRetCode <= KSqlErrGeneral)
1.59 + {
1.60 + return ESqlDbError;
1.61 + }
1.62 + return ESqlOsError;
1.63 + }
1.64 +
1.65 +/**
1.66 +Initialises the pointer to the implementation object to NULL.
1.67 +
1.68 +@capability None
1.69 +*/
1.70 +EXPORT_C RSqlDatabase::RSqlDatabase() :
1.71 + iImpl(NULL)
1.72 + {
1.73 + }
1.74 +
1.75 +/**
1.76 +Creates a new shared non-secure or private secure database.
1.77 +
1.78 +@param aDbFileName The full path name of the file that is to host the database.
1.79 +@param aConfig the configuration string "PARAM=VALUE;....".
1.80 + The following parameters can be set using the configuration string:
1.81 + cache_size=value - where "value" is the cache size in pages.
1.82 + "value" must be a positive integer number;
1.83 + page_size=value - where "value" is the page size in bytes.
1.84 + The "page_size" parameter can accept the following values:
1.85 + 512, 1024, 2048, 4096, 8192, 16384, 32768;
1.86 + encoding=value - where "value" is the desired database encoding.
1.87 + "value" could be either "UTF-8" or "UTF-16";
1.88 + compaction=value - where "value" is the desired compaction mode.
1.89 + "value" could be either "background", "synchronous" or "manual".
1.90 +
1.91 +@return KErrNone, the operation has completed successfully;
1.92 + KErrNoMemory, an out of memory condition has occurred;
1.93 + KErrBadName, the file name is invalid - it has either a zero length or it is the name of a directory;
1.94 + KErrAlreadyExists, the file already exists;
1.95 + KErrNotReady, the drive does not exist or is not ready;
1.96 + KErrInUse, the file is already open;
1.97 + KErrArgument, the file name refers to a secure database, invalid configuration string, invalid parameter values
1.98 + in the configuration string.
1.99 + Note that database specific errors categorised as ESqlDbError, and
1.100 + other system-wide error codes may also be returned.
1.101 +
1.102 +@capability None
1.103 +*/
1.104 +EXPORT_C TInt RSqlDatabase::Create(const TDesC& aDbFileName, const TDesC8* aConfig)
1.105 + {
1.106 + __SQLTRACE_BORDEREXPR(TPtrC8 config(aConfig ? *aConfig : KNullDesC8));
1.107 + __SQLTRACE_BORDERVAR(TBuf<100> des16prnbuf);
1.108 + SQL_TRACE_BORDER(OstTraceExt3(TRACE_BORDER, RSQLDATABASE_CREATE_ENTRY, "Entry;0x%X;RSqlDatabase::Create;aDbFileName=%S;aConfig=%s", (TUint)this, __SQLPRNSTR(aDbFileName), __SQLPRNSTR8(config, des16prnbuf)));
1.109 + TRAPD(err, iImpl = CSqlDatabaseImpl::NewL(ESqlSrvDbCreate, aDbFileName, NULL, aConfig));
1.110 + SQL_TRACE_BORDER(OstTraceExt3(TRACE_BORDER, RSQLDATABASE_CREATE_Exit, "Exit;0x%X;RSqlDatabase::Create;iImpl=0x%X;err=%d", (TUint)this, (TUint)iImpl, err));
1.111 + return err;
1.112 + }
1.113 +
1.114 +/**
1.115 +Creates a new shared secure database.
1.116 +
1.117 +@param aDbFileName The name of the file that is to host the database.
1.118 + The format of the name is \<drive\>:\<[SID]database file name excluding the path\>.
1.119 + "[SID]" refers to the application SID.
1.120 +@param aSecurityPolicy The container for the security policies.
1.121 +@param aConfig the configuration string "PARAM=VALUE;...."
1.122 + The following parameters can be set using the configuration string:
1.123 + cache_size=value - where "value" is the cache size in pages.
1.124 + "value" must be a positive integer number;
1.125 + page_size=value - where "value" is the page size in bytes.
1.126 + The "page_size" parameter can accept the following values:
1.127 + 512, 1024, 2048, 4096, 8192, 16384, 32768;
1.128 + encoding=value - where "value" is the desired database encoding.
1.129 + "value" could be either "UTF-8" or "UTF-16";
1.130 + compaction=value - where "value" is the desired compaction mode.
1.131 + "value" could be either "background", "synchronous" or "manual".
1.132 +
1.133 +
1.134 +@return KErrNone, the operation has completed successfully;
1.135 + KErrNoMemory, an out of memory condition has occurred;
1.136 + KErrArgument, the file name does not refer to a secure database;
1.137 + KErrArgument, system table name found in the security policies (aSecurityPolicy),
1.138 + invalid configuration string, invalid parameter values
1.139 + in the configuration string;
1.140 + KErrBadName, the file name is invalid - it has either a zero length or it is the name of a directory;
1.141 + KErrAlreadyExists, the file already exists;
1.142 + KErrNotReady, the drive does not exist or is not ready;
1.143 + KErrInUse, the file is already open;
1.144 + KErrPermissionDenied, the caller does not satisfy the relevant database security policies.
1.145 + Note that database specific errors categorised as ESqlDbError, and
1.146 + other system-wide error codes may also be returned.
1.147 +
1.148 +@capability The calling application must satisfy the database policy of RSqlSecurityPolicy::ESchemaPolicy type;
1.149 +
1.150 +@see RSqlSecurityPolicy
1.151 +@see RSqlSecurityPolicy::TPolicyType
1.152 +*/
1.153 +EXPORT_C TInt RSqlDatabase::Create(const TDesC& aDbFileName,
1.154 + const RSqlSecurityPolicy& aSecurityPolicy, const TDesC8* aConfig)
1.155 + {
1.156 + __SQLTRACE_BORDEREXPR(TPtrC8 config(aConfig ? *aConfig : KNullDesC8));
1.157 + __SQLTRACE_BORDERVAR(TBuf<100> des16prnbuf);
1.158 + SQL_TRACE_BORDER(OstTraceExt4(TRACE_BORDER, RSQLDATABASE_CREATE2_ENTRY, "Entry;0x%X;RSqlDatabase::Create;aDbFileName=%S;aSecurityPolicy=0x%X;aConfig=%s", (TUint)this, __SQLPRNSTR(aDbFileName), (TUint)&aSecurityPolicy, __SQLPRNSTR8(config, des16prnbuf)));
1.159 + TRAPD(err, iImpl = CSqlDatabaseImpl::NewL(ESqlSrvDbCreateSecure, aDbFileName, &aSecurityPolicy.Impl(), aConfig));
1.160 + SQL_TRACE_BORDER(OstTraceExt3(TRACE_BORDER, RSQLDATABASE_CREATE2_Exit, "Exit;0x%X;RSqlDatabase::Create;iImpl=0x%X;err=%d", (TUint)this, (TUint)iImpl, err));
1.161 + return err;
1.162 + }
1.163 +
1.164 +/**
1.165 +Opens an existing database, which can be:
1.166 +@code
1.167 + - shared non-secure;
1.168 + - shared secure;
1.169 + - private secure;
1.170 +@endcode
1.171 +
1.172 +@param aDbFileName The name of the file that hosts the database. If this is
1.173 + a secure database, then the format of the name must be:
1.174 + \<drive\>:\<[SID]database file name excluding the path\>.
1.175 + If this is a non-secure database, then aDbFileName has to be the full database file name.
1.176 + "[SID]" refers to SID of the application which created the database.
1.177 +@param aConfig the configuration string "PARAM=VALUE;...."
1.178 + The following parameters can be set using the configuration string:
1.179 + cache_size=value - where "value" is the cache size in pages.
1.180 + "value" must be a positive integer number;
1.181 +
1.182 +
1.183 +@return KErrNone, the operation has completed successfully;
1.184 + KErrNoMemory, an out of memory condition has occurred;
1.185 + KErrBadName, the file name is invalid - it has either a zero length or it is the name of a directory;
1.186 + KErrNotReady, the drive does not exist or is not ready;
1.187 + KErrInUse, the file is already open;
1.188 + KErrNotFound, database file not found;
1.189 + KErrArgument, invalid configuration string, invalid parameter values
1.190 + in the configuration string;
1.191 + KErrGeneral, missing or invalid security policies (if the database to be opened is a secure database);
1.192 + KErrPermissionDenied, the caller does not satisfy the relevant database security policies;
1.193 + KErrNotSupported, incompatible SQL security version (if the database to be opened is a secure database).
1.194 + Note that database specific errors categorised as ESqlDbError, and
1.195 + other system-wide error codes may also be returned.
1.196 +
1.197 +@capability None, if aDbFileName refers to a non-secure database;
1.198 + RSqlSecurityPolicy::ESchemaPolicy or
1.199 + RSqlSecurityPolicy::EReadPolicy or
1.200 + RSqlSecurityPolicy::EWritePolicy database policy type, if aDbFileName refers to a secure database;
1.201 +
1.202 +@see RSqlSecurityPolicy
1.203 +@see RSqlSecurityPolicy::TPolicyType
1.204 +*/
1.205 +EXPORT_C TInt RSqlDatabase::Open(const TDesC& aDbFileName, const TDesC8* aConfig)
1.206 + {
1.207 + __SQLTRACE_BORDEREXPR(TPtrC8 config(aConfig ? *aConfig : KNullDesC8));
1.208 + __SQLTRACE_BORDERVAR(TBuf<100> des16prnbuf);
1.209 + SQL_TRACE_BORDER(OstTraceExt3(TRACE_BORDER, RSQLDATABASE_OPEN_ENTRY, "Entry;0x%X;RSqlDatabase::Open;aDbFileName=%S;aConfig=%s", (TUint)this, __SQLPRNSTR(aDbFileName), __SQLPRNSTR8(config, des16prnbuf)));
1.210 + TRAPD(err, iImpl = CSqlDatabaseImpl::NewL(ESqlSrvDbOpen, aDbFileName, NULL, aConfig));
1.211 + SQL_TRACE_BORDER(OstTraceExt3(TRACE_BORDER, RSQLDATABASE_OPEN_EXIT, "Exit;0x%X;RSqlDatabase::Open;iImpl=0x%X;err=%d", (TUint)this, (TUint)iImpl, err));
1.212 + return err;
1.213 + }
1.214 +
1.215 +/**
1.216 +Creates a new shared non-secure or private secure database.
1.217 +
1.218 +@param aDbFileName The full path name of the file that is to host the database.
1.219 +@param aConfig the configuration string "PARAM=VALUE;...."
1.220 + The following parameters can be set using the configuration string:
1.221 + cache_size=value - where "value" is the cache size in pages.
1.222 + "value" must be a positive integer number;
1.223 + page_size=value - where "value" is the page size in bytes.
1.224 + The "page_size" parameter can accept the following values:
1.225 + 512, 1024, 2048, 4096, 8192, 16384, 32768;
1.226 + encoding=value - where "value" is the desired database encoding.
1.227 + "value" could be either "UTF-8" or "UTF-16";
1.228 + compaction=value - where "value" is the desired compaction mode.
1.229 + "value" could be either "background", "synchronous" or "manual".
1.230 +
1.231 +
1.232 +@leave KErrNoMemory, an out of memory condition has occurred;
1.233 + KErrBadName, the file name is invalid - it has either a zero length or it is the name of a directory;
1.234 + KErrAlreadyExists, the file already exists;
1.235 + KErrNotReady, the drive does not exist or is not ready;
1.236 + KErrInUse, the file is already open;
1.237 + KErrArgument, the file name refers to a secure database,
1.238 + invalid configuration string, invalid parameter values
1.239 + in the configuration string.
1.240 + Note that the function may leave with database specific errors categorised as ESqlDbError and
1.241 + other system-wide error codes.
1.242 +
1.243 +@capability None
1.244 +*/
1.245 +EXPORT_C void RSqlDatabase::CreateL(const TDesC& aDbFileName, const TDesC8* aConfig)
1.246 + {
1.247 + __SQLTRACE_BORDEREXPR(TPtrC8 config(aConfig ? *aConfig : KNullDesC8));
1.248 + __SQLTRACE_BORDERVAR(TBuf<100> des16prnbuf);
1.249 + SQL_TRACE_BORDER(OstTraceExt3(TRACE_BORDER, RSQLDATABASE_CREATEL_ENTRY, "Entry;0x%X;RSqlDatabase::CreateL;aDbFileName=%S;aConfig=%s", (TUint)this, __SQLPRNSTR(aDbFileName), __SQLPRNSTR8(config, des16prnbuf)));
1.250 + iImpl = CSqlDatabaseImpl::NewL(ESqlSrvDbCreate, aDbFileName, NULL, aConfig);
1.251 + SQL_TRACE_BORDER(OstTraceExt2(TRACE_BORDER, RSQLDATABASE_CREATEL_EXIT, "Entry;0x%X;RSqlDatabase::CreateL;iImpl=0x%X", (TUint)this, (TUint)iImpl));
1.252 + }
1.253 +
1.254 +/**
1.255 +Creates a new shared secure database.
1.256 +@param aDbFileName The name of the file that is to host the database.
1.257 + The format of the name is \<drive\>:\<[SID]database file name excluding the path\>.
1.258 + "[SID]" refers to the application SID.
1.259 +@param aSecurityPolicy The container for the security policies.
1.260 +@param aConfig the configuration string "PARAM=VALUE;...."
1.261 + The following parameters can be set using the configuration string:
1.262 + cache_size=value - where "value" is the cache size in pages.
1.263 + "value" must be a positive integer number;
1.264 + page_size=value - where "value" is the page size in bytes.
1.265 + The "page_size" parameter can accept the following values:
1.266 + 512, 1024, 2048, 4096, 8192, 16384, 32768;
1.267 + encoding=value - where "value" is the desired database encoding.
1.268 + "value" could be either "UTF-8" or "UTF-16";
1.269 +
1.270 + compaction=value - where "value" is the desired compaction mode.
1.271 + "value" could be either "background", "synchronous" or "manual".
1.272 +
1.273 +@leave KErrNoMemory, an out of memory condition has occurred;
1.274 + KErrArgument, the file name does not refer to a secure database;
1.275 + KErrArgument, system table name found in the security policies (aSecurityPolicy),
1.276 + invalid configuration string, invalid parameter values
1.277 + in the configuration string;
1.278 + KErrBadName, the file name is invalid - it has either a zero length or it is the name of a directory;
1.279 + KErrAlreadyExists, the file already exists;
1.280 + KErrNotReady, the drive does not exist or is not ready;
1.281 + KErrInUse, the file is already open;
1.282 + KErrPermissionDenied, the caller does not satisfy the relevant database security policies.
1.283 + Note that the function may leave with database specific errors categorised as ESqlDbError and
1.284 + other system-wide error codes.
1.285 +
1.286 +@capability The calling application must satisfy the database policy of RSqlSecurityPolicy::ESchemaPolicy type;
1.287 +
1.288 +@see RSqlSecurityPolicy
1.289 +@see RSqlSecurityPolicy::TPolicyType
1.290 +*/
1.291 +EXPORT_C void RSqlDatabase::CreateL(const TDesC& aDbFileName,
1.292 + const RSqlSecurityPolicy& aSecurityPolicy, const TDesC8* aConfig)
1.293 + {
1.294 + __SQLTRACE_BORDEREXPR(TPtrC8 config(aConfig ? *aConfig : KNullDesC8));
1.295 + __SQLTRACE_BORDERVAR(TBuf<100> des16prnbuf);
1.296 + SQL_TRACE_BORDER(OstTraceExt4(TRACE_BORDER, RSQLDATABASE_CREATEL2_ENTRY, "Entry;0x%X;RSqlDatabase::CreateL;aDbFileName=%S;aSecurityPolicy=0x%X;aConfig=%s", (TUint)this, __SQLPRNSTR(aDbFileName), (TUint)&aSecurityPolicy, __SQLPRNSTR8(config, des16prnbuf)));
1.297 + iImpl = CSqlDatabaseImpl::NewL(ESqlSrvDbCreateSecure, aDbFileName, &aSecurityPolicy.Impl(), aConfig);
1.298 + SQL_TRACE_BORDER(OstTraceExt2(TRACE_BORDER, RSQLDATABASE_CREATEL2_EXIT, "Exit;0x%X;RSqlDatabase::CreateL;iImpl=0x%X", (TUint)this, (TUint)iImpl));
1.299 + }
1.300 +
1.301 +/**
1.302 +Opens an existing database, which can be:
1.303 +@code
1.304 + - shared non-secure;
1.305 + - shared secure;
1.306 + - private secure;
1.307 +@endcode
1.308 +
1.309 +@param aDbFileName The name of the file that hosts the database. If this is
1.310 + a secure database, then the format of the name must be:
1.311 + \<drive\>:\<[SID]database file name excluding the path\>.
1.312 + If this is a non-secure database, then aDbFileName has to be the full database file name.
1.313 + "[SID]" refers to SID of the application which created the database.
1.314 +@param aConfig the configuration string "PARAM=VALUE;...."
1.315 + The following parameters can be set using the configuration string:
1.316 + cache_size=value - where "value" is the cache size in pages.
1.317 + "value" must be a positive integer number;
1.318 +
1.319 +
1.320 +@leave KErrNoMemory, an out of memory condition has occurred;
1.321 + KErrBadName, the file name is invalid - it has either a zero length or it is the name of a directory;
1.322 + KErrNotReady, the drive does not exist or is not ready;
1.323 + KErrInUse, the file is already open;
1.324 + KErrNotFound, database file not found;
1.325 + KErrArgument, invalid configuration string, invalid parameter values
1.326 + in the configuration string;
1.327 + KErrGeneral, missing or invalid security policies (if the database to be opened is a secure database);
1.328 + KErrPermissionDenied, the caller does not satisfy the relevant database security policies;
1.329 + KErrNotSupported, incompatible SQL security version (if the database to be opened is a secure database).
1.330 + Note that the function may leave with database specific errors categorised as ESqlDbError and
1.331 + other system-wide error codes.
1.332 +
1.333 +@capability None, if aDbFileName refers to a non-secure database;
1.334 + RSqlSecurityPolicy::ESchemaPolicy or
1.335 + RSqlSecurityPolicy::EReadPolicy or
1.336 + RSqlSecurityPolicy::EWritePolicy database policy type, if aDbFileName refers to a secure database;
1.337 +
1.338 +@see RSqlSecurityPolicy
1.339 +@see RSqlSecurityPolicy::TPolicyType
1.340 +*/
1.341 +EXPORT_C void RSqlDatabase::OpenL(const TDesC& aDbFileName, const TDesC8* aConfig)
1.342 + {
1.343 + __SQLTRACE_BORDEREXPR(TPtrC8 config(aConfig ? *aConfig : KNullDesC8));
1.344 + SQL_TRACE_BORDER(OstTraceExt3(TRACE_BORDER, RSQLDATABASE_OPENL_ENTRY, "Entry;0x%X;RSqlDatabase::OpenL;aDbFileName=%S;aConfig=%s", (TUint)this, __SQLPRNSTR(aDbFileName), __SQLPRNSTR(config)));
1.345 + iImpl = CSqlDatabaseImpl::NewL(ESqlSrvDbOpen, aDbFileName, NULL, aConfig);
1.346 + SQL_TRACE_BORDER(OstTraceExt2(TRACE_BORDER, RSQLDATABASE_OPENL_EXIT, "Exit;0x%X;RSqlDatabase::OpenL;iImpl=0x%X", (TUint)this, (TUint)iImpl));
1.347 + }
1.348 +
1.349 +/**
1.350 +Closes this handle to the database.
1.351 +
1.352 +The function frees memory and any allocated resources.
1.353 +
1.354 +You can reuse this object, but you must reinitialise it by calling
1.355 +RSqlDatabase::Create() or RSqlDatabase::Open().
1.356 +
1.357 +@see RSqlDatabase::Create()
1.358 +@see RSqlDatabase::Open()
1.359 +
1.360 +@capability None
1.361 +*/
1.362 +EXPORT_C void RSqlDatabase::Close()
1.363 + {
1.364 + SQL_TRACE_BORDER(OstTraceExt2(TRACE_BORDER, RSQLDATABASE_CLOSE_ENTRY, "Entry;0x%X;RSqlDatabase::Close;iImpl=0x%X", (TUint)this, (TUint)iImpl));
1.365 + delete iImpl;
1.366 + SQL_TRACE_BORDER(OstTraceExt2(TRACE_BORDER, RSQLDATABASE_CLOSE_EXIT, "Exit;0x%X;RSqlDatabase::Close;iImpl=0x%X", (TUint)this, (TUint)iImpl));
1.367 + iImpl = NULL;
1.368 + }
1.369 +
1.370 +/**
1.371 +Attaches an existing database to the current database connection.
1.372 +
1.373 +The attached database can be read, written or modified.
1.374 +One database can be attched multiple times to the same connection, using different logical database names.
1.375 +Tables in an attached database can be referred to using "database-name.table-name" syntax.
1.376 +If an attached table doesn't have a duplicate table name in the main database, it doesn't
1.377 +require a database name prefix.
1.378 +
1.379 +Transactions involving multiple attached databases are atomic.
1.380 +
1.381 +@param aDbFileName The name of the file that hosts the database. If this is
1.382 + a secure database, then the format of the name must be:
1.383 + \<drive\>:\<[SID]database file name excluding the path\>.
1.384 + If this is a private or shared non-secure database, then aDbFileName has to be the full
1.385 + database file name. "[SID]" refers to SID of the application which created the attached database.
1.386 +@param aDbName Logical database name. It must be unique (per database connection). This is the name which can
1.387 + be used for accessing tables in the attached database. The syntax is "database-name.table-name".
1.388 +
1.389 +@return KErrNone, the operation has completed successfully;
1.390 + KErrNoMemory, an out of memory condition has occurred;
1.391 + KErrBadName, the file name is invalid - it has either a zero length or it is the name of a directory;
1.392 + KErrNotReady, the drive does not exist or is not ready;
1.393 + KErrInUse, the file is already open;
1.394 + KErrNotFound, database file not found;
1.395 + KErrGeneral, missing or invalid security policies (if the database to be opened is a secure database);
1.396 + KErrPermissionDenied, the caller does not satisfy the relevant database security policies;
1.397 + KErrNotSupported, incompatible SQL security version (if the database to be opened is a secure database).
1.398 + Note that database specific errors categorised as ESqlDbError, and
1.399 + other system-wide error codes may also be returned.
1.400 +
1.401 +@capability None, if aDbFileName refers to a non-secure database;
1.402 + RSqlSecurityPolicy::ESchemaPolicy or
1.403 + RSqlSecurityPolicy::EReadPolicy or
1.404 + RSqlSecurityPolicy::EWritePolicy database policy type, if aDbFileName refers to a secure database;
1.405 +
1.406 +@see RSqlSecurityPolicy
1.407 +@see RSqlSecurityPolicy::TPolicyType
1.408 +*/
1.409 +EXPORT_C TInt RSqlDatabase::Attach(const TDesC& aDbFileName, const TDesC& aDbName)
1.410 + {
1.411 + SQL_TRACE_BORDER(OstTraceExt3(TRACE_BORDER, RSQLDATABASE_ATTACH_ENTRY, "Entry;0x%X;RSqlDatabase::Attach;aDbFileName=%S;aDbName=%S", (TUint)this, __SQLPRNSTR(aDbFileName), __SQLPRNSTR(aDbName)));
1.412 + TInt err = Impl().Attach(aDbFileName, aDbName);
1.413 + SQL_TRACE_BORDER(OstTraceExt2(TRACE_BORDER, RSQLDATABASE_ATTACH_EXIT, "Entry;0x%X;RSqlDatabase::Attach;err=%d", (TUint)this, err));
1.414 + return err;
1.415 + }
1.416 +
1.417 +/**
1.418 +Detaches previously attached database.
1.419 +
1.420 +@param aDbName Logical database name.
1.421 + The logical name of the database to be detached.
1.422 +
1.423 +@return KErrNone, the operation completed has successfully;
1.424 + KErrNotFound, no attached database with aDbName name;
1.425 + Note that database specific errors categorised as ESqlDbError, and
1.426 + other system-wide error codes may also be returned.
1.427 +
1.428 +@capability None
1.429 +*/
1.430 +EXPORT_C TInt RSqlDatabase::Detach(const TDesC& aDbName)
1.431 + {
1.432 + SQL_TRACE_BORDER(OstTraceExt2(TRACE_BORDER, RSQLDATABASE_DETACH_ENTRY, "Entry;0x%X;RSqlDatabase::Detach;aDbName=%S", (TUint)this, __SQLPRNSTR(aDbName)));
1.433 + TInt err = Impl().Detach(aDbName);
1.434 + SQL_TRACE_BORDER(OstTraceExt2(TRACE_BORDER, RSQLDATABASE_DETACH_EXIT, "Exit;0x%X;RSqlDatabase::Detach;err=%d", (TUint)this, err));
1.435 + return err;
1.436 + }
1.437 +
1.438 +/**
1.439 +Copies a database file to the specified location.
1.440 +
1.441 +Note that this is a static function, and its use is not
1.442 +restricted to any specific RSqlDatabase instance.
1.443 +
1.444 +@param aSrcDbFileName Source database file name.
1.445 + If this is a secure database, then the format of the name must be:
1.446 + \<drive\>:\<[SID]database file name excluding the path\>.
1.447 + If this is a non-secure database, then aDbFileName has to be the full database file name.
1.448 + "[SID]" refers to SID of the application which created the database.
1.449 +@param aDestDbFileName Destination database file name.
1.450 + If this is a secure database, then the format of the name must be:
1.451 + \<drive\>:\<[SID]database file name excluding the path\>.
1.452 + If this is a non-secure database, then aDbFileName has to be the full database file name.
1.453 + "[SID]" refers to SID of the application which performs the copying operation.
1.454 +
1.455 +The allowed copying operations are:
1.456 +- secure to secure database. Only the application created the database is allowed to copy it.
1.457 +- non-secure to non-secure database. No restrictions apply to this operation.
1.458 +
1.459 +@return KErrNone, the operation completed has successfully;
1.460 + KErrBadName, the file name is invalid - it has either a zero length or it is the name of a directory;
1.461 + KErrNotReady, the drive does not exist or is not ready;
1.462 + KErrInUse, the file is already open;
1.463 + KErrNotFound, database file not found;
1.464 + KErrPermissionDenied, the SID of the calling application does not match the SID of source or destination database.
1.465 + Note that other system-wide error codes may also be returned.
1.466 +
1.467 +@capability None
1.468 +
1.469 +Note that if the source database is a secure database, only the application, which created the database, can copy it.
1.470 +*/
1.471 +EXPORT_C TInt RSqlDatabase::Copy(const TDesC& aSrcDbFileName, const TDesC& aDestDbFileName)
1.472 + {
1.473 + SQL_TRACE_BORDER(OstTraceExt2(TRACE_BORDER, RSQLDATABASE_COPY_ENTRY, "Entry;0;RSqlDatabase::Copy;aSrcDbFileName=%S;aDestDbFileName=%S", __SQLPRNSTR(aSrcDbFileName), __SQLPRNSTR(aDestDbFileName)));
1.474 + TInt err = CSqlDatabaseImpl::Copy(aSrcDbFileName, aDestDbFileName);
1.475 + SQL_TRACE_BORDER(OstTrace1(TRACE_BORDER, RSQLDATABASE_COPY_EXIT, "Exit;0;RSqlDatabase::Copy;err=%d", err));
1.476 + return err;
1.477 + }
1.478 +
1.479 +/**
1.480 +Deletes the specified database file.
1.481 +
1.482 +Note that this is a static function, and its use is not
1.483 +restricted to any specific RSqlDatabase instance.
1.484 +
1.485 +@param aDbFileName The name of the database file.
1.486 + If this is a secure database, then the format of the name must be:
1.487 + \<drive\>:\<[SID]database file name excluding the path\>.
1.488 + If this is a private or shared non-secure database, then aDbFileName has to be the
1.489 + full database file name. "[SID]" refers to SID of the application which created the database.
1.490 +
1.491 +@return KErrNone, the operation has completed successfully;
1.492 + KErrBadName, the file name is invalid - it has either a zero length or it is the name of a directory;
1.493 + KErrNotReady, the drive does not exist or is not ready;
1.494 + KErrInUse, the database file is in use;
1.495 + KErrNotFound, the database file cannot be found;
1.496 + KErrAccessDenied, access to the database file is denied (e.g. it might be a read-only file);
1.497 + KErrPermissionDenied, the SID of the calling application does not match the SID of the database;
1.498 + Note that other system-wide error codes may also be returned.
1.499 +
1.500 +@capability None
1.501 +
1.502 +Note that if the database to be deleted is a secure database, only the application, which created the database, can delete it.
1.503 +*/
1.504 +EXPORT_C TInt RSqlDatabase::Delete(const TDesC& aDbFileName)
1.505 + {
1.506 + SQL_TRACE_BORDER(OstTraceExt1(TRACE_BORDER, RSQLDATABASE_DELETE_ENTRY, "Entry;0;RSqlDatabase::Delete;aDbFileName=%S", __SQLPRNSTR(aDbFileName)));
1.507 + TInt err = CSqlDatabaseImpl::Delete(aDbFileName);
1.508 + SQL_TRACE_BORDER(OstTrace1(TRACE_BORDER, RSQLDATABASE_DELETE_EXIT, "Exit;0;RSqlDatabase::Delete;err=%d", err));
1.509 + return err;
1.510 + }
1.511 +
1.512 +/**
1.513 +Initializes aSecurityPolicy output parameter with a copy of the database security policies.
1.514 +The caller is responsible for destroying the initialized aSecurityPolicy paramemter.
1.515 +
1.516 +Note that there may be no security policies in force for this database.
1.517 +
1.518 +@param aSecurityPolicy Input/Output parameter, which will be initialized with the database
1.519 + security policies.
1.520 +
1.521 +@return KErrNone, the operation has completed successfully;
1.522 + KErrNotSupported, the current database is not a secure database;
1.523 + KErrNoMemory, an out of memory condition has occurred;
1.524 +
1.525 +@capability None
1.526 +*/
1.527 +EXPORT_C TInt RSqlDatabase::GetSecurityPolicy(RSqlSecurityPolicy& aSecurityPolicy) const
1.528 + {
1.529 + SQL_TRACE_BORDER(OstTraceExt2(TRACE_BORDER, RSQLDATABASE_GETSECURITYPOLICY_ENTRY, "Entry;0x%X;RSqlDatabase::GetSecurityPolicy;aSecurityPolicy=0x%X", (TUint)this, (TUint)&aSecurityPolicy));
1.530 + TRAPD(err, CSqlSecurityPolicy* securityPolicy = Impl().CloneSecurityPolicyL(); aSecurityPolicy.Set(*securityPolicy));
1.531 + SQL_TRACE_BORDER(OstTraceExt2(TRACE_BORDER, RSQLDATABASE_GETSECURITYPOLICY_EXIT, "Exit;0x%X;RSqlDatabase::GetSecurityPolicy;err=%d", (TUint)this, err));
1.532 + return err;
1.533 + }
1.534 +
1.535 +/**
1.536 +Initializes aSecurityPolicy output parameter with a copy of the database security policies.
1.537 +The caller is responsible for destroying the initialized aSecurityPolicy paramemter.
1.538 +
1.539 +Note that there may be no security policies in force for this database.
1.540 +
1.541 +@param aSecurityPolicy Input/Output parameter, which will be initialized with the database
1.542 + security policies.
1.543 +
1.544 +@leave KErrNotSupported, the current database is not a secure database;
1.545 + KErrNoMemory, an out of memory condition has occurred;
1.546 +
1.547 +@capability None
1.548 +*/
1.549 +EXPORT_C void RSqlDatabase::GetSecurityPolicyL(RSqlSecurityPolicy& aSecurityPolicy) const
1.550 + {
1.551 + SQL_TRACE_BORDER(OstTraceExt2(TRACE_BORDER, RSQLDATABASE_GETSECURITYPOLICYL_ENTRY, "Entry;0x%X;RSqlDatabase::GetSecurityPolicyL;aSecurityPolicy=0x%X", (TUint)this, (TUint)&aSecurityPolicy));
1.552 + CSqlSecurityPolicy* securityPolicy = Impl().CloneSecurityPolicyL();
1.553 + aSecurityPolicy.Set(*securityPolicy);
1.554 + SQL_TRACE_BORDER(OstTrace1(TRACE_BORDER, RSQLDATABASE_GETSECURITYPOLICYL_EXIT, "Exit;0x%X;RSqlDatabase::GetSecurityPolicyL", (TUint)this));
1.555 + }
1.556 +
1.557 +/**
1.558 +Sets the transaction isolation level for the database.
1.559 +
1.560 +A transaction isolation level defines the way in which a transaction
1.561 +interacts with other transactions that may be in progress concurrently.
1.562 +
1.563 +Transaction isolation levels are defined by the values of the
1.564 +RSqlDatabase::TIsolationLevel enum.
1.565 +
1.566 +The default isolation level is RSqlDatabase::ESerializable
1.567 +
1.568 +Note that the isolation level is not a persistent property of the database.
1.569 +It is set to the default value, i.e. RSqlDatabase::ESerializable,
1.570 +whenever the database is created or opened.
1.571 +
1.572 +@param aIsolationLevel The isolation level to be set.
1.573 +
1.574 +@return KErrNone, if the operation has completed successfully;
1.575 + KErrNotSupported, invalid (not supported) transaction isolation level;
1.576 +
1.577 +@see RSqlDatabase::TIsolationLevel
1.578 +
1.579 +@capability None
1.580 +*/
1.581 +EXPORT_C TInt RSqlDatabase::SetIsolationLevel(RSqlDatabase::TIsolationLevel aIsolationLevel)
1.582 + {
1.583 + SQL_TRACE_BORDER(OstTraceExt2(TRACE_BORDER, RSQLDATABASE_SETISOLATIONLEVEL_ENTRY, "Entry;0x%X;RSqlDatabase::SetIsolationLevel;aIsolationLevel=%d", (TUint)this, aIsolationLevel));
1.584 + TInt err = Impl().SetIsolationLevel(aIsolationLevel);
1.585 + SQL_TRACE_BORDER(OstTraceExt2(TRACE_BORDER, RSQLDATABASE_SETISOLATIONLEVEL_EXIT, "Exit;0x%X;RSqlDatabase::SetIsolationLevel;err=%d", (TUint)this, err));
1.586 + return err;
1.587 + }
1.588 +
1.589 +/**
1.590 +Executes one or more 16-bit SQL statements.
1.591 +
1.592 +This method should be used for executing DDL/DML statements, but note the following point:
1.593 +- if an SQL statement contains one or more parameters, then the function will execute it,
1.594 +giving the parameters default NULL values.
1.595 +
1.596 +This class (RSqlDatabase) does not offer functions for setting the parameter values.
1.597 +Use the RSqlStatement class instead.
1.598 +
1.599 +If the call to this function fails because of a database-specific type error
1.600 +(i.e. the error is categorised as of type ESqlDbError), then a textual description of
1.601 +the error can be obtained calling RSqlDatabase::LastErrorMessage().
1.602 +
1.603 +@param aSqlStmt A string of 16-bit wide characters containing one or more DDL/DML SQL statements;
1.604 + each statement is separated by a ';' character.
1.605 +
1.606 +@return >=0, The operation has completed successfully. The number of database rows that were
1.607 + changed/inserted/deleted by the most recently completed DDL/DML sql statement.
1.608 + Exception: If the executed statement is "DELETE FROM <table>", then the function returns 0
1.609 + if the operation has completed successfully (disregarding the number of the deleted rows);
1.610 + KErrNoMemory, an out of memory condition has occured;
1.611 + KSqlErrGeneral, a syntax error has occurred - text describing the problem
1.612 + can be obtained by calling RSqlDatabase::LastErrorMessage();
1.613 + KErrDiskFull, There is no available disk space to complete the operation. If the executed statement is a DELETE
1.614 + statement, try to use the reserved disk space (if there is a reserved disk space) to complete the operation.
1.615 + In all other cases the database connection should be closed and some disk space freed before reopening
1.616 + the database;
1.617 + KErrPermissionDenied, the caller does not satisfy the relevant database security policies.
1.618 + Note that database specific errors categorised as ESqlDbError, and
1.619 + other system-wide error codes may also be returned.
1.620 +
1.621 +@capability None, if current RSqlDatabase object represents a handle to a non-secure database;
1.622 + RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement modifies a secure database schema;
1.623 + RSqlSecurityPolicy::EReadPolicy or
1.624 + RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement reads from a secure database;
1.625 + RSqlSecurityPolicy::EWritePolicy or
1.626 + RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement writes to a secure database;
1.627 +
1.628 +@see RSqlStatement
1.629 +@see TSqlRetCodeClass::ESqlDbError
1.630 +@see RSqlDatabase::LastErrorMessage()
1.631 +@see RSqlSecurityPolicy
1.632 +@see RSqlSecurityPolicy::TPolicyType
1.633 +*/
1.634 +EXPORT_C TInt RSqlDatabase::Exec(const TDesC& aSqlStmt)
1.635 + {
1.636 + SQL_TRACE_BORDER(OstTraceExt2(TRACE_BORDER, RSQLDATABASE_EXEC16_ENTRY, "Entry;0x%X;RSqlDatabase::Exec16;aSqlStmt=%S", (TUint)this, __SQLPRNSTR(aSqlStmt)));
1.637 + TInt err = Impl().Exec(aSqlStmt);
1.638 + SQL_TRACE_BORDER(OstTraceExt2(TRACE_BORDER, RSQLDATABASE_EXEC16_EXIT, "Exit;0x%X;RSqlDatabase::Exec16;err=%d", (TUint)this, err));
1.639 + return err;
1.640 + }
1.641 +
1.642 +/**
1.643 +Executes one or more 8-bit SQL statements.
1.644 +
1.645 +This method should be used for executing DDL/DML statements, but note the following point:
1.646 +- if an SQL statement contains one or more parameters, then the function will execute it,
1.647 +giving the parameters default NULL values.
1.648 +
1.649 +This class (RSqlDatabase) does not offer functions for setting the parameter values.
1.650 +Use the RSqlStatement class instead.
1.651 +
1.652 +If the call to this function fails because of a database-specific type error
1.653 +(i.e. the error is categorised as ESqlDbError), then a textual description of
1.654 +the error can be obtained calling RSqlDatabase::LastErrorMessage().
1.655 +
1.656 +@param aSqlStmt A string of 8-bit wide characters containing one or more DDL/DML SQL statements;
1.657 + each statement is separated by a ';' character.
1.658 +
1.659 +@return >=0, The operation has completed successfully. The number of database rows that were
1.660 + changed/inserted/deleted by the most recently completed DDL/DML sql statement.
1.661 + Exception: If the executed statement is "DELETE FROM <table>", then the function returns 0
1.662 + if the operation has completed successfully (disregarding the number of the deleted rows);
1.663 + KErrNoMemory, an out of memory condition has occured;
1.664 + KSqlErrGeneral, a syntax error has occurred - text describing the problem
1.665 + can be obtained by calling RSqlDatabase::LastErrorMessage();
1.666 + KErrDiskFull, There is no available disk space to complete the operation. If the executed statement is a DELETE
1.667 + statement, try to use the reserved disk space (if there is a reserved disk space) to complete the operation.
1.668 + In all other cases the database connection should be closed and some disk space freed before reopening
1.669 + the database;
1.670 + KErrPermissionDenied, the caller does not satisfy the relevant database security policies;
1.671 + Note that database specific errors categorised as ESqlDbError, and
1.672 + other system-wide error codes may also be returned.
1.673 +
1.674 +@capability None, if current RSqlDatabase object represents a handle to a non-secure database;
1.675 + RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement modifies a secure database schema;
1.676 + RSqlSecurityPolicy::EReadPolicy or
1.677 + RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement reads from a secure database;
1.678 + RSqlSecurityPolicy::EWritePolicy or
1.679 + RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement writes to a secure database;
1.680 +
1.681 +@see RSqlStatement
1.682 +@see TSqlRetCodeClass::ESqlDbError
1.683 +@see RSqlDatabase::LastErrorMessage()
1.684 +@see RSqlSecurityPolicy
1.685 +@see RSqlSecurityPolicy::TPolicyType
1.686 +*/
1.687 +EXPORT_C TInt RSqlDatabase::Exec(const TDesC8& aSqlStmt)
1.688 + {
1.689 + __SQLTRACE_BORDERVAR(TBuf<100> des16prnbuf);
1.690 + SQL_TRACE_BORDER(OstTraceExt2(TRACE_BORDER, RSQLDATABASE_EXEC8_ENTRY, "Entry;0x%X;RSqlDatabase::Exec8;aSqlStmt=%s", (TUint)this, __SQLPRNSTR8(aSqlStmt, des16prnbuf)));
1.691 + TInt err = Impl().Exec(aSqlStmt);
1.692 + SQL_TRACE_BORDER(OstTraceExt2(TRACE_BORDER, RSQLDATABASE_EXEC8_EXIT, "Exit;0x%X;RSqlDatabase::Exec8;err=%d", (TUint)this, err));
1.693 + return err;
1.694 + }
1.695 +
1.696 +/**
1.697 +Executes one or more 16-bit SQL statements asynchronously to allow client to avoid being blocked
1.698 +by server activity.
1.699 +
1.700 +No other operations can be performed on current RSqlDatabase object and RSqlStatement objects using it
1.701 +until the asynchronous operation completes.
1.702 +
1.703 +This method should be used for executing DDL/DML statements, but note the following point:
1.704 +- if an SQL statement contains one or more parameters, then the function will execute it,
1.705 +giving the parameters default NULL values.
1.706 +
1.707 +This class (RSqlDatabase) does not offer functions for setting the parameter values.
1.708 +Use the RSqlStatement class instead.
1.709 +
1.710 +If the call to this function fails because of a database-specific type error
1.711 +(i.e. the error is categorised as ESqlDbError), then a textual description of
1.712 +the error can be obtained calling RSqlDatabase::LastErrorMessage().
1.713 +
1.714 +@param aSqlStmt A string of 16-bit wide characters containing one or more DDL/DML SQL statements;
1.715 + each statement is separated by a ';' character.
1.716 +@param aStatus Completion status of asynchronous request, one of the following:
1.717 + >=0, The operation has completed successfully. The number of database rows that were
1.718 + changed/inserted/deleted by the most recently completed DDL/DML sql statement.
1.719 + Exception: If the executed statement is "DELETE FROM <table>", then the function returns 0
1.720 + if the operation has completed successfully (disregarding the number of the deleted rows);
1.721 + KErrNoMemory, an out of memory condition has occured;
1.722 + KSqlErrGeneral, a syntax error has occurred - text describing the problem
1.723 + can be obtained by calling RSqlDatabase::LastErrorMessage();
1.724 + KErrDiskFull, There is no available disk space to complete the operation. If the executed statement is a DELETE
1.725 + statement, try to use the reserved disk space (if there is a reserved disk space) to complete the operation.
1.726 + In all other cases the database connection should be closed and some disk space freed before reopening
1.727 + the database;
1.728 + KErrPermissionDenied, the caller does not satisfy the relevant database security policies;
1.729 + Note that aStatus may be set with database specific errors categorised as ESqlDbError,
1.730 + and other system-wide error codes.
1.731 +
1.732 +
1.733 +@capability None, if current RSqlDatabase object represents a handle to a non-secure database;
1.734 + RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement modifies a secure database schema;
1.735 + RSqlSecurityPolicy::EReadPolicy or
1.736 + RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement reads from a secure database;
1.737 + RSqlSecurityPolicy::EWritePolicy or
1.738 + RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement writes to a secure database;
1.739 +
1.740 +@see RSqlStatement
1.741 +@see TSqlRetCodeClass::ESqlDbError
1.742 +@see RSqlDatabase::LastErrorMessage()
1.743 +@see RSqlSecurityPolicy
1.744 +@see RSqlSecurityPolicy::TPolicyType
1.745 +*/
1.746 +EXPORT_C void RSqlDatabase::Exec(const TDesC& aSqlStmt, TRequestStatus& aStatus)
1.747 + {
1.748 + SQL_TRACE_BORDER(OstTraceExt2(TRACE_BORDER, RSQLDATABASE_EXECASYNC16_ENTRY, "Entry;0x%X;RSqlDatabase::ExecAsync16;aSqlStmt=%S", (TUint)this, __SQLPRNSTR(aSqlStmt)));
1.749 + Impl().Exec(aSqlStmt, aStatus);
1.750 + SQL_TRACE_BORDER(OstTraceExt2(TRACE_BORDER, RSQLDATABASE_EXECASYNC16_EXIT, "Exit;0x%X;RSqlDatabase::ExecAsync16;aStatus.Int()=%d", (TUint)this, aStatus.Int()));
1.751 + }
1.752 +
1.753 +/**
1.754 +Executes one or more 8-bit SQL statements asynchronously to allow client to avoid being blocked
1.755 +by server activity.
1.756 +
1.757 +No other operations can be performed on current RSqlDatabase object and RSqlStatement objects using it
1.758 +until the asynchronous operation completes.
1.759 +
1.760 +This method should be used for executing DDL/DML statements, but note the following point:
1.761 +- if an SQL statement contains one or more parameters, then the function will execute it,
1.762 +giving the parameters default NULL values.
1.763 +
1.764 +This class (RSqlDatabase) does not offer functions for setting the parameter values.
1.765 +Use the RSqlStatement class instead.
1.766 +
1.767 +If the call to this function fails because of a database-specific type error
1.768 +(i.e. the error is categorised as ESqlDbError), then a textual description of
1.769 +the error can be obtained calling RSqlDatabase::LastErrorMessage().
1.770 +
1.771 +@param aSqlStmt A string of 8-bit wide characters containing one or more DDL/DML SQL statements;
1.772 + each statement is separated by a ';' character.
1.773 +@param aStatus Completion status of asynchronous request, one of the following:
1.774 + >=0, The operation has completed successfully. The number of database rows that were
1.775 + changed/inserted/deleted by the most recently completed DDL/DML sql statement.
1.776 + Exception: If the executed statement is "DELETE FROM <table>", then the function returns 0
1.777 + if the operation has completed successfully (disregarding the number of the deleted rows);
1.778 + KErrNoMemory, an out of memory condition has occured;
1.779 + KSqlErrGeneral, a syntax error has occurred - text describing the problem
1.780 + can be obtained by calling RSqlDatabase::LastErrorMessage();
1.781 + KErrDiskFull, There is no available disk space to complete the operation. If the executed statement is a DELETE
1.782 + statement, try to use the reserved disk space (if there is a reserved disk space) to complete the operation.
1.783 + In all other cases the database connection should be closed and some disk space freed before reopening
1.784 + the database;
1.785 + KErrPermissionDenied, the caller does not satisfy the relevant database security policies;
1.786 + Note that aStatus may be set with database specific errors categorised as ESqlDbError,
1.787 + and other system-wide error codes.
1.788 +
1.789 +
1.790 +@capability None, if current RSqlDatabase object represents a handle to a non-secure database;
1.791 + RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement modifies a secure database schema;
1.792 + RSqlSecurityPolicy::EReadPolicy or
1.793 + RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement reads from a secure database;
1.794 + RSqlSecurityPolicy::EWritePolicy or
1.795 + RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement writes to a secure database;
1.796 +
1.797 +@see RSqlStatement
1.798 +@see TSqlRetCodeClass::ESqlDbError
1.799 +@see RSqlDatabase::LastErrorMessage()
1.800 +@see RSqlSecurityPolicy
1.801 +@see RSqlSecurityPolicy::TPolicyType
1.802 +*/
1.803 +EXPORT_C void RSqlDatabase::Exec(const TDesC8& aSqlStmt, TRequestStatus& aStatus)
1.804 + {
1.805 + __SQLTRACE_BORDERVAR(TBuf<100> des16prnbuf);
1.806 + SQL_TRACE_BORDER(OstTraceExt2(TRACE_BORDER, RSQLDATABASE_EXECASYNC8_ENTRY, "Entry;0x%X;RSqlDatabase::ExecAsync8;aSqlStmt=%s", (TUint)this, __SQLPRNSTR8(aSqlStmt, des16prnbuf)));
1.807 + Impl().Exec(aSqlStmt, aStatus);
1.808 + SQL_TRACE_BORDER(OstTraceExt2(TRACE_BORDER, RSQLDATABASE_EXECASYNC8_EXIT, "Exit;0x%X;RSqlDatabase::ExecAsync8;aStatus.Int()=%d", (TUint)this, aStatus.Int()));
1.809 + }
1.810 +
1.811 +/**
1.812 +Retrieves a reference to the textual description of the error returned by the
1.813 +most recent call to any of the functions:
1.814 +- RSqlDatabase::Exec()
1.815 +- RSqlStatement::Exec()
1.816 +- RSqlStatement::Next()
1.817 +- RSqlStatement::Reset()
1.818 +
1.819 +Note that the function can only return a reference to text for
1.820 +database-specific type errors, i.e. those errors that are categorised as of
1.821 +type ESqlDbError.
1.822 +
1.823 +@return A non-modifiable pointer descriptor representing the most recent error
1.824 + message. Note that message may be NULL, i.e. the descriptor may have
1.825 + zero length.
1.826 +
1.827 +@see TSqlRetCodeClass::ESqlDbError
1.828 +@see RSqlDatabase::Exec()
1.829 +@see RSqlStatement::Exec()
1.830 +@see RSqlStatement::Next()
1.831 +@see RSqlStatement::Reset()
1.832 +
1.833 +@capability None
1.834 +*/
1.835 +EXPORT_C TPtrC RSqlDatabase::LastErrorMessage() const
1.836 + {
1.837 + TPtrC msg(Impl().LastErrorMessage());
1.838 + SQL_TRACE_BORDER(OstTraceExt2(TRACE_BORDER, RSQLDATABASE_LASTERRORMESSAGE, "0x%X;RSqlDatabase::LastErrorMessage;msg=%S", (TUint)this, __SQLPRNSTR(msg)));
1.839 + return msg;
1.840 + }
1.841 +
1.842 +/**
1.843 +Returns the ROWID of the most recent successful INSERT into the database
1.844 +from this database connection.
1.845 +
1.846 +@return >0, the ROWID of the most recent successful INSERT into the database
1.847 + from this database connection;
1.848 + 0, if no successful INSERTs have ever occurred from this database connection
1.849 + <0, if one of the system-wide error codes is returned
1.850 +
1.851 +@capability None
1.852 +*/
1.853 +EXPORT_C TInt64 RSqlDatabase::LastInsertedRowId() const
1.854 + {
1.855 + SQL_TRACE_BORDER(OstTrace1(TRACE_BORDER, RSQLDATABASE_LASTINSERTEDROWID_ENTRY, "Entry;0x%X;RSqlDatabase::LastInsertedRowId", (TUint)this));
1.856 + TInt64 rc = Impl().LastInsertedRowId();
1.857 + SQL_TRACE_BORDER(OstTraceExt2(TRACE_BORDER, RSQLDATABASE_LASTINSERTEDROWID_EXIT, "Exit;0x%X;RSqlDatabase::LastInsertedRowId;RowId=%lld", (TUint)this, rc));
1.858 + return rc;
1.859 + }
1.860 +
1.861 +/**
1.862 +Checks the database transaction state.
1.863 +
1.864 +@return True, if the database is in transaction, false otherwise.
1.865 +
1.866 +@capability None
1.867 +*/
1.868 +EXPORT_C TBool RSqlDatabase::InTransaction() const
1.869 + {
1.870 + SQL_TRACE_BORDER(OstTrace1(TRACE_BORDER, RSQLDATABASE_INTRABSACTION_ENTRY, "Entry;0x%X;RSqlDatabase::InTransaction", (TUint)this));
1.871 + TBool res = Impl().InTransaction();
1.872 + SQL_TRACE_BORDER(OstTraceExt2(TRACE_BORDER, RSQLDATABASE_INTRABSACTION_EXIT, "Exit;0x%X;RSqlDatabase::InTransaction;res=%d", (TUint)this, res));
1.873 + return res;
1.874 + }
1.875 +
1.876 +/**
1.877 +Returns the database file size, in bytes.
1.878 +
1.879 +@return >= 0, the operation has completed successfully. The number is the size of the main
1.880 + database file;
1.881 + KErrNoMemory, an out of memory condition has occurred;
1.882 + KErrTooBig, the database is too big and the size cannot fit into 32-bit signed integer;
1.883 + Note that database specific errors categorised as ESqlDbError, and
1.884 + other system-wide error codes may also be returned.
1.885 +
1.886 +@capability None
1.887 +*/
1.888 +EXPORT_C TInt RSqlDatabase::Size() const
1.889 + {
1.890 + SQL_TRACE_BORDER(OstTrace1(TRACE_BORDER, RSQLDATABASE_SIZE_ENTRY, "Entry;0x%X;RSqlDatabase::Size", (TUint)this));
1.891 + TInt rc = Impl().Size();
1.892 + SQL_TRACE_BORDER(OstTraceExt2(TRACE_BORDER, RSQLDATABASE_SIZE_EXIT, "Exit;0x%X;RSqlDatabase::Size;rc=%d", (TUint)this, rc));
1.893 + return rc;
1.894 + }
1.895 +
1.896 +/**
1.897 +Returns the database file size and free space, in bytes.
1.898 +
1.899 +@param aSize An output parameter. If the call was successfull the aSize object will contain information
1.900 + about the database size and database free space.
1.901 +@param aDbName The attached database name or KNullDesC for the main database
1.902 +
1.903 +@return KErrNone, The operation has completed succesfully;
1.904 + KErrBadName, Invalid (too long) attached database name;
1.905 + KSqlErrGeneral, There is no an attached database with aDbName name;
1.906 + Note that database specific errors categorised as ESqlDbError, and
1.907 + other system-wide error codes may also be returned.
1.908 +
1.909 +@capability None
1.910 +*/
1.911 +EXPORT_C TInt RSqlDatabase::Size(RSqlDatabase::TSize& aSize, const TDesC& aDbName) const
1.912 + {
1.913 + SQL_TRACE_BORDER(OstTraceExt2(TRACE_BORDER, RSQLDATABASE_SIZE2_ENTRY, "Entry;0x%X;RSqlDatabase::Size-2;aDbName=%S", (TUint)this, __SQLPRNSTR(aDbName)));
1.914 + TInt err = Impl().Size(aSize, aDbName);
1.915 + SQL_TRACE_BORDER(OstTraceExt4(TRACE_BORDER, RSQLDATABASE_SIZE2_EXIT, "Exit;0x%X;RSqlDatabase::Size-2;err=%d;aSize.iSize=%lld;aSize.iFree=%lld", (TUint)this, err, aSize.iSize, aSize.iFree));
1.916 + return err;
1.917 + }
1.918 +
1.919 +/**
1.920 +Compacts the database.
1.921 +This function should be used for databases that have been configured for a manual compaction during
1.922 +the database creation.
1.923 +The function has no effect if the database has been configured for an auto compaction.
1.924 +The function has no effect if the aSize argument value is zero.
1.925 +The function has no effect also if there aren't any free pages in the database file.
1.926 +If the database has been configured for a background compaction, then the function works as if the database
1.927 +has been configured for a manual compaction.
1.928 +
1.929 +@param aSize Can be one of:
1.930 + RSqlDatabase::EMaxCompaction - requests a full database compaction. All free pages
1.931 + (if any exists) will be removed;
1.932 + Positive 32-bit signed integer value - the server will attempt to compact the database removing
1.933 + at most aSize bytes from the database file, rounded up to the nearest page count,
1.934 + e.g. request for removing 1 byte will remove one free page from the database;
1.935 +
1.936 +@param aDbName The attached database name or KNullDesC for the main database
1.937 +
1.938 +@return Zero or positive integer - the operation has completed succesfully, the return value is the
1.939 + size of the removed free space in bytes,
1.940 + KErrArgument, Invalid aSize value;
1.941 + KErrBadName, Invalid (too long) attached database name;
1.942 + KSqlErrReadOnly, Read-only database;
1.943 + KSqlErrGeneral, There is no an attached database with aDbName name;
1.944 + Note that database specific errors categorised as ESqlDbError, and
1.945 + other system-wide error codes may also be returned.
1.946 +
1.947 +@capability None
1.948 +*/
1.949 +EXPORT_C TInt RSqlDatabase::Compact(TInt64 aSize, const TDesC& aDbName)
1.950 + {
1.951 + SQL_TRACE_BORDER(OstTraceExt3(TRACE_BORDER, RSQLDATABASE_COMPACT_ENTRY, "Entry;0x%X;RSqlDatabase::Compact;aSize=%lld;aDbName=%S", (TUint)this, aSize, __SQLPRNSTR(aDbName)));
1.952 + TInt rc = Impl().Compact(aSize, aDbName);
1.953 + SQL_TRACE_BORDER(OstTraceExt2(TRACE_BORDER, RSQLDATABASE_COMPACT_EXIT, "Exit;0x%X;RSqlDatabase::Compact;rc=%d", (TUint)this, rc));
1.954 + return rc;
1.955 + }
1.956 +
1.957 +/**
1.958 +Compacts the database asynchronously.
1.959 +This function should be used for databases that have been configured for a manual compaction during
1.960 +the database creation.
1.961 +The function has no effect if the database has been configured for an auto compaction.
1.962 +The function has no effect if the aSize argument value is zero.
1.963 +The function has no effect also if there aren't any free pages in the database file.
1.964 +If the database has been configured for a background compaction, then the function works as if the database
1.965 +has been configured for a manual compaction.
1.966 +
1.967 +@param aStatus Completion status of asynchronous request, one of the following:
1.968 + Zero or positive integer - the operation has completed succesfully, the return value is the
1.969 + size of the removed free space in bytes,
1.970 + KErrArgument, Invalid aSize value;
1.971 + KErrBadName, Invalid (too long) attached database name;
1.972 + KSqlErrReadOnly, Read-only database;
1.973 + KSqlErrGeneral, There is no an attached database with aDbName name;
1.974 + Note that database specific errors categorised as ESqlDbError, and
1.975 + other system-wide error codes may also be returned.
1.976 +
1.977 +
1.978 +@param aSize Can be one of:
1.979 + RSqlDatabase::EMaxCompaction - requests a full database compaction. All free pages
1.980 + (if any exists) will be removed;
1.981 + Positive 32-bit signed integer value - the server will attempt to compact the database removing
1.982 + at most aSize bytes from the database file, rounded up to the nearest page count,
1.983 + e.g. request for removing 1 byte will remove one free page from the database;
1.984 +
1.985 +@param aDbName The attached database name or KNullDesC for the main database
1.986 +
1.987 +@capability None
1.988 +*/
1.989 +EXPORT_C void RSqlDatabase::Compact(TInt64 aSize, TRequestStatus& aStatus, const TDesC& aDbName)
1.990 + {
1.991 + SQL_TRACE_BORDER(OstTraceExt3(TRACE_BORDER, RSQLDATABASE_COMPACTASYNC_ENTRY, "Entry;0x%X;RSqlDatabase::CompactAsync;aSize=%lld;aDbName=%S", (TUint)this, aSize, __SQLPRNSTR(aDbName)));
1.992 + Impl().Compact(aSize, aDbName, aStatus);
1.993 + SQL_TRACE_BORDER(OstTraceExt2(TRACE_BORDER, RSQLDATABASE_COMPACTASYNC_EXIT, "Exit;0x%X;RSqlDatabase::CompactAsync;aStatus.Int()=%d", (TUint)this, aStatus.Int()));
1.994 + }
1.995 +
1.996 +/**
1.997 +Reserves a predefined amount of disk space on the drive where the database file is.
1.998 +
1.999 +At the moment the max possible amount, allowed by the file server, is reserved on the database file drive.
1.1000 +Use this call to ensure that if your "delete records" transaction fails because of "out of
1.1001 +disk space" circumstances, you can get an access to the already reserved disk space and
1.1002 +complete your transaction successfully the second time.
1.1003 +
1.1004 +There is no strong, 100% guarantee, that the reserved disk space will always help the client
1.1005 +in "low memory" situations.
1.1006 +
1.1007 +@param aSpace This parameter is not used at the moment.
1.1008 +
1.1009 +@return KErrNone, The operation has completed succesfully;
1.1010 + KErrNoMemory, Out of memory condition has occured;
1.1011 + KErrAlreadyExists, The space has already been reserved;
1.1012 + Note that other system-wide error codes may also be returned.
1.1013 +
1.1014 +@see RSqlDatabase::FreeReservedSpace()
1.1015 +@see RSqlDatabase::GetReserveAccess()
1.1016 +@see RSqlDatabase::ReleaseReserveAccess()
1.1017 +*/
1.1018 +EXPORT_C TInt RSqlDatabase::ReserveDriveSpace(TInt aSize)
1.1019 + {
1.1020 + SQL_TRACE_BORDER(OstTraceExt2(TRACE_BORDER, RSQLDATABASE_RESERVEDRIVESPACE_ENTRY, "Entry;0x%X;RSqlDatabase::ReserveDriveSpace;aSize=%d", (TUint)this, aSize));
1.1021 + //Usage of the IPC call arguments:
1.1022 + //Arg 0: [out] requested size
1.1023 + TInt err = Impl().Session().SendReceive(ESqlSrvDbReserveDriveSpace, TIpcArgs(aSize));
1.1024 + SQL_TRACE_BORDER(OstTraceExt2(TRACE_BORDER, RSQLDATABASE_RESERVEDRIVESPACE_EXIT, "Exit;0x%X;RSqlDatabase::ReserveDriveSpace;err=%d", (TUint)this, err));
1.1025 + return err;
1.1026 + }
1.1027 +
1.1028 +/**
1.1029 +Frees the reserved disk space.
1.1030 +
1.1031 +@see RSqlDatabase::ReserveDriveSpace()
1.1032 +@see RSqlDatabase::GetReserveAccess()
1.1033 +@see RSqlDatabase::ReleaseReserveAccess()
1.1034 +*/
1.1035 +EXPORT_C void RSqlDatabase::FreeReservedSpace()
1.1036 + {
1.1037 + SQL_TRACE_BORDER(OstTrace1(TRACE_BORDER, RSQLDATABASE_FREERESERVEDSPACE_ENTRY, "Entry;0x%X;RSqlDatabase::FreeReservedSpace", (TUint)this));
1.1038 + __SQLTRACE_BORDERVAR(TInt err =) Impl().Session().SendReceive(ESqlSrvDbFreeReservedSpace);
1.1039 + SQL_TRACE_BORDER(OstTraceExt2(TRACE_BORDER, RSQLDATABASE_FREERESERVEDSPACE_EXIT, "Exit;0x%X;RSqlDatabase::FreeReservedSpace;err=%d", (TUint)this, err));
1.1040 + }
1.1041 +
1.1042 +/**
1.1043 +Gives the client an access to the already reserved disk space.
1.1044 +
1.1045 +@return KErrNone, The operation has completed succesfully;
1.1046 + KErrNotFound, An attempt is made to get an access to a disk space, which is not reserved yet;
1.1047 + KErrInUse, An access to the reserved space has already been given;
1.1048 + Note that other system-wide error codes may also be returned.
1.1049 +
1.1050 +@see RSqlDatabase::ReserveDriveSpace()
1.1051 +@see RSqlDatabase::FreeReservedSpace()
1.1052 +@see RSqlDatabase::ReleaseReserveAccess()
1.1053 +*/
1.1054 +EXPORT_C TInt RSqlDatabase::GetReserveAccess()
1.1055 + {
1.1056 + SQL_TRACE_BORDER(OstTrace1(TRACE_BORDER, RSQLDATABASE_GETRESERVEACCESS_ENTRY, "Exit;0x%X;RSqlDatabase::GetReserveAccess", (TUint)this));
1.1057 + TInt err = Impl().Session().SendReceive(ESqlSrvDbGetReserveAccess);
1.1058 + SQL_TRACE_BORDER(OstTraceExt2(TRACE_BORDER, RSQLDATABASE_GETRESERVEACCESS_EXIT, "Exit;0x%X;RSqlDatabase::GetReserveAccess;err=%d", (TUint)this, err));
1.1059 + return err;
1.1060 + }
1.1061 +
1.1062 +/**
1.1063 +Releases the access to the reserved disk space.
1.1064 +
1.1065 +@see RSqlDatabase::ReserveDriveSpace()
1.1066 +@see RSqlDatabase::FreeReservedSpace()
1.1067 +@see RSqlDatabase::GetReserveAccess()
1.1068 +*/
1.1069 +EXPORT_C void RSqlDatabase::ReleaseReserveAccess()
1.1070 + {
1.1071 + SQL_TRACE_BORDER(OstTrace1(TRACE_BORDER, RSQLDATABASE_RELEASERESERVEACCESS_ENTRY, "Entry;0x%X;RSqlDatabase::ReleaseReserveAccess", (TUint)this));
1.1072 + __SQLTRACE_BORDERVAR(TInt err =) Impl().Session().SendReceive(ESqlSrvDbReleaseReserveAccess);
1.1073 + SQL_TRACE_BORDER(OstTraceExt2(TRACE_BORDER, RSQLDATABASE_RELEASERESERVEACCESS_EXIT, "Exit;0x%X;RSqlDatabase::ReleaseReserveAccess;err=%d", (TUint)this, err));
1.1074 + }
1.1075 +
1.1076 +/**
1.1077 +Returns a reference to the implementation object of RSqlDatabase - CSqlDatabaseImpl.
1.1078 +
1.1079 +@panic SqlDb 2 Create() or Open() has not previously been called on this RSqlDatabase object.
1.1080 +
1.1081 +@internalComponent
1.1082 +*/
1.1083 +CSqlDatabaseImpl& RSqlDatabase::Impl() const
1.1084 + {
1.1085 + __ASSERT_ALWAYS(iImpl != NULL, __SQLPANIC(ESqlPanicInvalidObj));
1.1086 + return *iImpl;
1.1087 + }