![[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
class CCommsDatabase : public CCommsDatabaseBase;
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(), CCommsDatabase(), CancelRequestNotification(), ClearAgentAndExtL(), ClearGlobalSettingL(), Close(), CloseDatabase(), CommitTransaction(), CreateDatabaseL(), DoClearCompatibilitySettingL(), DoFindConnectionPrefLC(), DoGetCompatibilitySettingL(), DoGetCurrentSettingL(), DoOpenAgentTableLC(), DoOpenConnectionPrefViewLC(), DoOpenL(), DoSetCompatibilitySettingL(), DoSetGlobalSettingL(), DoSetGlobalSettingL(), DoSetIAPCompatibilitySettingL(), ECompatibilitySetting, EGlobalSetting, ENotASetting, GetAgentClientTimeoutL(), GetAgentDesL(), GetAgentExtL(), GetAgentL(), GetAgentRouteTimeoutL(), GetAgentTimeoutL(), GetClientTimeoutL(), GetCurrentDialInSettingL(), GetCurrentDialOutSettingL(), GetDefaultRecordL(), GetGlobalSettingL(), GetGlobalSettingL(), GetRouteTimeoutL(), GlobalSettingTypeL(), InTransaction(), NewL(), NewL(), NewL(), NewL(), Open(), OpenConnectionPrefTableInRankOrderLC(), OpenConnectionPrefTableLC(), OpenConnectionPrefTableLC(), OpenConnectionPrefTableViewOnRankLC(), OpenDefaultDbL(), OpenGlobalSettingsTableLC(), OpenIAPTableViewMatchingBearerSetLC(), OpenTableLC(), OpenViewLC(), OpenViewMatchingBoolLC(), OpenViewMatchingTextLC(), OpenViewMatchingTextLC(), OpenViewMatchingUintLC(), OpenViewOnProxyRecordLC(), RequestNotification(), ResolvePhoneNumberFromDatabaseL(), ResolvePhoneNumberL(), RollbackTransaction(), SetAgentClientTimeoutL(), SetAgentDesL(), SetAgentExtL(), SetAgentL(), SetAgentRouteTimeoutL(), SetAgentTimeoutL(), SetClientTimeoutL(), SetDefaultRecordL(), SetGlobalSettingL(), SetGlobalSettingL(), SetRouteTimeoutL(), ShowHiddenRecords(), TGlobalSettingType, Type(), ValidateRankL(), ValidateServiceL(), ~CCommsDatabase()
Inherited from CBase:
operator new()
Inherited from CCommsDatabaseBase:
BeginInternalTransactionL(),
CommitInternalTransaction(),
ConvertToUid(),
Database(),
DatabaseUpdateHasOccurred(),
DoClose(),
DoOpenIAPTableViewL(),
DoOpenTableViewL(),
DoOpenViewMatchingTextL(),
DoOpenViewMatchingUintL(),
GetRandomNumber(),
IsDatabaseWriteLockedL(),
NotifyAllChanges(),
NotifyChangeL(),
PopulateChargeCardL(),
PopulateDialLocationL(),
RollbackInternalTransaction(),
TCommDbSystemAgentNotification,
Version(),
iDatabase,
iDbs,
iInInternalTransaction,
iNotifications,
iNotifier,
iNotifierOpenError,
iShowHiddenRecords,
iSystemAgent,
iSystemAgentNotifier,
iUid,
iUpdateHasOccurred,
iValue
static CCommsDatabase* NewL();
Withdrawn in 6.0
Supported from 7.0
Allocates and constructs a new communications database object on the heap.If the database filestore does not exist the default filestore is duplicated. If no default filestore exists an empty database is created.
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.
|
static CCommsDatabase* NewL(TBool aUseDefaultDb);
Supported from 7.0
Creates a CCommsDatabase. If the database filestore exists and aUseDefaultDb is ETrue the default filestore is duplicated. Otherwise an empty database is created. If the commdb doesn't exist and this and aUseDefaultDb is EFalse the this function will leave.
|
|
|
static CCommsDatabase* NewL(TCommDbOpeningMethod& aOpeningMethod);
Supported from 7.0
Creates a CCommsDatabase as with NewL(). The method of opening: (Created, CopiedDefault or Opened) is returned in aOpeningMethod.
|
|
static CCommsDatabase* NewL(TCommDbDatabaseType aType);
Supported from 6.0
Withdrawn in 7.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.
|
|
~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.
|
void GetGlobalSettingL(const TDesC& aSetting, TUint32& aValue);
Supported from 6.0
Gets a global settings table integer field.
|
|
void GetGlobalSettingL(const TDesC& aSetting, TDes& aValue);
Supported from 6.0
Gets a global settings table string field.
|
|
void SetGlobalSettingL(const TDesC& aSetting, TUint32 aValue);
Supported from 6.0
Sets a global settings table integer field.
|
|
void SetGlobalSettingL(const TDesC& aSetting, const TDesC& aValue);
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.
|
void GetCurrentDialInSettingL(const TDesC& aSetting, TUint32& aValue);
Supported from 7.0
Retrieve settings for the dial in IAP.
|
|
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.
|
|
|
|
void SetAgentL(const TDesC& aService, const TDesC& aAgent);
Supported from 7.0
Set the agent to be used when accessing the specified service.
|
void SetAgentExtL(const TDesC& aService, const TDesC& aAgentExt);
Supported from 7.0
Set the agent extension to be used when accessing the specified service.
|
void SetAgentClientTimeoutL(const TDesC& aService, TInt aClientTimeout);
Set the client timeout associated with the specified service.
|
void SetAgentRouteTimeoutL(const TDesC& aService, TInt aRouteTimeout);
Set the route timeout associated with the specified service.
|
void GetAgentL(const TDesC& aService, TDes& aAgent);
Gets the agent associated with the specified service.
|
void GetAgentExtL(const TDesC& aService, TDes& aAgentExt);
Gets the agent extension associated with the specified service.
|
TInt GetAgentClientTimeoutL(const TDesC& aService);
Gets the client timeout associated with the specified service.
|
|
TInt GetAgentRouteTimeoutL(const TDesC& aService);
Gets the route timeout associated with the specified service.
|
|
void ClearAgentAndExtL(const TDesC& aService);
Clear any agent, agent extension or timeout associated with the specified service.
|
|
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 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().
|
|
void CancelRequestNotification();
Withdrawn in 6.0
Cancels an outstanding request for notification of changes to the communications database.
An outstanding request completes with
KErrCancel.
|
TCommDbDatabaseType Type() const;
Supported from 6.0
Withdrawn in 7.0
Gets the 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 this
CCommsDatabase object; however, creation of the communications
database and connection to the DBMS server only occur on the first call to
Open().
|
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 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();
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 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.
|
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.
|
|
|
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 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.
|
|
|
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 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.
|
|
|
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 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.
|
|
|
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 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.
|
|
|
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.
|
|
|
|
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.
|
|
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.
|
|
|
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() or
RollbackTransaction().
|
![[Top]](../../../../_stock/arrow_up_2.gif){kind=icon}
CCommsDbTableView behaviour. See the
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
to BeginTransaction() has been called.
|
|
TInt ShowHiddenRecords();
Withdrawn in 6.0
Ensures that hidden records are included in the search criteria when creating views using the member functions:
|
|
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 dat