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

     2 // All rights reserved.

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

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

     5 // which accompanies this distribution, and is available

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

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 //

    15 

    16 #include "SqlPanic.h"			//ESqlPanicInvalidObj, ESqlPanicObjExists

    17 #include "SqlDatabaseImpl.h"	//CSqlDatabaseImpl

    18 

    19 /**

    20 Gets the category of the return code value that is returned by

    21 a call to the SQL API.

    22 

    23 A call to the SQL API may complete with a non-zero return code indicating that some

    24 unexpected behaviour has occurred. This can be categorised in a number of ways,

    25 for example, as a Symbian OS error, or as a database error etc etc. 

    26 

    27 This function takes the return code value and gets the category associated with

    28 that value. The categories are defined by the enum values of

    29 the TSqlRetCodeClass enum.

    30 

    31 @param aSqlRetCode The return code value returned from a call to any (member)

    32                    function that forms part of the SQL interface.

    33 

    34 @return The category associated with the specified return code value. This is

    35         one of the TSqlRetCodeClass enum values.

    36 

    37 @see TSqlRetCodeClass

    38 

    39 @capability None

    40 

    41 @publishedAll

    42 @released

    43 */

    44 EXPORT_C TSqlRetCodeClass SqlRetCodeClass(TInt aSqlRetCode)

    45 	{

    46 	if(aSqlRetCode >= 0)

    47 		{

    48 		return ESqlInformation;	

    49 		}

    50 	else if(aSqlRetCode <= KSqlErrGeneral)

    51 		{

    52 		return ESqlDbError;	

    53 		}

    54 	return ESqlOsError;

    55 	}

    56 

    57 /**

    58 Initialises the pointer to the implementation object to NULL.

    59 

    60 @capability None

    61 */

    62 EXPORT_C RSqlDatabase::RSqlDatabase() :

    63 	iImpl(NULL)

    64 	{

    65 	}

    66 	

    67 /**

    68 Creates a new shared non-secure or private secure database.

    69 

    70 @param aDbFileName The full path name of the file that is to host the database.

    71 @param aConfig the configuration string "PARAM=VALUE;....".

    72 			   The following parameters can be set using the configuration string:

    73 			   cache_size=value - where "value" is the cache size in pages.

    74 			   					  "value" must be a positive integer number;

    75 			   page_size=value - where "value" is the page size in bytes.

    76 			   					 The "page_size" parameter can accept the following values:

    77 			   					 512, 1024, 2048, 4096, 8192, 16384, 32768;

    78 			   encoding=value - where "value" is the desired database encoding.

    79 			   					 "value" could be either "UTF-8" or "UTF-16";

    80         	   compaction=value - where "value" is the desired compaction mode. 

    81                   				  "value" could be either "background", "synchronous" or "manual".

    82 

    83 @return KErrNone, the operation has completed successfully; 

    84         KErrNoMemory, an out of memory condition has occurred;

    85         KErrBadName, the file name is invalid - it has either a zero length or it is the name of a directory;

    86         KErrAlreadyExists, the file already exists;

    87         KErrNotReady, the drive does not exist or is not ready;

    88         KErrInUse, the file is already open;

    89         KErrArgument, the file name refers to a secure database, invalid configuration string, invalid parameter values

    90         			  in the configuration string.

    91                       Note that database specific errors categorised as ESqlDbError, and

    92                       other system-wide error codes may also be returned.

    93 

    94 @capability None

    95 */

    96 EXPORT_C TInt RSqlDatabase::Create(const TDesC& aDbFileName, const TDesC8* aConfig)

    97 	{

    98 	SQLUTRACE_PROFILER(this);

    99 	SYMBIAN_TRACE_SQL_EVENTS_ONLY(UTF::Printf(UTF::TTraceContext(UTF::EInternals), KStrParam16, 1, &aDbFileName));

   100 	SYMBIAN_TRACE_SQL_EVENTS_ONLY(aConfig ? (void)UTF::Printf(UTF::TTraceContext(UTF::EInternals), 

   101 			KStrParam, 2, aConfig) : void(0));

   102 	

   103 	TRAPD(err, iImpl = CSqlDatabaseImpl::NewL(ESqlSrvDbCreate, aDbFileName, NULL, aConfig));

   104 	return err;

   105 	}

   106 	

   107 /**

   108 Creates a new shared secure database.

   109 

   110 @param aDbFileName       The name of the file that is to host the database.

   111                          The format of the name is \<drive\>:\<[SID]database file name excluding the path\>.

   112                          "[SID]" refers to the application SID.

   113 @param aSecurityPolicy The container for the security policies.

   114 @param aConfig the configuration string "PARAM=VALUE;...."

   115 			   The following parameters can be set using the configuration string:

   116 			   cache_size=value - where "value" is the cache size in pages.

   117 			   					  "value" must be a positive integer number;

   118 			   page_size=value - where "value" is the page size in bytes.

   119 			   					 The "page_size" parameter can accept the following values:

   120 			   					 512, 1024, 2048, 4096, 8192, 16384, 32768;

   121 			   encoding=value - where "value" is the desired database encoding.

   122 			   					 "value" could be either "UTF-8" or "UTF-16";

   123          	   compaction=value - where "value" is the desired compaction mode. 

   124                   				 "value" could be either "background", "synchronous" or "manual".

   125 			   

   126 

   127 @return KErrNone, the operation has completed successfully;

   128         KErrNoMemory, an out of memory condition has occurred;

   129         KErrArgument, the file name does not refer to a secure database;

   130         KErrArgument, system table name found in the security policies (aSecurityPolicy),

   131         			  invalid configuration string, invalid parameter values

   132         			  in the configuration string;

   133         KErrBadName, the file name is invalid - it has either a zero length or it is the name of a directory;

   134         KErrAlreadyExists, the file already exists;

   135         KErrNotReady, the drive does not exist or is not ready;

   136         KErrInUse, the file is already open;

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

   138                       Note that database specific errors categorised as ESqlDbError, and

   139                       other system-wide error codes may also be returned.

   140 

   141 @capability The calling application must satisfy the database policy of RSqlSecurityPolicy::ESchemaPolicy type;

   142 

   143 @see RSqlSecurityPolicy

   144 @see RSqlSecurityPolicy::TPolicyType

   145 */

   146 EXPORT_C TInt RSqlDatabase::Create(const TDesC& aDbFileName,

   147 						const RSqlSecurityPolicy& aSecurityPolicy, const TDesC8* aConfig)

   148 	{

   149 	SQLUTRACE_PROFILER(this);

   150 	SYMBIAN_TRACE_SQL_EVENTS_ONLY(UTF::Printf(UTF::TTraceContext(UTF::EInternals), KStrParam16, 1, &aDbFileName));

   151 	SYMBIAN_TRACE_SQL_EVENTS_ONLY(aConfig ? (void)UTF::Printf(UTF::TTraceContext(UTF::EInternals), 

   152 			KStrParam, 2, aConfig) : void(0));

   153 	

   154 	TRAPD(err, 	iImpl = CSqlDatabaseImpl::NewL(ESqlSrvDbCreateSecure, aDbFileName,

   155 			&aSecurityPolicy.Impl(), aConfig));

   156 	return err;

   157 	}

   158 	

   159 /**

   160 Opens an existing database, which can be:

   161 @code

   162  - shared non-secure;

   163  - shared secure;

   164  - private secure;

   165 @endcode

   166 

   167 @param aDbFileName The name of the file that hosts the database. If this is

   168                    a secure database, then the format of the name must be:

   169                    \<drive\>:\<[SID]database file name excluding the path\>.

   170                    If this is a non-secure database, then aDbFileName has to be the full database file name.

   171                    "[SID]" refers to SID of the application which created the database.

   172 @param aConfig the configuration string "PARAM=VALUE;...."

   173 			   The following parameters can be set using the configuration string:

   174 			   cache_size=value - where "value" is the cache size in pages.

   175 			   					  "value" must be a positive integer number;

   176 			   

   177 

   178 @return KErrNone, the operation has completed successfully;

   179         KErrNoMemory, an out of memory condition has occurred;

   180         KErrBadName, the file name is invalid - it has either a zero length or it is the name of a directory;

   181         KErrNotReady, the drive does not exist or is not ready;

   182         KErrInUse, the file is already open;

   183         KErrNotFound, database file not found;

   184         KErrArgument, invalid configuration string, invalid parameter values

   185         			  in the configuration string;

   186         KErrGeneral, missing or invalid security policies (if the database to be opened is a secure database);

   187         KErrPermissionDenied, the caller does not satisfy the relevant database security policies;

   188         KErrNotSupported, incompatible SQL security version (if the database to be opened is a secure database).

   189                       Note that database specific errors categorised as ESqlDbError, and

   190                       other system-wide error codes may also be returned.

   191 

   192 @capability None, if aDbFileName refers to a non-secure database;

   193             RSqlSecurityPolicy::ESchemaPolicy or 

   194             RSqlSecurityPolicy::EReadPolicy or 

   195             RSqlSecurityPolicy::EWritePolicy database policy type, if aDbFileName refers to a secure database;

   196 

   197 @see RSqlSecurityPolicy

   198 @see RSqlSecurityPolicy::TPolicyType

   199 */

   200 EXPORT_C TInt RSqlDatabase::Open(const TDesC& aDbFileName, const TDesC8* aConfig)

   201 	{

   202 	SQLUTRACE_PROFILER(this);

   203 	SYMBIAN_TRACE_SQL_EVENTS_ONLY(UTF::Printf(UTF::TTraceContext(UTF::EInternals), KStrParam16, 1, &aDbFileName));

   204 	SYMBIAN_TRACE_SQL_EVENTS_ONLY(aConfig ? (void)UTF::Printf(UTF::TTraceContext(UTF::EInternals), 

   205 			KStrParam, 2, aConfig) : void(0));

   206 	

   207 	TRAPD(err, iImpl = CSqlDatabaseImpl::NewL(ESqlSrvDbOpen, aDbFileName, NULL, aConfig));

   208 	return err;

   209 	}

   210 

   211 /**

   212 Creates a new shared non-secure or private secure database.

   213  

   214 @param aDbFileName The full path name of the file that is to host the database.

   215 @param aConfig the configuration string "PARAM=VALUE;...."

   216 			   The following parameters can be set using the configuration string:

   217 			   cache_size=value - where "value" is the cache size in pages.

   218 			   					  "value" must be a positive integer number;

   219 			   page_size=value - where "value" is the page size in bytes.

   220 			   					 The "page_size" parameter can accept the following values:

   221 			   					 512, 1024, 2048, 4096, 8192, 16384, 32768;

   222 			   encoding=value - where "value" is the desired database encoding.

   223 			   					 "value" could be either "UTF-8" or "UTF-16";

   224         	   compaction=value - where "value" is the desired compaction mode. 

   225                   				 "value" could be either "background", "synchronous" or "manual".

   226 			   

   227 

   228 @leave  KErrNoMemory, an out of memory condition has occurred;

   229         KErrBadName, the file name is invalid - it has either a zero length or it is the name of a directory;

   230         KErrAlreadyExists, the file already exists;

   231         KErrNotReady, the drive does not exist or is not ready;

   232         KErrInUse, the file is already open;

   233         KErrArgument, the file name refers to a secure database,

   234         			  invalid configuration string, invalid parameter values

   235         			  in the configuration string.

   236                       Note that the function may leave with database specific errors categorised as ESqlDbError and

   237                       other system-wide error codes.

   238 

   239 @capability None

   240 */

   241 EXPORT_C void RSqlDatabase::CreateL(const TDesC& aDbFileName, const TDesC8* aConfig)

   242 	{

   243 	SQLUTRACE_PROFILER(this);

   244 	SYMBIAN_TRACE_SQL_EVENTS_ONLY(UTF::Printf(UTF::TTraceContext(UTF::EInternals), KStrParam16, 1, &aDbFileName));

   245 	SYMBIAN_TRACE_SQL_EVENTS_ONLY(aConfig ? (void)UTF::Printf(UTF::TTraceContext(UTF::EInternals), 

   246 			KStrParam, 2, aConfig) : void(0));

   247 	

   248 	iImpl = CSqlDatabaseImpl::NewL(ESqlSrvDbCreate, aDbFileName, NULL, aConfig);

   249 	}

   250 	

   251 /**

   252 Creates a new shared secure database.

   253 @param aDbFileName       The name of the file that is to host the database.

   254                          The format of the name is \<drive\>:\<[SID]database file name excluding the path\>.

   255                          "[SID]" refers to the application SID.

   256 @param aSecurityPolicy   The container for the security policies.

   257 @param aConfig the configuration string "PARAM=VALUE;...."

   258 			   The following parameters can be set using the configuration string:

   259 			   cache_size=value - where "value" is the cache size in pages.

   260 			   					  "value" must be a positive integer number;

   261 			   page_size=value - where "value" is the page size in bytes.

   262 			   					 The "page_size" parameter can accept the following values:

   263 			   					 512, 1024, 2048, 4096, 8192, 16384, 32768;

   264 			   encoding=value - where "value" is the desired database encoding.

   265 			   					 "value" could be either "UTF-8" or "UTF-16";

   266 			   

   267 			   compaction=value - where "value" is the desired compaction mode. 

   268                   				  "value" could be either "background", "synchronous" or "manual".

   269                   				  

   270 @leave  KErrNoMemory, an out of memory condition has occurred;

   271         KErrArgument, the file name does not refer to a secure database;

   272         KErrArgument, system table name found in the security policies (aSecurityPolicy),

   273         			  invalid configuration string, invalid parameter values

   274         			  in the configuration string;

   275         KErrBadName, the file name is invalid - it has either a zero length or it is the name of a directory;

   276         KErrAlreadyExists, the file already exists;

   277         KErrNotReady, the drive does not exist or is not ready;

   278         KErrInUse, the file is already open;

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

   280                       Note that the function may leave with database specific errors categorised as ESqlDbError and

   281                       other system-wide error codes.

   282 

   283 @capability The calling application must satisfy the database policy of RSqlSecurityPolicy::ESchemaPolicy type;

   284 

   285 @see RSqlSecurityPolicy

   286 @see RSqlSecurityPolicy::TPolicyType

   287 */

   288 EXPORT_C void RSqlDatabase::CreateL(const TDesC& aDbFileName,

   289 				const RSqlSecurityPolicy& aSecurityPolicy, const TDesC8* aConfig)

   290 	{

   291 	SQLUTRACE_PROFILER(this);

   292 	SYMBIAN_TRACE_SQL_EVENTS_ONLY(UTF::Printf(UTF::TTraceContext(UTF::EInternals), KStrParam16, 1, &aDbFileName));

   293 	SYMBIAN_TRACE_SQL_EVENTS_ONLY(aConfig ? (void)UTF::Printf(UTF::TTraceContext(UTF::EInternals), 

   294 			KStrParam, 2, aConfig) : void(0));

   295 	

   296 	iImpl = CSqlDatabaseImpl::NewL(ESqlSrvDbCreateSecure, aDbFileName,

   297 						&aSecurityPolicy.Impl(), aConfig);

   298 	}

   299 	

   300 /**

   301 Opens an existing database, which can be:

   302 @code

   303  - shared non-secure;

   304  - shared secure;

   305  - private secure;

   306 @endcode

   307 

   308 @param aDbFileName The name of the file that hosts the database. If this is

   309                    a secure database, then the format of the name must be:

   310                    \<drive\>:\<[SID]database file name excluding the path\>.

   311                    If this is a non-secure database, then aDbFileName has to be the full database file name.

   312                    "[SID]" refers to SID of the application which created the database.

   313 @param aConfig the configuration string "PARAM=VALUE;...."

   314 			   The following parameters can be set using the configuration string:

   315 			   cache_size=value - where "value" is the cache size in pages.

   316 			   					  "value" must be a positive integer number;

   317 			   

   318 

   319 @leave  KErrNoMemory, an out of memory condition has occurred;

   320         KErrBadName, the file name is invalid - it has either a zero length or it is the name of a directory;

   321         KErrNotReady, the drive does not exist or is not ready;

   322         KErrInUse, the file is already open;

   323         KErrNotFound, database file not found;

   324         KErrArgument, invalid configuration string, invalid parameter values

   325         			  in the configuration string;

   326         KErrGeneral, missing or invalid security policies (if the database to be opened is a secure database);

   327         KErrPermissionDenied, the caller does not satisfy the relevant database security policies;

   328         KErrNotSupported, incompatible SQL security version (if the database to be opened is a secure database).

   329                       Note that the function may leave with database specific errors categorised as ESqlDbError and

   330                       other system-wide error codes.

   331 

   332 @capability None, if aDbFileName refers to a non-secure database;

   333             RSqlSecurityPolicy::ESchemaPolicy or 

   334             RSqlSecurityPolicy::EReadPolicy or 

   335             RSqlSecurityPolicy::EWritePolicy database policy type, if aDbFileName refers to a secure database;

   336 

   337 @see RSqlSecurityPolicy

   338 @see RSqlSecurityPolicy::TPolicyType

   339 */

   340 EXPORT_C void RSqlDatabase::OpenL(const TDesC& aDbFileName, const TDesC8* aConfig)

   341 	{

   342 	SQLUTRACE_PROFILER(this);

   343 	SYMBIAN_TRACE_SQL_EVENTS_ONLY(UTF::Printf(UTF::TTraceContext(UTF::EInternals), KStrParam16, 1, &aDbFileName));

   344 	SYMBIAN_TRACE_SQL_EVENTS_ONLY(aConfig ? (void)UTF::Printf(UTF::TTraceContext(UTF::EInternals), 

   345 			KStrParam, 2, aConfig) : void(0));

   346 	

   347 	iImpl = CSqlDatabaseImpl::NewL(ESqlSrvDbOpen, aDbFileName, NULL, aConfig);

   348 	}

   349 

   350 /**

   351 Closes this handle to the database.

   352 

   353 The function frees memory and any allocated resources.

   354 

   355 You can reuse this object, but you must reinitialise it by calling

   356 RSqlDatabase::Create() or RSqlDatabase::Open().

   357 

   358 @see RSqlDatabase::Create()

   359 @see RSqlDatabase::Open()

   360 

   361 @capability None

   362 */

   363 EXPORT_C void RSqlDatabase::Close()

   364 	{

   365 	SQLUTRACE_PROFILER(this);

   366 	delete iImpl;

   367 	iImpl = NULL;

   368 	}

   369 	

   370 /**

   371 Attaches an existing database to the current database connection.

   372 

   373 The attached database can be read, written or modified. 

   374 One database can be attched multiple times to the same connection, using different logical database names.

   375 Tables in an attached database can be referred to using "database-name.table-name" syntax.

   376 If an attached table doesn't have a duplicate table name in the main database, it doesn't 

   377 require a database name prefix. 

   378 

   379 Transactions involving multiple attached databases are atomic.

   380 

   381 @param aDbFileName The name of the file that hosts the database. If this is

   382                    a secure database, then the format of the name must be:

   383                    \<drive\>:\<[SID]database file name excluding the path\>.

   384                    If this is a private or shared non-secure database, then aDbFileName has to be the full 

   385                    database file name. "[SID]" refers to SID of the application which created the attached database.

   386 @param aDbName Logical database name. It must be unique (per database connection). This is the name which can

   387                be used for accessing tables in the attached database. The syntax is "database-name.table-name".

   388 

   389 @return KErrNone, the operation has completed successfully;

   390         KErrNoMemory, an out of memory condition has occurred;

   391         KErrBadName, the file name is invalid - it has either a zero length or it is the name of a directory;

   392         KErrNotReady, the drive does not exist or is not ready;

   393         KErrInUse, the file is already open;

   394         KErrNotFound, database file not found;

   395         KErrGeneral, missing or invalid security policies (if the database to be opened is a secure database);

   396         KErrPermissionDenied, the caller does not satisfy the relevant database security policies;

   397         KErrNotSupported, incompatible SQL security version (if the database to be opened is a secure database).

   398                       Note that database specific errors categorised as ESqlDbError, and

   399                       other system-wide error codes may also be returned.

   400 

   401 @capability None, if aDbFileName refers to a non-secure database;

   402             RSqlSecurityPolicy::ESchemaPolicy or 

   403             RSqlSecurityPolicy::EReadPolicy or 

   404             RSqlSecurityPolicy::EWritePolicy database policy type, if aDbFileName refers to a secure database;

   405 

   406 @see RSqlSecurityPolicy

   407 @see RSqlSecurityPolicy::TPolicyType

   408 */

   409 EXPORT_C TInt RSqlDatabase::Attach(const TDesC& aDbFileName, const TDesC& aDbName)

   410 	{

   411 	SQLUTRACE_PROFILER(this);

   412 	SYMBIAN_TRACE_SQL_EVENTS_ONLY(UTF::Printf(UTF::TTraceContext(UTF::EInternals), KStrStrParam16, &aDbFileName, &aDbName));

   413 	

   414 	return Impl().Attach(aDbFileName, aDbName);

   415 	}

   416 		

   417 /**

   418 Detaches previously attached database.

   419 

   420 @param aDbName Logical database name. 

   421 			   The logical name of the database to be detached.

   422 

   423 @return KErrNone, the operation completed has successfully;

   424         KErrNotFound, no attached database with aDbName name;

   425                       Note that database specific errors categorised as ESqlDbError, and

   426                       other system-wide error codes may also be returned.

   427 

   428 @capability None

   429 */

   430 EXPORT_C TInt RSqlDatabase::Detach(const TDesC& aDbName)

   431 	{

   432 	SQLUTRACE_PROFILER(this);

   433 	SYMBIAN_TRACE_SQL_EVENTS_ONLY(UTF::Printf(UTF::TTraceContext(UTF::EInternals), KStrParam16, 1, &aDbName));

   434 	

   435 	return Impl().Detach(aDbName);

   436 	}

   437 

   438 /**

   439 Copies a database file to the specified location.

   440 

   441 Note that this is a static function, and its use is not

   442 restricted to any specific RSqlDatabase instance.

   443 

   444 @param aSrcDbFileName Source database file name.

   445 					  If this is a secure database, then the format of the name must be:

   446 					  \<drive\>:\<[SID]database file name excluding the path\>.

   447 					  If this is a non-secure database, then aDbFileName has to be the full database file name.

   448 					  "[SID]" refers to SID of the application which created the database.

   449 @param aDestDbFileName Destination database file name.

   450 					  If this is a secure database, then the format of the name must be:

   451 					  \<drive\>:\<[SID]database file name excluding the path\>.

   452 					  If this is a non-secure database, then aDbFileName has to be the full database file name.

   453 					  "[SID]" refers to SID of the application which performs the copying operation.

   454 

   455 The allowed copying operations are:

   456 - secure to secure database. Only the application created the database is allowed to copy it.

   457 - non-secure to non-secure database. No restrictions apply to this operation.

   458 

   459 @return KErrNone, the operation completed has successfully;

   460         KErrBadName, the file name is invalid - it has either a zero length or it is the name of a directory;

   461         KErrNotReady, the drive does not exist or is not ready;

   462         KErrInUse, the file is already open;

   463         KErrNotFound, database file not found;

   464         KErrPermissionDenied, the SID of the calling application does not match the SID of source or destination database.

   465                       Note that other system-wide error codes may also be returned.

   466 

   467 @capability None

   468 

   469 Note that if the source database is a secure database, only the application, which created the database, can copy it.

   470 */

   471 EXPORT_C TInt RSqlDatabase::Copy(const TDesC& aSrcDbFileName, const TDesC& aDestDbFileName)

   472 	{

   473 	SQLUTRACE_PROFILER(0);

   474 	SYMBIAN_TRACE_SQL_EVENTS_ONLY(UTF::Printf(UTF::TTraceContext(UTF::EInternals), KStrStrParam16, 

   475 			&aSrcDbFileName, &aDestDbFileName));

   476 

   477 	return CSqlDatabaseImpl::Copy(aSrcDbFileName, aDestDbFileName);

   478 	}

   479 	

   480 /**

   481 Deletes the specified database file.

   482 

   483 Note that this is a static function, and its use is not

   484 restricted to any specific RSqlDatabase instance.

   485 

   486 @param aDbFileName The name of the database file.

   487 				   If this is a secure database, then the format of the name must be:

   488 				   \<drive\>:\<[SID]database file name excluding the path\>.

   489 				   If this is a private or shared non-secure database, then aDbFileName has to be the 

   490 				   full database file name. "[SID]" refers to SID of the application which created the database.

   491 

   492 @return KErrNone, the operation has completed successfully;

   493         KErrBadName, the file name is invalid - it has either a zero length or it is the name of a directory;

   494         KErrNotReady, the drive does not exist or is not ready;

   495         KErrInUse, the database file is in use;

   496         KErrNotFound, the database file cannot be found;

   497         KErrAccessDenied, access to the database file is denied (e.g. it might be a read-only file);

   498         KErrPermissionDenied, the SID of the calling application does not match the SID of the database;

   499                       Note that other system-wide error codes may also be returned.

   500 

   501 @capability None

   502 

   503 Note that if the database to be deleted is a secure database, only the application, which created the database, can delete it.

   504 */

   505 EXPORT_C TInt RSqlDatabase::Delete(const TDesC& aDbFileName)

   506 	{

   507 	SQLUTRACE_PROFILER(0);

   508 	SYMBIAN_TRACE_SQL_EVENTS_ONLY(UTF::Printf(UTF::TTraceContext(UTF::EInternals), KStrParam16, 1, &aDbFileName));

   509 	

   510 	return CSqlDatabaseImpl::Delete(aDbFileName);

   511 	}

   512 	

   513 /**

   514 Initializes aSecurityPolicy output parameter with a copy of the database security policies.

   515 The caller is responsible for destroying the initialized aSecurityPolicy paramemter.

   516 

   517 Note that there may be no security policies in force for this database.

   518 

   519 @param aSecurityPolicy Input/Output parameter, which will be initialized with the database

   520 						 security policies.

   521 

   522 @return KErrNone, the operation has completed successfully;

   523 		KErrNotSupported, the current database is not a secure database;

   524         KErrNoMemory, an out of memory condition has occurred;

   525 

   526 @capability None

   527 */

   528 EXPORT_C TInt RSqlDatabase::GetSecurityPolicy(RSqlSecurityPolicy& aSecurityPolicy) const

   529 	{

   530 	SQLUTRACE_PROFILER(this);

   531 	TRAPD(err, CSqlSecurityPolicy* securityPolicy = Impl().CloneSecurityPolicyL();

   532 		aSecurityPolicy.Set(*securityPolicy));

   533 	

   534 	return err;

   535 	}

   536 	

   537 /**

   538 Initializes aSecurityPolicy output parameter with a copy of the database security policies.

   539 The caller is responsible for destroying the initialized aSecurityPolicy paramemter.

   540 

   541 Note that there may be no security policies in force for this database.

   542 

   543 @param aSecurityPolicy Input/Output parameter, which will be initialized with the database

   544 						 security policies.

   545 

   546 @leave  KErrNotSupported, the current database is not a secure database;

   547         KErrNoMemory, an out of memory condition has occurred;

   548 

   549 @capability None

   550 */

   551 EXPORT_C void RSqlDatabase::GetSecurityPolicyL(RSqlSecurityPolicy& aSecurityPolicy) const

   552 	{

   553 	SQLUTRACE_PROFILER(this);

   554 	CSqlSecurityPolicy* securityPolicy = Impl().CloneSecurityPolicyL();

   555 	aSecurityPolicy.Set(*securityPolicy);	

   556 	}

   557 	

   558 /**

   559 Sets the transaction isolation level for the database.

   560 

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

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

   563 

   564 Transaction isolation levels are defined by the values of the

   565 RSqlDatabase::TIsolationLevel enum.

   566 

   567 The default isolation level is RSqlDatabase::ESerializable

   568 

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

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

   571 whenever the database is created or opened.

   572 

   573 @param aIsolationLevel The isolation level to be set.

   574 

   575 @return KErrNone, if the operation has completed successfully;

   576 		KErrNotSupported, invalid (not supported) transaction isolation level;

   577 

   578 @see RSqlDatabase::TIsolationLevel

   579 

   580 @capability None

   581 */

   582 EXPORT_C TInt RSqlDatabase::SetIsolationLevel(RSqlDatabase::TIsolationLevel aIsolationLevel)

   583 	{

   584 	SQLUTRACE_PROFILER(this);

   585 	return Impl().SetIsolationLevel(aIsolationLevel);

   586 	}

   587 	

   588 /**

   589 Executes one or more 16-bit SQL statements.

   590 

   591 This method should be used for executing DDL/DML statements, but note the following point:

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

   593 giving the parameters default NULL values.

   594 

   595 This class (RSqlDatabase) does not offer functions for setting the parameter values. 

   596 Use the RSqlStatement class instead.

   597 

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

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

   600 the error can be obtained calling RSqlDatabase::LastErrorMessage().

   601 

   602 @param aSqlStmt A string of 16-bit wide characters containing one or more DDL/DML SQL statements;

   603                 each statement is separated by a ';' character.

   604 

   605 @return >=0, The operation has completed successfully. The number of database rows that were 

   606 			 changed/inserted/deleted by the most recently completed DDL/DML sql statement.

   607 			 Exception: If the executed statement is "DELETE FROM <table>", then the function returns 0 

   608 			 if the operation has completed successfully (disregarding the number of the deleted rows);

   609         KErrNoMemory, an out of memory condition has occured;

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

   611                         can be obtained by calling 	RSqlDatabase::LastErrorMessage();

   612         KErrDiskFull, There is no available disk space to complete the operation. If the executed statement is a DELETE

   613         			  statement, try to use the reserved disk space (if there is a reserved disk space) to complete the operation.

   614         			  In all other cases the database connection should be closed and some disk space freed before reopening 

   615         			  the database; 

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

   617                       Note that database specific errors categorised as ESqlDbError, and

   618                       other system-wide error codes may also be returned.

   619 

   620 @capability None, if current RSqlDatabase object represents a handle to a non-secure database;

   621             RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement modifies a secure database schema; 

   622             RSqlSecurityPolicy::EReadPolicy or 

   623             RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement reads from a secure database; 

   624             RSqlSecurityPolicy::EWritePolicy or

   625             RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement writes to a secure database;

   626 

   627 @see RSqlStatement

   628 @see TSqlRetCodeClass::ESqlDbError

   629 @see RSqlDatabase::LastErrorMessage()

   630 @see RSqlSecurityPolicy

   631 @see RSqlSecurityPolicy::TPolicyType

   632 */

   633 EXPORT_C TInt RSqlDatabase::Exec(const TDesC& aSqlStmt)

   634 	{

   635 	SQLUTRACE_PROFILER(this);

   636 	SYMBIAN_TRACE_SQL_EVENTS_ONLY(UTF::Printf(UTF::TTraceContext(UTF::EInternals), KStrParam16, 1, &aSqlStmt));

   637 

   638 	return Impl().Exec(aSqlStmt);

   639 	}

   640 	

   641 /**

   642 Executes one or more 8-bit SQL statements.

   643 

   644 This method should be used for executing DDL/DML statements, but note the following point:

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

   646 giving the parameters default NULL values.

   647 

   648 This class (RSqlDatabase) does not offer functions for setting the parameter values. 

   649 Use the RSqlStatement class instead.

   650 

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

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

   653 the error can be obtained calling RSqlDatabase::LastErrorMessage().

   654 

   655 @param aSqlStmt A string of 8-bit wide characters containing one or more DDL/DML SQL statements;

   656                 each statement is separated by a ';' character.

   657 

   658 @return >=0, The operation has completed successfully. The number of database rows that were 

   659 			 changed/inserted/deleted by the most recently completed DDL/DML sql statement.

   660 			 Exception: If the executed statement is "DELETE FROM <table>", then the function returns 0 

   661 			 if the operation has completed successfully (disregarding the number of the deleted rows);

   662         KErrNoMemory,  an out of memory condition has occured;

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

   664                         can be obtained by calling 	RSqlDatabase::LastErrorMessage();

   665         KErrDiskFull, There is no available disk space to complete the operation. If the executed statement is a DELETE

   666         			  statement, try to use the reserved disk space (if there is a reserved disk space) to complete the operation.

   667         			  In all other cases the database connection should be closed and some disk space freed before reopening 

   668         			  the database; 

   669         KErrPermissionDenied, the caller does not satisfy the relevant database security policies;

   670                       Note that database specific errors categorised as ESqlDbError, and

   671                       other system-wide error codes may also be returned.

   672 

   673 @capability None, if current RSqlDatabase object represents a handle to a non-secure database;

   674             RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement modifies a secure database schema; 

   675             RSqlSecurityPolicy::EReadPolicy or 

   676             RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement reads from a secure database; 

   677             RSqlSecurityPolicy::EWritePolicy or

   678             RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement writes to a secure database;

   679 

   680 @see RSqlStatement

   681 @see TSqlRetCodeClass::ESqlDbError

   682 @see RSqlDatabase::LastErrorMessage()

   683 @see RSqlSecurityPolicy

   684 @see RSqlSecurityPolicy::TPolicyType

   685 */

   686 EXPORT_C TInt RSqlDatabase::Exec(const TDesC8& aSqlStmt)

   687 	{

   688 	SQLUTRACE_PROFILER(this);

   689 	SYMBIAN_TRACE_SQL_EVENTS_ONLY(UTF::Printf(UTF::TTraceContext(UTF::EInternals), KStrParam, 1, &aSqlStmt));

   690 

   691 	return Impl().Exec(aSqlStmt);

   692 	}

   693 

   694 /**

   695 Executes one or more 16-bit SQL statements asynchronously to allow client to avoid being blocked 

   696 by server activity.

   697 

   698 No other operations can be performed on current RSqlDatabase object and RSqlStatement objects using it

   699 until the asynchronous operation completes.

   700 

   701 This method should be used for executing DDL/DML statements, but note the following point:

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

   703 giving the parameters default NULL values.

   704 

   705 This class (RSqlDatabase) does not offer functions for setting the parameter values. 

   706 Use the RSqlStatement class instead.

   707 

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

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

   710 the error can be obtained calling RSqlDatabase::LastErrorMessage().

   711 

   712 @param aSqlStmt A string of 16-bit wide characters containing one or more DDL/DML SQL statements;

   713                 each statement is separated by a ';' character.

   714 @param aStatus Completion status of asynchronous request, one of the following:

   715 			>=0, The operation has completed successfully. The number of database rows that were 

   716 			   	   changed/inserted/deleted by the most recently completed DDL/DML sql statement.

   717 			 Exception: If the executed statement is "DELETE FROM <table>", then the function returns 0 

   718 			 if the operation has completed successfully (disregarding the number of the deleted rows);

   719         	KErrNoMemory,  an out of memory condition has occured;

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

   721                         can be obtained by calling 	RSqlDatabase::LastErrorMessage();

   722         	KErrDiskFull, There is no available disk space to complete the operation. If the executed statement is a DELETE

   723         			  statement, try to use the reserved disk space (if there is a reserved disk space) to complete the operation.

   724         			  In all other cases the database connection should be closed and some disk space freed before reopening 

   725         			  the database; 

   726         	KErrPermissionDenied, the caller does not satisfy the relevant database security policies;

   727                       Note that aStatus may be set with database specific errors categorised as ESqlDbError, 

   728                       and other system-wide error codes.

   729 

   730 

   731 @capability None, if current RSqlDatabase object represents a handle to a non-secure database;

   732             RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement modifies a secure database schema; 

   733             RSqlSecurityPolicy::EReadPolicy or 

   734             RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement reads from a secure database; 

   735             RSqlSecurityPolicy::EWritePolicy or

   736             RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement writes to a secure database;

   737 

   738 @see RSqlStatement

   739 @see TSqlRetCodeClass::ESqlDbError

   740 @see RSqlDatabase::LastErrorMessage()

   741 @see RSqlSecurityPolicy

   742 @see RSqlSecurityPolicy::TPolicyType

   743 */

   744 EXPORT_C void RSqlDatabase::Exec(const TDesC& aSqlStmt, TRequestStatus& aStatus)

   745 	{

   746 	SQLUTRACE_PROFILER(this);

   747 	SYMBIAN_TRACE_SQL_EVENTS_ONLY(UTF::Printf(UTF::TTraceContext(UTF::EInternals), KStrParam16, 1, &aSqlStmt));

   748 

   749 	Impl().Exec(aSqlStmt, aStatus);

   750 	}

   751 

   752 /**

   753 Executes one or more 8-bit SQL statements asynchronously to allow client to avoid being blocked 

   754 by server activity.

   755 

   756 No other operations can be performed on current RSqlDatabase object and RSqlStatement objects using it

   757 until the asynchronous operation completes.

   758 

   759 This method should be used for executing DDL/DML statements, but note the following point:

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

   761 giving the parameters default NULL values.

   762 

   763 This class (RSqlDatabase) does not offer functions for setting the parameter values. 

   764 Use the RSqlStatement class instead.

   765 

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

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

   768 the error can be obtained calling RSqlDatabase::LastErrorMessage().

   769 

   770 @param aSqlStmt A string of 8-bit wide characters containing one or more DDL/DML SQL statements;

   771                 each statement is separated by a ';' character.

   772 @param aStatus Completion status of asynchronous request, one of the following:

   773 			>=0, The operation has completed successfully. The number of database rows that were 

   774 			   	   changed/inserted/deleted by the most recently completed DDL/DML sql statement.

   775 			 Exception: If the executed statement is "DELETE FROM <table>", then the function returns 0 

   776 			 if the operation has completed successfully (disregarding the number of the deleted rows);

   777         	KErrNoMemory,  an out of memory condition has occured;

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

   779                         can be obtained by calling 	RSqlDatabase::LastErrorMessage();

   780         	KErrDiskFull, There is no available disk space to complete the operation. If the executed statement is a DELETE

   781         			  statement, try to use the reserved disk space (if there is a reserved disk space) to complete the operation.

   782         			  In all other cases the database connection should be closed and some disk space freed before reopening 

   783         			  the database; 

   784         	KErrPermissionDenied, the caller does not satisfy the relevant database security policies;

   785                       Note that aStatus may be set with database specific errors categorised as ESqlDbError, 

   786                       and other system-wide error codes.

   787 

   788 

   789 @capability None, if current RSqlDatabase object represents a handle to a non-secure database;

   790             RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement modifies a secure database schema; 

   791             RSqlSecurityPolicy::EReadPolicy or 

   792             RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement reads from a secure database; 

   793             RSqlSecurityPolicy::EWritePolicy or

   794             RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement writes to a secure database;

   795 

   796 @see RSqlStatement

   797 @see TSqlRetCodeClass::ESqlDbError

   798 @see RSqlDatabase::LastErrorMessage()

   799 @see RSqlSecurityPolicy

   800 @see RSqlSecurityPolicy::TPolicyType

   801 */

   802 EXPORT_C void RSqlDatabase::Exec(const TDesC8& aSqlStmt, TRequestStatus& aStatus)

   803 	{

   804 	SQLUTRACE_PROFILER(this);

   805 	SYMBIAN_TRACE_SQL_EVENTS_ONLY(UTF::Printf(UTF::TTraceContext(UTF::EInternals), KStrParam, 1, &aSqlStmt));

   806 

   807 	Impl().Exec(aSqlStmt, aStatus);

   808 	}

   809 	

   810 /**

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

   812 most recent call to any of the functions:

   813 - RSqlDatabase::Exec()

   814 - RSqlStatement::Exec()

   815 - RSqlStatement::Next()

   816 - RSqlStatement::Reset()

   817 

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

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

   820 type ESqlDbError.

   821 

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

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

   824         zero length.

   825  

   826 @see TSqlRetCodeClass::ESqlDbError

   827 @see RSqlDatabase::Exec()

   828 @see RSqlStatement::Exec()

   829 @see RSqlStatement::Next()

   830 @see RSqlStatement::Reset()

   831 

   832 @capability None

   833 */

   834 EXPORT_C TPtrC RSqlDatabase::LastErrorMessage() const

   835 	{

   836 	SQLUTRACE_PROFILER(0);

   837 	return Impl().LastErrorMessage();

   838 	}

   839 

   840 /**

   841 Returns the ROWID of the most recent successful INSERT into the database 

   842 from this database connection.

   843 

   844 @return >0, the ROWID of the most recent successful INSERT into the database

   845 			from this database connection;

   846 		0, 	if no successful INSERTs have ever occurred from this database connection

   847 		<0, if one of the system-wide error codes is returned

   848 

   849 @capability None

   850 */

   851 EXPORT_C TInt64 RSqlDatabase::LastInsertedRowId() const

   852 	{

   853 	SQLUTRACE_PROFILER(0);

   854 	return Impl().LastInsertedRowId();	

   855 	}

   856 

   857 /**

   858 Checks the database transaction state.

   859 

   860 @return True, if the database is in transaction, false otherwise.

   861 

   862 @capability None

   863 */

   864 EXPORT_C TBool RSqlDatabase::InTransaction() const

   865 	{

   866 	SQLUTRACE_PROFILER(0);

   867 	return Impl().InTransaction();

   868 	}

   869 	

   870 /**

   871 Returns the database file size, in bytes.

   872 

   873 @return >= 0, 		  the operation has completed successfully. The number is the size of the main

   874 					  database file;

   875         KErrNoMemory, an out of memory condition has occurred;

   876         KErrTooBig,   the database is too big and the size cannot fit into 32-bit signed integer;

   877                       Note that database specific errors categorised as ESqlDbError, and

   878                       other system-wide error codes may also be returned.

   879 

   880 @capability None

   881 */

   882 EXPORT_C TInt RSqlDatabase::Size() const

   883 	{

   884 	SQLUTRACE_PROFILER(0);

   885 	return Impl().Size();

   886 	}

   887 

   888 /**

   889 Returns the database file size and free space, in bytes.

   890 

   891 @param aSize An output parameter. If the call was successfull the aSize object will contain information

   892 			 about the database size and database free space.

   893 @param aDbName The attached database name or KNullDesC for the main database

   894 

   895 @return KErrNone, The operation has completed succesfully;

   896         KErrBadName, Invalid (too long) attached database name;

   897         KSqlErrGeneral, There is no an attached database with aDbName name;

   898                   Note that database specific errors categorised as ESqlDbError, and

   899                   other system-wide error codes may also be returned.

   900                   

   901 @capability None

   902 */

   903 EXPORT_C TInt RSqlDatabase::Size(RSqlDatabase::TSize& aSize, const TDesC& aDbName) const

   904 	{

   905 	SQLUTRACE_PROFILER(0);

   906 	SYMBIAN_TRACE_SQL_EVENTS_ONLY(UTF::Printf(UTF::TTraceContext(UTF::EInternals), KStrParam16, 2, &aDbName));

   907 	

   908 	return Impl().Size(aSize, aDbName);

   909 	}

   910 

   911 /**

   912 Compacts the database.

   913 This function should be used for databases that have been configured for a manual compaction during 

   914 the database creation.

   915 The function has no effect if the database has been configured for an auto compaction.

   916 The function has no effect if the aSize argument value is zero.

   917 The function has no effect also if there aren't any free pages in the database file.

   918 If the database has been configured for a background compaction, then the function works as if the database

   919 has been configured for a manual compaction.

   920 

   921 @param aSize Can be one of:

   922 				RSqlDatabase::EMaxCompaction - requests a full database compaction. All free pages

   923 				  (if any exists) will be removed;

   924 				Positive 32-bit signed integer value - the server will attempt to compact the database removing 

   925 				  at most aSize bytes from the database file, rounded up to the nearest page count, 

   926 				  e.g. request for removing 1 byte will remove one free page from the database;

   927 

   928 @param aDbName The attached database name or KNullDesC for the main database

   929 

   930 @return Zero or positive integer - the operation has completed succesfully, the return value is the

   931          						   size of the removed free space in bytes,

   932 		KErrArgument, Invalid aSize value;

   933         KErrBadName, Invalid (too long) attached database name;

   934         KSqlErrReadOnly, Read-only database;

   935         KSqlErrGeneral, There is no an attached database with aDbName name;

   936                   Note that database specific errors categorised as ESqlDbError, and

   937                   other system-wide error codes may also be returned.

   938                   

   939 @capability None

   940 */

   941 EXPORT_C TInt RSqlDatabase::Compact(TInt64 aSize, const TDesC& aDbName)

   942 	{

   943 	SQLUTRACE_PROFILER(this);

   944 	SYMBIAN_TRACE_SQL_EVENTS_ONLY(UTF::Printf(UTF::TTraceContext(UTF::EInternals), KSizeStrParam16, 1, aSize, 2, &aDbName));

   945 

   946 	return Impl().Compact(aSize, aDbName);

   947 	}

   948 	

   949 /**

   950 Compacts the database asynchronously.

   951 This function should be used for databases that have been configured for a manual compaction during 

   952 the database creation.

   953 The function has no effect if the database has been configured for an auto compaction.

   954 The function has no effect if the aSize argument value is zero.

   955 The function has no effect also if there aren't any free pages in the database file.

   956 If the database has been configured for a background compaction, then the function works as if the database

   957 has been configured for a manual compaction.

   958 

   959 @param aStatus Completion status of asynchronous request, one of the following:

   960 		Zero or positive integer - the operation has completed succesfully, the return value is the

   961          						   size of the removed free space in bytes,

   962 		KErrArgument, Invalid aSize value;

   963         KErrBadName, Invalid (too long) attached database name;

   964         KSqlErrReadOnly, Read-only database;

   965         KSqlErrGeneral, There is no an attached database with aDbName name;

   966                   Note that database specific errors categorised as ESqlDbError, and

   967                   other system-wide error codes may also be returned.

   968 

   969 

   970 @param aSize Can be one of:

   971 				 RSqlDatabase::EMaxCompaction - requests a full database compaction. All free pages

   972 				  (if any exists) will be removed;

   973 				 Positive 32-bit signed integer value - the server will attempt to compact the database removing 

   974 				  at most aSize bytes from the database file, rounded up to the nearest page count, 

   975 				  e.g. request for removing 1 byte will remove one free page from the database;

   976 

   977 @param aDbName The attached database name or KNullDesC for the main database

   978                   

   979 @capability None

   980 */

   981 EXPORT_C void RSqlDatabase::Compact(TInt64 aSize, TRequestStatus& aStatus, const TDesC& aDbName)

   982 	{

   983 	SQLUTRACE_PROFILER(this);

   984 	SYMBIAN_TRACE_SQL_EVENTS_ONLY(UTF::Printf(UTF::TTraceContext(UTF::EInternals), KSizeStrParam16, 1, aSize, 3, &aDbName));

   985 

   986 	Impl().Compact(aSize, aDbName, aStatus);

   987 	}

   988 

   989 /**

   990 Reserves a predefined amount of disk space on the drive where the database file is.

   991 

   992 At the moment the max possible amount, allowed by the file server, is reserved on the database file drive.

   993 Use this call to ensure that if your "delete records" transaction fails because of "out of

   994 disk space" circumstances, you can get an access to the already reserved disk space and 

   995 complete your transaction successfully the second time.

   996 

   997 There is no strong, 100% guarantee, that the reserved disk space will always help the client

   998 in "low memory" situations.

   999 

  1000 @param aSpace This parameter is not used at the moment.

  1001 

  1002 @return KErrNone,          The operation has completed succesfully;

  1003 	    KErrNoMemory,      Out of memory condition has occured;

  1004         KErrAlreadyExists, The space has already been reserved;

  1005                            Note that other system-wide error codes may also be returned.

  1006 

  1007 @see RSqlDatabase::FreeReservedSpace()

  1008 @see RSqlDatabase::GetReserveAccess()

  1009 @see RSqlDatabase::ReleaseReserveAccess()

  1010 */

  1011 EXPORT_C TInt RSqlDatabase::ReserveDriveSpace(TInt aSize)

  1012 	{

  1013 	SQLUTRACE_PROFILER(this);

  1014 	//Usage of the IPC call arguments: 

  1015 	//Arg 0: [out]  requested size

  1016 	return Impl().Session().SendReceive(ESqlSrvDbReserveDriveSpace, TIpcArgs(aSize));

  1017 	}

  1018 	

  1019 /**

  1020 Frees the reserved disk space.

  1021 

  1022 @see RSqlDatabase::ReserveDriveSpace()

  1023 @see RSqlDatabase::GetReserveAccess()

  1024 @see RSqlDatabase::ReleaseReserveAccess()

  1025 */

  1026 EXPORT_C void RSqlDatabase::FreeReservedSpace()

  1027 	{

  1028 	SQLUTRACE_PROFILER(this);

  1029 	Impl().Session().SendReceive(ESqlSrvDbFreeReservedSpace);

  1030 	}

  1031 	

  1032 /**

  1033 Gives the client an access to the already reserved disk space.

  1034 

  1035 @return KErrNone,     The operation has completed succesfully;

  1036         KErrNotFound, An attempt is made to get an access to a disk space, which is not reserved yet;

  1037         KErrInUse,    An access to the reserved space has already been given;

  1038                       Note that other system-wide error codes may also be returned.

  1039 

  1040 @see RSqlDatabase::ReserveDriveSpace()

  1041 @see RSqlDatabase::FreeReservedSpace()

  1042 @see RSqlDatabase::ReleaseReserveAccess()

  1043 */

  1044 EXPORT_C TInt RSqlDatabase::GetReserveAccess()

  1045 	{

  1046 	SQLUTRACE_PROFILER(this);

  1047 	return Impl().Session().SendReceive(ESqlSrvDbGetReserveAccess);

  1048 	}

  1049 	

  1050 /**

  1051 Releases the access to the reserved disk space.

  1052 

  1053 @see RSqlDatabase::ReserveDriveSpace()

  1054 @see RSqlDatabase::FreeReservedSpace()

  1055 @see RSqlDatabase::GetReserveAccess()

  1056 */

  1057 EXPORT_C void RSqlDatabase::ReleaseReserveAccess()

  1058 	{

  1059 	SQLUTRACE_PROFILER(this);

  1060 	Impl().Session().SendReceive(ESqlSrvDbReleaseReserveAccess);

  1061 	}

  1062 

  1063 /**

  1064 Returns a reference to the implementation object of RSqlDatabase - CSqlDatabaseImpl.

  1065 

  1066 @panic SqlDb 2 Create() or Open() has not previously been called on this RSqlDatabase object.

  1067 

  1068 @internalComponent

  1069 */

  1070 CSqlDatabaseImpl& RSqlDatabase::Impl() const

  1071 	{

  1072 	__SQLASSERT_ALWAYS(iImpl != NULL, ESqlPanicInvalidObj);

  1073 	return *iImpl;	

  1074 	}