Class RDbs

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(), Connect(), CopyDatabase(), DatabaseNamesL(), DeleteDatabase(), EReadPolicy, ESchemaPolicy, EWritePolicy, FreeReservedSpace(), GetBackupPath(), GetDatabasePolicy(), GetPolicy(), GetReserveAccess(), GetTablePolicies(), GetTablePolicy(), ReleaseReserveAccess(), ReserveDriveSpace(), ResourceCheck(), ResourceCount(), ResourceMark(), SetHeapFailure(), TPolicyType, Version()

Inherited from RHandleBase:
Attributes(), Close(), Duplicate(), FullName(), Handle(), HandleInfo(), Name(), SetHandle(), SetHandleNC(), iHandle

Inherited from RSessionBase:
CreateSession(), EAutoAttach, EExplicitAttach, Open(), Send(), SendReceive(), SetReturnedHandle(), ShareAuto(), ShareProtected(), TAttachMode

static IMPORT_C 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 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

CDbDatabaseNames * 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 TDesC &aSrcDbName Source database name (<drive>:<name>.<ext> format) const TDesC &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 TDesC &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. 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 TDesC &aTableName Table name. 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 TDesC &aTableName Table name. 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 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 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 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() return value

See also:

• RFs::ReserveDriveSpace()

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() return values

See also:

• RFs::GetReserveAccess()

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.

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 TDesC &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. TDes &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 TDesC &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