RSqlSecurityPolicy Class Reference

#include <sqldb.h>

Link against: sqldb.lib

class RSqlSecurityPolicy
Public Member Enumerations
enumTObjectType { ETable }
enumTPolicyType { ESchemaPolicy, EReadPolicy, EWritePolicy }
Public Member Functions
RSqlSecurityPolicy()
IMPORT_C voidClose()
IMPORT_C TIntCreate(const TSecurityPolicy &)
IMPORT_C voidCreateL(const TSecurityPolicy &)
IMPORT_C TSecurityPolicyDbPolicy(TPolicyType)
IMPORT_C TSecurityPolicyDefaultPolicy()
IMPORT_C voidExternalizeL(RWriteStream &)
IMPORT_C voidInternalizeL(RReadStream &)
IMPORT_C TSecurityPolicyPolicy(TObjectType, const TDesC &, TPolicyType)
IMPORT_C TIntSetDbPolicy(TPolicyType, const TSecurityPolicy &)
IMPORT_C TIntSetPolicy(TObjectType, const TDesC &, TPolicyType, const TSecurityPolicy &)

Detailed Description

A container for the security policies for a shared SQL database.

The container can contain:
  • security policies that apply to the database.

  • security policies that apply to individual database objects, i.e. database tables.

For the database, you use RSqlSecurityPolicy::SetDbPolicy() to apply a separate security policy to:
  • the database schema.

  • read activity on the database.

  • write activity on the database.

For database tables, you use RSqlSecurityPolicy::SetPolicy() to apply a separate security policy to:
  • write activity on each named database table.

  • read activity on each named database table.

A client uses a RSqlSecurityPolicy object to create a secure database. It does this by:

Once a secure shared database has been created with specific security policies, these policies are made persistent and cannot be changed during the life of that database.

Security policies are encapsulated by TSecurityPolicy objects. The general usage pattern is to create the security policies container object (RSqlSecurityPolicy) using a default security policy (TSecurityPolicy), and then to assign more specific 'overriding' security policies.

The following code fragment shows how you do this:

TSecurityPolicy defaultPolicy;
RSqlSecurityPolicy securityPolicy;
RSqlDatabase database;
TInt err;

// Create security policies container object using a default security policy.
securityPolicy.Create(defaultPolicy); 

// Set up policy to apply to database schema
// and assign it
TSecurityPolicy schemaPolicy;
...
err = securityPolicy.SetDbPolicy(RSqlSecurityPolicy::ESchemaPolicy, schemaPolicy);

// Set up policy to apply to write activity on the database
// and assign it
TSecurityPolicy writePolicy;
...
err = securityPolicy.SetDbPolicy(RSqlSecurityPolicy::EWritePolicy, writePolicy);

// Set up policy to apply to write activity to the database table named "Table1"
// and assign it
TSecurityPolicy tablePolicy1;
...
err = securityPolicy.SetPolicy(RSqlSecurityPolicy::ETable, _L("Table1"), RSqlSecurityPolicy::EWritePolicy, tablePolicy1);

// Set up policy to apply to read activity to the database table named "Table2"
TSecurityPolicy tablePolicy2;
err = securityPolicy.SetPolicy(RSqlSecurityPolicy::ETable, _L("Table2"), RSqlSecurityPolicy::EReadPolicy, tablePolicy2);

// Create the database, passing the security policies
err = database.Create(KDatabaseName, securityPolicy);

// We can close the RSqlSecurityPolicy object.
securityPolicy.Close();

Note that in this example code fragment, the client has not assigned specific overriding policies for all possible cases; for example, no overriding policy has been assigned to control read activity on the database, read activity on "Table1", nor write activity on "Table2". For these cases, the default security policy will apply.

A client can also retrieve a database's security policies by calling RSqlDatabase::GetSecurityPolicy(); this returns a RSqlSecurityPolicy object containing the security policies. Note that it is the client's responsibility to close the RSqlSecurityPolicy object when the client no longer needs it. The following code fragment suggests how you might do this:

RSqlDatabase database;
RSqlSecurityPolicy securityPolicy;

// Retrieve the security policies; on return from the call to 
// GetSecurityPolicy(), the RSqlSecurityPolicy object passed 
// to this function will contain the security policies.
database.GetSecurityPolicy(securityPolicy);
...
// This is the security policy that applies to database schema
TSecurityPolicy schemaPolicy = securityPolicy.DbPolicy(RSqlSecurityPolicy::ESchemaPolicy);
...
// This is the security policy that applies to write activity to the database
// table named "Table1".
TSecurityPolicy writePolicy = securityPolicy.Policy(RSqlSecurityPolicy::ETable, _L("Table1"), RSqlSecurityPolicy::EWritePolicy);
...
// Close the RSqlSecurityPolicy object when no longer needed.
securityPolicy.Close();

Note that in the cases where an 'overriding' security policy was not originally assigned, then the security policy returned will simply be the default security policy.

Note: The database security policies are used to control the access to the objects (tables, indexes, triggers, views) in the main database. The access to the temporary tables, indexes, etc. is not a subject of any restrictions, e.g. a client with "read" database security policy only can create and use temporary tables, views, indexes, triggers.

See also: TSecurityPolicy RSqlDatabase RSqlSecurityPolicy::SetDbPolicy() RSqlSecurityPolicy::SetPolicy()

Member Enumeration Documentation

Enum TObjectType

Not currently supported.

Defines a set of values that represents the database objects which can be protected by database security policy types.

EnumeratorValueDescription
ETable

Enum TPolicyType

Defines a set of values that represents the database security policy types. Each database security policy type refers to a set of capabilities encapsulated in a TSecurityPolicy object. The TSecurityPolicy object defines what capabilities the calling application must have in order to perform partiqular database operation.

See also: TSecurityPolicy

EnumeratorValueDescription
ESchemaPolicy

Schema database security policy. An application with schema database security policy can modify the database schema, write to database, read from database.

EReadPolicy

Read database security policy. An application with read database security policy can read from database.

EWritePolicy

Write database security policy. An application with write database security policy can write to database.

Constructor & Destructor Documentation

RSqlSecurityPolicy ( )

IMPORT_CRSqlSecurityPolicy()

Initializes RSqlSecurityPolicy instance data members with their default values.

capability
None

Member Function Documentation

Close ( )

IMPORT_C voidClose()

Frees the allocated by RSqlSecurityPolicy instance memory and other resources.

capability
None

Create ( const TSecurityPolicy & )

IMPORT_C TIntCreate(const TSecurityPolicy &aDefaultPolicy)

Initializes RSqlSecurityPolicy instance.

See also: TSecurityPolicy

capability
None
ParameterDescription
aDefaultPolicyDefault security policy which will be used for the database and all database objects.

Returns: KErrNone, the operation has completed successfully; KErrNoMemory, an out of memory condition has occured. Note that database specific errors categorised as ESqlDbError, and other system-wide error codes may also be returned.

CreateL ( const TSecurityPolicy & )

IMPORT_C voidCreateL(const TSecurityPolicy &aDefaultPolicy)

Initializes RSqlSecurityPolicy instance.

leave
KErrNoMemory, an out of memory condition has occured. Note that database specific errors categorised as ESqlDbError, and other system-wide error codes may also be returned.

See also: TSecurityPolicy

capability
None
ParameterDescription
aDefaultPolicyDefault security policy which will be used for the database and all database objects.

DbPolicy ( TPolicyType )

IMPORT_C TSecurityPolicyDbPolicy(TPolicyTypeaPolicyType)const

Gets a database security policy of the specified type.

panic
SqlDb 4 Invalid aPolicyType value.

See also: RSqlSecurityPolicy::TPolicyType TSecurityPolicy

capability
None
ParameterDescription
aPolicyTypeDatabase security policy type: RSqlSecurityPolicy::ESchemaPolicy, RSqlSecurityPolicy::EReadPolicy, RSqlSecurityPolicy::EWritePolicy.

Returns: The requested database security policy.

DefaultPolicy ( )

IMPORT_C TSecurityPolicyDefaultPolicy()const

Gets the default database security policy.

See also: TSecurityPolicy

capability
None

Returns: The default security policy.

ExternalizeL ( RWriteStream & )

IMPORT_C voidExternalizeL(RWriteStream &aStream)const

Externalizes RSqlSecurityPolicy instance to a write stream.

leave
KErrNoMemory, an out of memory condition has occured.
capability
None
ParameterDescription
aStreamStream to which RSqlSecurityPolicy instance should be externalised.

InternalizeL ( RReadStream & )

IMPORT_C voidInternalizeL(RReadStream &aStream)

Initializes RSqlSecurityPolicy instance from a stream. In case of an error the original security policy data is preserved.

leave
KErrNoMemory, an out of memory condition has occured. Note that the function may leave with other system-wide error codes.
capability
None
ParameterDescription
aStreamA read stream containing the data with which the RSqlSecurityPolicy instance will be initialized.

Policy ( TObjectType, const TDesC &, TPolicyType )

IMPORT_C TSecurityPolicyPolicy(TObjectTypeaObjectType,
const TDesC &aObjectName,
TPolicyTypeaPolicyType
)const

Gets a database object security policy of the specified type.

If no security policy of the specified type exists for that database object - the default security policy will be returned.

panic
SqlDb 4 Invalid aPolicyType value.
panic
SqlDb 4 Invalid aObjectType value (It has to be RSqlSecurityPolicy::ETable).
panic
SqlDb 4 Invalid aObjectName value (Null descriptor).

See also: RSqlSecurityPolicy::TObjectType RSqlSecurityPolicy::TPolicyType TSecurityPolicy

capability
None
ParameterDescription
aObjectTypeDatabase object type. At the moment there is only one database object type - RSqlSecurityPolicy::ETable.
aObjectNameDatabase object name. It cannot be a null descriptor.
aPolicyTypeDatabase object security policy type: RSqlSecurityPolicy::EReadPolicy, RSqlSecurityPolicy::EWritePolicy.

Returns: The requested security policy.

SetDbPolicy ( TPolicyType, const TSecurityPolicy & )

IMPORT_C TIntSetDbPolicy(TPolicyTypeaPolicyType,
const TSecurityPolicy &aPolicy
)

Sets a database security policy of a specific type.

Sets database security policy (aPolicy argument) of aPolicyType type. If the aPolicyType database security policy has already been set then it will be replaced with the supplied policy.

panic
SqlDb 4 Invalid aPolicyType value.

See also: RSqlSecurityPolicy::TPolicyType TSecurityPolicy

capability
None
ParameterDescription
aPolicyTypeDatabase security policy type: RSqlSecurityPolicy::ESchema, RSqlSecurityPolicy::ERead, RSqlSecurityPolicy::EWrite.
aPolicyThe database security policy.

Returns: KErrNone

SetPolicy ( TObjectType, const TDesC &, TPolicyType, const TSecurityPolicy & )

IMPORT_C TIntSetPolicy(TObjectTypeaObjectType,
const TDesC &aObjectName,
TPolicyTypeaPolicyType,
const TSecurityPolicy &aPolicy
)

Sets a database object security policy of a specific type.

If there is no entry in the security policy container for the object with aObjectName name, then a new entry for this object will be created and all object security policies will be initialized with the default security policy. The specific database object policy, refered by aPolicyType parameter, will be set after that.

If an entry for aObjectName object already exists, its security policy of "aPolicyType" type will be reinitialized with the data of aPolicy parameter.

panic
SqlDb 4 Invalid aPolicyType value.
panic
SqlDb 4 Invalid aObjectType value (It has to be RSqlSecurityPolicy::ETable).
panic
SqlDb 4 Invalid aObjectName value (Null descriptor).

See also: RSqlSecurityPolicy::TObjectType RSqlSecurityPolicy::TPolicyType TSecurityPolicy

capability
None
ParameterDescription
aObjectTypeDatabase object type. At the moment there is only one database object type - RSqlSecurityPolicy::ETable.
aObjectNameDatabase object name. It cannot be a null descriptor.
aPolicyTypeDatabase object security policy type: RSqlSecurityPolicy::EReadPolicy, RSqlSecurityPolicy::EWritePolicy.
aPolicyDatabase security policy.

Returns: KErrNone, the operation has completed successfully; KErrNoMemory, an out of memory condition has occured.