Collapse all Symbian^3 Product Developer Library

RSqlDbSession Class Reference

class RSqlDbSession : public RSessionBase

RSqlDbSession class is used for establishing a connection with the database server. It can be used also for:

executing SQL statements or a set of SQL statements, separated with ";";
attaching/detaching databases;
copying databases;
deleting databases;
retrieving last error messages;

Inherits from

RSqlDbSession
- RSessionBase
  - RHandleBase

Public Member Functions
	RSqlDbSession()
TInt	Attach(const TDesC &, const TDesC &)
void	Close()
TInt	Connect(TSqlSrvFunction, const TDesC &, const TDesC8 &, const TDesC8 *)
TInt	CopyDatabase(const TDesC &, const TDesC &)
TInt	DeleteDatabase(const TDesC &)
TInt	Detach(const TDesC &)
TInt	Exec(const TDesC &)
TInt	Exec(const TDesC8 &)
void	Exec(const TDesC &, TRequestStatus &)
void	Exec(const TDesC8 &, TRequestStatus &)
TInt	ExecScalarFullSelect(const TDesC &, TSqlColumnType, TDes8 &)
TInt	ExecScalarFullSelect(const TDesC8 &, TSqlColumnType, TDes8 &)
TInt	GetSecurityPolicy(RSqlBufFlat &)
TPtrC	LastErrorMessage()
TInt64	LastInsertedRowId()
TInt	SendReceive(TInt)
void	SendReceive(TInt, TRequestStatus &)
TInt	SendReceive(TInt, const TIpcArgs &)
void	SendReceive(TInt, const TIpcArgs &, TRequestStatus &)
TInt	SetIsolationLevel(RSqlDatabase::TIsolationLevel)

Private Member Functions
TInt	CreateAndSendFileHandle(TSqlFhCmdFunctor &, TDbfAction)
TInt	DoConnect(TSqlSrvFunction, const TDesC &, const TDesC8 &, const TDesC8 *)
TInt	DoCreateSession()
TInt	InitResourceTestData()

Inherited Functions
	RHandleBase::Attributes()const
	RHandleBase::BTraceId()const
	RHandleBase::DoExtendedClose()
	RHandleBase::Duplicate(const RThread &,TOwnerType)
	RHandleBase::FullName()const
	RHandleBase::FullName(TDes &)const
	RHandleBase::Handle()const
	RHandleBase::HandleInfo(THandleInfo *)
	RHandleBase::Name()const
	RHandleBase::NotifyDestruction(TRequestStatus &)
	RHandleBase::Open(const TFindHandleBase &,TOwnerType)
	RHandleBase::OpenByName(const TDesC &,TOwnerType,TInt)
	RHandleBase::RHandleBase()
	RHandleBase::RHandleBase(TInt)
	RHandleBase::SetHandle(TInt)
	RHandleBase::SetHandleNC(TInt)
	RSessionBase::CreateSession(RServer2,const TVersion &)
	RSessionBase::CreateSession(RServer2,const TVersion &,TInt)
	RSessionBase::CreateSession(RServer2,const TVersion &,TInt,TIpcSessionType,const TSecurityPolicy ,TRequestStatus )
	RSessionBase::CreateSession(const TDesC &,const TVersion &)
	RSessionBase::CreateSession(const TDesC &,const TVersion &,TInt)
	RSessionBase::CreateSession(const TDesC &,const TVersion &,TInt,TIpcSessionType,const TSecurityPolicy ,TRequestStatus )
	RSessionBase::CreateSession(const TDesC &,const TVersion &,TInt,TRequestStatus *)
	RSessionBase::Open(RMessagePtr2,TInt,TOwnerType)
	RSessionBase::Open(RMessagePtr2,TInt,const TSecurityPolicy &,TOwnerType)
	RSessionBase::Open(TInt,TOwnerType)
	RSessionBase::Open(TInt,const TSecurityPolicy &,TOwnerType)
	RSessionBase::Send(TInt)const
	RSessionBase::Send(TInt,const TIpcArgs &)const
	RSessionBase::SendReceive(TInt)const
	RSessionBase::SendReceive(TInt,TRequestStatus &)const
	RSessionBase::SendReceive(TInt,const TIpcArgs &)const
	RSessionBase::SendReceive(TInt,const TIpcArgs &,TRequestStatus &)const
	RSessionBase::SetReturnedHandle(TInt)
	RSessionBase::SetReturnedHandle(TInt,RHandleBase &)
	RSessionBase::SetReturnedHandle(TInt,const TSecurityPolicy &)
	RSessionBase::ShareAuto()
	RSessionBase::ShareProtected()

Private Member Enumerations
enum	TDbfAction { EDbfCreate, EDbfOpen }

Inherited Enumerations
	RHandleBase:TAttributes
	RSessionBase:TAttachMode

Private Attributes
HBufC *	iLastErrorMessage

Inherited Attributes
	RHandleBase::iHandle

Constructor & Destructor Documentation

RSqlDbSession()

RSqlDbSession

(

)

[inline]

Member Functions Documentation

Attach(const TDesC &, const TDesC &)

TInt	Attach	(	const TDesC &	aDbFileName,
			const TDesC &	aDbName
		)

Sends a command to the server to attach an existing database to the current connection.

The database can be:

 - shared secure database;
 - shared non-secure database;
 - private secure database;

Usage of the IPC call arguments: Arg 0: [out] Database file name length. Arg 1: [out] Database file name. Arg 2: [out] Logical database name length. Arg 3: [out] Logical database name.

Parameters

const TDesC & aDbFileName	Database file name.
const TDesC & aDbName	Logical database name.

Close()

void

(

)

Closes the database and releases the connection with the database server.

Connect(TSqlSrvFunction, const TDesC &, const TDesC8 &, const TDesC8 *)

TInt	Connect	(	TSqlSrvFunction	aFunction,
			const TDesC &	aDbFileName,
			const TDesC8 &	aSecurityPolicyData,
			const TDesC8 *	aConfig
		)

Establishes a connection with the SQL server.

The method initializes RSqlDbSession object establishing a connection with the SQL server. If the connection has established successfully, the method sends a message to the server to create or open (depending on aFunction parameter) a database file with aDbFileName name.

Usage of the IPC call arguments:

Arg 0: [out] database file name length
Arg 1: [out] database file name
Arg 2: [out] security policies buffer length if aFunction is ESqlSrvDbCreateSecure
Arg 3: [out] security policies buffer if aFunction is ESqlSrvDbCreateSecure

Parameters

TSqlSrvFunction aFunction	Specifies which operation has to be performed: 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	Database file name, including the path. If it is a request for creating/opening secure database, then the name format is <drive>:<[SID]database_file_name>.
const TDesC8 & aSecurityPolicyData	Security policy data. Non-empty descriptor only for secure databases
const TDesC8 * aConfig	the configuration string "PARAM=VALUE;...."

CopyDatabase(const TDesC &, const TDesC &)

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

Copies a database.

The method establishes a temporary connection with the SQL server and issues a request for copying aSrcDbFileName database file to aDestDbFileName file. After the server completes the request CopyDatabase() closes the connection.

Usage of the IPC call arguments: Arg 0: [out] source database file name length Arg 1: [out] source database file name Arg 2: [out] destination database file name length Arg 3: [out] destination database file name

Parameters

const TDesC & aSrcDbFileName	Source database file name.
const TDesC & aDestDbFileName	Destination database file name.

CreateAndSendFileHandle(TSqlFhCmdFunctor &, TDbfAction)

TInt	CreateAndSendFileHandle	(	TSqlFhCmdFunctor &	aFhCmdSender,
			TDbfAction	aDbfAction
		)	[private]

Creates/opens database file locally and sends the file handle to the SQL server.

This function is used only when the SQL server fails to create/open/attach the requested database file with KErrPermissionDenied error. One of the reasons for that error may be that the database file is in the calling application's private data cage. In this case an attempt is made to create/open the database file locally and if the operation completes successfully, then the file handle is passed to the SQL server.

Parameters

TSqlFhCmdFunctor & aFhCmdSender	A reference to a functor instance which is used for sending the file handles to the SQL server.
TDbfAction aDbfAction	It is set by the caller to RSqlDbSession::EDbfCreate if the database file has to be created or to RSqlDbSession::EDbfOpen if the database file already exists and has to be opened

DeleteDatabase(const TDesC &)

TInt

DeleteDatabase

(

const TDesC &

aDbFileName

)

[static]

Deletes a database.

The database can be:

 - shared secure database;
 - shared non-secure database;
 - private secure database;

The method establishes a temporary connection with the SQL server and issues a "delete" request regarding aDbFileName database file. After the server completes the request DeleteDatabase() closes the connection.

Usage of the IPC call arguments: Arg 0: [out] database file name length Arg 1: [out] database file name

Parameters

const TDesC & aDbFileName

Database file name. It must include the path if it is not a secure database.

Detach(const TDesC &)

TInt

Detach

(

const TDesC &

aDbName

)

[inline]

Sends a command to the server to detach previously attached database.

Usage of the IPC call arguments: Arg 0: [out] Logical database name length. Arg 1: [out] Logical database name.

Parameters

const TDesC & aDbName

Logical database name.

DoConnect(TSqlSrvFunction, const TDesC &, const TDesC8 &, const TDesC8 *)

TInt	DoConnect	(	TSqlSrvFunction	aFunction,
			const TDesC &	aDbFileName,
			const TDesC8 &	aSecurityPolicyData,
			const TDesC8 *	aConfig
		)	[private]

Prepares the "security & configuration" string and sends the command to the SQL server.

Parameters

TSqlSrvFunction aFunction	Specifies which operation has to be performed: 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	Database file name, including the path. If it is a request for creating/opening secure database, then the name format is <drive>:<[SID]database_file_name>.
const TDesC8 & aSecurityPolicyData	Security policy data. Non-empty descriptor only for secure databases
const TDesC8 * aConfig	the configuration string "PARAM=VALUE;...."

DoCreateSession()

TInt

DoCreateSession

(

)

[private]

The method establishes a connection with the SQL server.

Exec(const TDesC &)

TInt

Exec

(

const TDesC &

aSqlStmt

)

[inline]

Executes one or more 16-bit SQL statements.

The method sends a message to the SQL server containing one or more 16-bit SQL statements to be executed. SQL statements of any kind can be executed, but the method won't return any record(s) if the SQL statement type is "SELECT". If the SQL statement(s) contains one or more parameters, these parameters will be set to NULL before the execution. If the call fails and the error class is ESqlDbError, a text description of the error can be obtained using LastErrorMessage() method.

Usage of the IPC call arguments: Arg 0: [out] 16-bit character length of SQL statement. Arg 1: [out] SQL statement(s).

Parameters

const TDesC & aSqlStmt

String containing one or more 8/16-bit SQL statements, separated with ';'.

Exec(const TDesC8 &)

TInt

Exec

(

const TDesC8 &

aSqlStmt

)

[inline]

Executes one or more 8-bit SQL statements.

The method sends a message to the SQL server containing one or more 8-bit SQL statements to be executed. SQL statements of any kind can be executed, but the method won't return any record(s) if the SQL statement type is "SELECT". If the SQL statement(s) contains one or more parameters, these parameters will be set to NULL before the execution. If the call fails and the error class is ESqlDbError, a text description of the error can be obtained using LastErrorMessage() method.

Usage of the IPC call arguments: Arg 0: [out] 8-bit character length of SQL statement. Arg 1: [out] SQL statement(s).

Parameters

const TDesC8 & aSqlStmt

String containing one or more 8-bit SQL statements, separated with ';'.

Exec(const TDesC &, TRequestStatus &)

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

Executes one or more 16-bit SQL statements asynchronously.

Usage of the IPC call arguments: Arg 0: [out] 16-bit character length of SQL statement. Arg 1: [out] SQL statement(s).

Parameters

const TDesC & aSqlStmt

String containing one or more 16-bit SQL statements, separated with ';'.

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 INSERT/UPDATE/DELETE 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); - KSqlErrStmtExpired, the SQL statement has expired (if new functions or collating sequences have been registered or if an authorizer function has been added or changed); - KErrNoMemory, an out of memory condition has occurred - the statement will be reset. 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 SQL statements asynchronously.

Usage of the IPC call arguments: Arg 0: [out] 8-bit character length of SQL statement. Arg 1: [out] SQL statement(s).

Parameters

const TDesC8 & aSqlStmt

String containing one or more 8-bit SQL statements, separated with ';'.

TRequestStatus & aStatus

ExecScalarFullSelect(const TDesC &, TSqlColumnType, TDes8 &)

TInt	ExecScalarFullSelect	(	const TDesC &	aSqlStmt,
			TSqlColumnType	aType,
			TDes8 &	aRes
		)	[inline]

Usage of the IPC call arguments: Arg 0: [out] (16-bit character length of SQL statement) | (expected column value type << 24). Arg 1: [out] SQL statement. Arg 2: [out] Byte max length of the receiving buffer Arg 3: [in/out] The receiving buffer

Parameters

const TDesC & aSqlStmt
TSqlColumnType aType
TDes8 & aRes

ExecScalarFullSelect(const TDesC8 &, TSqlColumnType, TDes8 &)

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

Usage of the IPC call arguments: Arg 0: [out] (8-bit character length of SQL statement) | (expected column value type << 24). Arg 1: [out] SQL statement. Arg 2: [out] Byte max length of the receiving buffer Arg 3: [in/out] The receiving buffer

Parameters

const TDesC8 & aSqlStmt
TSqlColumnType aType
TDes8 & aRes

GetSecurityPolicy(RSqlBufFlat &)

TInt

GetSecurityPolicy

(

RSqlBufFlat &

aSecurityPolicyBuf

)

Retrieves the database security policies.

Usage of the IPC call arguments: Arg 0: [out] security policy buffer size Arg 1: [in/out] buffer for the database security policies

Parameters

RSqlBufFlat & aSecurityPolicyBuf

InitResourceTestData()

TInt

InitResourceTestData

(

)

[private]

The method gets called immediatelly after the establishing client-server connection but before the create/open database message. If a request was made by the client (using TSqlResourceTester methods) to test the server under out of memory conditions, InitResourceTestData() will send this request to the server, putting the just created connection in a "out of memory" test mode.

LastErrorMessage()

TPtrC

LastErrorMessage

(

)

Retrieves a reference to the textual description of the error returned by the most recent call to any of the functions:

Note that the function can only return a reference to text for database-specific type errors, i.e. those errors that are categorised as of type ESqlDbError.

If an error occurs during the retrieval of the last error message, the function silently ignores the error and returns a NULL descriptor.

Usage of the IPC call arguments: Arg 0: [out] max length of the message buffer Arg 1: [in/out] buffer for the last error message

LastInsertedRowId()

TInt64

LastInsertedRowId

(

)

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

Usage of the IPC call arguments: Arg 0: [in/out] the receiving buffer for the last inserted ROWID

SendReceive(TInt)

TInt

SendReceive

(

TInt

aFunction

)

[inline]

The method sends a message to the SQL server.

Parameters

TInt aFunction

Function code

SendReceive(TInt, TRequestStatus &)

void	SendReceive	(	TInt	aFunction,
			TRequestStatus &	aStatus
		)	[inline]

The method sends a message asynchronously to the SQL server.

Parameters

TInt aFunction	Function code
TRequestStatus & aStatus

SendReceive(TInt, const TIpcArgs &)

TInt	SendReceive	(	TInt	aFunction,
			const TIpcArgs &	aArgs
		)	[inline]

The method sends a message with arguments to the SQL server.

Parameters

TInt aFunction	Function code
const TIpcArgs & aArgs	Message arguments

SendReceive(TInt, const TIpcArgs &, TRequestStatus &)

void	SendReceive	(	TInt	aFunction,
			const TIpcArgs &	aArgs,
			TRequestStatus &	aStatus
		)	[inline]

The method sends asynchronously a message with arguments to the SQL server.

Parameters

TInt aFunction	Function code
const TIpcArgs & aArgs	Message arguments
TRequestStatus & aStatus	Completion status of asynchronous request

SetIsolationLevel(RSqlDatabase::TIsolationLevel)

TInt

SetIsolationLevel

(

RSqlDatabase::TIsolationLevel

aIsolationLevel

)

[inline]

Sets the transaction isolation level.

The method sends a message to the SQL server to set the desired isolation level. The default isolation level is RSqlDatabase::ESerializable, but can be changed to RSqlDatabase::EReadUncommitted for database connections which share the access to the same database file.

Usage of the IPC call arguments: Arg 0: [out] Isolation level type.

Parameters

RSqlDatabase::TIsolationLevel aIsolationLevel

Desired isolation level: RSqlDatabase::ESerializable or RSqlDatabase::EReadUncommitted.

Member Enumerations Documentation

Enum TDbfAction

Enumerators

EDbfCreate
EDbfOpen

Member Data Documentation

HBufC * iLastErrorMessage

HBufC *

iLastErrorMessage

[private]