#include <d32dbms.h>
| class RDbDatabase |
| Protected Attributes | |
|---|---|
| RDbHandle< CDbDatabase > | iDatabase |
| Public Member Functions | |
|---|---|
| IMPORT_C TInt | AlterTable(const TDesC &, const CDbColSet &) |
| IMPORT_C TInt | Begin() |
| IMPORT_C void | Close() |
| IMPORT_C CDbColSet * | ColSetL(const TDesC &) |
| IMPORT_C TInt | Commit() |
| IMPORT_C TInt | Compact() |
| IMPORT_C TInt | CreateIndex(const TDesC &, const TDesC &, const CDbKey &) |
| TInt | CreateTable(const TDesC &, const CDbColSet &) |
| TInt | CreateTable(const TDesC &, const CDbColSet &, const CDbKey &) |
| IMPORT_C TInt | Destroy() |
| IMPORT_C TInt | DropIndex(const TDesC &, const TDesC &) |
| IMPORT_C TInt | DropTable(const TDesC &) |
| IMPORT_C TInt | Execute(const TDesC &, TDbTextComparison) |
| IMPORT_C TBool | InTransaction() |
| IMPORT_C CDbIndexNames * | IndexNamesL(const TDesC &) |
| IMPORT_C TBool | IsDamaged() |
| IMPORT_C CDbKey * | KeyL(const TDesC &, const TDesC &) |
| IMPORT_C TInt | Recover() |
| IMPORT_C void | Rollback() |
| IMPORT_C TSize | Size() |
| IMPORT_C CDbTableNames * | TableNamesL() |
| IMPORT_C TInt | UpdateStats() |
Abstract class providing the functionality of a database.
The source of the database and the implementation characteristics of a particular database are provided by a class derived from RDbDatabase.
DBMS has one such implementation: the store database.
This class is not intended for user derivation.
Note: For functions (i.e. Execute) that take an Sql string, if the string contains a LIKE clause with * (asterisks) wildcard then the characters between them must be no longer than length 255. If only one * exists then the length is taken from the start and to the end of the clause. However, if the clause contains a ? (question mark) wildcard within it then the characters between must be no longer than length 253.
Alters a table synchronously.
| Parameter | Description |
|---|---|
| aName | Table name. |
| aNewDef | A new set of column definitions which describe the table structure. |
Returns: KErrNone The operation has completed successfully; KErrNoMemory, an out of memory condition has occurred; KErrArgument, empty column set, duplicated column name, invalid column length; KErrNotFound, there is no table with the supplied name; KErrNotSupported, unknown column type, unknown column attributes; KErrPermissionDenied, the caller does not satisfy the relevant database security policies. Note that other system-wide error codes may also be returned.
| IMPORT_C TInt | Begin | ( | ) |
Begins a transaction.
DBMS server only supports one 'granularity' of transaction lock: the whole database. Beginning a transaction locks the database, and this can fail if another client has already got a lock which excludes this client. If the same client has already locked the database it will be panic'd. The function is guaranteed to return KErrNone for client-side access.
DBMS transactions do not provide any form of isolation between the clients: while one client is updating a table within a transaction, other clients will be able to see the changes as they are made. As a result, if a client retrieves two separate rows from a database there is no automatic guarantee that the data being retrieved has not been changed between the reads - this can lead to an 'inconsistent read'. A client can prevent an update while retrieving related rows by enclosing the individual reads within a transaction. Such a transaction will not modify the database and only operates as a read-lock: releasing such a lock using Commit() or Rollback() will not affect the database in any way.
on a shared database Begin() will attempt to get a shared read-lock on the database, and will fail with KErrLocked if anyone has an exclusive write-lock. Other clients with read-locks will not cause this operation to fail.
any operation which will modify the database attempts to gain an exclusive write-lock on the database, and will fail with KErrLocked if anyone else has any lock on the database. If the current client already has a read-lock as a result of calling Begin(), then it will be upgraded to an exclusive write-lock.
Commit() or Rollback() after a read-lock has been acquired (but not a write-lock) will release that client's lock. The database will only be considered to be unlocked when all such locks are removed by all clients, when it will report a EUnlock event to any notifiers.
Commit() or Rollback() after a write-lock has been acquired will release the lock, and report the ECommit or ERollback event to any notifiers.
automatic transactions will be used as at present if updates are made outside of explicit transactions, and such updates will also be able to fail with KErrLocked if an exclusive lock cannot be acquired.
Allowing read-locks to be shared enables greater concurrency at the same time as providing some safe guard against inconsistent reads. It does, however, lead to the possibility of deadlock: two clients wanting to update the database can reach deadlock if they both Begin() a transaction before either of them starts an update, then one client's read-lock will prevent the other from upgrading to a write lock and vice versa. The only way out of this is to code the clients in such a way as to back out of such a deadlock situation, rather than retry forever without releasing the locks.
A client will be able to change the database schema while other clients are using the database, as long as the other clients have no locks on it. As described above, other clients may find that their rowsets are then invalidated asynchronously as a result of this.
Returns: KErrNone The operation has completed successfully; KErrLocked, the database is locked by another client; KErrPermissionDenied, the caller does not satisfy the relevant database security policies. Note that other system-wide error codes may also be returned.
| IMPORT_C void | Close | ( | ) |
Closes a database. Commits any pending transaction. Frees the allocated resources.
Returns the table definition.
| Parameter | Description |
|---|---|
| aName | Table name. |
Returns: A pointer to a CDbColSet container with column definitions . The caller is responsible for destroying the returned CDbColSet instance.
| IMPORT_C TInt | Commit | ( | ) |
Commits the current transaction.
Returns: KErrNone The operation has completed successfully; KErrPermissionDenied, the caller does not satisfy the relevant database security policies. Note that other system-wide error codes may also be returned.
| IMPORT_C TInt | Compact | ( | ) |
Synchronous database compaction. Compacts the database and returns when complete. Note that this can take an extended time to complete, so an incremental form is also provided. There is a complementary interface to calculate and report database size and usage information, which can be used by the clients to determine when it may be appropriate to compact the database.
See also: RDbIncremental::Compact() RDbDatabase::UpdateStats() RDbDatabase::Size()
Returns: KErrNone The operation has completed successfully; KErrNoMemory, an out of memory condition has occurred; KErrPermissionDenied, the caller does not satisfy the relevant database security policies. Note that other system-wide error codes may also be returned.
Creates an index synchronously.
| Parameter | Description |
|---|---|
| aName | Index name. |
| aTable | Table name. |
| aKey | Index definition |
Returns: KErrNone The operation has completed successfully; KErrNoMemory, an out of memory condition has occurred; KErrBadName, invalid index name (containing spaces for example); KErrAlreadyExists, an index with that name already exists; KErrNotFound, there is no table with that name; KErrPermissionDenied, the caller does not satisfy the relevant database security policies. Note that other system-wide error codes may also be returned.
Creates a table on the database.
| Parameter | Description |
|---|---|
| aName | Table name. |
| aDef | A set of column definitions which describe the table structure. |
Returns: KErrNone The operation has completed successfully; KErrNoMemory, an out of memory condition has occurred; KErrAlreadyExists, a table with that name already exists; KErrArgument, empty column set, duplicated column name, invalid column length; KErrBadName, invalid table name, invalid column name (containing spaces for example); KErrNotSupported, unknown column type, unknown column attributes; KErrPermissionDenied, the caller does not satisfy the relevant database security policies. Note that other system-wide error codes may also be returned.
Creates a table on the database.
| Parameter | Description |
|---|---|
| aName | Table name. |
| aDef | A set of column definitions which describe the table structure. |
| aPrimaryKey | Primary key definition. |
Returns: KErrNone The operation has completed successfully; KErrNoMemory, an out of memory condition has occurred; KErrAlreadyExists, a table with that name already exists; KErrArgument, empty column set, duplicated column name, invalid column length; KErrBadName, invalid table name, invalid column name (containing spaces for example); KErrNotSupported, unknown column type, unknown column attributes; KErrPermissionDenied, the caller does not satisfy the relevant database security policies. Note that other system-wide error codes may also be returned.
| IMPORT_C TInt | Destroy | ( | ) |
Drops the tables and destroys the database. This handle is closed on successful destruction.
Returns: KErrNone The operation has completed successfully; KErrNoMemory, an out of memory condition has occurred; KErrPermissionDenied, the caller does not satisfy the relevant database security policies. Note that other system-wide error codes may also be returned.
Drops an index synchronously.
| Parameter | Description |
|---|---|
| aName | Index name. |
| aTable | Table name. |
Returns: KErrNone The operation has completed successfully; KErrNotFound, there is no table or index with that name; KErrPermissionDenied, the caller does not satisfy the relevant database security policies. Note that other system-wide error codes may also be returned.
Drops a table synchronously.
| Parameter | Description |
|---|---|
| aName | Table name. |
Returns: KErrNone The operation has completed successfully; KErrNotFound, there is no table with the supplied name; KErrPermissionDenied, the caller does not satisfy the relevant database security policies. Note that other system-wide error codes may also be returned.
| IMPORT_C TInt | Execute | ( | const TDesC & | aSql, |
| TDbTextComparison | aComparison = EDbCompareNormal | |||
| ) | ||||
in CREATE INDEX statements it specifies the comparison operation used for text columns in the index key;
in UPDATE and DELETE statements it specifies the comparison operation used to evaluate the WHERE clause; Other statements ignore the value of aComp. A negative return value indicates an error. A successful DDL operation always returns KErrNone (zero), a successful DML operation returns the number of rows that were inserted, updated or deleted by the operation.
the schema access policy for the database, if the SQL statement is CREATE/DROP/ALTER;
the write access policy for the table in the SQL, if the SQL statement is INSERT/UPDATE/DELETE;
| Parameter | Description |
|---|---|
| aSql | A string of 16-bit wide characters containing one SQL statement. |
| aComparison | Tells the DBMS how to compare text and long text columns. |
Returns: Zero or positive value, the number of rows that were inserted, updated or deleted by the operation; KErrLocked, the database is locked by another client; KErrPermissionDenied, the caller does not satisfy the relevant database security policies. Note that other system-wide error codes may also be returned.
| IMPORT_C TBool | InTransaction | ( | ) | const |
Returns: True if the database is in a transaction, false otherwise.
| IMPORT_C CDbIndexNames * | IndexNamesL | ( | const TDesC & | aTable | ) | const |
Lists the indexes on a table.
| Parameter | Description |
|---|---|
| aTable | Table name. |
Returns: A pointer to a CDbIndexNames container with column definitions . The caller is responsible for destroying the returned CDbIndexNames instance.
| IMPORT_C TBool | IsDamaged | ( | ) | const |
Reports the damage status of the database. The function checks database indexes and returs true if some of them are broken.
Returns: True if the database is damaged, false otherwise.
Returns the index key.
| Parameter | Description |
|---|---|
| aName | Index name. |
| aTable | Table name. |
Returns: A pointer to a CDbKey object containing the index definition. The caller is responsible for destroying the returned CDbKey instance.
| IMPORT_C TInt | Recover | ( | ) |
Synchronous database recovery. Recover() will try to rebuild database indexes if they are broken. If the database data is corrupted, it cannot be recovered.
Returns: KErrNone The operation has completed successfully; KErrNoMemory, an out of memory condition has occurred; KErrPermissionDenied, the caller does not satisfy the relevant database security policies. Note that other system-wide error codes may also be returned.
| IMPORT_C void | Rollback | ( | ) |
Rollbacks the current transaction.
| IMPORT_C TSize | Size | ( | ) | const |
Returns the currently available size information for the database. This comprises a size in bytes for the database objects and a percentage used value which indicates how much of that size is live data-the remainder may be available for compaction. Some types of database may not be able to report this information, e.g. a RDbStoreDatabase, and others may need to have UpdateStats() in order to provide valid data. In these cases, the values in the RDbDatabase::TSize structure will contain an error value to indicate this.
Returns: RDbDatabase::TSize object, containing the database size and the percentage used value.
| IMPORT_C CDbTableNames * | TableNamesL | ( | ) | const |
Lists the tables on the database.
Returns: A pointer to a CDbTableNames container with table names. The caller is responsible for destroying the returned CDbTableNames instance.
| IMPORT_C TInt | UpdateStats | ( | ) |
Update any calculated statistics for the database. Note that this can take an extended time to complete, so an incremental form is also provided - RDbIncremental::UpdateStats().
See also: RDbIncremental::UpdateStats()
Returns: KErrNone The operation has completed successfully; KErrNoMemory, an out of memory condition has occurred; KErrPermissionDenied, the caller does not satisfy the relevant database security policies. Note that other system-wide error codes may also be returned.