--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/persistentstorage/sql/SRC/Client/SQLDatabase.cpp Fri Jan 22 11:06:30 2010 +0200
@@ -0,0 +1,1074 @@
+// Copyright (c) 2005-2009 Nokia Corporation and/or its subsidiary(-ies).
+// All rights reserved.
+// This component and the accompanying materials are made available
+// under the terms of "Eclipse Public License v1.0"
+// which accompanies this distribution, and is available
+// at the URL "http://www.eclipse.org/legal/epl-v10.html".
+//
+// Initial Contributors:
+// Nokia Corporation - initial contribution.
+//
+// Contributors:
+//
+// Description:
+//
+
+#include "SqlPanic.h" //ESqlPanicInvalidObj, ESqlPanicObjExists
+#include "SqlDatabaseImpl.h" //CSqlDatabaseImpl
+
+/**
+Gets the category of the return code value that is returned by
+a call to the SQL API.
+
+A call to the SQL API may complete with a non-zero return code indicating that some
+unexpected behaviour has occurred. This can be categorised in a number of ways,
+for example, as a Symbian OS error, or as a database error etc etc.
+
+This function takes the return code value and gets the category associated with
+that value. The categories are defined by the enum values of
+the TSqlRetCodeClass enum.
+
+@param aSqlRetCode The return code value returned from a call to any (member)
+ function that forms part of the SQL interface.
+
+@return The category associated with the specified return code value. This is
+ one of the TSqlRetCodeClass enum values.
+
+@see TSqlRetCodeClass
+
+@capability None
+
+@publishedAll
+@released
+*/
+EXPORT_C TSqlRetCodeClass SqlRetCodeClass(TInt aSqlRetCode)
+ {
+ if(aSqlRetCode >= 0)
+ {
+ return ESqlInformation;
+ }
+ else if(aSqlRetCode <= KSqlErrGeneral)
+ {
+ return ESqlDbError;
+ }
+ return ESqlOsError;
+ }
+
+/**
+Initialises the pointer to the implementation object to NULL.
+
+@capability None
+*/
+EXPORT_C RSqlDatabase::RSqlDatabase() :
+ iImpl(NULL)
+ {
+ }
+
+/**
+Creates a new shared non-secure or private secure database.
+
+@param aDbFileName The full path name of the file that is to host the database.
+@param aConfig the configuration string "PARAM=VALUE;....".
+ The following parameters can be set using the configuration string:
+ cache_size=value - where "value" is the cache size in pages.
+ "value" must be a positive integer number;
+ page_size=value - where "value" is the page size in bytes.
+ The "page_size" parameter can accept the following values:
+ 512, 1024, 2048, 4096, 8192, 16384, 32768;
+ encoding=value - where "value" is the desired database encoding.
+ "value" could be either "UTF-8" or "UTF-16";
+ compaction=value - where "value" is the desired compaction mode.
+ "value" could be either "background", "synchronous" or "manual".
+
+@return KErrNone, the operation has completed successfully;
+ KErrNoMemory, an out of memory condition has occurred;
+ KErrBadName, the file name is invalid - it has either a zero length or it is the name of a directory;
+ KErrAlreadyExists, the file already exists;
+ KErrNotReady, the drive does not exist or is not ready;
+ KErrInUse, the file is already open;
+ KErrArgument, the file name refers to a secure database, invalid configuration string, invalid parameter values
+ in the configuration string.
+ Note that database specific errors categorised as ESqlDbError, and
+ other system-wide error codes may also be returned.
+
+@capability None
+*/
+EXPORT_C TInt RSqlDatabase::Create(const TDesC& aDbFileName, const TDesC8* aConfig)
+ {
+ SQLUTRACE_PROFILER(this);
+ SYMBIAN_TRACE_SQL_EVENTS_ONLY(UTF::Printf(UTF::TTraceContext(UTF::EInternals), KStrParam16, 1, &aDbFileName));
+ SYMBIAN_TRACE_SQL_EVENTS_ONLY(aConfig ? (void)UTF::Printf(UTF::TTraceContext(UTF::EInternals),
+ KStrParam, 2, aConfig) : void(0));
+
+ TRAPD(err, iImpl = CSqlDatabaseImpl::NewL(ESqlSrvDbCreate, aDbFileName, NULL, aConfig));
+ return err;
+ }
+
+/**
+Creates a new shared secure database.
+
+@param aDbFileName The name of the file that is to host the database.
+ The format of the name is \<drive\>:\<[SID]database file name excluding the path\>.
+ "[SID]" refers to the application SID.
+@param aSecurityPolicy The container for the security policies.
+@param aConfig the configuration string "PARAM=VALUE;...."
+ The following parameters can be set using the configuration string:
+ cache_size=value - where "value" is the cache size in pages.
+ "value" must be a positive integer number;
+ page_size=value - where "value" is the page size in bytes.
+ The "page_size" parameter can accept the following values:
+ 512, 1024, 2048, 4096, 8192, 16384, 32768;
+ encoding=value - where "value" is the desired database encoding.
+ "value" could be either "UTF-8" or "UTF-16";
+ compaction=value - where "value" is the desired compaction mode.
+ "value" could be either "background", "synchronous" or "manual".
+
+
+@return KErrNone, the operation has completed successfully;
+ KErrNoMemory, an out of memory condition has occurred;
+ KErrArgument, the file name does not refer to a secure database;
+ KErrArgument, system table name found in the security policies (aSecurityPolicy),
+ invalid configuration string, invalid parameter values
+ in the configuration string;
+ KErrBadName, the file name is invalid - it has either a zero length or it is the name of a directory;
+ KErrAlreadyExists, the file already exists;
+ KErrNotReady, the drive does not exist or is not ready;
+ KErrInUse, the file is already open;
+ KErrPermissionDenied, the caller does not satisfy the relevant database security policies.
+ Note that database specific errors categorised as ESqlDbError, and
+ other system-wide error codes may also be returned.
+
+@capability The calling application must satisfy the database policy of RSqlSecurityPolicy::ESchemaPolicy type;
+
+@see RSqlSecurityPolicy
+@see RSqlSecurityPolicy::TPolicyType
+*/
+EXPORT_C TInt RSqlDatabase::Create(const TDesC& aDbFileName,
+ const RSqlSecurityPolicy& aSecurityPolicy, const TDesC8* aConfig)
+ {
+ SQLUTRACE_PROFILER(this);
+ SYMBIAN_TRACE_SQL_EVENTS_ONLY(UTF::Printf(UTF::TTraceContext(UTF::EInternals), KStrParam16, 1, &aDbFileName));
+ SYMBIAN_TRACE_SQL_EVENTS_ONLY(aConfig ? (void)UTF::Printf(UTF::TTraceContext(UTF::EInternals),
+ KStrParam, 2, aConfig) : void(0));
+
+ TRAPD(err, iImpl = CSqlDatabaseImpl::NewL(ESqlSrvDbCreateSecure, aDbFileName,
+ &aSecurityPolicy.Impl(), aConfig));
+ return err;
+ }
+
+/**
+Opens an existing database, which can be:
+@code
+ - shared non-secure;
+ - shared secure;
+ - private secure;
+@endcode
+
+@param aDbFileName The name of the file that hosts the database. If this is
+ a secure database, then the format of the name must be:
+ \<drive\>:\<[SID]database file name excluding the path\>.
+ If this is a non-secure database, then aDbFileName has to be the full database file name.
+ "[SID]" refers to SID of the application which created the database.
+@param aConfig the configuration string "PARAM=VALUE;...."
+ The following parameters can be set using the configuration string:
+ cache_size=value - where "value" is the cache size in pages.
+ "value" must be a positive integer number;
+
+
+@return KErrNone, the operation has completed successfully;
+ KErrNoMemory, an out of memory condition has occurred;
+ KErrBadName, the file name is invalid - it has either a zero length or it is the name of a directory;
+ KErrNotReady, the drive does not exist or is not ready;
+ KErrInUse, the file is already open;
+ KErrNotFound, database file not found;
+ KErrArgument, invalid configuration string, invalid parameter values
+ in the configuration string;
+ KErrGeneral, missing or invalid security policies (if the database to be opened is a secure database);
+ KErrPermissionDenied, the caller does not satisfy the relevant database security policies;
+ KErrNotSupported, incompatible SQL security version (if the database to be opened is a secure database).
+ Note that database specific errors categorised as ESqlDbError, and
+ other system-wide error codes may also be returned.
+
+@capability None, if aDbFileName refers to a non-secure database;
+ RSqlSecurityPolicy::ESchemaPolicy or
+ RSqlSecurityPolicy::EReadPolicy or
+ RSqlSecurityPolicy::EWritePolicy database policy type, if aDbFileName refers to a secure database;
+
+@see RSqlSecurityPolicy
+@see RSqlSecurityPolicy::TPolicyType
+*/
+EXPORT_C TInt RSqlDatabase::Open(const TDesC& aDbFileName, const TDesC8* aConfig)
+ {
+ SQLUTRACE_PROFILER(this);
+ SYMBIAN_TRACE_SQL_EVENTS_ONLY(UTF::Printf(UTF::TTraceContext(UTF::EInternals), KStrParam16, 1, &aDbFileName));
+ SYMBIAN_TRACE_SQL_EVENTS_ONLY(aConfig ? (void)UTF::Printf(UTF::TTraceContext(UTF::EInternals),
+ KStrParam, 2, aConfig) : void(0));
+
+ TRAPD(err, iImpl = CSqlDatabaseImpl::NewL(ESqlSrvDbOpen, aDbFileName, NULL, aConfig));
+ return err;
+ }
+
+/**
+Creates a new shared non-secure or private secure database.
+
+@param aDbFileName The full path name of the file that is to host the database.
+@param aConfig the configuration string "PARAM=VALUE;...."
+ The following parameters can be set using the configuration string:
+ cache_size=value - where "value" is the cache size in pages.
+ "value" must be a positive integer number;
+ page_size=value - where "value" is the page size in bytes.
+ The "page_size" parameter can accept the following values:
+ 512, 1024, 2048, 4096, 8192, 16384, 32768;
+ encoding=value - where "value" is the desired database encoding.
+ "value" could be either "UTF-8" or "UTF-16";
+ compaction=value - where "value" is the desired compaction mode.
+ "value" could be either "background", "synchronous" or "manual".
+
+
+@leave KErrNoMemory, an out of memory condition has occurred;
+ KErrBadName, the file name is invalid - it has either a zero length or it is the name of a directory;
+ KErrAlreadyExists, the file already exists;
+ KErrNotReady, the drive does not exist or is not ready;
+ KErrInUse, the file is already open;
+ KErrArgument, the file name refers to a secure database,
+ invalid configuration string, invalid parameter values
+ in the configuration string.
+ Note that the function may leave with database specific errors categorised as ESqlDbError and
+ other system-wide error codes.
+
+@capability None
+*/
+EXPORT_C void RSqlDatabase::CreateL(const TDesC& aDbFileName, const TDesC8* aConfig)
+ {
+ SQLUTRACE_PROFILER(this);
+ SYMBIAN_TRACE_SQL_EVENTS_ONLY(UTF::Printf(UTF::TTraceContext(UTF::EInternals), KStrParam16, 1, &aDbFileName));
+ SYMBIAN_TRACE_SQL_EVENTS_ONLY(aConfig ? (void)UTF::Printf(UTF::TTraceContext(UTF::EInternals),
+ KStrParam, 2, aConfig) : void(0));
+
+ iImpl = CSqlDatabaseImpl::NewL(ESqlSrvDbCreate, aDbFileName, NULL, aConfig);
+ }
+
+/**
+Creates a new shared secure database.
+@param aDbFileName The name of the file that is to host the database.
+ The format of the name is \<drive\>:\<[SID]database file name excluding the path\>.
+ "[SID]" refers to the application SID.
+@param aSecurityPolicy The container for the security policies.
+@param aConfig the configuration string "PARAM=VALUE;...."
+ The following parameters can be set using the configuration string:
+ cache_size=value - where "value" is the cache size in pages.
+ "value" must be a positive integer number;
+ page_size=value - where "value" is the page size in bytes.
+ The "page_size" parameter can accept the following values:
+ 512, 1024, 2048, 4096, 8192, 16384, 32768;
+ encoding=value - where "value" is the desired database encoding.
+ "value" could be either "UTF-8" or "UTF-16";
+
+ compaction=value - where "value" is the desired compaction mode.
+ "value" could be either "background", "synchronous" or "manual".
+
+@leave KErrNoMemory, an out of memory condition has occurred;
+ KErrArgument, the file name does not refer to a secure database;
+ KErrArgument, system table name found in the security policies (aSecurityPolicy),
+ invalid configuration string, invalid parameter values
+ in the configuration string;
+ KErrBadName, the file name is invalid - it has either a zero length or it is the name of a directory;
+ KErrAlreadyExists, the file already exists;
+ KErrNotReady, the drive does not exist or is not ready;
+ KErrInUse, the file is already open;
+ KErrPermissionDenied, the caller does not satisfy the relevant database security policies.
+ Note that the function may leave with database specific errors categorised as ESqlDbError and
+ other system-wide error codes.
+
+@capability The calling application must satisfy the database policy of RSqlSecurityPolicy::ESchemaPolicy type;
+
+@see RSqlSecurityPolicy
+@see RSqlSecurityPolicy::TPolicyType
+*/
+EXPORT_C void RSqlDatabase::CreateL(const TDesC& aDbFileName,
+ const RSqlSecurityPolicy& aSecurityPolicy, const TDesC8* aConfig)
+ {
+ SQLUTRACE_PROFILER(this);
+ SYMBIAN_TRACE_SQL_EVENTS_ONLY(UTF::Printf(UTF::TTraceContext(UTF::EInternals), KStrParam16, 1, &aDbFileName));
+ SYMBIAN_TRACE_SQL_EVENTS_ONLY(aConfig ? (void)UTF::Printf(UTF::TTraceContext(UTF::EInternals),
+ KStrParam, 2, aConfig) : void(0));
+
+ iImpl = CSqlDatabaseImpl::NewL(ESqlSrvDbCreateSecure, aDbFileName,
+ &aSecurityPolicy.Impl(), aConfig);
+ }
+
+/**
+Opens an existing database, which can be:
+@code
+ - shared non-secure;
+ - shared secure;
+ - private secure;
+@endcode
+
+@param aDbFileName The name of the file that hosts the database. If this is
+ a secure database, then the format of the name must be:
+ \<drive\>:\<[SID]database file name excluding the path\>.
+ If this is a non-secure database, then aDbFileName has to be the full database file name.
+ "[SID]" refers to SID of the application which created the database.
+@param aConfig the configuration string "PARAM=VALUE;...."
+ The following parameters can be set using the configuration string:
+ cache_size=value - where "value" is the cache size in pages.
+ "value" must be a positive integer number;
+
+
+@leave KErrNoMemory, an out of memory condition has occurred;
+ KErrBadName, the file name is invalid - it has either a zero length or it is the name of a directory;
+ KErrNotReady, the drive does not exist or is not ready;
+ KErrInUse, the file is already open;
+ KErrNotFound, database file not found;
+ KErrArgument, invalid configuration string, invalid parameter values
+ in the configuration string;
+ KErrGeneral, missing or invalid security policies (if the database to be opened is a secure database);
+ KErrPermissionDenied, the caller does not satisfy the relevant database security policies;
+ KErrNotSupported, incompatible SQL security version (if the database to be opened is a secure database).
+ Note that the function may leave with database specific errors categorised as ESqlDbError and
+ other system-wide error codes.
+
+@capability None, if aDbFileName refers to a non-secure database;
+ RSqlSecurityPolicy::ESchemaPolicy or
+ RSqlSecurityPolicy::EReadPolicy or
+ RSqlSecurityPolicy::EWritePolicy database policy type, if aDbFileName refers to a secure database;
+
+@see RSqlSecurityPolicy
+@see RSqlSecurityPolicy::TPolicyType
+*/
+EXPORT_C void RSqlDatabase::OpenL(const TDesC& aDbFileName, const TDesC8* aConfig)
+ {
+ SQLUTRACE_PROFILER(this);
+ SYMBIAN_TRACE_SQL_EVENTS_ONLY(UTF::Printf(UTF::TTraceContext(UTF::EInternals), KStrParam16, 1, &aDbFileName));
+ SYMBIAN_TRACE_SQL_EVENTS_ONLY(aConfig ? (void)UTF::Printf(UTF::TTraceContext(UTF::EInternals),
+ KStrParam, 2, aConfig) : void(0));
+
+ iImpl = CSqlDatabaseImpl::NewL(ESqlSrvDbOpen, aDbFileName, NULL, aConfig);
+ }
+
+/**
+Closes this handle to the database.
+
+The function frees memory and any allocated resources.
+
+You can reuse this object, but you must reinitialise it by calling
+RSqlDatabase::Create() or RSqlDatabase::Open().
+
+@see RSqlDatabase::Create()
+@see RSqlDatabase::Open()
+
+@capability None
+*/
+EXPORT_C void RSqlDatabase::Close()
+ {
+ SQLUTRACE_PROFILER(this);
+ delete iImpl;
+ iImpl = NULL;
+ }
+
+/**
+Attaches an existing database to the current database connection.
+
+The attached database can be read, written or modified.
+One database can be attched multiple times to the same connection, using different logical database names.
+Tables in an attached database can be referred to using "database-name.table-name" syntax.
+If an attached table doesn't have a duplicate table name in the main database, it doesn't
+require a database name prefix.
+
+Transactions involving multiple attached databases are atomic.
+
+@param aDbFileName The name of the file that hosts the database. If this is
+ a secure database, then the format of the name must be:
+ \<drive\>:\<[SID]database file name excluding the path\>.
+ If this is a private or shared non-secure database, then aDbFileName has to be the full
+ database file name. "[SID]" refers to SID of the application which created the attached database.
+@param aDbName Logical database name. It must be unique (per database connection). This is the name which can
+ be used for accessing tables in the attached database. The syntax is "database-name.table-name".
+
+@return KErrNone, the operation has completed successfully;
+ KErrNoMemory, an out of memory condition has occurred;
+ KErrBadName, the file name is invalid - it has either a zero length or it is the name of a directory;
+ KErrNotReady, the drive does not exist or is not ready;
+ KErrInUse, the file is already open;
+ KErrNotFound, database file not found;
+ KErrGeneral, missing or invalid security policies (if the database to be opened is a secure database);
+ KErrPermissionDenied, the caller does not satisfy the relevant database security policies;
+ KErrNotSupported, incompatible SQL security version (if the database to be opened is a secure database).
+ Note that database specific errors categorised as ESqlDbError, and
+ other system-wide error codes may also be returned.
+
+@capability None, if aDbFileName refers to a non-secure database;
+ RSqlSecurityPolicy::ESchemaPolicy or
+ RSqlSecurityPolicy::EReadPolicy or
+ RSqlSecurityPolicy::EWritePolicy database policy type, if aDbFileName refers to a secure database;
+
+@see RSqlSecurityPolicy
+@see RSqlSecurityPolicy::TPolicyType
+*/
+EXPORT_C TInt RSqlDatabase::Attach(const TDesC& aDbFileName, const TDesC& aDbName)
+ {
+ SQLUTRACE_PROFILER(this);
+ SYMBIAN_TRACE_SQL_EVENTS_ONLY(UTF::Printf(UTF::TTraceContext(UTF::EInternals), KStrStrParam16, &aDbFileName, &aDbName));
+
+ return Impl().Attach(aDbFileName, aDbName);
+ }
+
+/**
+Detaches previously attached database.
+
+@param aDbName Logical database name.
+ The logical name of the database to be detached.
+
+@return KErrNone, the operation completed has successfully;
+ KErrNotFound, no attached database with aDbName name;
+ Note that database specific errors categorised as ESqlDbError, and
+ other system-wide error codes may also be returned.
+
+@capability None
+*/
+EXPORT_C TInt RSqlDatabase::Detach(const TDesC& aDbName)
+ {
+ SQLUTRACE_PROFILER(this);
+ SYMBIAN_TRACE_SQL_EVENTS_ONLY(UTF::Printf(UTF::TTraceContext(UTF::EInternals), KStrParam16, 1, &aDbName));
+
+ return Impl().Detach(aDbName);
+ }
+
+/**
+Copies a database file to the specified location.
+
+Note that this is a static function, and its use is not
+restricted to any specific RSqlDatabase instance.
+
+@param aSrcDbFileName Source database file name.
+ If this is a secure database, then the format of the name must be:
+ \<drive\>:\<[SID]database file name excluding the path\>.
+ If this is a non-secure database, then aDbFileName has to be the full database file name.
+ "[SID]" refers to SID of the application which created the database.
+@param aDestDbFileName Destination database file name.
+ If this is a secure database, then the format of the name must be:
+ \<drive\>:\<[SID]database file name excluding the path\>.
+ If this is a non-secure database, then aDbFileName has to be the full database file name.
+ "[SID]" refers to SID of the application which performs the copying operation.
+
+The allowed copying operations are:
+- secure to secure database. Only the application created the database is allowed to copy it.
+- non-secure to non-secure database. No restrictions apply to this operation.
+
+@return KErrNone, the operation completed has successfully;
+ KErrBadName, the file name is invalid - it has either a zero length or it is the name of a directory;
+ KErrNotReady, the drive does not exist or is not ready;
+ KErrInUse, the file is already open;
+ KErrNotFound, database file not found;
+ KErrPermissionDenied, the SID of the calling application does not match the SID of source or destination database.
+ Note that other system-wide error codes may also be returned.
+
+@capability None
+
+Note that if the source database is a secure database, only the application, which created the database, can copy it.
+*/
+EXPORT_C TInt RSqlDatabase::Copy(const TDesC& aSrcDbFileName, const TDesC& aDestDbFileName)
+ {
+ SQLUTRACE_PROFILER(0);
+ SYMBIAN_TRACE_SQL_EVENTS_ONLY(UTF::Printf(UTF::TTraceContext(UTF::EInternals), KStrStrParam16,
+ &aSrcDbFileName, &aDestDbFileName));
+
+ return CSqlDatabaseImpl::Copy(aSrcDbFileName, aDestDbFileName);
+ }
+
+/**
+Deletes the specified database file.
+
+Note that this is a static function, and its use is not
+restricted to any specific RSqlDatabase instance.
+
+@param aDbFileName The name of the database file.
+ If this is a secure database, then the format of the name must be:
+ \<drive\>:\<[SID]database file name excluding the path\>.
+ If this is a private or shared non-secure database, then aDbFileName has to be the
+ full database file name. "[SID]" refers to SID of the application which created the database.
+
+@return KErrNone, the operation has completed successfully;
+ KErrBadName, the file name is invalid - it has either a zero length or it is the name of a directory;
+ KErrNotReady, the drive does not exist or is not ready;
+ KErrInUse, the database file is in use;
+ KErrNotFound, the database file cannot be found;
+ KErrAccessDenied, access to the database file is denied (e.g. it might be a read-only file);
+ KErrPermissionDenied, the SID of the calling application does not match the SID of the database;
+ Note that other system-wide error codes may also be returned.
+
+@capability None
+
+Note that if the database to be deleted is a secure database, only the application, which created the database, can delete it.
+*/
+EXPORT_C TInt RSqlDatabase::Delete(const TDesC& aDbFileName)
+ {
+ SQLUTRACE_PROFILER(0);
+ SYMBIAN_TRACE_SQL_EVENTS_ONLY(UTF::Printf(UTF::TTraceContext(UTF::EInternals), KStrParam16, 1, &aDbFileName));
+
+ return CSqlDatabaseImpl::Delete(aDbFileName);
+ }
+
+/**
+Initializes aSecurityPolicy output parameter with a copy of the database security policies.
+The caller is responsible for destroying the initialized aSecurityPolicy paramemter.
+
+Note that there may be no security policies in force for this database.
+
+@param aSecurityPolicy Input/Output parameter, which will be initialized with the database
+ security policies.
+
+@return KErrNone, the operation has completed successfully;
+ KErrNotSupported, the current database is not a secure database;
+ KErrNoMemory, an out of memory condition has occurred;
+
+@capability None
+*/
+EXPORT_C TInt RSqlDatabase::GetSecurityPolicy(RSqlSecurityPolicy& aSecurityPolicy) const
+ {
+ SQLUTRACE_PROFILER(this);
+ TRAPD(err, CSqlSecurityPolicy* securityPolicy = Impl().CloneSecurityPolicyL();
+ aSecurityPolicy.Set(*securityPolicy));
+
+ return err;
+ }
+
+/**
+Initializes aSecurityPolicy output parameter with a copy of the database security policies.
+The caller is responsible for destroying the initialized aSecurityPolicy paramemter.
+
+Note that there may be no security policies in force for this database.
+
+@param aSecurityPolicy Input/Output parameter, which will be initialized with the database
+ security policies.
+
+@leave KErrNotSupported, the current database is not a secure database;
+ KErrNoMemory, an out of memory condition has occurred;
+
+@capability None
+*/
+EXPORT_C void RSqlDatabase::GetSecurityPolicyL(RSqlSecurityPolicy& aSecurityPolicy) const
+ {
+ SQLUTRACE_PROFILER(this);
+ CSqlSecurityPolicy* securityPolicy = Impl().CloneSecurityPolicyL();
+ aSecurityPolicy.Set(*securityPolicy);
+ }
+
+/**
+Sets the transaction isolation level for the database.
+
+A transaction isolation level defines the way in which a transaction
+interacts with other transactions that may be in progress concurrently.
+
+Transaction isolation levels are defined by the values of the
+RSqlDatabase::TIsolationLevel enum.
+
+The default isolation level is RSqlDatabase::ESerializable
+
+Note that the isolation level is not a persistent property of the database.
+It is set to the default value, i.e. RSqlDatabase::ESerializable,
+whenever the database is created or opened.
+
+@param aIsolationLevel The isolation level to be set.
+
+@return KErrNone, if the operation has completed successfully;
+ KErrNotSupported, invalid (not supported) transaction isolation level;
+
+@see RSqlDatabase::TIsolationLevel
+
+@capability None
+*/
+EXPORT_C TInt RSqlDatabase::SetIsolationLevel(RSqlDatabase::TIsolationLevel aIsolationLevel)
+ {
+ SQLUTRACE_PROFILER(this);
+ return Impl().SetIsolationLevel(aIsolationLevel);
+ }
+
+/**
+Executes one or more 16-bit SQL statements.
+
+This method should be used for executing DDL/DML statements, but note the following point:
+- if an SQL statement contains one or more parameters, then the function will execute it,
+giving the parameters default NULL values.
+
+This class (RSqlDatabase) does not offer functions for setting the parameter values.
+Use the RSqlStatement class instead.
+
+If the call to this function fails because of a database-specific type error
+(i.e. the error is categorised as of type ESqlDbError), then a textual description of
+the error can be obtained calling RSqlDatabase::LastErrorMessage().
+
+@param aSqlStmt A string of 16-bit wide characters containing one or more DDL/DML SQL statements;
+ each statement is separated by a ';' character.
+
+@return >=0, The operation has completed successfully. The number of database rows that were
+ changed/inserted/deleted by the most recently completed DDL/DML sql statement.
+ Exception: If the executed statement is "DELETE FROM <table>", then the function returns 0
+ if the operation has completed successfully (disregarding the number of the deleted rows);
+ KErrNoMemory, an out of memory condition has occured;
+ KSqlErrGeneral, a syntax error has occurred - text describing the problem
+ can be obtained by calling RSqlDatabase::LastErrorMessage();
+ KErrDiskFull, There is no available disk space to complete the operation. If the executed statement is a DELETE
+ statement, try to use the reserved disk space (if there is a reserved disk space) to complete the operation.
+ In all other cases the database connection should be closed and some disk space freed before reopening
+ the database;
+ KErrPermissionDenied, the caller does not satisfy the relevant database security policies.
+ Note that database specific errors categorised as ESqlDbError, and
+ other system-wide error codes may also be returned.
+
+@capability None, if current RSqlDatabase object represents a handle to a non-secure database;
+ RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement modifies a secure database schema;
+ RSqlSecurityPolicy::EReadPolicy or
+ RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement reads from a secure database;
+ RSqlSecurityPolicy::EWritePolicy or
+ RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement writes to a secure database;
+
+@see RSqlStatement
+@see TSqlRetCodeClass::ESqlDbError
+@see RSqlDatabase::LastErrorMessage()
+@see RSqlSecurityPolicy
+@see RSqlSecurityPolicy::TPolicyType
+*/
+EXPORT_C TInt RSqlDatabase::Exec(const TDesC& aSqlStmt)
+ {
+ SQLUTRACE_PROFILER(this);
+ SYMBIAN_TRACE_SQL_EVENTS_ONLY(UTF::Printf(UTF::TTraceContext(UTF::EInternals), KStrParam16, 1, &aSqlStmt));
+
+ return Impl().Exec(aSqlStmt);
+ }
+
+/**
+Executes one or more 8-bit SQL statements.
+
+This method should be used for executing DDL/DML statements, but note the following point:
+- if an SQL statement contains one or more parameters, then the function will execute it,
+giving the parameters default NULL values.
+
+This class (RSqlDatabase) does not offer functions for setting the parameter values.
+Use the RSqlStatement class instead.
+
+If the call to this function fails because of a database-specific type error
+(i.e. the error is categorised as ESqlDbError), then a textual description of
+the error can be obtained calling RSqlDatabase::LastErrorMessage().
+
+@param aSqlStmt A string of 8-bit wide characters containing one or more DDL/DML SQL statements;
+ each statement is separated by a ';' character.
+
+@return >=0, The operation has completed successfully. The number of database rows that were
+ changed/inserted/deleted by the most recently completed DDL/DML sql statement.
+ Exception: If the executed statement is "DELETE FROM <table>", then the function returns 0
+ if the operation has completed successfully (disregarding the number of the deleted rows);
+ KErrNoMemory, an out of memory condition has occured;
+ KSqlErrGeneral, a syntax error has occurred - text describing the problem
+ can be obtained by calling RSqlDatabase::LastErrorMessage();
+ KErrDiskFull, There is no available disk space to complete the operation. If the executed statement is a DELETE
+ statement, try to use the reserved disk space (if there is a reserved disk space) to complete the operation.
+ In all other cases the database connection should be closed and some disk space freed before reopening
+ the database;
+ KErrPermissionDenied, the caller does not satisfy the relevant database security policies;
+ Note that database specific errors categorised as ESqlDbError, and
+ other system-wide error codes may also be returned.
+
+@capability None, if current RSqlDatabase object represents a handle to a non-secure database;
+ RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement modifies a secure database schema;
+ RSqlSecurityPolicy::EReadPolicy or
+ RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement reads from a secure database;
+ RSqlSecurityPolicy::EWritePolicy or
+ RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement writes to a secure database;
+
+@see RSqlStatement
+@see TSqlRetCodeClass::ESqlDbError
+@see RSqlDatabase::LastErrorMessage()
+@see RSqlSecurityPolicy
+@see RSqlSecurityPolicy::TPolicyType
+*/
+EXPORT_C TInt RSqlDatabase::Exec(const TDesC8& aSqlStmt)
+ {
+ SQLUTRACE_PROFILER(this);
+ SYMBIAN_TRACE_SQL_EVENTS_ONLY(UTF::Printf(UTF::TTraceContext(UTF::EInternals), KStrParam, 1, &aSqlStmt));
+
+ return Impl().Exec(aSqlStmt);
+ }
+
+/**
+Executes one or more 16-bit SQL statements asynchronously to allow client to avoid being blocked
+by server activity.
+
+No other operations can be performed on current RSqlDatabase object and RSqlStatement objects using it
+until the asynchronous operation completes.
+
+This method should be used for executing DDL/DML statements, but note the following point:
+- if an SQL statement contains one or more parameters, then the function will execute it,
+giving the parameters default NULL values.
+
+This class (RSqlDatabase) does not offer functions for setting the parameter values.
+Use the RSqlStatement class instead.
+
+If the call to this function fails because of a database-specific type error
+(i.e. the error is categorised as ESqlDbError), then a textual description of
+the error can be obtained calling RSqlDatabase::LastErrorMessage().
+
+@param aSqlStmt A string of 16-bit wide characters containing one or more DDL/DML SQL statements;
+ each statement is separated by a ';' character.
+@param aStatus Completion status of asynchronous request, one of the following:
+ >=0, The operation has completed successfully. The number of database rows that were
+ changed/inserted/deleted by the most recently completed DDL/DML sql statement.
+ Exception: If the executed statement is "DELETE FROM <table>", then the function returns 0
+ if the operation has completed successfully (disregarding the number of the deleted rows);
+ KErrNoMemory, an out of memory condition has occured;
+ KSqlErrGeneral, a syntax error has occurred - text describing the problem
+ can be obtained by calling RSqlDatabase::LastErrorMessage();
+ KErrDiskFull, There is no available disk space to complete the operation. If the executed statement is a DELETE
+ statement, try to use the reserved disk space (if there is a reserved disk space) to complete the operation.
+ In all other cases the database connection should be closed and some disk space freed before reopening
+ the database;
+ KErrPermissionDenied, the caller does not satisfy the relevant database security policies;
+ Note that aStatus may be set with database specific errors categorised as ESqlDbError,
+ and other system-wide error codes.
+
+
+@capability None, if current RSqlDatabase object represents a handle to a non-secure database;
+ RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement modifies a secure database schema;
+ RSqlSecurityPolicy::EReadPolicy or
+ RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement reads from a secure database;
+ RSqlSecurityPolicy::EWritePolicy or
+ RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement writes to a secure database;
+
+@see RSqlStatement
+@see TSqlRetCodeClass::ESqlDbError
+@see RSqlDatabase::LastErrorMessage()
+@see RSqlSecurityPolicy
+@see RSqlSecurityPolicy::TPolicyType
+*/
+EXPORT_C void RSqlDatabase::Exec(const TDesC& aSqlStmt, TRequestStatus& aStatus)
+ {
+ SQLUTRACE_PROFILER(this);
+ SYMBIAN_TRACE_SQL_EVENTS_ONLY(UTF::Printf(UTF::TTraceContext(UTF::EInternals), KStrParam16, 1, &aSqlStmt));
+
+ Impl().Exec(aSqlStmt, aStatus);
+ }
+
+/**
+Executes one or more 8-bit SQL statements asynchronously to allow client to avoid being blocked
+by server activity.
+
+No other operations can be performed on current RSqlDatabase object and RSqlStatement objects using it
+until the asynchronous operation completes.
+
+This method should be used for executing DDL/DML statements, but note the following point:
+- if an SQL statement contains one or more parameters, then the function will execute it,
+giving the parameters default NULL values.
+
+This class (RSqlDatabase) does not offer functions for setting the parameter values.
+Use the RSqlStatement class instead.
+
+If the call to this function fails because of a database-specific type error
+(i.e. the error is categorised as ESqlDbError), then a textual description of
+the error can be obtained calling RSqlDatabase::LastErrorMessage().
+
+@param aSqlStmt A string of 8-bit wide characters containing one or more DDL/DML SQL statements;
+ each statement is separated by a ';' character.
+@param aStatus Completion status of asynchronous request, one of the following:
+ >=0, The operation has completed successfully. The number of database rows that were
+ changed/inserted/deleted by the most recently completed DDL/DML sql statement.
+ Exception: If the executed statement is "DELETE FROM <table>", then the function returns 0
+ if the operation has completed successfully (disregarding the number of the deleted rows);
+ KErrNoMemory, an out of memory condition has occured;
+ KSqlErrGeneral, a syntax error has occurred - text describing the problem
+ can be obtained by calling RSqlDatabase::LastErrorMessage();
+ KErrDiskFull, There is no available disk space to complete the operation. If the executed statement is a DELETE
+ statement, try to use the reserved disk space (if there is a reserved disk space) to complete the operation.
+ In all other cases the database connection should be closed and some disk space freed before reopening
+ the database;
+ KErrPermissionDenied, the caller does not satisfy the relevant database security policies;
+ Note that aStatus may be set with database specific errors categorised as ESqlDbError,
+ and other system-wide error codes.
+
+
+@capability None, if current RSqlDatabase object represents a handle to a non-secure database;
+ RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement modifies a secure database schema;
+ RSqlSecurityPolicy::EReadPolicy or
+ RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement reads from a secure database;
+ RSqlSecurityPolicy::EWritePolicy or
+ RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement writes to a secure database;
+
+@see RSqlStatement
+@see TSqlRetCodeClass::ESqlDbError
+@see RSqlDatabase::LastErrorMessage()
+@see RSqlSecurityPolicy
+@see RSqlSecurityPolicy::TPolicyType
+*/
+EXPORT_C void RSqlDatabase::Exec(const TDesC8& aSqlStmt, TRequestStatus& aStatus)
+ {
+ SQLUTRACE_PROFILER(this);
+ SYMBIAN_TRACE_SQL_EVENTS_ONLY(UTF::Printf(UTF::TTraceContext(UTF::EInternals), KStrParam, 1, &aSqlStmt));
+
+ Impl().Exec(aSqlStmt, aStatus);
+ }
+
+/**
+Retrieves a reference to the textual description of the error returned by the
+most recent call to any of the functions:
+- RSqlDatabase::Exec()
+- RSqlStatement::Exec()
+- RSqlStatement::Next()
+- RSqlStatement::Reset()
+
+Note that the function can only return a reference to text for
+database-specific type errors, i.e. those errors that are categorised as of
+type ESqlDbError.
+
+@return A non-modifiable pointer descriptor representing the most recent error
+ message. Note that message may be NULL, i.e. the descriptor may have
+ zero length.
+
+@see TSqlRetCodeClass::ESqlDbError
+@see RSqlDatabase::Exec()
+@see RSqlStatement::Exec()
+@see RSqlStatement::Next()
+@see RSqlStatement::Reset()
+
+@capability None
+*/
+EXPORT_C TPtrC RSqlDatabase::LastErrorMessage() const
+ {
+ SQLUTRACE_PROFILER(0);
+ return Impl().LastErrorMessage();
+ }
+
+/**
+Returns the ROWID of the most recent successful INSERT into the database
+from this database connection.
+
+@return >0, the ROWID of the most recent successful INSERT into the database
+ from this database connection;
+ 0, if no successful INSERTs have ever occurred from this database connection
+ <0, if one of the system-wide error codes is returned
+
+@capability None
+*/
+EXPORT_C TInt64 RSqlDatabase::LastInsertedRowId() const
+ {
+ SQLUTRACE_PROFILER(0);
+ return Impl().LastInsertedRowId();
+ }
+
+/**
+Checks the database transaction state.
+
+@return True, if the database is in transaction, false otherwise.
+
+@capability None
+*/
+EXPORT_C TBool RSqlDatabase::InTransaction() const
+ {
+ SQLUTRACE_PROFILER(0);
+ return Impl().InTransaction();
+ }
+
+/**
+Returns the database file size, in bytes.
+
+@return >= 0, the operation has completed successfully. The number is the size of the main
+ database file;
+ KErrNoMemory, an out of memory condition has occurred;
+ KErrTooBig, the database is too big and the size cannot fit into 32-bit signed integer;
+ Note that database specific errors categorised as ESqlDbError, and
+ other system-wide error codes may also be returned.
+
+@capability None
+*/
+EXPORT_C TInt RSqlDatabase::Size() const
+ {
+ SQLUTRACE_PROFILER(0);
+ return Impl().Size();
+ }
+
+/**
+Returns the database file size and free space, in bytes.
+
+@param aSize An output parameter. If the call was successfull the aSize object will contain information
+ about the database size and database free space.
+@param aDbName The attached database name or KNullDesC for the main database
+
+@return KErrNone, The operation has completed succesfully;
+ KErrBadName, Invalid (too long) attached database name;
+ KSqlErrGeneral, There is no an attached database with aDbName name;
+ Note that database specific errors categorised as ESqlDbError, and
+ other system-wide error codes may also be returned.
+
+@capability None
+*/
+EXPORT_C TInt RSqlDatabase::Size(RSqlDatabase::TSize& aSize, const TDesC& aDbName) const
+ {
+ SQLUTRACE_PROFILER(0);
+ SYMBIAN_TRACE_SQL_EVENTS_ONLY(UTF::Printf(UTF::TTraceContext(UTF::EInternals), KStrParam16, 2, &aDbName));
+
+ return Impl().Size(aSize, aDbName);
+ }
+
+/**
+Compacts the database.
+This function should be used for databases that have been configured for a manual compaction during
+the database creation.
+The function has no effect if the database has been configured for an auto compaction.
+The function has no effect if the aSize argument value is zero.
+The function has no effect also if there aren't any free pages in the database file.
+If the database has been configured for a background compaction, then the function works as if the database
+has been configured for a manual compaction.
+
+@param aSize Can be one of:
+ RSqlDatabase::EMaxCompaction - requests a full database compaction. All free pages
+ (if any exists) will be removed;
+ Positive 32-bit signed integer value - the server will attempt to compact the database removing
+ at most aSize bytes from the database file, rounded up to the nearest page count,
+ e.g. request for removing 1 byte will remove one free page from the database;
+
+@param aDbName The attached database name or KNullDesC for the main database
+
+@return Zero or positive integer - the operation has completed succesfully, the return value is the
+ size of the removed free space in bytes,
+ KErrArgument, Invalid aSize value;
+ KErrBadName, Invalid (too long) attached database name;
+ KSqlErrReadOnly, Read-only database;
+ KSqlErrGeneral, There is no an attached database with aDbName name;
+ Note that database specific errors categorised as ESqlDbError, and
+ other system-wide error codes may also be returned.
+
+@capability None
+*/
+EXPORT_C TInt RSqlDatabase::Compact(TInt64 aSize, const TDesC& aDbName)
+ {
+ SQLUTRACE_PROFILER(this);
+ SYMBIAN_TRACE_SQL_EVENTS_ONLY(UTF::Printf(UTF::TTraceContext(UTF::EInternals), KSizeStrParam16, 1, aSize, 2, &aDbName));
+
+ return Impl().Compact(aSize, aDbName);
+ }
+
+/**
+Compacts the database asynchronously.
+This function should be used for databases that have been configured for a manual compaction during
+the database creation.
+The function has no effect if the database has been configured for an auto compaction.
+The function has no effect if the aSize argument value is zero.
+The function has no effect also if there aren't any free pages in the database file.
+If the database has been configured for a background compaction, then the function works as if the database
+has been configured for a manual compaction.
+
+@param aStatus Completion status of asynchronous request, one of the following:
+ Zero or positive integer - the operation has completed succesfully, the return value is the
+ size of the removed free space in bytes,
+ KErrArgument, Invalid aSize value;
+ KErrBadName, Invalid (too long) attached database name;
+ KSqlErrReadOnly, Read-only database;
+ KSqlErrGeneral, There is no an attached database with aDbName name;
+ Note that database specific errors categorised as ESqlDbError, and
+ other system-wide error codes may also be returned.
+
+
+@param aSize Can be one of:
+ RSqlDatabase::EMaxCompaction - requests a full database compaction. All free pages
+ (if any exists) will be removed;
+ Positive 32-bit signed integer value - the server will attempt to compact the database removing
+ at most aSize bytes from the database file, rounded up to the nearest page count,
+ e.g. request for removing 1 byte will remove one free page from the database;
+
+@param aDbName The attached database name or KNullDesC for the main database
+
+@capability None
+*/
+EXPORT_C void RSqlDatabase::Compact(TInt64 aSize, TRequestStatus& aStatus, const TDesC& aDbName)
+ {
+ SQLUTRACE_PROFILER(this);
+ SYMBIAN_TRACE_SQL_EVENTS_ONLY(UTF::Printf(UTF::TTraceContext(UTF::EInternals), KSizeStrParam16, 1, aSize, 3, &aDbName));
+
+ Impl().Compact(aSize, aDbName, aStatus);
+ }
+
+/**
+Reserves a predefined amount of disk space on the drive where the database file is.
+
+At the moment the max possible amount, allowed by the file server, is reserved on the database file drive.
+Use this call to ensure that if your "delete records" transaction fails because of "out of
+disk space" circumstances, you can get an access to the already reserved disk space and
+complete your transaction successfully the second time.
+
+There is no strong, 100% guarantee, that the reserved disk space will always help the client
+in "low memory" situations.
+
+@param aSpace This parameter is not used at the moment.
+
+@return KErrNone, The operation has completed succesfully;
+ KErrNoMemory, Out of memory condition has occured;
+ KErrAlreadyExists, The space has already been reserved;
+ Note that other system-wide error codes may also be returned.
+
+@see RSqlDatabase::FreeReservedSpace()
+@see RSqlDatabase::GetReserveAccess()
+@see RSqlDatabase::ReleaseReserveAccess()
+*/
+EXPORT_C TInt RSqlDatabase::ReserveDriveSpace(TInt aSize)
+ {
+ SQLUTRACE_PROFILER(this);
+ //Usage of the IPC call arguments:
+ //Arg 0: [out] requested size
+ return Impl().Session().SendReceive(ESqlSrvDbReserveDriveSpace, TIpcArgs(aSize));
+ }
+
+/**
+Frees the reserved disk space.
+
+@see RSqlDatabase::ReserveDriveSpace()
+@see RSqlDatabase::GetReserveAccess()
+@see RSqlDatabase::ReleaseReserveAccess()
+*/
+EXPORT_C void RSqlDatabase::FreeReservedSpace()
+ {
+ SQLUTRACE_PROFILER(this);
+ Impl().Session().SendReceive(ESqlSrvDbFreeReservedSpace);
+ }
+
+/**
+Gives the client an access to the already reserved disk space.
+
+@return KErrNone, The operation has completed succesfully;
+ KErrNotFound, An attempt is made to get an access to a disk space, which is not reserved yet;
+ KErrInUse, An access to the reserved space has already been given;
+ Note that other system-wide error codes may also be returned.
+
+@see RSqlDatabase::ReserveDriveSpace()
+@see RSqlDatabase::FreeReservedSpace()
+@see RSqlDatabase::ReleaseReserveAccess()
+*/
+EXPORT_C TInt RSqlDatabase::GetReserveAccess()
+ {
+ SQLUTRACE_PROFILER(this);
+ return Impl().Session().SendReceive(ESqlSrvDbGetReserveAccess);
+ }
+
+/**
+Releases the access to the reserved disk space.
+
+@see RSqlDatabase::ReserveDriveSpace()
+@see RSqlDatabase::FreeReservedSpace()
+@see RSqlDatabase::GetReserveAccess()
+*/
+EXPORT_C void RSqlDatabase::ReleaseReserveAccess()
+ {
+ SQLUTRACE_PROFILER(this);
+ Impl().Session().SendReceive(ESqlSrvDbReleaseReserveAccess);
+ }
+
+/**
+Returns a reference to the implementation object of RSqlDatabase - CSqlDatabaseImpl.
+
+@panic SqlDb 2 Create() or Open() has not previously been called on this RSqlDatabase object.
+
+@internalComponent
+*/
+CSqlDatabaseImpl& RSqlDatabase::Impl() const
+ {
+ __SQLASSERT_ALWAYS(iImpl != NULL, ESqlPanicInvalidObj);
+ return *iImpl;
+ }