Navigation

Views

The Maemo connectivity subsystem is implemented by using known Linux conventions. It resides in the user space of Linux, and relies on the Linux kernel through standard C libraries. GPRS or WLAN is the main channel to the Internet. The Bluetooth software of Maemo is based on BlueZ, which is known as the de-facto implementation of Bluetooth for Linux. D-Bus is used for internal application level message exchange.

Even though the connectivity device drivers are closely related to this subsystem, they are considered to be outside of the scope of this manual.

The central concept for maemo Internet connections is the Internet Access Point (IAP), which represents a logical Internet (IP) connection that the user defines. An IAP has a unique name, usually in form of UUID). Among other things, it defines the radio bearer (e.g. WLAN, GPRS), and usually also the data transfer speed, username, password, proxy server, and the corresponding access point in the Internet or the telephone number of the service provider's modem.

This section describes the system decomposition of the Connectivity subsystem. Maemo applications can open Internet connections by using the LibConIC API. The Internet Access subsystem take care of the connection to the phone, if necessary, by using the services of the Phone Access subsystem. If an application needs to gain access to the phone's files, the File selector consults the Phone Access subsystem.

Phone Access is the subsystem handling connections to a cellular phone. It offers a search utility for finding potential phones and inquiring the services they can offer. This is based on the standard Bluetooth service discovery mechanism. Phone Access also keeps a record of phones that have connected to the device in GConf, and provides a list of them for the user to choose from. Phone Access relies on the Linux Bluetooth implementation called BlueZ. BlueZ offers the Berkeley socket interface to the HCI and to the L2CAP protocol for the user space applications.

In principle, any cellular phone supporting Bluetooth Service Discovery Protocol (SDP) and File Transfer Profile (FTP) can connect to Maemo. However, different mobile phones implement varying levels of file transfer services and OBEX. Some products limit access to the Inbox (Object Push), whereas more sophisticated ones make the Gallery and the memory card available. The recent products support the OBEX Capability request for retrieving more specific information about the file system on the phone.

Maemo connects to a phone on an on-demand basis, such as when an application requires a connection. For example, when the Internet browser is about to open a URL, it requests Phone Access to establish a connection to the phone. This causes Phone Access to bind an RFCOMM device to the requested service on the phone. In a similar fashion, the File Selector can set up a file transfer connection to the phone using another RFCOMM device. After binding to a service, the application in question can open the local RFCOMM device. Normal file selector access is performed with GnomeVFS layer to get transparent access to phone in the same way as internal flash and MMC are accessed.

Name

General Bluetooth UI

Purpose

User interface for managing all paired BT devices

Responsibilities and additional requirements

Keeping a list of all paired devices (not only phones)

Concurrent usage

N/A

Name

BT search

Purpose

Searches for available Bluetooth devices

Responsibilities and additional requirements

Bluetooth inquiry

Checking on offline mode state

Concurrent usage

N/A

Name

BT service discovery

Purpose

Checks if a found Bluetooth device is sufficient

Responsibilities and additional requirements

Bluetooth service discovery (SDP)

Concurrent usage

Not limited (but used by Phone selection UI and Phone connection daemon only)

Name

GW OBEX library

Purpose

Provides access to OpenOBEX library for the File selector (Gnome VFS) on a higher abstraction level than OpenOBEX itself supports

The Internet Access subsystem manages connections to the Internet over different bearers and is also responsible for the configuration and management of Internet Access Points. Internet Access provides applications with TCP/IP connections. They can be established in the following ways:

WLAN connection to a wireless access point.

Bluetooth connection through phone using Point-to-Point Protocol (PPP) and a cellular modem (in the phone).

For Bluetooth connections, AT commands are applied to establish a PPP link to the cellular modem and the connection to the Internet.

Name

IC daemon

Purpose

IC daemon establishes Internet connections over different bearers.

Responsibilities and additional requirements

Controlling that only one Internet connection (one active IAP) can exist at any given time

Using WLAN or GPRS connection daemon for getting a network device and getting the connection authenticated

This section describes how the Internet Connectivity daemon works internally. The following subsections explain the behavior and the decomposition of this component in detail, also covering the interfaces that this component realizes.

If the ICd receives a request to activate or deactivate an IAP, the ICd activates the IAP or, if no IAP has been defined as the default, shows a uI requesting the user to choose one. Depending on the type of the IAP, the ICd uses the appropriate network type plug-in to activate or deactivate specific network interface.

The ICd tracks the applications requesting IAPs by recording their D-Bus base service names. This allows the ICd to detect situations where processes using an IAP have aborted or crashed.

Maemo version 3.0 introduced the automatic connection creation feature in the Internet Connectivity Daemon. In other words, the device tries to connect automatically to the saved IAPs, and keep connected as long as possible. With this feature, applications like e-mail and RSS reader are always up to date. The device is also always ready for online use, for example, incoming VoIP calls or IM chat. In earlier versions, the Internet connection was automatically closed if no application was using it or when the connection was idle for the period of time defined by the idle timeout configuration parameter.

When the device is not connected, it scans for saved IAPs and tries to connect automatically, taking into account the value defined by the search interval configuration parameter. The search interval can be 5, 10, 30 or 60 minutes; all other values are automatically mapped to "Never". This setup switches off the automatic connection feature. In this case, the device behaves just like the former versions: Connections are created only when applications require it.

Because each application keeps its data updated and provides the always-online feature, the ICd is only responsible for creating connections.

While writing an application making use of the ICd system, keep the following in mind:

The application must always use the existing available connection.

As in former versions, if the device is not connected but a connection is required by user interaction, the application must require connection creation using LibConIC API.

Ensure that the user is aware of updates and can see the time when the data was last updated.

Ensure that the application registers via LibConIC and listens to signals emitted by the ICd (Connection Created, Lost and Changed), and react as follows:

Connection Created: Use the connection and update all data.

Connection Lost: Go to an idle state silently and wait until a new connection is created.

Connection Changed: Use the new connection.

Ensure that automatic data updates run in background and silently:

Avoid alarming the user with unnecessary banners or dialogs.

Ensure that usernames and passwords are saved so that automatic updates can be performed without prompts.

During and after updates, ensure that no failures display error notifications.

The connectivity infrastructure must take care of error situations in a centralized way.

You can switch off the automatic connection creation feature by using offline mode. While in this mode, the configuration parameter for allowing WLAN in offline mode is checked. Depending on the state of this configuration parameter, WLAN IAPs are either enabled or disabled in the offline mode. Also other radios like Bluetooth are normally disabled in the offline mode.

For connecting to a WLAN, the ICd needs to associate with the network as well as enable EAP authentication and the DHCP client as needed. Independently of whether an active IAP using WLAN exists, the requested WLAN network is first scanned to ensure that it is available. If the requested network is found and the current IAP is using WLAN, the current IAP is deactivated. WLAN is activated according to the following procedure:

If the network requires EAP authentication, the EAP authentication procedure is started. While performing the EAP authentication, the EAP software may show GUI dialogs relating to the EAP authentication procedure. When EAP authentication is complete, the EAP software sets security keys for the WLAN network, resulting in state change messages from wlancond. The ICd receives these messages but ignores them and waits for the reply from EAP authentication instead. If the EAP authentication fails, the ICd aborts with a D-Bus error message.

After the EAP process starts, the ICd instructs wlancond to associate with the WLAN network. Any static security settings relating to pre-shared security keys are also supplied at this point. If it cannot establish a connection to the WLAN network, the ICd aborts with an error.

Because the DHCP client is a stand-alone program, start it by using exec if the WLAN IAP requires dynamic IP address acquisition. When the DHCP client has obtained an IP address, it configures IP-related parameters, and sends a D-Bus signal to the ICd. If it cannot obtain the IP address lease, the ICd times out, stops the DHCP client and aborts with a D-Bus error message.

Internet Connectivity API (in shorter form: Libconic) is an API for applications to manage internet connections on Maemo devices. It was introduced in the first IT OS 2007 release, deprecating the old OSSO IC API (osso-ic-lib). OSSO IC API was conclusively removed in the IT OS 2008 release. For more information on libconic interfaces, see Internet Connectivity API

Libconic is high level and stable object-oriented API suitable for the following purposes:

Before applications can use the Libconic API, they must meet the following requirements:

use non-blocking sockets

have the system D-Bus running

g_type_init() has to be called

employ no threading support in the Libconic API

If the application is a standard Hildon application, almost all of these requirements are already fulfilled. LibOSSO context initialization connects the application to both session and system D-Bus buses, g_type_init() is called as a part of gtk_init(), and probably no extra threads are used.

Blocking sockets cannot be used because that would also block incoming Connectivity events. Non-blocking sockets should be used in order to receive the events properly. For example, GLib IO Channels with the G_IO_FLAG_NONBLOCK flag provide non-blocking way to use sockets.

With threads, blocking sockets can be used, although Libconic API itself is not thread safe.

Libconic API uses internally system D-Bus for delivering messages to the Connectivity components. Applications must be running normal D-Bus dispatch, watch and timeout monitoring before using the Libconic API. If the GLib mainloop is used, this can be accomplished with dbus_connection_setup_with_g_main().

LibConIc is an asynchronous connection API, which heavily relies on GObject signals. Basically this means that GMainloop must be iterated in order to successfully execute connection requests. After the application is set up, use a ConIcConnection object to request a connection:

At this point, the application does not yet have an Internet connection. A successful return from con_ic_connection_connect() means only that the request was successfully dispatched to the Internet Connectivity daemon. When the daemon has a connection ready, the application receives an event (as an GObject signal) indicating that the device is connected. If the connection attempt fails, the application receives a disconnected event with an error describing the reason for the failure.

The connection handler (my_connection_handler() function registered in the previous snippet) could look like this:

Sometimes the application does not actively start connections but needs to detect if the device is online. The Libconic "automatic events" feature, enabled with the automatic-connection-eventsGObject property, can achieve this:

When automatic events are turned on, the application receives connected and disconnected events for all Internet connection changes. In addition to this, the application receives an event for the initial connection status. If the device is disconnected, ConIcConnectionEvent with status CON_IC_STATUS_DISCONNECTED is emitted. This event has NULL IAP ID and bearer, because there is no IAP getting disconnected, but the event indicates that the device is offline.

N.B. The main loop must be iterated in order to receive the event. If you need the connection status information synchronously, you can iterate the main loop yourself:

To receive statistics of the current Internet connection, use the con_ic_connection_statistics() function and the corresponding event handler. You can retrieve statistics for a specified IAP or just for the current default connection. Note that currently the Internet Connectivity daemon provides only one Internet connection at a time, so the best option is to leave IAP ID NULL.

Libconic allows you to set up Internet connection proxy settings for various protocols. The first step is to discover the current proxy mode by using the con_ic_connection_get_proxy_mode() function. Next, use the following functions to get the actual proxy settings:

If proxy mode is CON_IC_PROXY_MODE_NONE, do not use any proxies.

If proxy mode is CON_IC_PROXY_MODE_MANUAL, use the following functions to query proxy settings:

con_ic_connection_get_proxy_host() to get the proxy host

con_ic_connection_get_proxy_port() to get the proxy port

con_ic_connection_get_proxy_ignore_hosts() to get a list of hosts for which the proxy should not be used.

If proxy mode is CON_IC_PROXY_MODE_AUTO, use con_ic_connection_get_proxy_autoconfig_url() to get a proxy auto configuration URL.

To query all user-saved connections (IAPs), use the con_ic_connection_get_all_iaps() function. The function returns simply a singly linked list of ConIcIap objects:

/* ConIcConnection object named "connection" has already been created */
GSList *saved_iaps = con_ic_connection_get_all_iaps(connection);
g_debug("The following connections have been saved by the user:");for(GSList *iter = saved_iaps; iter != NULL; iter = g_slist_next(iter)){/* Get IAP object and print some information about it */
ConIcIap *iap =(ConIcIap *)iter->data;
g_debug("Connection %s called '%s' using bearer %s",
con_ic_iap_get_id(iap), con_ic_iap_get_name(iap),
con_ic_iap_get_bearer_type(iap));/* We unref the IAP object as we are not going to use it anymore */
g_object_unref(iap);}
g_slist_free(saved_iaps);

In this example, ctx->rfcomm_dev points to a string containing the device node name (e.g. /dev/rfcomm0). ctx->use_ftp dictates whether to set up standard folder browsing services. If use_ftp is untrue, then INBOX is connected.

The LibOpenOBEX library implements a generic OBEX Session Protocol, but not the OBEX Application Framework. OBEX is a protocol designed to allow data interchanging between different kinds of connections (e.g. Bluetooth, IrDA). For more information on the OBEX protocol, see http://www.irda.org; select the Developer->Specifications category. OBEX resembles the HTTP protocol, expect for a few differences:

Transports: While HTTP is normally layered above a TCP/IP connection, OBEX is usually transported over IrLAP/IrLMP/Tiny TP (on IrDA) or over Baseband/Link Manager/L2CAP/RFCOMM (on Bluetooth).

Binary transmissions: OBEX communicates using binary transmissions, as HTTP is transmitted in a human-readable XML-based format.

Session support: HTTP is stateless, while OBEX maintains the connection.

Connectivity UI contains various dialogs and other components used to control the connectivity. The different UI parts are:

Connectivity UI

Connectivity dialogs

Status bar applets

Control panel applet

Bluetooth UIs

The connectivity dialogs are invoked by D-Bus method calls, so for example the ICd is using these D-Bus method calls for showing dialogs when they are needed. The next section specifies the D-Bus API of Maemo connectivity UI.

Shows server certificate error and expiration dialogs. If both boolean arguments are false, the error dialog is shown. If either or both boolean arguments are TRUE, the expiration dialog is shown instead.