EPOC   SDK Home Glossary Indexes Previous Next Up

CCommsDatabase class


Contents


CCommsDatabase class — The communications database

Section Contents


Overview

Compatibility

Applications that use this class will not work correctly on a version of EPOC earlier than ER5.

Derivation

CBase

Abstract: CBase behavior.

CCommsDatabase

The communications database.

Defined in

commdb.h

Link against

commdb.lib

Description

This class encapsulates the behaviour required to access the communications database through the DBMS. An object of this type must be constructed and opened by a client before any of the tables in the database can be accessed.


Allocation and construction


NewL() — Create new communications database object

static CCommsDatabase* NewL();

Description

Use this static function to allocate and construct a new communications database object on the heap.

If there is insufficient memory available to create the object, the function leaves. If allocation is successful, it returns a pointer to the new object.

Return value

CCommsDatabase*

A pointer to a communications database object


Destruction


~CCommsDatabase() — Destructor

~CCommsDatabase();

Description

The destructor frees all resources owned by this object, prior to its destruction.

In particular, the destructor closes the communications database and disconnects from the DBMS.


Underlying DBMS version information


Version() — Version information

TVersion Version() const;

Description

Use this function to return the version of the underlying DBMS.

Return value

TVersion

The object containing the version information.


Open the database


Open() — Connect to the DBMS server and open the database

TInt Open();

Description

Use this function to connect to the DBMS. If the communications database does not exist, it is created with an empty set of tables before the connection to the server takes place.

The database is opened for shared access.

This function can be called any number of times on this CCommsDatabase object; however, creation of the communications database and connection to the DBMS server only occur on the first call to Open().

Return value

TInt

KErrNone if successful, otherwise one of the system error codes.


Close() — Close the database and disconnect from the DBMS server

void Close();

Description

Use this function to:

If there has been more than one earlier call to Open() on this CCommsDatabase object and this call is not the last call to Close(), then the database remains open, it is not compacted and the connection to the DBMS remains active.

If this is the last call to Close() on this CCommsDatabase object, then any outstanding notification request is cancelled.

Close() can be safely called, if the database has already been closed and the connection to the DBMS removed.


CloseDatabase() — Close the database only

void CloseDatabase();

Description

Use this function to:

If there has been more than one earlier call to Open() on this CCommsDatabase object and this call is not the last call to CloseDatabase(), then the database remains open and is not compacted.

CloseDatabase() can be safely called, if the database has already been closed.

Notes

This function does not disconnect the client from the DBMS. The connection can be severed later by calling Close().

If there is an outstanding request for notification of changes to the database, then this request remains outstanding while the connection to the DBMS remains.


Notification service


RequestNotification() — Issue request for notification of change to database

TInt RequestNotification(TRequestStatus& aStatus);

Description

Use this function to request 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().

See also asycnhronous services.

Arguments

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 one of the system error codes.


CancelRequestNotification() — Cancel outstanding request for notification of change to database

void CancelRequestNotification();

Description

Use this function to cancel an outstanding request for notification of changes to the communications database.

An oustanding request completes with KErrCancel.


Open views onto a table in the communications database


OpenTableLC() — Open a view on all of the records in a table

CCommsDbTableView* OpenTableLC(const TDesC& aTableName);

Description

Use this function to open a view onto the whole table whose name is passed in the descriptor aTableName and return 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.

Arguments

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 considerations

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

Notes

The function generates an SQL query to create the view.


OpenViewMatchingUintLC() — Open a view based on matching an unsigned integer value

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

Description

Use this function to open a view onto the table whose name is passed in the descriptor aTableName and return 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.

Arguments

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

Return Value

CCommsDbTableView*

A pointer to the view object.

Leave considerations

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

Notes

The function generates an SQL query to create the view.


OpenViewMatchingBoolLC() — Open a view based on matching a boolean value

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

Description

Use this function to open a view onto the table whose name is passed in the descriptor aTableName and return 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 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.

Arguments

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

Return Value

CCommsDbTableView*

A pointer to the view object.

Leave considerations

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

Notes

The function generates an SQL query to create the view.


OpenViewMatchingTextLC() — Open a view based on matching narrow text

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

Description

Use this function to open a view onto the table whose name is passed in the descriptor aTableName and return 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.

Arguments

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.

Return Value

CCommsDbTableView*

A pointer to the view object.

Leave considerations

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

Notes

The function generates an SQL query to create the view.


OpenViewMatchingTextLC() — Open a view based on matching wide text

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

Description

Use this function to open a view onto the table whose name is passed in the descriptor aTableName and return 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 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.

Arguments

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.

Return Value

CCommsDbTableView*

A pointer to the view object.

Leave considerations

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

Notes

The function generates an SQL query to create the view.


OpenViewLC() — Open a view based on an explictly coded SQL query

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

Description

Use this function to open a view onto the table whose name is passed in the descriptor aTableName and return 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.

Arguments

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 considerations

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


Transaction support


BeginTransaction() — Mark start of transaction; gets shared read-lock

TInt BeginTransaction();

Description

Use this function to mark the start of a transaction and get 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().

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.

Notes

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 the InsertRecord(), UpdateRecord(), DeleteRecord(), PutRecordChanges() and CancelRecordChanges() member functions of the CCommsDbTableView class.


CommitTransaction() — Mark end of transaction; commit any changes; remove lock

TInt CommitTransaction();

Description

Use this function to mark the end of a transaction and commit 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 one of the system error codes.


RollbackTransaction() — Mark end of transaction; abandon changes; remove lock

void RollbackTransaction();

Description

Use this function to mark the end of a transaction and abandon 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.


InTransaction() — Determine whether a transaction is in progress

TBool InTransaction();

Description

Use this function to determine whether a transaction is in progress, i.e. whether a call to BeginTransaction() has been called.

Return value

TBool

true, if a transaction is in progress;

false, otherwise.


Default record handling


GetDefaultRecordL() — Get Id of default record in specified table

void GetDefaultRecordL(const TDesC& aTableName, TUint32& aId);

Description

Use this function to fetch the Id of the default record belonging to the table whose name is passed in the descriptor aTableName. The Id is copied into aId.

The only tables which can have a default record are:

If this function is called for any other table, then the function leaves with KErrNotSupported.

Arguments

const TDesC& aTableName

A reference to a descriptor containing the name of a table in the communications database.

TUint32& aId

A reference to an unsigned integer passed by the caller. On successful return from this function, contains the Id of the default record.

Notes

The default record can be a hidden record.


SetDefaultRecordL() — Set Id of specified table's default record

void SetDefaultRecordL(const TDesC& aTableName, TUint32 aId);

Description

Use this function to identify, to CommDb, the Id of the default record belonging to the table whose name is passed in the descriptor aTableName.

Not all tables can have a default record; if the table name passed in aTableName is not one of:

then this function leaves with KErrNotSupported.

Arguments

const TDesC& aTableName

A reference to a descriptor containing the name of a table in the communications database.

TUint32 aId

The Id of the record in table aTableName which is to be the default record of this table.

Notes

The default record can be a hidden record.


Hidden records


ShowHiddenRecords() — Show hidden records when generating views

TInt ShowHiddenRecords();

Description

Use this function to ensure that hidden records are included in the search criteria when creating views using the member functions:

Return value

TInt

KErrNone always.


Accessing timeouts


GetClientTimeoutL() — Fetch the client timeout value

void GetClientTimeoutL(TUint32& aTimeout);

Description

Use this function to fetch the client timeout value from the communications database.

The function puts the value into aTimeout.

Arguments

TUint32& aTimeout

A reference to an unsigned integer passed by the caller. On successful return from this function, contains a copy of the client timeout value.


SetClientTimeoutL() — Set the client timeout value

void SetClientTimeoutL(const TUint32 aTimeout);

Description

Use this function to set the client timeout value in the communications database to the value in the unsigned integer aTimeout.

Arguments

TUint32 aTimeout

The client timeout value to be set.


GetRouteTimeoutL() — Fetch the route timeout value

void GetRouteTimeoutL(TUint32& aTimeout);

Description

Use this function to fetch the route timeout value from the communications database.

The function puts the value into aTimeout.

Arguments

TUint32& aTimeout

A reference to an unsigned integer passed by the caller. On successful return from this function, contains a copy of the route timeout value.


SetRouteTimeoutL() — Set the route timeout value

void SetRouteTimeoutL(const TUint32 aTimeout);

Description

Use this function to set the route timeout value into the communications database to the value in the unsigned integer aTimeout.

Arguments

TUint32 aTimeout

The route timeout value to be set.


Resolve phone number


ResolvePhoneNumberL() — Resolve phone number using current location

static void ResolvePhoneNumberL(TDesC& aNumber, TDes8& aDialString, TParseMode aDialParseMode);

Description

Use this static function to resolve the telephone number supplied in the descriptor aNumber and place the parsed number into aDialString. The resolution of the number uses the default record in the Location table to determine dialling codes and formats.

All read operations to tables within the database are wrapped within a transaction.

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

Arguments

TDesC& aNumber

A reference to the descriptor containing the number to be parsed.

TDes8& aDialString

A reference to an 8 bit 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

Notes

The function is static and does not need an explicitly constructed instance of a CCommsDatabase object. Opening and accessing the communications database is handled implicitly by the function.

Leave considerations

The function leaves if there is no default record in the Location table.


ResolvePhoneNumberFromDatabaseL() — Resolve phone number using current location

void ResolvePhoneNumberFromDatabaseL(TDesC& aNumber, TDes8& aDialString, TParseMode aDialParseMode);

Description

Use this member function to resolve the telephone number supplied in the descriptor aNumber and place the parsed number into aDialString. The resolution of the number uses the default record in the Location table to determine dialling codes and formats.

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

Arguments

TDesC& aNumber

A reference to the descriptor containing the number to be parsed.

TDes8& aDialString

A reference to an 8 bit 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

Notes

Unlike the static function ResolvePhoneNumberL(), this function does not wrap read operations in a transaction.

Leave considerations

The function leaves if there is no default record in the Location table.

EPOC       SDK Home Glossary Indexes Previous Next Up