/!\The backed up content of this page is deprecated and will not be included in search results!

Clear message

Information on this page is deprecated. Please, provide future updates through NetworkManager Bugzilla. http://blogs.gnome.org/dcbw/2009/06/22/mobile-broadband-assistant-makes-it-easy/

Service Provider Database

Contents

  1. Service Provider Database
    1. License
  2. How to Contribute
    1. Checkout/Clone
    2. Adding and Updating Information
      1. Add New Country
      2. Add New Service Provider
        1. name
        2. network type
        3. username and password
        4. dns
        5. gateway
    3. Validate
    4. Diff
    5. Contribute
  3. Updating GPRS EC Legacy
  4. Specification
    1. DTD
    2. Elements
      1. serviceproviders
      2. country
      3. provider
      4. name
      5. gsm
      6. apn
      7. username
      8. password
      9. dns
      10. gateway
      11. cdma
  5. Discussion
    1. Example XML file
  6. Service Provider Database
    1. License
  7. How to Contribute
    1. Checkout/Clone
    2. Adding and Updating Information
      1. Add New Country
      2. Add New Service Provider
        1. name
        2. network type
        3. username and password
        4. dns
        5. gateway
    3. Validate
    4. Diff
    5. Contribute
  8. Updating GPRS EC Legacy
  9. Specification
    1. DTD
    2. Elements
      1. serviceproviders
      2. country
      3. provider
      4. name
      5. gsm
      6. apn
      7. username
      8. password
      9. dns
      10. gateway
      11. cdma
  10. Discussion
    1. Example XML file
When you want to configure a mobile broadband connections there usually is some service provider specific information you have to know before the connection can be established. 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 becomes with tie-in 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 it's 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.dtd">

<serviceproviders format="1.0">

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

                <username>bt</username>
                <password>bt</password>
                
                <gateway>212.183.137.12</gateway>
        </provider>
</country>

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

</serviceproviders>

Checkout/Clone

First you have to have an up-to-date copy of the database. Database is stored in a SVN and Git repositories so you need to have subversion or git package installed.

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

$ svn co http://svn.gnome.org/svn/mobile-broadband-provider-info/trunk mobile-broadband-provider-info
or
$ git clone git://git.gnome.org/mobile-broadband-provider-info
$ 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/
$ svn update
or 
$ 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 wish to contribute should join at #mbca on freenode and inform others about their plans. This way people can communicate and collaborate easily.

Add New Country

New country is added like this: 

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

</country>

every country has a mandatory attribute code that is the ISO 3166-1 (lower case) alpha-2 code of the country. If 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 country name in English above <country> element is preferred to be taken from /usr/share/zoneinfo/iso3166.tab.

Add New Service Provider

New service provider information is added between<provider> and </provider> elements. 

        <provider>
                <name>Elisa</name>
                <gsm>
                        <apn>internet</apn>
                </gsm>
        </provider>

Note that there should be different provider declarations for every service provider of the country even if the providers have same settings. Yes, you have to duplicate the information, but it's important that the users see a complete list of providers.

If a service provider owns other providers, but they are marketed separately, list every subprovider as standalone and not like "Provider", "Provider (subprovider1)", "Provider (subprovider2)".

If service provider has multiple subscription models that are marketed separately list them like "Provider", "Provider (alternate model)", etc. Use the same terms and names for subscription models as service providers do with their marketing so that ordinary user who have bought a subscription will recognize the correct one.

Please, keep the providers in sane order.

name

First element is <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 <name> element there must be a network element. Network can be GSM or CDMA based.

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

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

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

If provider is using CDMA based betwork you should add <cdma /> element: 

                <name>Some CDMA Provider</name>
                <cdma />

note the '/'.

username and password

After network element there can be optional <username> and <password> elements if service provider requires generic username and password. 

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

dns

If 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

Gateway can be specified with <gateway> element 

                <gateway>212.183.137.12</gateway>

Validate

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 create an unified diff of your changes, a patch.

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

$ svn update

then make your patch: 

$ svn diff serviceproviders.xml
--- serviceproviders.xml        (revision 2)
+++ serviceproviders.xml        (working copy)
@@ -1063,20 +1063,26 @@
                <dns>217.78.192.78</dns>
        </provider>
        <provider>
+               <name>Elisa</name>
+               <gsm>
+                       <apn>internet</apn>
+               </gsm>
+       </provider>
+       <provider>
                <name>Saunalahti</name>
                <gsm>
                        <apn>internet.saunalahti</apn>

$ svn diff serviceproviders.xml > add_provider_fi_elisa.patch

Give your patch a nice name that describes the changes.

Contribute

When you are happy with your patch send it to <antti AT kaijanmaki DOT net> and he will update the database.

Updating GPRS EC Legacy

Current database is based on GPRS Easy Connect database which stored the service provider names in English. Now the names should be translated to native form of the countries. There is a lot of (pre-paid), (post-paid), etc. postfixed names and some service providers might be already out of business. It would be best if every entry could be checked and removed or updated if necessary. Names and different subscription models should be named as they are locally marketed so that local people recognize them.

Specification

DTD

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

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

<!ELEMENT provider ( name+,
                     (gsm|cdma),
                     username?,
                     password?,
                     dns*,
                     gateway?)>
                     
<!ELEMENT name (#PCDATA)>
<!ATTLIST name xml:lang CDATA #IMPLIED>

<!ELEMENT gsm (apn)>
<!ELEMENT apn (#PCDATA)>

<!ELEMENT cdma EMPTY>

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

Elements

serviceproviders

document root

attribute: format document format version number

country

groups service providers

attribute: code ISO 3166-1 alpha-2 code of the country

the code will be used to localize the country names.

provider

contains data of one service provider

If a service provider has multiple subscription models with different settings each model will have its own provider element.

name

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

if a country has multiple languages there can be multible elements with xml:lang attribute. The first element must not contain the attribute.

gsm

specifies GSM network. network data is needed because GSM modems use *99***<cid># as connection sequence, and cmda uses #777. Different networks also may have different parameters.

apn

specifies the Access Point Name

username

username if any. Service providers use generic usernames.

password

password if any. Service providers use generic passwords.

dns

DNS server address. Of none are specified, DNS servers will be automatically acquired.

gateway

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

cdma

specifies CDMA network.

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

Example XML file

Service Provider Database

Contents

  1. Service Provider Database
    1. License
  2. How to Contribute
    1. Checkout/Clone
    2. Adding and Updating Information
      1. Add New Country
      2. Add New Service Provider
        1. name
        2. network type
        3. username and password
        4. dns
        5. gateway
    3. Validate
    4. Diff
    5. Contribute
  3. Updating GPRS EC Legacy
  4. Specification
    1. DTD
    2. Elements
      1. serviceproviders
      2. country
      3. provider
      4. name
      5. gsm
      6. apn
      7. username
      8. password
      9. dns
      10. gateway
      11. cdma
  5. Discussion
    1. Example XML file
  6. Service Provider Database
    1. License
  7. How to Contribute
    1. Checkout/Clone
    2. Adding and Updating Information
      1. Add New Country
      2. Add New Service Provider
        1. name
        2. network type
        3. username and password
        4. dns
        5. gateway
    3. Validate
    4. Diff
    5. Contribute
  8. Updating GPRS EC Legacy
  9. Specification
    1. DTD
    2. Elements
      1. serviceproviders
      2. country
      3. provider
      4. name
      5. gsm
      6. apn
      7. username
      8. password
      9. dns
      10. gateway
      11. cdma
  10. Discussion
    1. Example XML file
When you want to configure a mobile broadband connections there usually is some service provider specific information you have to know before the connection can be established. 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 becomes with tie-in 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 it's 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.dtd">

<serviceproviders format="1.0">

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

                <username>bt</username>
                <password>bt</password>
                
                <gateway>212.183.137.12</gateway>
        </provider>
</country>

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

</serviceproviders>

Checkout/Clone

First you have to have an up-to-date copy of the database. Database is stored in a SVN and Git repositories so you need to have subversion or git package installed.

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

$ svn co http://svn.gnome.org/svn/mobile-broadband-provider-info/trunk mobile-broadband-provider-info
or
$ git clone git://git.gnome.org/mobile-broadband-provider-info
$ 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/
$ svn update
or 
$ 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 wish to contribute should join at #mbca on freenode and inform others about their plans. This way people can communicate and collaborate easily.

Add New Country

New country is added like this: 

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

</country>

every country has a mandatory attribute code that is the ISO 3166-1 (lower case) alpha-2 code of the country. If 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 country name in English above <country> element is preferred to be taken from /usr/share/zoneinfo/iso3166.tab.

Add New Service Provider

New service provider information is added between<provider> and </provider> elements. 

        <provider>
                <name>Elisa</name>
                <gsm>
                        <apn>internet</apn>
                </gsm>
        </provider>

Note that there should be different provider declarations for every service provider of the country even if the providers have same settings. Yes, you have to duplicate the information, but it's important that the users see a complete list of providers.

If a service provider owns other providers, but they are marketed separately, list every subprovider as standalone and not like "Provider", "Provider (subprovider1)", "Provider (subprovider2)".

If service provider has multiple subscription models that are marketed separately list them like "Provider", "Provider (alternate model)", etc. Use the same terms and names for subscription models as service providers do with their marketing so that ordinary user who have bought a subscription will recognize the correct one.

Please, keep the providers in sane order.

name

First element is <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 <name> element there must be a network element. Network can be GSM or CDMA based.

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

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

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

If provider is using CDMA based betwork you should add <cdma /> element: 

                <name>Some CDMA Provider</name>
                <cdma />

note the '/'.

username and password

After network element there can be optional <username> and <password> elements if service provider requires generic username and password. 

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

dns

If 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

Gateway can be specified with <gateway> element 

                <gateway>212.183.137.12</gateway>

Validate

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 create an unified diff of your changes, a patch.

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

$ svn update

then make your patch: 

$ svn diff serviceproviders.xml
--- serviceproviders.xml        (revision 2)
+++ serviceproviders.xml        (working copy)
@@ -1063,20 +1063,26 @@
                <dns>217.78.192.78</dns>
        </provider>
        <provider>
+               <name>Elisa</name>
+               <gsm>
+                       <apn>internet</apn>
+               </gsm>
+       </provider>
+       <provider>
                <name>Saunalahti</name>
                <gsm>
                        <apn>internet.saunalahti</apn>

$ svn diff serviceproviders.xml > add_provider_fi_elisa.patch

Give your patch a nice name that describes the changes.

Contribute

When you are happy with your patch send it to <antti AT kaijanmaki DOT net> and he will update the database.

Updating GPRS EC Legacy

Current database is based on GPRS Easy Connect database which stored the service provider names in English. Now the names should be translated to native form of the countries. There is a lot of (pre-paid), (post-paid), etc. postfixed names and some service providers might be already out of business. It would be best if every entry could be checked and removed or updated if necessary. Names and different subscription models should be named as they are locally marketed so that local people recognize them.

Specification

DTD

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

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

<!ELEMENT provider ( name+,
                     (gsm|cdma),
                     username?,
                     password?,
                     dns*,
                     gateway?)>
                     
<!ELEMENT name (#PCDATA)>
<!ATTLIST name xml:lang CDATA #IMPLIED>

<!ELEMENT gsm (apn)>
<!ELEMENT apn (#PCDATA)>

<!ELEMENT cdma EMPTY>

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

Elements

serviceproviders

document root

attribute: format document format version number

country

groups service providers

attribute: code ISO 3166-1 alpha-2 code of the country

the code will be used to localize the country names.

provider

contains data of one service provider

If a service provider has multiple subscription models with different settings each model will have its own provider element.

name

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

if a country has multiple languages there can be multible elements with xml:lang attribute. The first element must not contain the attribute.

gsm

specifies GSM network. network data is needed because GSM modems use *99***<cid># as connection sequence, and cmda uses #777. Different networks also may have different parameters.

apn

specifies the Access Point Name

username

username if any. Service providers use generic usernames.

password

password if any. Service providers use generic passwords.

dns

DNS server address. Of none are specified, DNS servers will be automatically acquired.

gateway

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

cdma

specifies CDMA network.

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

Example XML file

NetworkManager/MobileBroadband/ServiceProviders (last edited 2009-06-24 09:26:39 by AnttiKaijanmaki)