![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
Section Contents
Applications that use this class will not work correctly on a version of EPOC earlier than ER5.
CBase |
Abstract: CBase behavior. |
CCommsDatabase |
The communications database. |
commdb.h
commdb.lib
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.
static CCommsDatabase* NewL();
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.
CCommsDatabase* |
A pointer to a communications database object |
~CCommsDatabase();
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.
TVersion Version() const;
Use this function to return the version of the underlying DBMS.
TVersion |
The object containing the version information. |
TInt Open();
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().
TInt |
KErrNone if successful, otherwise one of the system error codes. |
void Close();
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.
void CloseDatabase();
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.
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.
TInt RequestNotification(TRequestStatus& aStatus);
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.
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. |
TInt |
KErrNone if successful, otherwise one of the system error codes. |
void CancelRequestNotification();
Use this function to cancel an outstanding request for notification of changes to the communications database.
An oustanding request completes with KErrCancel.
CCommsDbTableView* OpenTableLC(const TDesC& aTableName);
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.
const TDesC& aTableName |
A reference to a descriptor containing the name of a table in the communications database. |
CCommsDbTableView* |
A pointer to the view object. |
The function may leave for a number of reasons, for example, if the table named in aTablename does not exist.
The function generates an SQL query to create the view.
CCommsDbTableView* OpenViewMatchingUintLC(const TDesC& aTableName, const TDesC& aColumnToMatch, TUint32 aValueToMatch);
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.
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. |
CCommsDbTableView* |
A pointer to the view object. |
The function may leave for a number of reasons, for example, if the table does not exist or the named column cannot be found.
The function generates an SQL query to create the view.
CCommsDbTableView* OpenViewMatchingBoolLC(const TDesC& aTableName, const TDesC& aColumnToMatch, TBool aValueToMatch);
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.
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. |
CCommsDbTableView* |
A pointer to the view object. |
The function may leave for a number of reasons, for example, if the table does not exist or the named column cannot be found.
The function generates an SQL query to create the view.
CCommsDbTableView* OpenViewMatchingTextLC(const TDesC& aTableName, const TDesC& aColumnToMatch, const TDesC8& aValueToMatch);
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.
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. |
CCommsDbTableView* |
A pointer to the view object. |
The function may leave for a number of reasons, for example, if the table does not exist or the named column cannot be found.
The function generates an SQL query to create the view.
CCommsDbTableView* OpenViewMatchingTextLC(const TDesC& aTableName, const TDesC& aColumnToMatch, const TDesC16& aValueToMatch);
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.
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. |
CCommsDbTableView* |
A pointer to the view object. |
The function may leave for a number of reasons, for example, if the table does not exist or the named column cannot be found.
The function generates an SQL query to create the view.
CCommsDbTableView* OpenViewLC(const TDesC& aTableName, const TDesC& aSqlQuery);
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.
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 |
CCommsDbTableView* |
A pointer to the view object. |
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();
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().
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. |
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.
TInt CommitTransaction();
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.
TInt |
KErrNone if successful, otherwise one of the system error codes. |
void RollbackTransaction();
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.
TBool InTransaction();
Use this function to determine whether a transaction is in progress, i.e. whether a call to BeginTransaction() has been called.
TBool |
true, if a transaction is in progress; false, otherwise. |
void GetDefaultRecordL(const TDesC& aTableName, TUint32& aId);
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.
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. |
The default record can be a hidden record.
void SetDefaultRecordL(const TDesC& aTableName, TUint32 aId);
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.
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. |
The default record can be a hidden record.
TInt ShowHiddenRecords();
Use this function to ensure that hidden records are included in the search criteria when creating views using the member functions:
TInt |
KErrNone always. |
void GetClientTimeoutL(TUint32& aTimeout);
Use this function to fetch the client timeout value from the communications database.
The function puts the value into aTimeout.
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. |
void SetClientTimeoutL(const TUint32 aTimeout);
Use this function to set the client timeout value in the communications database to the value in the unsigned integer aTimeout.
TUint32 aTimeout |
The client timeout value to be set. |
void GetRouteTimeoutL(TUint32& aTimeout);
Use this function to fetch the route timeout value from the communications database.
The function puts the value into aTimeout.
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. |
void SetRouteTimeoutL(const TUint32 aTimeout);
Use this function to set the route timeout value into the communications database to the value in the unsigned integer aTimeout.
TUint32 aTimeout |
The route timeout value to be set. |
static void ResolvePhoneNumberL(TDesC& aNumber, TDes8& aDialString, TParseMode aDialParseMode);
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.
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 |
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.
The function leaves if there is no default record in the Location table.
void ResolvePhoneNumberFromDatabaseL(TDesC& aNumber, TDes8& aDialString, TParseMode aDialParseMode);
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.
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 |
Unlike the static function ResolvePhoneNumberL(), this function does not wrap read operations in a transaction.
The function leaves if there is no default record in the Location table.
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |