![[Index]](../../../stock/btn_index.gif){kind=small}
![[Glossary]](../../../stock/btn_glossary.gif){kind=small}
![[Previous]](../../../stock/btn_prev.gif){kind=small}
![[Next]](../../../stock/btn_next.gif){kind=small}
| |
|
| |
Location:
commdb.h
Link against: commdb.lib
CCommsDatabase
Supported from 5.0
Accesses 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.
|
Defined in CCommsDatabase:
BeginTransaction(), CancelRequestNotification(), ClearGlobalSettingL(), Close(), CloseDatabase(), CommitTransaction(), GetClientTimeoutL(), GetCurrentDialOutSettingL(), GetDefaultRecordL(), GetGlobalSettingL(), GetRouteTimeoutL(), InTransaction(), NewL(), Open(), OpenConnectionPrefTableInRankOrderLC(), OpenConnectionPrefTableLC(), OpenConnectionPrefTableViewOnRankLC(), OpenIAPTableViewMatchingBearerSetLC(), OpenTableLC(), OpenViewLC(), OpenViewMatchingBoolLC(), OpenViewMatchingTextLC(), OpenViewMatchingUintLC(), OpenViewOnProxyRecordLC(), RequestNotification(), ResolvePhoneNumberFromDatabaseL(), ResolvePhoneNumberL(), RollbackTransaction(), SetClientTimeoutL(), SetDefaultRecordL(), SetGlobalSettingL(), SetRouteTimeoutL(), ShowHiddenRecords(), Type(), ~CCommsDatabase()
Inherited from CBase:
operator new()
Inherited from CCommsDatabaseBase:
IsDatabaseWriteLockedL(),
Version()
static CCommsDatabase* NewL(TCommDbDatabaseType aType);
Supported from 6.0
Allocates and constructs a new communications database object on the heap.
The function creates the directory for the database file and creates a database with empty tables if there is no existing database. It also connects the DBMS server and opens the database for shared access. It leaves with an error if the database and server are not opened successfully. The error can be any error returned by calls to the file server or the DBMS server.
The database and the connection to the server are closed on
deletion of all instantiations of CCommsDatabase.
The aType parameter indicates the type of database
the client is expecting to open. The two types are:
IAP type: the database has an IAP table, which defines sets of ISP, modem, location and chargecards which may be used together.
ISP type: the database is arranged using separate ISP, location, modem and chargecard tables whose records are not associated by using IAPs.
These two types cannot co-exist: any particular database is of one type or the other. If the client knows which type of database it wants to open, then it should use the appropriate parameter. If on the other hand it does not mind which type the database is, it can specify the type as unknown. Note, however, that if the type is unknown, a database must already exist. If not, the type must be specified.
|
|
static CCommsDatabase* NewL();
Withdrawn in 6.0
Allocates and constructs 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();
Supported from 6.0
Frees all resources owned by this object, prior to its destruction.
In particular, the destructor closes the communications database and disconnects from the DBMS.
|
TCommDbDatabaseType Type() const;
Supported from 6.0
Gets the database type.
|
|
void GetGlobalSettingL(const TDesC& aSetting, TUint32& aVal);
Supported from 6.0
Gets a global settings table integer field.
Note that:
If a client attempts to get the default Dial Out IAP with a Version 6.1 database, the function gets the default IAP in the first connection preference for the outgoing direction if it is a dial out ISP-type IAP and returns its ID, otherwise an error is returned.
If a client attempts to get the ASK_USER_BEFORE_DIAL field with a Version 6.1 database, the function returns a true value if CONNECT_PREF_DIALOG_PREF in the first connection preference has been set to produce a prompt, otherwise false.
|
|
void GetGlobalSettingL(const TDesC& aSetting, TDes& aVal);
Supported from 6.0
Gets a global settings table string field.
|
|
void SetGlobalSettingL(const TDesC& aSetting, TUint32 aVal);
Supported from 6.0
Sets a global settings table integer field.
If a client attempts to set the default Dial Out IAP with a Version 6.1 database, the function sets the default IAP in the first connection preference for the outgoing direction to the specified IAP, and the bearer set to CSD.
If a client attempts to set the ASK_USER_BEFORE_DIAL field with a Version 6.1 database, the function sets CONNECT_PREF_DIALOG_PREF in the first connection preference to produce a prompt if true is specified, or do not prompt if false is specified.
|
|
void SetGlobalSettingL(const TDesC& aSetting, const TDesC& aVal);
Supported from 6.0
Sets a global settings table string field.
|
|
void ClearGlobalSettingL(const TDesC& aSetting);
Supported from 6.0
Clears a global settings table field.
|
|
|
void GetCurrentDialOutSettingL(const TDesC& aSetting, TUint32& aValue);
Supported from 6.0
Gets the default ISP, location or modem for dial-out.
This function is not used with IAP databases.
The function is provided for simplicity, as its use is not dependent on a database type.
|
|
TInt Open();
Withdrawn in 6.0
Connects 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
thisCCommsDatabase object; however, creation of the communications
database and connection to the DBMS server only occur on the first call
toOpen().
|
void Close();
Withdrawn in 6.0
Compacts, closes, and disconnects from, the communications database.
If there has been more than one earlier call to Open() on
this CCommsDatabase object and this call is not the last call
toClose(), 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
thisCCommsDatabase 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();
Withdrawn in 6.0
Compacts and closes the communications database.
If there has been more than one earlier call to Open() on
this CCommsDatabase object and this call is not the last call
toCloseDatabase(), 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.
|
TInt RequestNotification(TRequestStatus& aStatus);
Withdrawn in 6.0
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
theRDbNotifier::TEvent enumeration defined in d32dbms.h.
Alternatively, if an outstanding notification request is cancelled by a
call to thisCCommsDatabase'sCancelRequestNotification()member
function, then the request completes with aKErrCancel.
An outstanding notification request is also cancelled if the connection
to the DBMS is severed through a call to Close().
|
|
void CancelRequestNotification();
Withdrawn in 6.0
Cancels an outstanding request for notification of changes to the communications database.
An outstanding request completes with KErrCancel.
|
CCommsDbTableView* OpenTableLC(const TDesC& aTableName);
Withdrawn in 6.0
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.
|
|
|
CCommsDbTableView* OpenViewMatchingUintLC(const TDesC& aTableName, const TDesC& aColumnToMatch, TUint32 aValueToMatch);
Withdrawn in 6.0
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.
|
|
|
CCommsDbTableView* OpenViewMatchingBoolLC(const TDesC& aTableName, const TDesC& aColumnToMatch, TBool aValueToMatch);
Withdrawn in 6.0
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.
|
|
|
CCommsDbTableView* OpenViewMatchingTextLC(const TDesC& aTableName, const TDesC& aColumnToMatch, const TDesC8& aValueToMatch);
Withdrawn in 6.0
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.
|
|
|
CCommsDbTableView* OpenViewMatchingTextLC(const TDesC& aTableName, const TDesC& aColumnToMatch, const TDesC16& aValueToMatch);
Withdrawn in 6.0
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.
|
|
|
CCommsDbTableView* OpenViewLC(const TDesC& aTableName, const TDesC& aSqlQuery);
Withdrawn in 6.0
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.
|
|
|
|
Views on the Connection Preferences table cannot be opened with the generic functions such as CCommsDatabaseBase::OpenViewLC(). Instead, one of the following must be used.
CCommsDbConnectionPrefTableView* OpenConnectionPrefTableLC();
Supported from 6.1
Opens a view on the Connection Preferences table.
When the use of the view object is complete, it should be popped from the cleanup stack, and deleted.
|
|
CCommsDbConnectionPrefTableView* OpenConnectionPrefTableLC(TCommDbConnectionDirection aDirection);
Supported from 6.1
Opens a view on the records in the Connection Preferences table with a specified direction.
When the use of the view object is complete, it should be popped from the cleanup stack, and deleted.
|
|
|
CCommsDbConnectionPrefTableView* OpenConnectionPrefTableInRankOrderLC(TCommDbConnectionDirection aDirection);
Supported from 6.1
Opens a view on the records in the Connection Preferences table with a specified direction, and with records sorted into ranking order.
Records are sorted in rank order from ranking 1 first. Records with rank 0 are not included.
When the use of the view object is complete, it should be popped from the cleanup stack, and deleted.
|
|
|
CCommsDbConnectionPrefTableView* OpenConnectionPrefTableViewOnRankLC(TCommDbConnectionDirection aDirection, TUint32 aRank);
Supported from 6.1
Opens a view on the records in the Connection Preferences table with a specified direction and ranking.
When the use of the view object is complete, it should be popped from the cleanup stack, and deleted.
|
|
|
|
CCommsDbTableView* OpenIAPTableViewMatchingBearerSetLC(TUint32 aBearerSet, TCommDbConnectionDirection aDirection);
Supported from 6.1
Opens a view on records in the IAP table with a specified range of service types.
IAP records are included that have matching bearers and direction, as read from the Connection preference table, to those specified.
When the use of the view object is complete, it should be popped from the cleanup stack, and deleted.
|
|
|
CCommsDbTableView* OpenViewOnProxyRecordLC(TUint32 aServiceId, const TDesC& aServiceType);
Supported from 6.1
Opens a view on records in the Proxies table with a specified range of service types and service IDs.
Proxies records are included that have matching service types and IDs. When the use of the view object is complete, it should be popped from the cleanup stack, and deleted.
|
|
|
|
TInt BeginTransaction();
Withdrawn in 6.0
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.
|
TInt CommitTransaction();
Withdrawn in 6.0
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.
|
void RollbackTransaction();
Withdrawn in 6.0
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();
Withdrawn in 6.0
Tests whether a transaction is in progress, i.e. whether a call
toBeginTransaction() has been called.
|
|
void GetDefaultRecordL(const TDesC& aTableName, TUint32& aId);
Withdrawn in 6.0
Gets the Id of the default record belonging to a specified table. The Id
is copied into aId.
The only tables which can have a default record are:
the dial out service table, with symbolic
name DIAL_OUT_SERVICE
the dial in service table, with symbolic
name DIAL_IN_SERVICE
the connected modem table, with symbolic
name CONNECTED_MODEM
the modem preferences table, with symbolic
name MODEM_PREFS
the location table, with symbolic name LOCATION.
Note:
The default record can be a hidden record.
|
|
void SetDefaultRecordL(const TDesC& aTableName, TUint32 aId);
Withdrawn in 6.0
Identifies, to CommDb, the Id of the default record belonging to a specified table.
Note:
The default record can be a hidden record.
|
|
|
TInt ShowHiddenRecords();
Withdrawn in 6.0
Ensures that hidden records are included in the search criteria when creating views using the member functions:
OpenTableLC()
OpenViewMatchingUintLC()
OpenViewMatchingBoolLC()
OpenViewMatchingTextLC()
|
|
void GetClientTimeoutL(TUint32& aTimeout);
Withdrawn in 6.0
Gets the client timeout value from the communications database.
The function puts the value into aTimeout.
|
void SetClientTimeoutL(const TUint32 aTimeout);
Withdrawn in 6.0
Sets the value of the client timeout in the communications database.
|
void GetRouteTimeoutL(TUint32& aTimeout);
Withdrawn in 6.0
Gets the route timeout value from the communications database.
The function puts the value into aTimeout.
|
void SetRouteTimeoutL(const TUint32 aTimeout);
Withdrawn in 6.0
Sets the value of the route timeout value in the communications database.
|
|
static void ResolvePhoneNumberL(TDesC& aNumber, TDes8& aDialString, TParseMode aDialParseMode);
Withdrawn in 6.0
Resolves a telephone number and places it into a reference containing the parsed number. The resolution of the number uses the default location table record 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.
Note:
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.
|
|
void ResolvePhoneNumberFromDatabaseL(TDesC& aNumber, TDes8& aDialString, TParseMode aDialParseMode);
Withdrawn in 6.0
Resolves the telephone number supplied in the descriptor and places it into a reference containing the parsed number.
The resolution of the number uses the default record to determine dialling codes and formats.
The function does not resolve for mobile phones; aNumber is
just copied to aDialString.
Note:
Unlike the static function ResolvePhoneNumberL() this
function does not wrap read operations in a transaction.
|
|
Copyright ©2002 Symbian Ltd. 6.1-00174 |
|
![[Top]](../../../stock/arrow_up_2.gif){kind=icon}
![[Top]](../../../stock/arrow_up.gif){kind=icon}