A few notes about the CommDb (use in Symbian OS)

More and more applications have to use the phones connectivity. Sending some short messages (SMS) for licensing, transmit pictures using multimedia messages (MMS), manage emails (Pop3, IMAP and SMTP) or simply use a client socket for HTTP or your custom protocol over TCP/IP using GPRS, CSD or WCDMA(UMTS). This list is only a brief summary of functions where the OS will have to access an internal database for informations about how to handle the respective protocol stack. The database is called CommDB.

Like other themes you will find a lot of basic information about this “communications database” in your SDKs documentation - search for “Using CommDB”.

In my last symbian project I made some additional insights (Symbian OS versions 6.1, 7.0, 7.0s) which I want to share with you - any comments are welcome . I won’t show much program code, because there are already many examples in the SDKs doc, the Symbian FAQ and some threads in the newsgroup. The article’s aim is to get you across the CommmDD-layout and the basically kinds to get access to it.

1. Basic terms

The CommDB is a file named cdbv2.dat for Symbian OS 6.1 (Series 60 v0.9, v1.0, v1.2) and cdbv3.dat for Symbian OS 7.0s/7.0 (Series 60 2.0 / UIQ 2.0, UIQ 2.1).

You will find this file twice on your phone:
  in C:/system/data/ - The RAM-Version for storing the current data
  in Z:/system/data/ - The ROM-Version. If the RAM-version cannot be found this file is copied to RAM. (Never checked this feature)

The file can be accessed through the communications database server (a layer over DBMS). This server gives you a logical access to an (extensible) database, existing of many “linked” tables. Each logical summary of information how to get connectivity access using a special protocol and/or bearer type is called Internet Access Point (IAP). Both Series 60 and UIQ offer a user interface to manage IAPs and alter the CommDB:

Each mobile network provider needs it’s own individual configuration. Therefore mostly the phones come from your provider with a subset of common IAPs, ready configured for SMS, WAP, WWW using different bearers like GSM, GPRS or GPRS. Users can add new access points manually by using the above dialogs or they make use of BIO messaging - a kind of system SMS from your provider to configure the phone.

As a developer you don’t really need to take account for selecting the right IAP for the required type of connection - the OS will prompt the user with a selection dialog. But if you want to use a special IAP for e.g. a dedicated WAP- or Intranet-Gateway you have to insert a new IAP and then select him. This can be done by direct altering the CommDB-Tables or if you developing for Series 60 by use of Nokia’s access-point-engine-library (ApEngine).

2. Nokia’s ApEngine (a general survey)

This library encapsulates the CommDB-API and brings a few dialogs/views, which one can embed to the program.
There are a few classes which make programmers live easier. (Link against apengine.lib.)

Classname	Headerfile	Description (taken from SDK)
CApSelect	<apselect.h>	This class is used to help client’s access point selection. Selection can be tailored with specific filters, rules and sort order. Provides methods for setting and getting filters and sort order.
ApListItem	<aplistitem.h>	This class is used to hold the main information of an access point. It is used in CApSelect.
CApDatahandler	<apdatahandler.h>	Representation of the access point handler. Encapsulates a session with the CommsDB Provides a way to access the database and manipulate its data. <!--[if !supportEmptyParas]-->
CApAccessPointItem	<apaccesspointitem.h> <!--[if !supportEmptyParas]--> <!--[endif]-->	CApAccessPointItem is used to exchange data between engine and client. It holds the information for an access point including WAP, IAP, ISP (if present & applies). This class uses the same approach as CommDB to read and write data: it has functions for each data type implemented. To read or write the data, we have to know the data type and the enum name of the ’column’. The column values has the names of the database columns with the ’EAp’ prefix. The reason for this (not using the database column descriptors) is performance. It is much faster to compare enum values than literals.
CApUtils	<aputils.h>	Representation of access point utilities. Provides utilities to access points for clients. Encapsulates database handling. This class provides utility functions for clients that need some specific information or parameters from (maybe more than one) AP. It is provided for ease of use so clients do not have to work with CApDataHandler’s concept (one object-one Uid).

There are some additional information in the headerfiles. Have a look insight. Some headerfiles are missing in OS 7.0s. I copied them from 6.1 and it works for my needs (TX to Jan .

Here are two short examples how to use it:

/*Ex1: Show a list of all IAPs (Series 60 only)    */

   CApSettingsHandler* settingsHandler = CApSettingsHandler::NewLC(
                                             EFalse,
                                             EApSettingsSelListIsListPane,
                                             EApSettingsSelMenuNormal,
                                             KEApIspTypeAll,
                                             EApBearerTypeAll,
                                             KEApSortNameAscending);
   TUint32 originallyFocused(uid);
   TUint32 selectedIap(uid);

   // Show the dialog
   settingsHandler->RunSettingsL(originallyFocused, selectedIap);

   CleanupStack::PopAndDestroy(settingsHandler);

   /*Ex2: Iterate over a list of IAPs (Series 60 only) */

   CCommsDatabase* CommDb = CCommsDatabase::NewL(EDatabaseTypeIAP);
   CleanupStack::PushL(CommDb);

   CApSelect* ApSelect = CApSelect::NewLC(*CommDb, KEApIspTypeAll ,EApBearerTypeAll ,KEApSortUidAscending);

   if (ApSelect->MoveToFirst())
   {
       do
       {
           TUint uid = ApSelect->Uid();
           //put here your IAP stuff

       }
       while(ApSelect->MoveNext());
   }

   CleanupStack::PopAndDestroy(ApSelect);
   CleanupStack::PopAndDestroy(CommDb);

When you use the ApEngine (or the Series 60 GUI) to add a new IAP, you always will find an entry in table WAP_ACCESS_POINT, even so if the IAP is not for a wap connection - it’s gateway will be set to "0.0.0.0"!

3. UiQ - missing access point engine

Unfortunately you will not find a apengine.dll in UiQ’s SDK (nor at the device ). If you want to select or create an IAP you have to use the “raw” CommDB-API - see your SDKs documentation “ How to access tables in the database”.

The SDKs documentation lists all necessary tables with short description of their content, but it’s obscure how they relate to each other. So I’ve created a CommDB-datamodel for Symbian OS 6.1, 7.0 and 7.0s. It’s not perfect , but they will really help you to gain insight.

• CommDB v2 - Symbian OS v6.1
• CommDB v3 - Symbian v7.0
• CommDB v3 - Symbian v7.0s

(cutout)

Legend: Each table and columns have a name(see <cdbcols.h>). E.g. table IAP has a column called COMMDB_ID - it’s the tables primary key (PK). The columns COMMDB_ID and COMMDB_NAME are “default” columns, which you will find nearly at every table. If there’s one or more foreign keys (IAP_SERVICE as FK2, FK3) then you can find this value - normally as primary key - in another table. This relation has as name, e.g. OUTGOING_GPRS_IAP_FK2. A choice have one or more foreign keys (FK2, FK3) to one or more tables. Which table to access is defined in IAP_SERVICE_TYPE (contains the name of the foreign table).

Some example code:

//Get all existing IAPs
    CCommsDatabase* CommDb = CCommsDatabase::NewL(EDatabaseTypeIAP);
    CleanupStack::PushL(CommDb);
    CCommsDbTableView* tableIAP = CommDb->OpenTableLC(TPtrC(IAP));
    if (tableIAP->GotoFirstRecord()==KErrNone)
    {        
       do {
            TUint32 uid(0);
            tableIAP->ReadUintL(TPtrC(COMMDB_ID),uid);
            ...
            tableIAP->ReadTextL(TPtrC(COMMDB_NAME),CommDBNamePtr);
            ...
        }
        while(tableIAP->GotoNextRecord()==KErrNone);
    }
    CleanupStack::PopAndDestroy(tableIAP);
    CleanupStack::PopAndDestroy(CommDb);

4. Symbian Tools

There are some tools available for editing and dumping the CommDB - CEDDUMP, CED, CommDb Editor - Read Symbians FAQ-1071 for more information.


That’s it.
All the best - happy coding

— 
Tobias Stöger

<!--[if !supportEmptyParas]--> <!--[endif]-->