This site has been retired. For up to date information, see handbook.gnome.org or gitlab.gnome.org.


[Home] [TitleIndex] [WordIndex] 

Service Provider Database

Contents

  1. Service Provider Database
    1. License
  2. How to Contribute
    1. Checkout/Clone
    2. Adding and Updating Information
      1. Adding a New Country
      2. Adding a New Service Provider
      3. Multiple Access Points (GSM)
    3. Before Submitting Your Changes
    4. Diff
    5. Submit Your Patch
  3. Full XML Specification
    1. Document Type Definition
    2. Elements
      1. serviceproviders
      2. country
      3. provider
      4. name
      5. gsm
      6. network-id
      7. apn
      8. username
      9. password
      10. dns
      11. gateway
      12. cdma
      13. sid
    3. Other Information
  4. Discussion
    1. Example XML file

When you want to configure a mobile broadband connection there usually is some service provider specific information you have to know before the connection can be established. The problem with this information is that it's highly technical for an ordinary consumer and it's available only from service providers web page or from Microsoft Windows installation media that comes with subscription devices.

The interesting side of this information is that it's the same for every user of a given service provider. This means that service provider specific information can be stored in a database. When this database is available the information can be fetched there and the ordinary user does not need to bother about it.

Mobile Broadband Configuration Assistant has its own database. This database is constructed by volunteers from different countries. The volunteers gather service provider specific information of all providers in their country and then add it to the database. After the information is added by even a single contributor all the users of the given country will benefit from that contribution and they will get their connections up and running with ease.

License

The database is released under Creative Commons Public Domain (CC-PD) and every contributor is obligated to accept it. Basically this means that contributors surrender all copyright and other rights they might have to their contributed work and the database can be used by anyone in any way. CC-PD was chosen because the database contains only information that is publicly available and the license doesn't restrict any project from using the database.

How to Contribute

Service provider specific information is stored in a XML file. XML is not the most optimized format for a database, but it's easy to read, understand and edit. Here is an example: 

<?xml version="1.0"?>
<!DOCTYPE serviceproviders SYSTEM "serviceproviders.2.dtd">

<serviceproviders format="2.0">

<!-- Britain -->
<country code="gb">
        <provider>
                <name>BT Mobile</name>
                <gsm>
                        <apn value="btmobile.bt.com">
                                <username>bt</username>
                                <password>bt</password>
                                <gateway>212.183.137.12</gateway>
                        </apn>
                </gsm>
        </provider>
</country>

<!-- Finland -->
<country code="fi">
        <provider>
                <name>DNA</name>
                <gsm>
                        <apn value="internet">
                                <dns>217.078.192.078</dns>
                                <dns>217.078.192.022</dns>
                        </apn>
                </gsm>
        </provider>
</country>

</serviceproviders>

Checkout/Clone

First you have to have an up-to-date copy of the database. Database is stored in a git repository so make sure you have the git package installed.

If this is the first time you want to edit the database you need to checkout the whole repository: 

$ git clone https://gitlab.gnome.org/GNOME/mobile-broadband-provider-info.git
$ cd mobile-broadband-provider-info/

If you already have an earlier version of the repository you have to update it: 

$ cd mobile-broadband-provider-info/
$ git pull

Adding and Updating Information

Edit the database with your favorite editor. Make sure you indent the elements with tabs, not with spaces!

To prevent people from stepping on each others toes and wasting energy by working on the same subject, everyone who wishes to contribute should join the IRC chatroom at #nm on Libera Chat and inform others about their plans. This way people can communicate and collaborate more easily.

Adding a New Country

A new country is added like this: 

<!-- Finland -->
<country code="fi">

</country>

That is, using the <country> tag. Every country has a mandatory attribute code that is the ISO 3166-1 (lower case) alpha-2 code of the country. If the country does not yet have an officially assigned code it can't be added to the database. Countries are sorted by codes. The comment containing the country name in English above <country> (<!-- Finland -->) element is preferably taken from /usr/share/zoneinfo/iso3166.tab.

That's how you begin. After you add a country however, you must also add a service provider.

Adding a New Service Provider

New service provider information is added between<provider> and </provider> elements. The <provider> tag must of course, be inside a <country tag. 

        <provider>
                <name>Elisa</name>
                <gsm>
                        <apn value="internet">
                                <name>Internet</name>
                        </apn>
                </gsm>
        </provider>

Note that there should be different provider declarations for every service provider in the country even if the providers have same settings. It's important that the users see a complete list of providers.

Please, keep the providers in sane order.

Here are the elements that a <provider> tag can contain. That is, the information that you must supply, in order to define a provider.

name

First element should be <name>. It's mandatory. Name will be written in native language and alphabets (latin, cyrillic, etc) of the country. If people of a country use multiple languages there can be multiple <name>elements with different xml:lang attribute. Note: the first element must not contain xml:lang attribute. 

        <provider>
                <name>Some Provider</name>
                <name xml:lang="ru">одна из услуг</name> <!-- http://translate.google.com :) -->

note: xml:lang feature is not intended for l10n junkies who want to translate everything that even remotely resembles letters!

network type

After the <name> tag, there must be a network tag. Network can be either GSM or CDMA based.

If provider is using a GSM based network you should add a <gsm> tag: 

                <name>Some GSM Provider</name>
                <gsm>
                        <apn>internet</apn>
                </gsm>

A GSM tag must contain one <apn> tag that defines the Access Point Name which the service provider uses.

If provider is using CDMA based network you should add a <cdma> tag: 

                <cdma />

note the '/' in the opening tag. It is depends. CDMA networks require less configuration information, and so the corresponding <cdma /> tag may be empty. That is why we need the '/' immediately before the '>'. If the CDMA provider requires a username and password pair for instance, then you need to supply that information. See the following section.

username and password

After the network tag, there can be an optional <username> and <password> tags if the service provider requires a generic username and password. 

                <cdma>
                        <username>uname</username
                        <password>password</password>
                </cdma>

For GSM networks, it should look like this: 

                <gsm>
                        <apn value="access point name">
                                <name>Descriptive Name of this Access point</name>
                                <username>user</username>
                                <password>pass</password>
                        </apn>
                </gsm>

Let us quickly recap what we have covered so far in an example. 

<!-- Finland -->
<country code="fi">
        <provider>
                <name>Provider Name</name>
                <gsm> <!-- this will be <cdma> if this provider was a CDMA network -->
                        <apn value="access point name">
                                <name>Descriptive name of this accesspoint</name>
                                <username>user</username>
                                <password>pass</password>
                        </apn>
                </gsm>
        </provider>

        <provider>
                <name>Provider 2</name>
                <cdma>
                        <username>user</username>
                        <password>pass</password>
                </cdma>
        </provider>
</country>

You should, as shown, include as many <provider> tags in a <country> as are necessary to capture all the service providers in that country.

DNS

Now, if the service provider uses manual DNS servers you can provide them with <dns> elements. 

                <dns>194.170.1.6</dns>
                <dns>194.170.1.7</dns>

If no <dns> element is specified DNS servers are set automatically.

Gateway

The gateway can be specified with the <gateway> tag: 

                <gateway>212.183.137.12</gateway>

DNS and Gateway information should be placed inside the <apn> tag.

Multiple Access Points (GSM)

If a provider has more than one access point (which is often the case in GSM networks, especially for billing purposes), you can and should add them simply by adding more <apn> tags containing the relevant information under the applicable <provider>.

Before Submitting Your Changes

After you have edited the database it must be validated against Document Type Definition, DTD. Validation detects errors on the format of the database. Validation is done using a program named xmllint which is part of libxml. On Ubuntu xmllint part of libxml2-utils package.

if the database is valid xmllint doesn't print anything. 

$ xmllint --noout --valid serviceproviders.xml

Here's an example of error where country has additional attribute foo: 

$ xmllint --noout --valid serviceproviders.xml 
serviceproviders.xml:40: element country: validity error : No declaration for attribute foo of element country
<country code="ae" foo="baa">
                            ^
$

Diff

When you are ready it's time to submit your changes.

First make sure there has been no conflicting changes meanwhile you made yours: 

$ git pull

then commit and make your patch: 

$ git commit

Ensure that the commit has a sensible commit message and subject text. Also make sure that the author of the patch is you.

Submit Your Patch

When you are happy with your patch, fork the repository on gitlab and create a merge request (you will get a link when you git push to your fork). It will be reviewed and committed in due course.

Full XML Specification

Document Type Definition

<!ELEMENT serviceproviders (country*)>
<!ATTLIST serviceproviders format CDATA #REQUIRED>

<!ELEMENT country (provider*)>
<!ATTLIST country code CDATA #REQUIRED>

<!ELEMENT provider (name+, gsm?, cdma?)>

<!ELEMENT gsm (network-id*, apn+)>
<!ELEMENT apn (name*,
               gateway?,
               username?,
               password?,
               dns*)>
<!ATTLIST apn value CDATA #REQUIRED>

<!ELEMENT network-id EMPTY>
<!ATTLIST network-id mcc CDATA #REQUIRED>
<!ATTLIST network-id mnc CDATA #REQUIRED>

<!ELEMENT username (#PCDATA)> 
<!ELEMENT password (#PCDATA)>
<!ELEMENT dns (#PCDATA)>
<!ELEMENT gateway (#PCDATA)>

<!ELEMENT cdma (name*,
                username?,
                password?,
                dns*,
                sid*)>

<!ELEMENT sid EMPTY>
<!ATTLIST sid value CDATA #REQUIRED>

<!ELEMENT name (#PCDATA)>
<!ATTLIST name xml:lang CDATA #IMPLIED>

Elements

serviceproviders

This is the document root. It can contain any number of the country element.

attribute: The format attribute of this element holds the document format version number. Currently, this should have the value "2.0".

country

Groups service providers by country.

attribute: The code attribute holds the ISO 3166-1 alpha-2 code of the country. The code will be used to localize the country names.

provider

Contains all the configuration data of one service provider. It should contain a <name> and either of <gsm> or <cdma> tags which encapsulate the configuration information.

name

The name of the service provider. Name should be written in the native language and alphabets of the country.

The <name> tag is also applicable to the cdma and apn elements and means roughly the same thing.

gsm

Specifies the network-type as GSM, and provides for the ability to supply the configuration information that GSM networks typically need. Network data is needed because GSM modems use *99***<cid># as connection sequence, and cmda uses #777. Different networks also may have different parameters.

network-id

Allows to provide the MCC and MNC for a GSM network. Include as many of this element as are needed to capture all the codes that a particular network may have. [todo: explain this better]. It is an empty element, so the opening tag must be closed with a '/' before the usual '>'. Like this:  <network-id mcc="000" mnc="00" /> 

attributes: network-id has two mandatory attributes. mnc and mcc.

apn

Specifies the Access Point Name. attribute: value holds the access point name as required by the network.

The name element can be used within the apn tag to provide a user-visible "description" for the access point.

username

username if any. Service providers often use generic usernames. Only valid inside apn or cdma.

password

password if any. Service providers often use generic passwords. Only valid inside apn or cdma.

dns

DNS server address. Of none are specified, DNS servers will be automatically acquired. Use multiple dns elements if more than one DNS servers are required.

gateway

Gateway address. if none is specified, will be automatically acquired.

cdma

specifies CDMA network.

sid

[please document]

Other Information

The easiest way to understand the XML schema described above is to read the serviceproviders.xml file inside the repository you checked out. Look at any particular country's information and model your entries or modifications to after it.

Discussion

'''TODO:'''
 *[[http://euc.jp/misc/cellphones.en.html#phs | PHS]]..? [[http://en.wikipedia.org/wiki/Personal_Handy-phone_System|wikipedia]]

Can be added later should users emerge. AnttiKaijanmaki


 *XML information is not updated with changes of <serviceproviders format="2.0">. The information is for <serviceproviders format="1.0">

Example XML file

2024-10-23 11:37