Symbian^3 Application Developer Library >

CSqlDatabaseImpl Class Reference

class CSqlDatabaseImpl : public CBase

CSqlDatabaseImpl implements RSqlDatabase .

It can be used for:

  • establishing a connection with the database;

  • attaching/detaching a database to/from the existing connection;

  • executing SQL statements or a set of SQL statements, separated with ";";

  • deleting databases;

  • retrieving last error messages;

  • setting the isolation level;

  • returning the database security policy;

RSqlDatabase

Inherits from

Public Member Functions
~CSqlDatabaseImpl ()
TInt Attach (const TDesC &, const TDesC &)
CSqlSecurityPolicy * CloneSecurityPolicyL ()
TInt Compact ( TInt , const TDesC &)
void Compact ( TInt , const TDesC &, TRequestStatus &)
TInt Copy (const TDesC &, const TDesC &)
TInt Delete (const TDesC &)
TInt Detach (const TDesC &)
TInt Exec (const TDesC16 &)
TInt Exec (const TDesC8 &)
void Exec (const TDesC16 &, TRequestStatus &)
void Exec (const TDesC8 &, TRequestStatus &)
TInt ExecScalarFullSelectL (const TDesC16 &, TSqlColumnType , TDes8 &)
TInt ExecScalarFullSelectL (const TDesC8 &, TSqlColumnType , TDes8 &)
TBool InTransaction ()
TPtrC LastErrorMessage ()
TInt64 LastInsertedRowId ()
CSqlDatabaseImpl * NewL ( TSqlSrvFunction , const TDesC &, const CSqlSecurityPolicy *, const TDesC8 *)
RSqlDbSession & Session ()
TInt SetIsolationLevel ( RSqlDatabase::TIsolationLevel )
TInt Size ()
TInt Size ( RSqlDatabase::TSize &, const TDesC &)
Private Member Functions
CSqlDatabaseImpl ()
void ConstructL ( TSqlSrvFunction , const TDesC &, const CSqlSecurityPolicy *, const TDesC8 *)
Inherited Functions
CBase::CBase()
CBase::Delete(CBase *)
CBase::Extension_(TUint,TAny *&,TAny *)
CBase::operator new(TUint)
CBase::operator new(TUint,TAny *)
CBase::operator new(TUint,TLeave)
CBase::operator new(TUint,TLeave,TUint)
CBase::operator new(TUint,TUint)
CBase::~CBase()
Private Attributes
RSqlDbSession iDbSession

Constructor & Destructor Documentation

CSqlDatabaseImpl()

CSqlDatabaseImpl ( ) [private, inline]

~CSqlDatabaseImpl()

~CSqlDatabaseImpl ( ) [virtual]

Frees the allocated by CSqlDatabaseImpl instance memory and other resources.

Member Functions Documentation

Attach(const TDesC &, const TDesC &)

TInt Attach ( const TDesC & aDbFileName,
const TDesC & aDbName
) [inline]

Attaches a secure or non-secure database.

Implements RSqlDatabase::Attach() .

RSqlDatabase RSqlDatabase::Attach()

Parameters

const TDesC & aDbFileName The name of the file that hosts the database. If this is a secure database, then the format of the name must be: <drive>:<[SID]database file name excluding the path>. If this is a private or shared non-secure database, then aDbFileName has to be the full database file name. "[SID]" refers to SID of the application which created the attached database.
const TDesC & aDbName Logical database name. It must be unique (per database connection). This is the name which can be used for accessing tables in the attached database. The syntax is "database-name.table-name".

CloneSecurityPolicyL()

CSqlSecurityPolicy * CloneSecurityPolicyL ( )

Creates and returns a copy of the database security policies object. The caller is responsible for destroying the returned CSqlSecurityPolicy instance.

Implements RSqlDatabase::GetSecurityPolicyL() .

leave
KErrNotSupported, the current database is not a secure database; KErrNoMemory, an out of memory condition has occurred;
RSqlDatabase RSqlDatabase::GetSecurityPolicyL()

Compact(TInt, const TDesC &)

TInt Compact ( TInt aSize,
const TDesC & aDbName
)

Implements RSqlDatabase::Compact() .

Usage of the IPC call arguments: Arg 0: [out] How much space in bytes should be compacted, all free pages should be removed if the parameter value is RSqlDatabase::EMaxCompaction . Arg 1: [out] The database name length in characters Arg 2: [out] The attached database name or KNullDesC for the main database

Parameters

TInt aSize Can be one of: RSqlDatabase::EMaxCompaction - requests a full database compaction. All free pages (if any exists) will be removed; Positive integer value - the server will attempt to compact the database removing at most aSize bytes from the database file, rounded up to the nearest page count, e.g. request for removing 1 byte will remove one free page from the database;
const TDesC & aDbName The attached database name or KNullDesC for the main database

Compact(TInt, const TDesC &, TRequestStatus &)

void Compact ( TInt aSize,
const TDesC & aDbName,
TRequestStatus & aStatus
)

Usage of the IPC call arguments: Arg 0: [out] How much space in bytes should be compacted, all free pages should be removed if the parameter value is RSqlDatabase::EMaxCompaction . Arg 1: [out] The database name length in characters Arg 2: [out] The attached database name or KNullDesC for the main database

Parameters

TInt aSize
const TDesC & aDbName
TRequestStatus & aStatus

ConstructL(TSqlSrvFunction, const TDesC &, const CSqlSecurityPolicy *, const TDesC8 *)

void ConstructL ( TSqlSrvFunction aFunction,
const TDesC & aDbFileName,
const CSqlSecurityPolicy * aSecurityPolicy = NULL,
const TDesC8 * aConfig = NULL
) [private]

Initializes the created CSqlDatabaseImpl instance.

leave
KErrNoMemory, an out of memory condition has occurred; KErrBadName, the file name is invalid - it has either a zero length or it is the name of a directory; KErrArgument, system table name found in the security policies (aSecurityPolicy); KErrAlreadyExists, the file already exists; KErrNotReady, the drive does not exist or is not ready; KErrInUse, the file is already open; KErrNotFound, database file not found; KErrGeneral, missing or invalid security policies (if the database to be opened is a secure database); KErrNotSupported, incompatible SQL security version (if the database to be opened is a secure database). KErrPermissionDenied, the caller does not satisfy the relevant database security policies. Note that the function may leave with database specific errors categorised as ESqlDbError and other system-wide error codes.
CSqlDatabaseImpl::NewL()
panic
SqlDb 4 In _DEBUG mode. aSecurityPolicy is NULL, but the request is for opening/creating a secure database.

Parameters

TSqlSrvFunction aFunction It may have one of the following values: ESqlSrvDbCreate - Create a shared non-secure or private secure database; ESqlSrvDbCreateSecure - Create a shared secure database; ESqlSrvDbOpen - Open a shared non-secure, shared secure or private secure database;
const TDesC & aDbFileName The name of the file that is to host the database. If it is a secure database, then the format of the name is <drive>:<[SID]database file name excluding the path>. "[SID]" refers to the application SID. If it is a non-secure database then aDbFileName should contain the full path name of the file that is to host the database.
const CSqlSecurityPolicy * aSecurityPolicy = NULL The container for the security policies. aSecurityPolicy is NULL if aDbFileName refers to a non-secure database.
const TDesC8 * aConfig = NULL the configuration string "PARAM=VALUE;...."

Copy(const TDesC &, const TDesC &)

TInt Copy ( const TDesC & aSrcDbFileName,
const TDesC & aDestDbFileName
) [static, inline]

Copies a database file to the specified location.

Implements RSqlDatabase::Copy() .

The allowed copying operations are:

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

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

RSqlDatabase RSqlDatabase::Copy()

Parameters

const TDesC & aSrcDbFileName Source database file name. If this is a secure database, then the format of the name must be: <drive>:<[SID]database file name excluding the path>. If this is a non-secure database, then aDbFileName has to be the full database file name. "[SID]" refers to SID of the application which created the database.
const TDesC & aDestDbFileName Destination database file name. If this is a secure database, then the format of the name must be: <drive>:<[SID]database file name excluding the path>. If this is a non-secure database, then aDbFileName has to be the full database file name. "[SID]" refers to SID of the application which performs the copying operation.

Delete(const TDesC &)

TInt Delete ( const TDesC & aDbFileName ) [static, inline]

Deletes the specified database file.

Implements RSqlDatabase::Delete() .

RSqlDatabase RSqlDatabase::Delete()

Parameters

const TDesC & aDbFileName The name of the database file. If this is a secure database, then the format of the name must be: <drive>:<[SID]database file name excluding the path>. If this is a private or shared non-secure database, then aDbFileName has to be the full database file name. "[SID]" refers to SID of the application which created the database.

Detach(const TDesC &)

TInt Detach ( const TDesC & aDbName ) [inline]

Detaches previously attached database.

Implements RSqlDatabase::Detach() .

RSqlDatabase RSqlDatabase::Detach()

Parameters

const TDesC & aDbName Logical database name. The logical name of the database to be detached.

Exec(const TDesC16 &)

TInt Exec ( const TDesC16 & aSqlStmt ) [inline]

Executes one or more 16-bit DDL/DML SQL statements.

Implements RSqlDatabase::Exec() .

RSqlDatabase RSqlDatabase::Exec()

Parameters

const TDesC16 & aSqlStmt A string of 16-bit wide characters containing one or more DDL/DML SQL statements; each statement is separated by a ';' character.

Exec(const TDesC8 &)

TInt Exec ( const TDesC8 & aSqlStmt ) [inline]

Executes one or more 8-bit DDL/DML SQL statements.

Implements RSqlDatabase::Exec() .

RSqlDatabase RSqlDatabase::Exec()

Parameters

const TDesC8 & aSqlStmt A string of 8-bit wide characters containing one or more DDL/DML SQL statements; each statement is separated by a ';' character.

Exec(const TDesC16 &, TRequestStatus &)

void Exec ( const TDesC16 & aSqlStmt,
TRequestStatus & aStatus
) [inline]

Executes one or more 16-bit DDL/DML SQL statements asynchronously.

Implements RSqlDatabase::Exec() .

RSqlDatabase RSqlDatabase::Exec()

Parameters

const TDesC16 & aSqlStmt A string of 16-bit wide characters containing one or more DDL/DML SQL statements; each statement is separated by a ';' character.
TRequestStatus & aStatus Completion status of asynchronous request, one of the following: - >=0, The operation has completed successfully. The number of database rows that were changed/inserted/deleted by the most recently completed DDL/DML sql statement. Exception: If the executed statement is "DELETE FROM <table>", then the function returns 0 if the operation has completed successfully (disregarding the number of the deleted rows); - KErrNoMemory, an out of memory condition has occured; - KSqlErrGeneral, a syntax error has occurred - text describing the problem can be obtained by calling RSqlDatabase::LastErrorMessage(); - KErrPermissionDenied, the caller does not satisfy the relevant database security policies; Note that aStatus may be set with database specific errors categorised as ESqlDbError, and other system-wide error codes.

Exec(const TDesC8 &, TRequestStatus &)

void Exec ( const TDesC8 & aSqlStmt,
TRequestStatus & aStatus
) [inline]

Executes one or more 8-bit DDL/DML SQL statements asynchronously.

Implements RSqlDatabase::Exec() .

RSqlDatabase RSqlDatabase::Exec()

Parameters

const TDesC8 & aSqlStmt A string of 8-bit wide characters containing one or more DDL/DML SQL statements; each statement is separated by a ';' character.
TRequestStatus & aStatus Completion status of asynchronous request, one of the following: - >=0, The operation has completed successfully. The number of database rows that were changed/inserted/deleted by the most recently completed DDL/DML sql statement. Exception: If the executed statement is "DELETE FROM <table>", then the function returns 0 if the operation has completed successfully (disregarding the number of the deleted rows); - KErrNoMemory, an out of memory condition has occured; - KSqlErrGeneral, a syntax error has occurred - text describing the problem can be obtained by calling RSqlDatabase::LastErrorMessage(); - KErrPermissionDenied, the caller does not satisfy the relevant database security policies; Note that aStatus may be set with database specific errors categorised as ESqlDbError, and other system-wide error codes.

ExecScalarFullSelectL(const TDesC16 &, TSqlColumnType, TDes8 &)

TInt ExecScalarFullSelectL ( const TDesC16 & aSqlStmt,
TSqlColumnType aType,
TDes8 & aRes
) [inline]

Sends a command to the server to Execute a SELECT query which is expected to return a single row consisting of a single column value and copies that value to the place refered by aRes parameter.

leave
The function may leave with database specific errors categorised as ESqlDbError and other system-wide error codes.

Parameters

const TDesC16 & aSqlStmt 16-bit SELECT sql query
TSqlColumnType aType The expected column type
TDes8 & aRes Output parameter. Refers to the place where the result must be copied

ExecScalarFullSelectL(const TDesC8 &, TSqlColumnType, TDes8 &)

TInt ExecScalarFullSelectL ( const TDesC8 & aSqlStmt,
TSqlColumnType aType,
TDes8 & aRes
) [inline]

Sends a command to the server to Execute a SELECT query which is expected to return a single row consisting of a single column value and copies that value to the place refered by aRes parameter.

leave
The function may leave with database specific errors categorised as ESqlDbError and other system-wide error codes.

Parameters

const TDesC8 & aSqlStmt 8-bit SELECT sql query
TSqlColumnType aType The expected column type
TDes8 & aRes Output parameter. Refers to the place where the result must be copied

InTransaction()

TBool InTransaction ( ) [inline]

LastErrorMessage()

TPtrC LastErrorMessage ( ) [inline]

Retrieves a reference to the textual description of the error returned by the most recent call.

Implements RSqlDatabase::LastErrorMessage() .

RSqlDatabase RSqlDatabase::LastErrorMessage()

LastInsertedRowId()

TInt64 LastInsertedRowId ( ) [inline]

Returns the ROWID of the most recent successful INSERT into the database from this database connection.

Implements RSqlDatabase::LastInsertedRowId() .

RSqlDatabase::LastInsertedRowId()

NewL(TSqlSrvFunction, const TDesC &, const CSqlSecurityPolicy *, const TDesC8 *)

CSqlDatabaseImpl * NewL ( TSqlSrvFunction aFunction,
const TDesC & aDbFileName,
const CSqlSecurityPolicy * aSecurityPolicy,
const TDesC8 * aConfig = NULL
) [static]

Creates a new CSqlDatabaseImpl instance.

CSqlDatabaseImpl implements RSqlDatabase , which means that CSqlDatabaseImpl instance will be created from RSqlDatabase functions doing RSqlDatabase instance initialization - Create() and Open().

leave
KErrNoMemory, an out of memory condition has occurred; KErrBadName, the file name is invalid - it has either a zero length or it is the name of a directory; KErrArgument, system table name found in the security policies (aSecurityPolicy); KErrAlreadyExists, the file already exists; KErrNotReady, the drive does not exist or is not ready; KErrInUse, the file is already open; KErrNotFound, database file not found; KErrGeneral, missing or invalid security policies (if the database to be opened is a secure database); KErrNotSupported, incompatible SQL security version (if the database to be opened is a secure database). KErrPermissionDenied, the caller does not satisfy the relevant database security policies. Note that the function may leave with database specific errors categorised as ESqlDbError and other system-wide error codes.
RSqlDatabase RSqlDatabase::Create() RSqlDatabase::Open() TSqlSrvFunction CSqlSecurityPolicy

Parameters

TSqlSrvFunction aFunction It may have one of the following values: ESqlSrvDbCreate - Create a shared non-secure or private secure database; ESqlSrvDbCreateSecure - Create a shared secure database; ESqlSrvDbOpen - Open a shared non-secure, shared secure or private secure database;
const TDesC & aDbFileName The name of the file that is to host the database. If it is a secure database, then the format of the name is <drive>:<[SID]database file name excluding the path>. "[SID]" refers to the application SID. If it is a non-secure database then aDbFileName should contain the full path name of the file that is to host the database.
const CSqlSecurityPolicy * aSecurityPolicy The container for the security policies. aSecurityPolicy is NULL if aDbFileName refers to a non-secure database.
const TDesC8 * aConfig = NULL the configuration string "PARAM=VALUE;...."

Session()

RSqlDbSession & Session ( ) [inline]

SetIsolationLevel(RSqlDatabase::TIsolationLevel)

TInt SetIsolationLevel ( RSqlDatabase::TIsolationLevel aIsolationLevel ) [inline]

Sets the transaction isolation level for the database.

Implements RSqlDatabase::SetIsolationLevel() .

RSqlDatabase RSqlDatabase::SetIsolationLevel()

Parameters

RSqlDatabase::TIsolationLevel aIsolationLevel The isolation level to be set. Allowed isolation level values are:RSqlDatabase::EReadUncommitted;RSqlDatabase::ESerializable;

Size()

TInt Size ( ) [inline]

Size(RSqlDatabase::TSize &, const TDesC &)

TInt Size ( RSqlDatabase::TSize & aSize,
const TDesC & aDbName
) [inline]

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

Usage of the IPC call arguments: Arg 0: [in/out] Points to a RSqldatabase::TSize object, where the database size and free space values will be copied. Arg 1: [out] The database name length in characters Arg 2: [out] The attached database name or KNullDesC for the main database

Parameters

RSqlDatabase::TSize & aSize An output parameter. If the call was successfull the aSize object will contain information about the database size and database free space.
const TDesC & aDbName The attached database name or KNullDesC for the main database

Member Data Documentation

RSqlDbSession iDbSession

RSqlDbSession iDbSession [private]

Copyright ©2010 Nokia Corporation and/or its subsidiary(-ies).
All rights reserved. Unless otherwise stated, these materials are provided under the terms of the Eclipse Public License v1.0.