CCommsDatabaseBase Class Reference

class CCommsDatabaseBase : public CBase

Base class for CCommsDatabase .

This class is never instantiated, but its member functions are used through the derived class.

Responsible for Transactions, Notifications, Write protection, Hidden records, Phone number resolution and Creating views. Stores the database, the session, transaction and notifier information.

CCommsDatabaseBase is an abstract base class as the CreateDatabaseL() and Open() methods are pure virtual.

Inherits from

Public Member Functions
~CCommsDatabaseBase ()
IMPORT_C TInt BeginTransaction ()
IMPORT_C void CancelRequestNotification ()
IMPORT_C TInt CheckReadCapability (const TDesC &, const RMessagePtr2 *)
IMPORT_C TInt CheckWriteCapability (const TDesC &, const RMessagePtr2 *)
IMPORT_C TInt CommitTransaction ()
IMPORT_C TBool InTransaction ()
IMPORT_C TInt InitializeFilestore ()
IMPORT_C TBool IsDatabaseWriteLockedL ()
IMPORT_C CCommsDbTableView * OpenTableLC (const TDesC &)
IMPORT_C CCommsDbTableView * OpenViewLC (const TDesC &, const TDesC &)
IMPORT_C CCommsDbTableView * OpenViewMatchingBoolLC (const TDesC &, const TDesC &, TBool )
IMPORT_C CCommsDbTableView * OpenViewMatchingTextLC (const TDesC &, const TDesC &, const TDesC8 &)
IMPORT_C CCommsDbTableView * OpenViewMatchingTextLC (const TDesC &, const TDesC &, const TDesC16 &)
IMPORT_C CCommsDbTableView * OpenViewMatchingUintLC (const TDesC &, const TDesC &, TUint32 )
IMPORT_C TInt RequestNotification ( TRequestStatus &)
IMPORT_C void ResolvePhoneNumberFromDatabaseL ( TDesC &, TDes &, TParseMode , TUint32 , TUint32 )
IMPORT_C void ResolvePhoneNumberL ( TDesC &, TDes &, TParseMode , TUint32 , TUint32 )
IMPORT_C void RollbackTransaction ()
IMPORT_C void ShowHiddenRecords ()
IMPORT_C TVersion Version ()
Protected Member Functions
CCommsDatabaseBase ()
void BeginInternalTransactionL ()
TInt CheckDBCapability ( RDbs::TPolicyType , const TDesC &, const RMessagePtr2 *)
TInt CommitInternalTransaction ()
void ConvertToUid (const TDesC &, TUint32 , TCommDbPublishSubscribeNotification &)
void CreateDatabaseL ()
RDbNamedDatabase * Database ()
void DatabaseUpdateHasOccurred ()
void DoClose ()
CCommsDbTableView * DoOpenIAPTableViewL (const TDesC &, const TDesC &)
CCommsDbTableView * DoOpenTableViewL (const TDesC &, const TDesC &)
CCommsDbTableView * DoOpenViewMatchingTextL (const TDesC &, const TDesC &, const TDesC8 &, TBool )
CCommsDbTableView * DoOpenViewMatchingTextL (const TDesC &, const TDesC &, const TDesC16 &, TBool )
CCommsDbTableView * DoOpenViewMatchingUintL (const TDesC &, const TDesC &, TUint32 , TBool )
TUint32 GetNewNumber ( TUid )
TInt NotifyAllChanges ()
void NotifyChangeL (const TDesC &, TUint32 )
void PopulateChargeCardL ( TUint32 , TChargeCard &)
void PopulateDialLocationL ( TUint32 , TDialLocation &)
void RollbackInternalTransaction ()
Private Member Functions
TBool ConvertTableName (const TDesC &, TDes &)
TInt DoCheckReadCapabilityL (const TDesC &, const RMessagePtr2 *)
TInt DoCheckWriteCapabilityL (const TDesC &, const RMessagePtr2 *)
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()
Protected Attributes
RDbNamedDatabase iDatabase
CCommsDatabaseImpl * iImpl
TBool iImplNotCreated
TBool iInInternalTransaction
RArray < TCommDbPublishSubscribeNotification > iNotifications
RDbNotifier iNotifier
TInt iNotifierOpenError
TBool iShowHiddenRecords

Constructor & Destructor Documentation

CCommsDatabaseBase()

IMPORT_C CCommsDatabaseBase ( ) [protected]

Default constructor for internal use only.

~CCommsDatabaseBase()

IMPORT_C ~CCommsDatabaseBase ( ) [virtual]

Member Functions Documentation

BeginInternalTransactionL()

void BeginInternalTransactionL ( ) [protected]

Lock the database for internal use - begin a transaction if we can!

BeginTransaction()

IMPORT_C TInt BeginTransaction ( )

Marks the start of a transaction and gets a shared read-lock on the database. Other clients of the database can concurrently acquire a shared read-lock but no client can gain an exclusive write-lock until this transaction (and any transaction started by other clients) completes as a result of a call to either CommitTransaction() or RollbackTransaction() .

A transaction consists of one or more record updates and/or insertions and/or deletions. The process of making changes to records within a view is part of CCommsDbTableView behaviour.

CancelRequestNotification()

IMPORT_C void CancelRequestNotification ( )

Cancels an outstanding request for notification of changes to the communications database.

An outstanding request completes with KErrCancel.

CheckDBCapability(RDbs::TPolicyType, const TDesC &, const RMessagePtr2 *)

TInt CheckDBCapability ( RDbs::TPolicyType aType,
const TDesC & aField,
const RMessagePtr2 * aMessage
) [protected]

Check that a given client has the capabilites required to perform the given operation on the given field

Parameters

RDbs::TPolicyType aType Specifies the requested operation (read or write)
const TDesC & aField Specifies the field to perform the operation on
const RMessagePtr2 * aMessage Contains the capabilites of the client

CheckReadCapability(const TDesC &, const RMessagePtr2 *)

IMPORT_C TInt CheckReadCapability ( const TDesC & aField,
const RMessagePtr2 * aMessage
)

Check the capabilites required to read a field from the database

Parameters

const TDesC & aField the name of the field to be read
const RMessagePtr2 * aMessage Message indicating the capabilites to be checked

CheckWriteCapability(const TDesC &, const RMessagePtr2 *)

IMPORT_C TInt CheckWriteCapability ( const TDesC & aField,
const RMessagePtr2 * aMessage
)

Check the capabilites required to write a field to the database

Parameters

const TDesC & aField the name of the field to be written
const RMessagePtr2 * aMessage Message indicating the capabilites to be checked

CommitInternalTransaction()

TInt CommitInternalTransaction ( ) [protected]

Unlocks the database from internal use - end a transaction. If the commit fails then do the rollback.

CommitTransaction()

IMPORT_C TInt CommitTransaction ( )

Marks the end of a transaction and commits any changes made since the start of the transaction. The client's shared read-lock is removed if no write operations were performed, or the exclusive write-lock is removed if write operations were performed.

capability
Dependent on table, see the guide page referenced below.

ConvertTableName(const TDesC &, TDes &)

TBool ConvertTableName ( const TDesC & aTableName,
TDes & aResult
) [private]

Parameters

const TDesC & aTableName
TDes & aResult

ConvertToUid(const TDesC &, TUint32, TCommDbPublishSubscribeNotification &)

void ConvertToUid ( const TDesC & aSetting,
TUint32 aVal,
TCommDbPublishSubscribeNotification & aNotification
) [protected]

Checks for the type of the setting passed and sets the value in the Commdb publish subscribe notification appropriately.

Nothing to do. Everything is done in CommsDat from v9.1

Parameters

const TDesC & aSetting Setting to get
TUint32 aVal Setting value.
TCommDbPublishSubscribeNotification & aNotification A reference to TCommDbSystemAgentNotification

CreateDatabaseL()

void CreateDatabaseL ( ) [protected, pure virtual]

Database()

RDbNamedDatabase * Database ( ) [protected, inline]

Returns the interface for creating and opening a database identified by name and format.

DatabaseUpdateHasOccurred()

void DatabaseUpdateHasOccurred ( ) [protected]

Sets the flag to signal that a successful update has occurred

DoCheckReadCapabilityL(const TDesC &, const RMessagePtr2 *)

TInt DoCheckReadCapabilityL ( const TDesC & aField,
const RMessagePtr2 * aMessage
) [private]

Parameters

const TDesC & aField
const RMessagePtr2 * aMessage

DoCheckWriteCapabilityL(const TDesC &, const RMessagePtr2 *)

TInt DoCheckWriteCapabilityL ( const TDesC & aField,
const RMessagePtr2 * aMessage
) [private]

Parameters

const TDesC & aField
const RMessagePtr2 * aMessage

DoClose()

void DoClose ( ) [protected]

Close the database and close the notifier and the server

DoOpenIAPTableViewL(const TDesC &, const TDesC &)

CCommsDbTableView * DoOpenIAPTableViewL ( const TDesC & aTableName,
const TDesC & aSqlQuery
) [protected]

This method is deprecated from 9.1 and always returns/leaves with KErrNotSupported instead of describing past operation/parameters.

Parameters

const TDesC & aTableName A reference to a descriptor containing the name of a table in the communications database.
const TDesC & aSqlQuery A reference to a descriptor containing the SQL query text

DoOpenTableViewL(const TDesC &, const TDesC &)

CCommsDbTableView * DoOpenTableViewL ( const TDesC & aTableName,
const TDesC & aSqlQuery
) [protected]

This method is deprecated from 9.1 and always returns/leaves with KErrNotSupported instead of describing past operation/parameters.

Parameters

const TDesC & aTableName A reference to a descriptor containing the name of a table in the communications database.
const TDesC & aSqlQuery A reference to a descriptor containing the SQL query text

DoOpenViewMatchingTextL(const TDesC &, const TDesC &, const TDesC8 &, TBool)

CCommsDbTableView * DoOpenViewMatchingTextL ( const TDesC & aTableName,
const TDesC & aColumnToMatch,
const TDesC8 & aValueToMatch,
TBool aIncludeHiddenRecords
) [protected]

Opens a view on the table aTableName containing all records where aColumnToMatch contains aValueToMatch

Parameters

const TDesC & aTableName A reference to a descriptor containing the name of a table in the communications database.
const TDesC & aColumnToMatch A reference to a descriptor containing the name of a column in table aTableName.
const TDesC8 & aValueToMatch reference to an unsigned integer passed by the caller.
TBool aIncludeHiddenRecords

DoOpenViewMatchingTextL(const TDesC &, const TDesC &, const TDesC16 &, TBool)

CCommsDbTableView * DoOpenViewMatchingTextL ( const TDesC & aTableName,
const TDesC & aColumnToMatch,
const TDesC16 & aValueToMatch,
TBool aIncludeHiddenRecords
) [protected]

Opens a view on the table aTableName containing all records where aColumnToMatch contains aValueToMatch

Parameters

const TDesC & aTableName A reference to a descriptor containing the name of a table in the communications database.
const TDesC & aColumnToMatch A reference to a descriptor containing the name of a column in table aTableName.
const TDesC16 & aValueToMatch reference to an unsigned integer passed by the caller.
TBool aIncludeHiddenRecords

DoOpenViewMatchingUintL(const TDesC &, const TDesC &, TUint32, TBool)

CCommsDbTableView * DoOpenViewMatchingUintL ( const TDesC & aTableName,
const TDesC & aColumnToMatch,
TUint32 aValueToMatch,
TBool aIncludeHiddenRecords
) [protected]

Opens a view on the table aTableName containing all records where aColumnToMatch contains aValueToMatch

Parameters

const TDesC & aTableName A reference to a descriptor containing the name of a table in the communications database.
const TDesC & aColumnToMatch A reference to a descriptor containing the name of a column in table aTableName.
TUint32 aValueToMatch reference to an unsigned integer passed by the caller.
TBool aIncludeHiddenRecords

GetNewNumber(TUid)

TUint32 GetNewNumber ( TUid aUid ) [protected]

Generates a new number for the given UID

Nothing to do. Everything is done in CommsDat from v9.1

Parameters

TUid aUid UID for which the new number is to be generated

InTransaction()

IMPORT_C TBool InTransaction ( )

Tests whether a transaction is in progress, i.e. whether a call to BeginTransaction() has been called.

InitializeFilestore()

IMPORT_C TInt InitializeFilestore ( ) [static]

This method is deprecated from 9.1 and always returns/leaves with KErrNotSupported instead of describing past operation/parameters.

IsDatabaseWriteLockedL()

IMPORT_C TBool IsDatabaseWriteLockedL ( )

Tests if the database is write locked.

Tries to open a transaction from another client.

Note:

Calling InTransaction() is not enough because if the transaction is automatic rather than explicit, this will still return EFalse.

NotifyAllChanges()

TInt NotifyAllChanges ( ) [protected]

Does the notification for all the changes that are stored in the member variable iNotifications.

Nothing to do. Everything is done in CommsDat from v9.1

NotifyChangeL(const TDesC &, TUint32)

void NotifyChangeL ( const TDesC & aSetting,
TUint32 aVal
) [protected]

Does the notification when the transaction is committed

Nothing to do. Everything is done in CommsDat from v9.1

Parameters

const TDesC & aSetting Setting to get
TUint32 aVal Setting value.

OpenTableLC(const TDesC &)

IMPORT_C CCommsDbTableView * OpenTableLC ( const TDesC & aTableName )

Fills the container with all records from table and returns a pointer to view class. The view excludes hidden records, unless access to them has previously been explicitly requested by calling the ShowHiddenRecords() member function of this object.

If the process is succesful, the function constructs and returns a pointer to a CCommsDbTableView object which encapsulates the information on that view. The pointer is also put onto the cleanup stack.

capability
Dependent on table, see the guide page referenced below.

Parameters

const TDesC & aTableName A reference to a descriptor containing the name of the table in the communications database to be opened.

OpenViewLC(const TDesC &, const TDesC &)

IMPORT_C CCommsDbTableView * OpenViewLC ( const TDesC & aTableName,
const TDesC & aSqlQuery
)

This method is deprecated from 9.1 and always returns/leaves with KErrNotSupported instead of describing past operation/parameters.

capability
Dependent on table, see the guide page referenced below.

Parameters

const TDesC & aTableName A reference to a descriptor containing the name of a table in the communications database.
const TDesC & aSqlQuery A reference to a descriptor containing the SQL query text.

OpenViewMatchingBoolLC(const TDesC &, const TDesC &, TBool)

IMPORT_C CCommsDbTableView * OpenViewMatchingBoolLC ( const TDesC & aTableName,
const TDesC & aColumnToMatch,
TBool aValueToMatch
)

Opens a view onto a specified table based on a matching boolean value, and returns a pointer to that view. The view includes all those records where the column, identified by aColumnToMatch, matches the boolean value aValueToMatch.

The view excludes hidden records, unless access to them has previously been explicitly requested by calling the ShowHiddenRecords() member function.

If the open process is successful, the function constructs and returns a pointer to a CCommsDbTableView object which encapsulates the information on that view. The pointer is also put onto the cleanup stack.

capability
Dependent on table, see the guide page referenced below.

Parameters

const TDesC & aTableName A reference to a descriptor containing the name of the table of interest in the communications database.
const TDesC & aColumnToMatch A reference to a descriptor containing the name of the column to be used in the selection process.
TBool aValueToMatch The value to be matched with the content of column aColumnToMatch.

OpenViewMatchingTextLC(const TDesC &, const TDesC &, const TDesC8 &)

IMPORT_C CCommsDbTableView * OpenViewMatchingTextLC ( const TDesC & aTableName,
const TDesC & aColumnToMatch,
const TDesC8 & aValueToMatch
)

Opens a view onto a specified table based on a matching 8 bit text type, and returns a pointer to that view.

The view includes all those records where the column, identified by aColumnToMatch, matches the narrow text supplied in the descriptor aValueToMatch.

The view excludes hidden records, unless access to them has previously been explicitly requested by calling the ShowHiddenRecords() member function of this object.

If the open process is succesful, the function constructs and returns a pointer to a CCommsDbTableView object which encapsulates the information on that view. The pointer is also put onto the cleanup stack.

capability
Dependent on table, see the guide page referenced below.

Parameters

const TDesC & aTableName A reference to a descriptor containing the name of a table in the communications database.
const TDesC & aColumnToMatch A reference to a descriptor containing the name of the column to be used in the selection process.
const TDesC8 & aValueToMatch The narrow (ASCII) text to be matched with the content of column aColumnToMatch.

OpenViewMatchingTextLC(const TDesC &, const TDesC &, const TDesC16 &)

IMPORT_C CCommsDbTableView * OpenViewMatchingTextLC ( const TDesC & aTableName,
const TDesC & aColumnToMatch,
const TDesC16 & aValueToMatch
)

Opens a view onto a specified table based on a matching 16 bit text type, and returns a pointer to that view. The view includes all those records where the column, identified by aColumnToMatch, matches the wide text supplied in the descriptor aValueToMatch.

The view excludes hidden records, unless access to them has previously been explicitly requested by calling the ShowHiddenRecords() member function of this object.

If the open process is successful, the function constructs and returns a pointer to a CCommsDbTableView object which encapsulates the information on that view. The pointer is also put onto the cleanup stack.

capability
Dependent on table, see the guide page referenced below.

Parameters

const TDesC & aTableName A reference to a descriptor containing the name of a table in the communications database.
const TDesC & aColumnToMatch A reference to a descriptor containing the name of the column to be used in the selection process.
const TDesC16 & aValueToMatch The wide (UNICODE) text to be matched with the content of column aColumnToMatch.

OpenViewMatchingUintLC(const TDesC &, const TDesC &, TUint32)

IMPORT_C CCommsDbTableView * OpenViewMatchingUintLC ( const TDesC & aTableName,
const TDesC & aColumnToMatch,
TUint32 aValueToMatch
)

Opens a view onto a specified table based on a matching unsigned integer value, and returns a pointer to that view. The view includes all those records where the column, identified by aColumnToMatch, matches the unsigned integer value aValueToMatch.

The view excludes hidden records, unless access to them has previously been explicitly requested by calling the ShowHiddenRecords() member function of this object.

If the open process is succesful, the function constructs and returns a pointer to a CCommsDbTableView object which encapsulates the information on that view. The pointer is also put onto the cleanup stack.

capability
Dependent on table, see the guide page referenced below.

Parameters

const TDesC & aTableName A reference to a descriptor containing the name of the table in the communications database on which a view is to be opened.
const TDesC & aColumnToMatch A reference to a descriptor containing the name of the column to be used in the selection process.
TUint32 aValueToMatch The value to be matched with the content of column aColumnToMatch.

PopulateChargeCardL(TUint32, TChargeCard &)

void PopulateChargeCardL ( TUint32 aId,
TChargeCard & aChargeCard
) [protected]

Populates aChargeCard with charge card account and PIN details and network operator specific dialling rules for local, national and international calls by getting the details from the database based on aId.

Parameters

TUint32 aId Unique Id associated with the record in the database.
TChargeCard & aChargeCard On return, contains the charge card account and PIN details and network operator specific dialling rules for local, national and international calls

PopulateDialLocationL(TUint32, TDialLocation &)

void PopulateDialLocationL ( TUint32 aId,
TDialLocation & aLocation
) [protected]

populates aLocation with configuration details related to the current location of the telephone equipment getting the details from the database based on aId.

Parameters

TUint32 aId Unique Id associated with the record in the database.
TDialLocation & aLocation On return, contains the configuration details related to the current location of the telephone equipment

RequestNotification(TRequestStatus &)

IMPORT_C TInt RequestNotification ( TRequestStatus & aStatus )

Requests notification when any change is made to the database, whether by this client or any other.

(If the notifier is not successfully opened the function simply returns an error code and none of the following applies).

When any change is made to the database the outstanding notification request completes and TRequestStatus contains a value indicating what type of change has occurred. The value is one of the enumerators of the RDbNotifier::TEvent enumeration.

Alternatively, if an outstanding notification request is cancelled by a call to this CCommsDatabase's CancelRequestNotification() member function, then the request completes with aStatus set to KErrCancel.

An outstanding notification request is also cancelled if the connection to the DBMS is severed through a call to DoClose() .

This is an asynchonous request.

Parameters

TRequestStatus & aStatus A reference to the request status object. If the request is cancelled, this is set to KErrCancel. If the request completes normally, this is set to one of the enumerators of the RDbNotifier::TEvent enumeration.

ResolvePhoneNumberFromDatabaseL(TDesC &, TDes &, TParseMode, TUint32, TUint32)

IMPORT_C void ResolvePhoneNumberFromDatabaseL ( TDesC & aNumber,
TDes & aDialString,
TParseMode aDialParseMode,
TUint32 aLocationId,
TUint32 aChargecardId
)

Resolves a given telephone number based on a specified dialling location and chargecard. A connection must already exist to the database.

The function does not resolve for mobile phones; aNumber is just copied to aDialString.

leave
KErrNotFound if the specified location and chargecard records cannot be found; KErrOverflow if aDialString is not long enough to hold the resolved number.

Parameters

TDesC & aNumber A reference to the descriptor containing the number to be parsed.
TDes & aDialString On return, a reference to a descriptor which contains the parsed number.
TParseMode aDialParseMode Indicates whether the parsed string is intended for dialling or for display.
TUint32 aLocationId ID of the location record.
TUint32 aChargecardId ID of the chargecard ID to be used for resolution.

ResolvePhoneNumberL(TDesC &, TDes &, TParseMode, TUint32, TUint32)

IMPORT_C void ResolvePhoneNumberL ( TDesC & aNumber,
TDes & aDialString,
TParseMode aDialParseMode,
TUint32 aLocationId,
TUint32 aChargecardId
) [static]

Resolves a given telephone number based on a specified dialling location and chargecard. The function does not require a connection to the database server, but will form one itself.

The function does not resolve for mobile phones; aNumber is just copied to aDialString.

leave
KErrNotFound if the specified location and chargecard records cannot be found; KErrOverflow if aDialString is not long enough to hold the resolved number.

Parameters

TDesC & aNumber The number to be parsed.
TDes & aDialString On return, contains the parsed number.
TParseMode aDialParseMode Indicates whether the parsed string is intended for dialling or for display.
TUint32 aLocationId ID of the dialling location record to be used for resolution.
TUint32 aChargecardId ID of the chargecard ID to be used for resolution.

RollbackInternalTransaction()

void RollbackInternalTransaction ( ) [protected]

Rollback the database after internal use - end a transaction

RollbackTransaction()

IMPORT_C void RollbackTransaction ( )
Marks the end of a transaction and abandons any changes made since the start of the transaction. The database is, in effect, rolled back to the state it was in at the beginning of the transaction. The client's shared read-lock is removed if no write operations were performed, or the exclusive write-lock is removed if write operations were performed.
capability
Dependent on table, see the guide page referenced below.

ShowHiddenRecords()

IMPORT_C void ShowHiddenRecords ( )

Ensures that hidden records are included in the search criteria when creating views using the member functions:

OpenTableLC()

OpenViewMatchingUintLC()

OpenViewMatchingBoolLC()

OpenViewMatchingTextLC()
capability
Dependent on table, see the guide page referenced below.

Version()

IMPORT_C TVersion Version ( ) const

Gets the version from CommsDat.

Member Data Documentation

RDbNamedDatabase iDatabase

RDbNamedDatabase iDatabase [protected]

CCommsDatabaseImpl * iImpl

CCommsDatabaseImpl * iImpl [protected]

TBool iImplNotCreated

TBool iImplNotCreated [protected]

TBool iInInternalTransaction

TBool iInInternalTransaction [protected]

RArray< TCommDbPublishSubscribeNotification > iNotifications

RArray < TCommDbPublishSubscribeNotification > iNotifications [protected]

RDbNotifier iNotifier

RDbNotifier iNotifier [protected]

TInt iNotifierOpenError

TInt iNotifierOpenError [protected]

TBool iShowHiddenRecords

TBool iShowHiddenRecords [protected]