Collapse all Symbian^3 Product 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;

Inherits from

CSqlDatabaseImpl
- CBase

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
		)

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

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]

CSqlDatabaseImpl Class Reference

Inherits from

Constructor & Destructor Documentation

CSqlDatabaseImpl()

~CSqlDatabaseImpl()

Member Functions Documentation

Attach(const TDesC &, const TDesC &)

Parameters

CloneSecurityPolicyL()

Compact(TInt, const TDesC &)

Parameters

Compact(TInt, const TDesC &, TRequestStatus &)

Parameters

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

Parameters

Copy(const TDesC &, const TDesC &)

Parameters

Delete(const TDesC &)

Parameters

Detach(const TDesC &)

Parameters

Exec(const TDesC16 &)

Parameters

Exec(const TDesC8 &)

Parameters

Exec(const TDesC16 &, TRequestStatus &)

Parameters

Exec(const TDesC8 &, TRequestStatus &)

Parameters

ExecScalarFullSelectL(const TDesC16 &, TSqlColumnType, TDes8 &)

Parameters

ExecScalarFullSelectL(const TDesC8 &, TSqlColumnType, TDes8 &)

Parameters

InTransaction()

LastErrorMessage()

LastInsertedRowId()

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

Parameters

Session()

SetIsolationLevel(RSqlDatabase::TIsolationLevel)

Parameters

Size()

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

Parameters

Member Data Documentation

RSqlDbSession iDbSession

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

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