Class CCommsDatabaseBase

CCommsDatabaseBase

Support

Supported from 6.0

Description

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

Derivation

CBase Base class for all classes to be instantiated on the heap CCommsDatabaseBase Base class for CCommsDatabase

Defined in CCommsDatabaseBase:
BeginTransaction(), CCommsDatabaseBase(), CancelRequestNotification(), CommitTransaction(), InTransaction(), IsDatabaseWriteLockedL(), OpenTableLC(), OpenViewLC(), OpenViewMatchingBoolLC(), OpenViewMatchingTextLC(), OpenViewMatchingUintLC(), RequestNotification(), ResolvePhoneNumberFromDatabaseL(), ResolvePhoneNumberL(), RollbackTransaction(), ShowHiddenRecords(), Version(), ~CCommsDatabaseBase()

Inherited from CBase:
operator new()

CCommsDatabaseBase();

Description

Default constructor.

~CCommsDatabaseBase();

Description

Destructor.

TBool IsDatabaseWriteLockedL();

Description

Tests if database is write locked.

Return value

TBool

TVersion Version() const;

Description

Gets the version of the underlying DBMS.

Return value

TVersion The object containing the version information.

TInt RequestNotification(TRequestStatus& aStatus);

Description

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

The request is an asynchronous request.

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 defined in d32dbms.h.

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

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

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.

Return value

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

void CancelRequestNotification();

Description

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

An outstanding request completes with KErrCancel.

CCommsDbTableView* OpenTableLC(const TDesC& aTableName);

Description

Opens a view onto a whole table and returns a pointer to that view.

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.

Note:

• The function generates an SQL query to create the view.

Parameters

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

Return value

CCommsDbTableView* A pointer to the view object.

Leave codes

The function may leave for a number of reasons, for example, if the table named in aTablename does not exist.

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

Description

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 byaColumnToMatch, matches the unsigned integer valueaValueToMatch.

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.

Note:

• The function generates an SQL query to create the view.

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. TUint32 aValueToMatch The value to be matched with the content of columnaColumnToMatch.

Return value

CCommsDbTableView* A pointer to the view object.

Leave codes

The function may leave for a number of reasons, for example, if the table does not exist or the named column cannot be found.

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

Description

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 byaColumnToMatch, matches the boolean valueaValueToMatch.

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 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.

Note:

• The function generates an SQL query to create the view.

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. TBool aValueToMatch The value to be matched with the content of columnaColumnToMatch.

Return value

CCommsDbTableView* A pointer to the view object.

Leave codes

The function may leave for a number of reasons, for example, if the table does not exist or the named column cannot be found.

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

Description

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 byaColumnToMatch, matches the narrow text supplied in the descriptoraValueToMatch.

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.

Note:

The function generates an SQL query to create the view.

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 columnaColumnToMatch.

Return value

CCommsDbTableView* A pointer to the view object.

Leave codes

The function may leave for a number of reasons, for example, if the table does not exist or the named column cannot be found.

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

Description

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 byaColumnToMatch, matches the wide text supplied in the descriptoraValueToMatch.

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.

Note:

• The function generates an SQL query to create the view.

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 columnaColumnToMatch.

Return value

CCommsDbTableView* A pointer to the view object.

Leave codes

The function may leave for a number of reasons, for example, if the table does not exist or the named column cannot be found.

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

Description

Opens a view onto a specified table based on an explicitly coded SQL query, and returns a pointer to that view.

The view includes all those records which match the SQL query supplied in the descriptor aSqlQuery. It is the caller's responsibility to code this query correctly.

As the SQL query is defined by the caller, the resulting view does not exclude hidden records unless explicitly stated in the query itself. To exclude hidden records, insert Hidden=0 as a search condition into the SQL query text.

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.

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

Return value

CCommsDbTableView* A pointer to the view object.

Leave codes

The function may leave for a number of reasons, for example, if the table does not exist or the named column cannot be found.

TInt BeginTransaction();

Description

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()orRollbackTransaction().

Note:

• 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. See theInsertRecord(),UpdateRecord(),DeleteRecord(),PutRecordChanges() andCancelRecordChanges() member functions of theCCommsDbTableView class.

Return value

TInt KErrNone if the database has been successfully locked; the transaction can start. KErrLocked if another client already has an exclusive write-lock on the database.

TInt CommitTransaction();

Description

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.

Return value

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

void RollbackTransaction();

Description

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.

TBool InTransaction();

Description

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

Return value

TBool true, if a transaction is in progress; false, otherwise.

void ShowHiddenRecords();

Description

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

• OpenTableLC()

• OpenViewMatchingUintLC()

• OpenViewMatchingBoolLC()

• OpenViewMatchingTextLC()

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

Description

Resolves a 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.

Parameters

TDesC& aNumber The number to be parsed. TDes& aDialString On return from the function, contains the parsed number. TParseMode aDialParseMode The parse mode: indicates whether the parsed string is intended for dialling or for display. This enumerator is defined in dial.h TUint32 aLocationId ID of the location record TUint32 aChargecardId ID of the chargecard ID to be used for resolution

Leave codes

KErrNotFound Specified location and chargecard records cannot be found or with KErrOverflow aDialString is not long enough to hold the resolved number.

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

Description

Resolves a 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.

Parameters

TDesC& aNumber A reference to the descriptor containing the number to be parsed. TDes& aDialString A reference to a descriptor; on return from the function, contains the parsed number. TParseMode aDialParseMode The parse mode: indicates whether the parsed string is intended for dialling or for display. This enumerator is defined in dial.h TUint32 aLocationId ID of the location record TUint32 aChargecardId ID of the chargecard ID to be used for resolution

Leave codes

KErrNotFound Specified location and chargecard records cannot be found or with KErrOverflow aDialString is not long enough to hold the resolved number.