1 // Copyright (c) 1998-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 "UD_STD.H"

    17 

    18 // Class RDbDatabase

    19 

    20 /**

    21 Closes a database. Commits any pending transaction. Frees the allocated resources.

    22 */

    23 EXPORT_C void RDbDatabase::Close()

    24 	{

    25 	CDbDatabase* db=iDatabase();

    26 	if (db && InTransaction())

    27 		Commit();	// attempt to commit

    28 	iDatabase.Close();

    29 	}

    30 

    31 //

    32 // Runs the incremental DDL object to completion.

    33 //

    34 LOCAL_C void CompleteDDLL(CDbIncremental* aIncremental,TInt& aStep)

    35 	{

    36 	__ASSERT((aIncremental==0)==(aStep==0));

    37 	if (!aIncremental)

    38 		return;

    39 	aIncremental->PushL();

    40 	do aIncremental->NextL(aStep);

    41 		while (aStep!=0);

    42 	CleanupStack::PopAndDestroy();	// aIncrmental

    43 	}

    44 

    45 //

    46 // Runs the DML incremental object to completion.

    47 //

    48 LOCAL_C void CompleteDMLL(CDbIncremental* aIncremental,TInt& aRows)

    49 	{

    50 	__ASSERT((aIncremental==0)!=(aRows==0));

    51 	if (!aIncremental)

    52 		return;

    53 	aIncremental->PushL();

    54 	while (aIncremental->NextL(aRows))

    55 		;

    56 	CleanupStack::PopAndDestroy();	// aIncremental

    57 	}

    58 

    59 LOCAL_C TInt Property(const RDbHandle<CDbDatabase>& aDb,CDbDatabase::TProperty aProperty)

    60 	{

    61 	return aDb->Property(aProperty);

    62 	}

    63 

    64 LOCAL_C TInt Utility(RDbHandle<CDbDatabase>& aDb,CDbDatabase::TUtility aType)

    65 	{

    66 	TInt step;

    67 	TRAPD(r,CompleteDDLL(aDb->UtilityL(aType,step),step));

    68 	return r;

    69 	}

    70 

    71 /**

    72 Reports the damage status of the database.

    73 The function checks database indexes and returs true if some of them are broken.

    74 

    75 @return True if the database is damaged, false otherwise.

    76 */

    77 EXPORT_C TBool RDbDatabase::IsDamaged() const

    78 	{

    79 	return Property(iDatabase,CDbDatabase::EIsDamaged);

    80 	}

    81 

    82 /**

    83 Synchronous database recovery.

    84 Recover() will try to rebuild database indexes if they are broken.

    85 If the database data is corrupted, it cannot be recovered.

    86 

    87 @return KErrNone The operation has completed successfully;

    88         KErrNoMemory, an out of memory condition has occurred;

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

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

    91 

    92 @capability Note For a secure shared database, the caller must satisfy the write 

    93             access policy for the database.

    94 */

    95 EXPORT_C TInt RDbDatabase::Recover()

    96 	{

    97 	return Utility(iDatabase,CDbDatabase::ERecover);

    98 	}

    99 

   100 /**

   101 Returns the currently available size information for the database. 

   102 This comprises a size in bytes for the database objects and a percentage used value which indicates 

   103 how much of that size is live data-the remainder may be available for compaction. 

   104 Some types of database may not be able to report this information, e.g. a RDbStoreDatabase, 

   105 and others may need to have UpdateStats() in order to provide valid data. 

   106 In these cases, the values in the RDbDatabase::TSize structure will contain an error value to indicate this.

   107 

   108 @return RDbDatabase::TSize object, containing the database size and the percentage used value.

   109 */

   110 EXPORT_C RDbDatabase::TSize RDbDatabase::Size() const

   111 	{

   112 	TSize size;

   113 	size.iSize=Property(iDatabase,CDbDatabase::ESize);

   114 	size.iUsage=Property(iDatabase,CDbDatabase::EUsage);

   115 	return size;

   116 	}

   117 

   118 /**

   119 Update any calculated statistics for the database. 

   120 Note that this can take an extended time to complete, 

   121 so an incremental form is also provided - RDbIncremental::UpdateStats().

   122 

   123 @return KErrNone The operation has completed successfully;

   124         KErrNoMemory, an out of memory condition has occurred;

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

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

   127 

   128 @capability Note For a secure shared database, the caller must satisfy the write 

   129             access policy for the database.

   130             

   131 @see RDbIncremental::UpdateStats()

   132 */

   133 EXPORT_C TInt RDbDatabase::UpdateStats()

   134 	{

   135 	return Utility(iDatabase,CDbDatabase::EStats);

   136 	}

   137 

   138 /**

   139 Synchronous database compaction.

   140 Compacts the database and returns when complete. 

   141 Note that this can take an extended time to complete, so an incremental form is also provided.

   142 There is a complementary interface to calculate and report database size and usage information, which

   143 can be used by the clients to determine when it may be appropriate to compact the database. 

   144 

   145 @see RDbIncremental::Compact()

   146 @see RDbDatabase::UpdateStats()

   147 @see RDbDatabase::Size()

   148 

   149 @return KErrNone The operation has completed successfully;

   150         KErrNoMemory, an out of memory condition has occurred;

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

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

   153 

   154 @capability Note For a secure shared database, the caller must satisfy the write 

   155             access policy for the database.

   156 */

   157 EXPORT_C TInt RDbDatabase::Compact()

   158 	{

   159 	return Utility(iDatabase,CDbDatabase::ECompact);

   160 	}

   161 

   162 

   163 /**

   164 Drops the tables and destroys the database.

   165 This handle is closed on successful destruction.

   166 

   167 @return KErrNone The operation has completed successfully;

   168         KErrNoMemory, an out of memory condition has occurred;

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

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

   171 

   172 @capability Note For a secure shared database, the caller must satisfy the schema 

   173             access policy for the database.

   174 */

   175 EXPORT_C TInt RDbDatabase::Destroy()

   176 	{

   177 	CDbTableNames* t=NULL;

   178 	TRAPD(r,t=TableNamesL());

   179 	if (r!=KErrNone)

   180 		return r;

   181 	TInt ii=t->Count();

   182 	do

   183 		{

   184 		if (--ii<0)

   185 			{

   186 			r=iDatabase->Destroy();

   187 			if (r==KErrNone)

   188 				iDatabase.Close();

   189 			break;

   190 			}

   191 		r=DropTable((*t)[ii]);

   192 		} while (r==KErrNone);

   193 	delete t;

   194 	return r;

   195 	}

   196 

   197 /**

   198 Begins a transaction.

   199 

   200 DBMS server only supports one 'granularity' of transaction lock: the whole database. 

   201 Beginning a transaction locks the database, and this can fail if another client has already got a lock which 

   202 excludes this client.

   203 If the same client has already locked the database it will be panic'd.

   204 The function is guaranteed to return KErrNone for client-side access. 

   205 

   206 DBMS transactions do not provide any form of isolation between the clients: 

   207 while one client is updating a table within a transaction, other clients will be able to see the changes as 

   208 they are made. As a result, if a client retrieves two separate rows  from a database there is no automatic 

   209 guarantee that the data being retrieved has not been changed between the reads - this can lead to 

   210 an 'inconsistent read'. A client can prevent an update while retrieving related rows by enclosing the individual 

   211 reads within a transaction. Such a transaction will not modify the database and only operates as a read-lock: 

   212 releasing such a lock using Commit() or Rollback() will not affect the database in any way.

   213 

   214 How RDbDatabase::Begin() works:

   215  - on a shared database Begin() will attempt to get a shared read-lock on the database, and will fail with 

   216    KErrLocked if anyone has an exclusive write-lock. Other clients with read-locks will not cause this operation 

   217    to fail.

   218  - any operation which will modify the database attempts to gain an exclusive write-lock on the database, 

   219    and will fail with KErrLocked if anyone else has any lock on the database. If the current client already has 

   220    a read-lock as a result of calling Begin(), then it will be upgraded to an exclusive write-lock.

   221  - Commit() or Rollback() after a read-lock has been acquired (but not a write-lock) will release that client's 

   222    lock. The database will only be considered to be unlocked when all such locks are removed by all clients, 

   223    when it will report a EUnlock event to any notifiers.

   224  - Commit() or Rollback() after a write-lock has been acquired will release the lock, and report the ECommit or 

   225    ERollback event to any notifiers.

   226  - automatic transactions will be used as at present if updates are made outside of explicit transactions, 

   227    and such updates will also be able to fail with KErrLocked if an exclusive lock cannot be acquired.

   228    

   229 Allowing read-locks to be shared enables greater concurrency at the same time as providing some safe guard 

   230 against inconsistent reads. It does, however, lead to the possibility of deadlock: two clients wanting to update 

   231 the database can reach deadlock if they both Begin() a transaction before either of them starts an update, 

   232 then one client's read-lock will prevent the other from upgrading to a write lock and vice versa. The only way out

   233 of this is to code the clients in such a way as to back out of such a deadlock situation, rather than retry 

   234 forever without releasing the locks. 

   235 

   236 A client will be able to change the database schema while other clients are using the database, 

   237 as long as the other clients have no locks on it. As described above, other clients may find that their

   238 rowsets are then invalidated asynchronously as a result of this.

   239 

   240 @return KErrNone The operation has completed successfully;

   241         KErrLocked, the database is locked by another client;

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

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

   244 

   245 @capability Note For a secure shared database, the caller must satisfy either the read, write

   246 			or the schema access policy for the database.

   247 */

   248 EXPORT_C TInt RDbDatabase::Begin()

   249 	{

   250 	return iDatabase->Begin();

   251 	}

   252 

   253 /**

   254 Commits the current transaction.

   255 

   256 @return KErrNone The operation has completed successfully;

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

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

   259 

   260 @capability Note For a secure shared database, the caller must satisfy either the read, write

   261 			or the schema access policy for the database.

   262 */

   263 EXPORT_C TInt RDbDatabase::Commit()

   264 	{

   265 	return iDatabase->Commit();

   266 	}

   267 

   268 /**

   269 Rollbacks the current transaction.

   270 

   271 @capability Note For a secure shared database, the caller must satisfy either the read, write

   272 			or the schema access policy for the database.

   273 */

   274 EXPORT_C void RDbDatabase::Rollback()

   275 	{

   276 	iDatabase->Rollback();

   277 	}

   278 

   279 /**

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

   281 */

   282 EXPORT_C TBool RDbDatabase::InTransaction() const

   283 	{

   284 	return Property(iDatabase,CDbDatabase::EInTransaction);

   285 	}

   286 

   287 /**

   288 Creates a table on the database.

   289 

   290 @param aName Table name.

   291 @param aColSet A set of column definitions which describe the table structure.

   292 @param aPrimaryKey Primary key definition. If it is NULL, no primary key will be created for the new table.

   293 

   294 @return KErrNone The operation has completed successfully;

   295         KErrNoMemory, an out of memory condition has occurred;

   296         KErrAlreadyExists, a table with that name already exists;

   297         KErrArgument, empty column set, duplicated column name, invalid column length;

   298         KErrBadName, invalid table name, invalid column name (containing spaces for example);

   299         KErrNotSupported, unknown column type, unknown column attributes;

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

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

   302 

   303 @capability Note For a secure shared database, the caller must satisfy the schema 

   304             access policy for the database.

   305 */

   306 EXPORT_C TInt RDbDatabase::CreateTable(const TDesC& aName,const CDbColSet& aColSet,const CDbKey* aPrimaryKey)

   307 	{

   308 	TRAPD(r,iDatabase->CreateTableL(aName,aColSet,aPrimaryKey));

   309 	return r;

   310 	}

   311 

   312 /**

   313 Drops a table synchronously.

   314 

   315 @param aName Table name.

   316 

   317 @return KErrNone The operation has completed successfully;

   318         KErrNotFound, there is no table with the supplied name;

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

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

   321 

   322 @capability Note For a secure shared database, the caller must satisfy the schema 

   323             access policy for the database.

   324 */

   325 EXPORT_C TInt RDbDatabase::DropTable(const TDesC& aName)

   326 	{

   327 	TInt step;

   328 	TRAPD(r,CompleteDDLL(iDatabase->DropTableL(aName,step),step));

   329 	return r;

   330 	}

   331 

   332 /**

   333 Alters a table synchronously.

   334 

   335 @param aName Table name.

   336 @param aColSet A new set of column definitions which describe the table structure.

   337 

   338 @return KErrNone The operation has completed successfully;

   339         KErrNoMemory, an out of memory condition has occurred;

   340         KErrArgument, empty column set, duplicated column name, invalid column length;

   341         KErrNotFound, there is no table with the supplied name;

   342         KErrNotSupported, unknown column type, unknown column attributes;

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

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

   345 

   346 @capability Note For a secure shared database, the caller must satisfy the schema 

   347             access policy for the database.

   348 */

   349 EXPORT_C TInt RDbDatabase::AlterTable(const TDesC& aName,const CDbColSet& aColSet)

   350 	{

   351 	TInt step;

   352 	TRAPD(r,CompleteDDLL(iDatabase->AlterTableL(aName,aColSet,step),step));

   353 	return r;

   354 	}

   355 

   356 /**

   357 Creates an index synchronously.

   358 

   359 @param aName Index name.

   360 @param aTableName Table name.

   361 @param aKey Index definition

   362 

   363 @return KErrNone The operation has completed successfully;

   364         KErrNoMemory, an out of memory condition has occurred;

   365         KErrBadName, invalid index name (containing spaces for example);

   366         KErrAlreadyExists, an index with that name already exists;

   367         KErrNotFound, there is no table with that name;

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

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

   370 

   371 @capability Note For a secure shared database, the caller must satisfy the schema 

   372             access policy for the database.

   373 */

   374 EXPORT_C TInt RDbDatabase::CreateIndex(const TDesC& aName,const TDesC& aTableName,const CDbKey& aKey)

   375 	{

   376 	TInt step;

   377 	TRAPD(r,CompleteDDLL(iDatabase->CreateIndexL(aName,aTableName,aKey,step),step));

   378 	return r;

   379 	}

   380 

   381 /**

   382 Drops an index synchronously.

   383 

   384 @param aName Index name.

   385 @param aTableName Table name.

   386 

   387 @return KErrNone The operation has completed successfully;

   388         KErrNotFound, there is no table or index with that name;

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

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

   391 

   392 @capability Note For a secure shared database, the caller must satisfy the schema 

   393             access policy for the database.

   394 */

   395 EXPORT_C TInt RDbDatabase::DropIndex(const TDesC& aName,const TDesC& aTableName)

   396 	{

   397 	TInt step;

   398 	TRAPD(r,CompleteDDLL(iDatabase->DropIndexL(aName,aTableName,step),step));

   399 	return r;

   400 	}

   401 

   402 /**

   403 Executes a SQL statement on the database, and returns when it is complete. 

   404 The aComp parameter is used in the execution of some SQL statements:

   405  - in CREATE INDEX statements it specifies the comparison operation used for text columns in the index key;

   406  - in UPDATE and DELETE statements it specifies the comparison operation used to evaluate the WHERE clause;

   407 Other statements ignore the value of aComp.

   408 A negative return value indicates an error. A successful DDL operation always returns KErrNone (zero), 

   409 a successful DML operation returns the number of rows that were inserted, updated or deleted by the operation.

   410 

   411 @param aSql A string of 16-bit wide characters containing one SQL statement.

   412 @param aComparison Tells the DBMS how to compare text and long text columns.

   413 

   414 @return Zero or positive value, the number of rows that were inserted, updated or deleted by the operation;

   415 		KErrLocked, the database is locked by another client;

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

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

   418 

   419 @capability Note For a secure shared database, the caller must satisfy:

   420             - the schema access policy for the database, if the SQL statement is 

   421 			  CREATE/DROP/ALTER; 

   422             - the write access policy for the table in the SQL, if the SQL statement is 

   423 			  INSERT/UPDATE/DELETE; 

   424 */

   425 EXPORT_C TInt RDbDatabase::Execute(const TDesC& aSql,TDbTextComparison aComparison)

   426 	{

   427 	TInt ret;

   428 	TRAP(ret, \

   429 		CDbIncremental* inc=iDatabase->ExecuteL(aSql,aComparison,ret); \

   430 		if (inc) \

   431 			ret ? CompleteDDLL(inc,ret) : CompleteDMLL(inc,ret); \

   432 		)

   433 	return ret;

   434 	}

   435 

   436 /**

   437 Lists the tables on the database.

   438 

   439 @return A pointer to a CDbTableNames container with table names. The caller is responsible for destroying

   440         the returned CDbTableNames instance.

   441 

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

   443                      Note that the function may leave with other system-wide error codes.

   444 */

   445 EXPORT_C CDbTableNames* RDbDatabase::TableNamesL() const

   446 	{

   447 	CDbTableNames* names=CDbTableNames::NewLC();

   448 	iDatabase->TablesL(*names);

   449 	CleanupStack::Pop();

   450 	return names;

   451 	}

   452 

   453 /**

   454 Returns the table definition.

   455 

   456 @param aName Table name.

   457 

   458 @return A pointer to a CDbColSet container with column definitions . The caller is responsible for destroying

   459         the returned CDbColSet instance.

   460 

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

   462 	   KErrNotFound, no table with that name exists;

   463                      Note that the function may leave with other system-wide error codes.

   464 */

   465 EXPORT_C CDbColSet* RDbDatabase::ColSetL(const TDesC& aName) const

   466 	{

   467 	CDbColSet* set=CDbColSet::NewLC();

   468 	iDatabase->ColumnsL(*set,aName);

   469 	CleanupStack::Pop();

   470 	return set;

   471 	}

   472 

   473 /**

   474 Lists the indexes on a table.

   475 

   476 @param aTable Table name.

   477 

   478 @return A pointer to a CDbIndexNames container with column definitions . The caller is responsible for destroying

   479         the returned CDbIndexNames instance.

   480 

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

   482 	   KErrNotFound, no table with that name exists;

   483                      Note that the function may leave with other system-wide error codes.

   484 */

   485 EXPORT_C CDbIndexNames* RDbDatabase::IndexNamesL(const TDesC& aTable) const

   486 	{

   487 	CDbIndexNames* names=CDbIndexNames::NewLC();

   488 	iDatabase->IndexesL(*names,aTable);

   489 	CleanupStack::Pop();

   490 	return names;

   491 	}

   492 

   493 /**

   494 Returns the index key.

   495 

   496 @param aName Index name.

   497 @param aTable Table name.

   498 

   499 @return A pointer to a CDbKey object containing the index definition. The caller is responsible for destroying

   500         the returned CDbKey instance.

   501 

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

   503 	   KErrNotFound, no index or table with that name exists;

   504                      Note that the function may leave with other system-wide error codes.

   505 */

   506 EXPORT_C CDbKey* RDbDatabase::KeyL(const TDesC& aName,const TDesC& aTable) const

   507 	{

   508 	CDbKey* key=CDbKey::NewLC();

   509 	iDatabase->KeysL(*key,aName,aTable);

   510 	CleanupStack::Pop();

   511 	return key;

   512 	}

   513 

   514 // class CDbDatabase

   515 

   516 CDbNotifier* CDbDatabase::NotifierL()

   517 	{

   518 	return AttachContext(this,OpenNotifierL());

   519 	}

   520 

   521 CDbIncremental* CDbDatabase::UtilityL(CDbDatabase::TUtility aType,TInt& aStep)

   522 	{

   523 	return AttachContext(this,OpenUtilityL(aType,aStep));

   524 	}

   525 

   526 CDbIncremental* CDbDatabase::DropTableL(const TDesC& aTable,TInt& aStep)

   527 	{

   528 	return AttachContext(this,OpenDropTableL(aTable,aStep));

   529 	}

   530 

   531 CDbIncremental* CDbDatabase::AlterTableL(const TDesC& aTable,const CDbColSet& aNewDef,TInt& aStep)

   532 	{

   533 	return AttachContext(this,OpenAlterTableL(aTable,aNewDef,aStep));

   534 	}

   535 

   536 CDbIncremental* CDbDatabase::CreateIndexL(const TDesC& aName,const TDesC& aTable,const CDbKey& aKey,TInt& aStep)

   537 	{

   538 	return AttachContext(this,OpenCreateIndexL(aName,aTable,aKey,aStep));

   539 	}

   540 

   541 CDbIncremental* CDbDatabase::DropIndexL(const TDesC& aName,const TDesC& aTable,TInt& aStep)

   542 	{

   543 	return AttachContext(this,OpenDropIndexL(aName,aTable,aStep));

   544 	}

   545 

   546 CDbIncremental* CDbDatabase::ExecuteL(const TDesC& aSql,TDbTextComparison aComparison,TInt& aInit)

   547 	{

   548 	return AttachContext(this,OpenExecuteL(aSql,aComparison,aInit));

   549 	}

   550 

   551 CDbCursor* CDbDatabase::ViewL(const TDbQuery& aQuery,const TDbWindow& aWindow,RDbRowSet::TAccess anAccess)

   552 	{

   553 	return AttachContext(this,PrepareViewL(aQuery,aWindow,anAccess));

   554 	}

   555 

   556 CDbCursor* CDbDatabase::TableL(const TDesC &aName,RDbRowSet::TAccess anAccess)

   557 	{

   558 	return AttachContext(this,OpenTableL(aName,anAccess));

   559 	}

   560 

   561 //

   562 // Reserved for future development

   563 //

   564 EXPORT_C void CDbDatabase::Reserved_1()

   565 	{

   566 	}

   567 

   568 //

   569 // Reserved for future development

   570 //

   571 EXPORT_C void CDbDatabase::Reserved_2()

   572 	{

   573 	}