Configuring Comms Database For Network Connections

This section explains how to configure Comms database for network connections over any kinds of data communications technology. Specifically, it explains the structure of the Comms database and how to configure the database to support specific network connections.

Symbian OS maintains a database of communications related configuration settings. This database is called Comms database and is always available on any Symbian platform.

The Comms database is accessed and manipulated by various tools and applications that need to manage voice or data transmissions using any kind of network technology. The comms database contains the necessary network configuration data for managing any kind of data connection over any kind of network. For example, to configure a modem you need to set fields such as

Name=DefaultModem
PortName=COMM::0
DataBits=8
StopBits=1
Parity=NONE
Rate=115200

You can manage the database statically using the command line tools CED and CEDDUMP or dynamically by using the CommsDat API.

For information about the mechanics of configuring the Comms databse using CED and CEDDUMP tools refer to Configuring comms database using CED and CEDDUMP.

Comms databse is a set of tables, each containing records and fields. Each table is identified by its name such as GlobalSettings, ModemBearer, IncomingGPRS and a corresponding numeric ID.

The CEDDUMP command line tool generate an image of the current comms database in configuration file format. A sample extract of one record in the LocationTable is shown below.

[Location]
ADD_SECTION
#COMMDB_ID=1
    Name= Direct Dial from Office in UK
    IntlPrefixCode=00
    NatPrefixCode=0
    NatCode=44
    AreaCode=207
    Mobile=FALSE
    UsePulseDial=FALSE
    WaitForDialTone=FALSE
    PauseAfterDialout=0
    FIELD_COUNT=9
END_ADD

The numeric ID is the record number of each table and it is not visible in the configuration file. Comments start with a # in column 1 of a line.

Tables may contain 0,1 or more records called as sections in the CED and CEDUMP. A new record to a table can be added as a new section in the configuration file. Each record in a table is identified by its name (i.e., the value of its Name field). Each record in a table is also identified by its record number: the first record added to a table is number 1, the second record is number 2, etc.

The configuration file can be used in two formats, CFG format and XML format.

For information on the file formats supported by CED and CEDDUMP refer to Comms database configuration file format.

CFG format

In CFG format, records in other tables are referenced using the record number and not the Name field.

[Location]
#>> This is the first record added. Therefore, it is record 1.
ADD_SECTION
#>> When CEDDUMP generates a configuration file from the database,
#>> it shows the record number as a comment:
# COMMDB_ID = 1
#>> **WARNING** If the configuration file is edited, the #COMMDB_ID
#>> may be incorrect
    Name= Direct Dial from Office in UK
    IntlPrefixCode=00
    [...]
END_ADD

[IAP]
ADD_SECTION
    Name=CSD: From UK location, dial out to an ISP using a Modem
    [...]
#>> Use Location tables’s record number 1
    Location=1
    [...]
END_ADD

NOTE: Comments beginning with #>> were added as part of this documentation.

XML format - (Recommended format)

In XML format a record from one table will contain a field that refers to a record from another table by latter's record name. In other words, the record name is used as a key. This gives the flexibility to the developers when using many records, hence XML format is recommended.

<LocationTable>
    <Location>
        <Name>Direct Dial from Office in UK</Name>
        #Name of this record
        <IntlPrefixCode-00>
        ...
        ... 
    </Location>
</LocationTable>

<IAPTable>
    <IAP operation ="add">
        <Name>CSD: From UK location, dial out to an ISP using a Modem</Name>
        <LocationRef>Location.Direct Dial from Office in UK</LocationRef>
    # In this format the reference to Location Table is specified as "Location.Direct Dial from office in UK"
        ...
        ...
    </Location>
</LocationTable>

NOTE: Comments beginning with # were added as part of this documentation.

Each table in the Comms database has a corresponding class in the COMMSDAT API. To identify tables, application developers use the constant defined for each table’s numeric ID, e.g., KCDTIdGlobalSettingsRecord, KCDTIdModemBearerRecord, KCDTIdIncomingGprsRecord. Refer to CommsDat API documentation for a complete list of classes and constants.

• Use CEDDUMP to generate an image of the current Comms database in CFG format

• Edit the configuration file to meet your requirements

• Use the configuration file as input to the CED command-line tool to generate a new Comms database

• The configuration file can also be used to append to an already existing Comms database

CED and CEDDUMP are often used as part of test procedures: to test a certain feature, you generate an appropriate Comms database, then you run the test script.

The following are some commonly used tables for making a data connection.For reference documentation on all fields in the public tables in Comms database refer to Comms Database Reference.

The diagram below shows the relationship among a subset of tables. These tables are the ones required for a CSD connection to an ISP and for PSD connections

Notice the central role of the IAP table. You can think of it as a table of network connection definitions. For example, for a connection to a specified internet provider, your wireless device must

• Dial a telephone number specified in a record in DialOutISP

• Use the dialling rules (area code, country code…) specified in a record in Location

• Use the IP address specified in a record in one of the Service tables (LANService, DialOutISP...)

• Use the modem specified by a record in ModemBearer

A record in the IAP table defines a specific network connection by specifying the Location, the Network, the Service and the Bearer. Here are the rules:

• For the dialling rules, specify a particular record number (shown as <n> in the diagram) in the Location table

• For the Network, specify a particular record number in the Network table

• For the Service, specify:

  The name of the service to use i.e., the name of one of the tables in the Services box. In our example, the service is DialOutISP.

  The number of the record in that table, i.e., the record referring to a particular ISP

• For the Bearer specify

  The name of the bearer to use i.e., the name of one of the tables in the Bearers box. In our example, the bearer is ModemBearer

  The name of the record in the specified table, i.e., the record referring to a particular model of modem.

The other tables play a key role in any network connection. The application's choice of IAP is determined by the record in the ConnectionPreferences table. The ConnectionPreferences table specifies whether to prompt the user with dialogs to choose the IAP and if not then use the preferred IAP specified in a ConnectionPreferences record.

GlobalSettings table contains only one record, with settings that are global to the Symbian OS device as a whole.

The Comms database can be used to configure any kind of network connection that is supported by Symbian OS and the wireless device. The following are some common use cases:

• Configuring Comms Database For Circuit Switched Data Cconnections

• Configuring Comms Database For Ethernet Connections

• Configuring Comms Databse For Packet Switched Data Connections

• Configuring Comms Database For VPN Connections

Comms Database Reference Table