RDbs in System Libraries DBMS

class RDbs : public RSessionBase;

Description

Client-server databases

Represents a session with the DBMS server. A thread uses this class to set up a DBMS server session and this provides the basis for sharing databases with other threads.

Derivation

RHandleBase - A handle to an object.

RSessionBase - Client-side handle to a session with a server.

RDbs - Client-server databases

Members

Defined in RDbs:

BackupPathsL(TSecureId,TUid)Retrieves a list of paths of secure shared databases, which share the same secur...
Connect()Makes a connection with the DBMS server. This function causes the server to star...
CopyDatabase(const TDesC &,const TDesC &,TUid)Copies an existing secure shared database to a new secure shared database. The n...
DatabaseNamesL(TDriveNumber,TUid)Retrieves a list of names of secure shared databases, which share the same secur...
DeleteDatabase(const TDesC &,TUid)Deletes an existing secure shared database.
EReadPolicy
ESchemaPolicy
EWritePolicy
FreeReservedSpace(TInt)The method frees the reserved by the DBMS session disk space.
GetBackupPath(TSecureId,const TDesC &,TUid,TDes &)The method will fill out aBackupPath argument with the full path of aDbName secu...
GetDatabasePolicy(TUid,TPolicyType,TSecurityPolicy &)Returns in the aDbPolicy output parameter the requested database security policy...
GetPolicy(TUid,const TDesC &,TUint,TSecurityPolicy &)Returns in aPolicy output parameter requested database/table security policy of ...
GetReserveAccess(TInt)Grants access to a given area on a given drive for RDbs session. Note this sessi...
GetTablePolicies(TUid,const TDesC &,TPolicyType,TSecurityPolicy &,TSecurityPolicy &)Returns in the aDbPolicy and aTablePolicy output parameters the requested databa...
GetTablePolicy(TUid,const TDesC &,TPolicyType,TSecurityPolicy &)Returns in the aTablePolicy output parameter the requested table security policy...
ReleaseReserveAccess(TInt)Revokes access on a given drive for RDbs session.
ReserveDriveSpace(TInt,TInt)Reserves a prederfined amount of disk space on aDrive drive. At the moment the m...
ResourceCheck()Checks that the number of DBMS objects allocated in this session is the same as ...
ResourceCount()Returns the number of DBMS objects allocated in this session.
ResourceMark()Marks the start point for checking the number of DBMS objects allocated in this ...
SetHeapFailure(TInt,TInt)
TPolicyTypeThis enum is used in GetDatabasePolicy/GetTablePolicy/GetTablePolicies calls and...
Version()Returns the version of the DBMS server.

Inherited from RHandleBase:

Attributes()const
BTraceId()constReturns a unique object identifier for use with BTrace
Close()Closes the handle.
Duplicate(const RThread &,TOwnerType)Creates a valid handle to the kernel object for which the specified thread alrea...
FullName()constGets the full name of the handle.
FullName(TDes &)constGets the full name of the handle.
Handle()constRetrieves the handle-number of the object associated with this handle.
HandleInfo(THandleInfo *)Gets information about the handle.
Name()constGets the name of the handle.
Open(const TFindHandleBase &,TOwnerType)Opens a handle to a kernel side object found using a find-handle object.
RHandleBase(TInt)Copy constructor.
SetHandle(TInt)Sets the handle-number of this handle to the specified value.
SetHandleNC(TInt)Sets the handle-number of this handle to the specified value, and marks it as no...
iHandle

Inherited from RSessionBase:

CreateSession(RServer2,const TVersion &)Creates a session with a server, specifying no message slots.
CreateSession(RServer2,const TVersion &,TInt)Creates a session with a server.
CreateSession(RServer2,const TVersion &,TInt,TIpcSessionType,const TSecurityPolicy *,TRequestStatus *)Creates a session with a server.
CreateSession(const TDesC &,const TVersion &)Creates a session with a server, specifying no message slots.
CreateSession(const TDesC &,const TVersion &,TInt)Creates a session with a server.
CreateSession(const TDesC &,const TVersion &,TInt,TIpcSessionType,const TSecurityPolicy *,TRequestStatus *)Creates a session with a server.
CreateSession(const TDesC &,const TVersion &,TInt,TRequestStatus *)
EAutoAttach
EExplicitAttach
Open(RMessagePtr2,TInt,TOwnerType)Opens a handle to a session using a handle number sent by a client to a server.
Open(RMessagePtr2,TInt,const TSecurityPolicy &,TOwnerType)Opens a handle to a session using a handle number sent by a client to a server, ...
Open(TInt,TOwnerType)Opens a handle to a session using a handle number passed as an environment data ...
Open(TInt,const TSecurityPolicy &,TOwnerType)Opens a handle to a session using a handle number passed as an environment data ...
Send(TInt)constIssues a blind request to the server with the specified function number, but wit...
Send(TInt,const TIpcArgs &)constIssues a blind request to the server with the specified function number, and arg...
SendReceive(TInt)constIssues a synchronous request to the server with the specified function number, b...
SendReceive(TInt,TRequestStatus &)constIssues an asynchronous request to the server with the specified function number,...
SendReceive(TInt,const TIpcArgs &)constIssues a synchronous request to the server with the specified function number an...
SendReceive(TInt,const TIpcArgs &,TRequestStatus &)constIssues an asynchronous request to the server with the specified function number ...
SetReturnedHandle(TInt)Sets the handle-number of this handle to the specified value.
SetReturnedHandle(TInt,RHandleBase &)
SetReturnedHandle(TInt,const TSecurityPolicy &)Sets the handle-number of this session handle to the specified value after valid...
ShareAuto()Creates a session that can be shared by other threads in the current process.
ShareProtected()Creates a session handle that can be be passed via IPC to another process as wel...
TAttachModeIndicates whether or not threads in the process are automatically attached to th...

IMPORT_C static TVersion Version();

Description

Returns the version of the DBMS server.

Return value

TVersion

Version information.

IMPORT_C TInt Connect();

Description

Makes a connection with the DBMS server. This function causes the server to start, if it is not already running.

This should be the first function called on an RDbs object after it is created.

Once a connection has been established, databases can be opened through the server.

Note that:

Threads can make any number of simultaneous connections to the DBMS server.

The session must stay open until all DBMS objects opened through the server have been closed.

The session is terminated by calling the RHandleBase::Close() member function provided by the RSessionBase class.

Return value

TInt

KErrNone if successful, otherwise another of the system-wide error codes.

IMPORT_C CDbDatabaseNames* DatabaseNamesL(TDriveNumber aDrive, TUid aPolicyUid);

Description

Retrieves a list of names of secure shared databases, which share the same security policy, as determined by the supplied UID. If a database name is longer than KDbMaxName, it will not be added to the list.

Parameters

`TDriveNumber aDrive`	The drive number to be searched.
`TUid aPolicyUid`	Database security policy UID.

Return value

CDbNames *

A list with names of the found databases, which have the same database security uid. The database name output format is: <name>.<ext>. The caller is resonsible for deleting the database names list.

Leave codes

`KErrNoMemory`	- not enough memory for the operation to be done
`KErrArgument`	- invalid UID parameter (including KNullUid value)
`KErrBadName`	- invalid drive number (not in A-Z range)
`KErrNotReady`	- the drive is not presented in the system
`Some`	other system-wide error codes

Capability:

Security policy note:

For a secure shared database, the caller must satisfy the schema access policy for the database.

IMPORT_C TInt CopyDatabase(const TDesC &aSrcDbName, const TDesC &aDestDbName, TUid aPolicyUid);

Description

Copies an existing secure shared database to a new secure shared database. The new database will have the same security policy as the old one. The maximum length of the target database name (with the extension) is KDbMaxName.

Parameters

`const TDesC16 &aSrcDbName`	Source database name (<drive>:<name>.<ext> format)
`const TDesC16 &aDestDbName`	Destination database name (<drive>:<name>.<ext> format)
`TUid aPolicyUid`	The database security policy UID. The destination database will have the same policy UID.

Return value

TInt

KErrNone if successful, otherwise one of the system-wide error codes, including: KErrPermissionDenied - the caller has not enough rights to do the operation or the destination drive is a ROM drive; KErrArgument - invalid source or destination database names (null name, too long name, only drive letter); invalid or null UID; KErrNotReady - the drive in database name is not presented in the system; KErrNotFound - the source database not found; KErrInUse - the source database is in use; KErrAlreadyExists - the destination database already exists; KErrNoMemory - not enough memory for the operation to be done;

Capability:

Security policy note:

For a secure shared database, the caller must satisfy the schema access policy for the database.

IMPORT_C TInt DeleteDatabase(const TDesC &aDbName, TUid aPolicyUid);

Description

Deletes an existing secure shared database.

Parameters

`const TDesC16 &aDbName`	Source database name (<drive>:<name>.<ext> format)
`TUid aPolicyUid`	Database security policy UID.

Return value

TInt

KErrNone if successful, otherwise one of the system-wide error codes, including: KErrInUse (if the database is in use at the moment); KErrNotFound - the database not found; KErrPermissionDenied - the caller has not enough rights to do the operation;

IMPORT_C TInt GetDatabasePolicy(TUid aPolicyUid, TPolicyType aPolicyType, TSecurityPolicy &aDbPolicy);

Description

Returns in the aDbPolicy output parameter the requested database security policy of type aPolicyType.

Parameters

`TUid aPolicyUid`	Database security policy UID.
`RDbs::TPolicyType aPolicyType`	Policy type: EReadPolicy, EWritePolicy, ESchemaPolicy.
`TSecurityPolicy &aDbPolicy`	It will be initialized with the requested security policy data after a successfull call.

Return value

TInt

KErrNone if successful, otherwise one of the system-wide error codes, including KErrArgument - some of the arguments has an invalid value.

IMPORT_C TInt GetTablePolicy(TUid aPolicyUid, const TDesC &aTableName, TPolicyType aPolicyType, TSecurityPolicy &aTablePolicy);

Description

Returns in the aTablePolicy output parameter the requested table security policy of type aPolicyType.

Parameters

`TUid aPolicyUid`	Database security policy UID.
`const TDesC16 &aTableName`	Table name.
`RDbs::TPolicyType aPolicyType`	Policy type: EReadPolicy, EWritePolicy.
`TSecurityPolicy &aTablePolicy`	It will be initialized with the requested security policy data after a successfull call.

Return value

TInt

KErrNone if successful, otherwise one of the system-wide error codes, including: KErrArgument - some of the arguments has an invalid value. KErrNotSupported - the method has been called with aPolicyType = ESchemaPolicy;

IMPORT_C TInt GetTablePolicies(TUid aPolicyUid, const TDesC &aTableName, TPolicyType aPolicyType, TSecurityPolicy &aDbPolicy, TSecurityPolicy &aTablePolicy);

Description

Returns in the aDbPolicy and aTablePolicy output parameters the requested database and table security policies of type aPolicyType.

Parameters

`TUid aPolicyUid`	Database security policy UID.
`const TDesC16 &aTableName`	Table name.
`RDbs::TPolicyType aPolicyType`	Policy type: EReadPolicy, EWritePolicy.
`TSecurityPolicy &aDbPolicy`	It will be initialized with the requested security policy data after a successfull call.
`TSecurityPolicy &aTablePolicy`	It will be initialized with the requested security policy data after a successfull call.

Return value

TInt

KErrNone if successful, otherwise one of the system-wide error codes, including: KErrArgument - some of the arguments has an invalid value. KErrNotSupported - the method has been called with aPolicyType = ESchemaPolicy;

IMPORT_C void ResourceMark();

Description

Marks the start point for checking the number of DBMS objects allocated in this session.

The function takes the current number of allocated DBMS objects as its benchmark number.

A call to this function is normally followed by a later call to RDbs::ResourceCheck() which expects that the number of allocated DBMS objects to be the same as this benchmark number.

IMPORT_C void ResourceCheck();

Description

Checks that the number of DBMS objects allocated in this session is the same as the benchmark number recorded by an earlier call to RDbs::ResourceMark().

The function raises a CSession 2 panic if the current number of DBMS objects is not the same as that recorded by an earlier call to RDbs::ResourceMark().

IMPORT_C TInt ResourceCount();

Description

Returns the number of DBMS objects allocated in this session.

Return value

TInt

The number of DBMS allocated objects.

IMPORT_C void SetHeapFailure(TInt aTAllocFail, TInt aRate);

Description

Parameters

`TInt aTAllocFail`
`TInt aRate`

IMPORT_C TInt ReserveDriveSpace(TInt aDriveNo, TInt aSpace);

Description

Reserves a prederfined amount of disk space on aDrive drive. At the moment the max possible amount, allowed by the file server, is reserved on aDrive drive.

Use this call to ensure that if your "delete records" transaction fails because of "out of disk space" circumstances, you can get an access to the already reserved disk space and complete your transaction successfully the second time.

There is no strong, 100% guarantee, that the reserved disk space will always help the client in "low memory" situations.

Parameters

`TInt aDriveNo`	Drive number to reserve space on
`TInt aSpace`	This parameter is not used at the moment. The caller shall set it to 0.

Return value

TInt

KErrNoMemory Out of memory KErrArgument Invalid aDriveNo. KErrInUse The space has already been reserved RFs::ReserveDriveSpace(TInt,TInt) return value

IMPORT_C void FreeReservedSpace(TInt aDriveNo);

Description

The method frees the reserved by the DBMS session disk space.

Parameters


                                 						TInt aDriveNo

Drive number, which reserved space has to be freed.

Panic codes

`In`	debug mode there will be a panic with the line number as an error code if there is no reserved disk space for aDrive.
`In`	debug mode there will be a panic with the line number as an error code if the reserved disk space is granted but not released.

IMPORT_C TInt GetReserveAccess(TInt aDriveNo);

Description

Grants access to a given area on a given drive for RDbs session. Note this session must have reserved space on this particular drive in order to be granted access to the reserved area.

Parameters


                                 						TInt aDriveNo

Drive number with a reserved disk space, an access to which is requested.

Return value

TInt

KErrArgument Invalid drive or there is no reserved disk space on aDriveNo. KErrInUse An access to the reserved space has already been given. RFs::GetReserveAccess(TInt) return values

IMPORT_C TInt ReleaseReserveAccess(TInt aDriveNo);

Description

Revokes access on a given drive for RDbs session.

Parameters


                                 						TInt aDriveNo

Drive number with a reserved disk space, the access to which has to be released.

Return value

TInt

KErrNone.

Panic codes

`In`	debug mode there will be a panic with the line number as an error code if there is no reserved disk space for aDrive.
`In`	debug mode there will be a panic with the line number as an error code if there is no granted access to the reserved disk space.

Interface status:

deprecated

IMPORT_C TInt GetBackupPath(TSecureId aRequesterSid, const TDesC &aDbName, TUid aDbPolicyUid, TDes &aBackupPath);

Description

The method will fill out aBackupPath argument with the full path of aDbName secure shared database.

Parameters

`TSecureId aRequesterSid`	Security ID of the process which is supposed to backup or restore the database. 0 or ECapability_None are invalid values for aRequesterSID parameter.
`const TDesC16 &aDbName`	Secure shared database name, which path will be set in aBackupPath parameter. The name's format is <drive>:<name>.<ext>
`TUid aDbPolicyUid`	Database security policy UID.
`TDes16 &aBackupPath`	An output parameter. After a successfull call, the DBMS server will fill out the full database path there. aBackupPath must offer enough space to get the whole database path. Probably the best aBackupPath length is KMaxPath value.

Return value

TInt

KErrNone if successful, otherwise one of the system-wide error codes, including:

IMPORT_C CDbStrings* BackupPathsL(TSecureId aRequesterSid, TUid aDbPolicyUid);

Description

Retrieves a list of paths of secure shared databases, which share the same security policy, as determined by the supplied aDbPolicyUid parameter. Note: If there is a database file which full path length is bigger than KDbMaxStrLen characters, then this file will not be added to the returned CDbStrings array.

Parameters

`TSecureId aRequesterSid`
`TUid aDbPolicyUid`	Database security policy UID.

Return value

CDbStrings *

A list with paths of the found databases, which have the same database security uid. The caller is resonsible for deleting the database paths list.

Leave codes

`KErrArgument`	- 0 or ECapability_None process SID, null database security UID.
`KErrPermissionDenied`	- the supplied process SID does not match the database backup& restore SID or the database backup&restore SID is 0 or ECapability_None.
`Some`	other system-wide error codes

private: TInt GetPolicy(TUid aPolicyUid, const TDesC &aTableName, TUint aMask, TSecurityPolicy &aPolicy);

Description

Returns in aPolicy output parameter requested database/table security policy of type aPolicyType.

Parameters

`TUid aPolicyUid`	Database security policy UID
`const TDesC16 &aTableName`	Table name.
`TUint aMask`	Bit-field: it includes ther policy type: EReadPolicy, EWritePolicy, ESchemaPolicy and the request type - database or table.
`TSecurityPolicy &aPolicy`	It will be initialized with the requested security policy data after a successfull call.

Return value


                                 						TInt

KErrNone if successful, otherwise some of the system-wide error codes, including: KErrArgument - some of the arguments has an invalid value. KErrNotSupported - the method has been called with aMask containing ESchemaPolicy for a table object.

TPolicyType

Description

This enum is used in GetDatabasePolicy/GetTablePolicy/GetTablePolicies calls and specifies requested security policy type: read/write/schema.

`EReadPolicy`
`EWritePolicy`
`ESchemaPolicy`

Class RDbs

Description

Derivation

Members

Member functions

Version()

Description

Return value

Connect()

Description

Return value

DatabaseNamesL(TDriveNumber,TUid)

Description

Parameters

Return value

Leave codes

CopyDatabase(const TDesC &,const TDesC &,TUid)

Description

Parameters

Return value

DeleteDatabase(const TDesC &,TUid)

Description

Parameters

Return value

GetDatabasePolicy(TUid,TPolicyType,TSecurityPolicy &)

Description

Parameters

Return value

GetTablePolicy(TUid,const TDesC &,TPolicyType,TSecurityPolicy &)

Description

Parameters

Return value

GetTablePolicies(TUid,const TDesC &,TPolicyType,TSecurityPolicy &,TSecurityPolicy &)

Description

Parameters

Return value

ResourceMark()

Description

ResourceCheck()

Description

ResourceCount()

Description

Return value

SetHeapFailure(TInt,TInt)

Description

Parameters

ReserveDriveSpace(TInt,TInt)

Description

Parameters

Return value

FreeReservedSpace(TInt)

Description

Parameters

Panic codes

GetReserveAccess(TInt)

Description

Parameters

Return value

ReleaseReserveAccess(TInt)

Description

Parameters

Return value

Panic codes

GetBackupPath(TSecureId,const TDesC &,TUid,TDes &)

Description

Parameters

Return value

BackupPathsL(TSecureId,TUid)

Description

Parameters

Return value

Leave codes

GetPolicy(TUid,const TDesC &,TUint,TSecurityPolicy &)

Description

Parameters

Return value

Member enumerations

Enum TPolicyType

Description

Class `RDbs`

`Version()`

`Connect()`

`DatabaseNamesL(TDriveNumber,TUid)`

`CopyDatabase(const TDesC &,const TDesC &,TUid)`

`DeleteDatabase(const TDesC &,TUid)`

`GetDatabasePolicy(TUid,TPolicyType,TSecurityPolicy &)`

`GetTablePolicy(TUid,const TDesC &,TPolicyType,TSecurityPolicy &)`

`GetTablePolicies(TUid,const TDesC &,TPolicyType,TSecurityPolicy &,TSecurityPolicy &)`

`ResourceMark()`

`ResourceCheck()`

`ResourceCount()`

`SetHeapFailure(TInt,TInt)`

`ReserveDriveSpace(TInt,TInt)`

`FreeReservedSpace(TInt)`

`GetReserveAccess(TInt)`

`ReleaseReserveAccess(TInt)`

`GetBackupPath(TSecureId,const TDesC &,TUid,TDes &)`

`BackupPathsL(TSecureId,TUid)`

`GetPolicy(TUid,const TDesC &,TUint,TSecurityPolicy &)`

Enum `TPolicyType`