Maemo Wiki Mirror - User contributions [en]

Documentation/Maemo 5 Developer Guide/Using Connectivity Components/Maemo Connectivity

2010-01-27T11:25:15Z

80.242.16.1: /* LibConIC Library */

= Maemo Connectivity =

==Introduction==
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.

===Components of the maemo connectivity architecture===
'''Maemo connectivity UI''' - User Interface parts of the connectivity. This includes Control Panel applets and several different dialogs.

'''Maemo connectivity daemon (ICd)''' - [http://maemo.org/api_refs/5.0/beta/libconic/ LibConIC] API works together with [http://maemo.org/api_refs/5.0/beta/icd2/ ICd], handling all Internet Access Points (IAPs). IC daemon handles both WLAN and GPRS connections.

'''OBEX wrapper''' - Interface to OBEX services. The primary target user of this library is the OBEX gnome-vfs module.

'''OpenOBEX''' - Open source implementation of the Object Exchange (OBEX) protocol. For more information on OpenOBEX, visit http://triq.net/obex/

'''BlueZ Bluetooth stack''' - The de-facto implementation of Bluetooth for Linux. For more information on BlueZ, visit [http://www.bluez.org/ http://www.bluez.org]

'''[http://git.kernel.org/?p=bluetooth/bluez.git;a=tree;f=doc;hb=HEAD BlueZ D-Bus API]''' - BlueZ accepts commands via D-Bus.

'''WLAN connectivity daemon''' - The daemon controlling WLAN connections.

'''WLAN device driver''' - mac80211 from Linux and wl12xx driver implemented by Nokia, licensed under GPLv2.

===Internet Access Points (IAP)===
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.

==Connectivity Subsystem ==
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.

In offline mode, none of the radios must be active. The Device System Management Entity (DSME) of maemo provides information about the transitions to and from the offline mode.

<div align="CENTER">

{| border="1" cellpadding="3"
| width="100" align="LEFT" valign="TOP" | Name
| width="350" align="LEFT" valign="TOP" | Connectivity UI
|-
| width="100" align="LEFT" valign="TOP" | Purpose
| width="350" align="LEFT" valign="TOP" | Provides the UI for managing phone and Internet connections. Available as a Control Panel applet, and from the Status Bar.
|-
| width="100" align="LEFT" valign="TOP" | Responsibilities and additional requirements
| width="350" align="LEFT" valign="TOP" |
* Displaying active connections with statistics
* Updating status indicators
* Providing dialogs for changing and disconnecting connections
|-
| width="100" align="LEFT" valign="TOP" | Concurrent usage
| width="350" align="LEFT" valign="TOP" | (N/A)
|}

 

{| border="1" cellpadding="3"
| width="100" align="LEFT" valign="TOP" | Name
| width="350" align="LEFT" valign="TOP" | Phone Access
|-
| width="100" align="LEFT" valign="TOP" | Purpose
| width="350" align="LEFT" valign="TOP" | Provides connections to phones with different Bluetooth profiles
|-
| width="100" align="LEFT" valign="TOP" | Responsibilities and additional requirements
| width="350" align="LEFT" valign="TOP" |
* Searching for phones and inquiring their services
* Keeping phone register
* Providing status of the phone connections for Connectivity UI
* Binding RFCOMM devices to Bluetooth services on the phone
* Providing easy access to OpenOBEX
|-
| width="100" align="LEFT" valign="TOP" | Concurrent usage
| width="350" align="LEFT" valign="TOP" | Number of clients not limited by maemo. However, some phones may not support more than one Bluetooth profile at a time.
|}

 

{| border="1" cellpadding="3"
| width="100" align="LEFT" valign="TOP" | Name
| width="350" align="LEFT" valign="TOP" | Internet Access
|-
| width="100" align="LEFT" valign="TOP" | Purpose
| width="350" align="LEFT" valign="TOP" | Provides Internet connections over different bearers.
|-
| width="100" align="LEFT" valign="TOP" | Responsibilities and additional requirements
| width="350" align="LEFT" valign="TOP" |
* Providing means for configuration and management of IAP settings
* Providing API for Internet connections over different bearers (e.g. WLAN, GPRS)
* Providing status of Internet connections for Connectivity UI
|-
| width="100" align="LEFT" valign="TOP" | Concurrent usage
| width="350" align="LEFT" valign="TOP" | Number of clients not limited, but only one connection to the Internet can exist at any given time
|}

</div>

Phone and Internet connections are quite different by nature and behavior. These are introduced in more detail in the following sections.

===Phone Access ===
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.

<div align="CENTER"></div><div align="CENTER">

{| border="1" cellpadding="3"
| width="100" align="LEFT" valign="TOP" | Name
| width="350" align="LEFT" valign="TOP" | General Bluetooth UI
|-
| width="100" align="LEFT" valign="TOP" | Purpose
| width="350" align="LEFT" valign="TOP" | User interface for managing all paired BT devices
|-
| width="100" align="LEFT" valign="TOP" | Responsibilities and additional requirements
| width="350" align="LEFT" valign="TOP" |
* Keeping a list of all paired devices (not only phones)
|-
| width="100" align="LEFT" valign="TOP" | Concurrent usage
| width="350" align="LEFT" valign="TOP" | N/A
|}

 

{| border="1" cellpadding="3"
| width="100" align="LEFT" valign="TOP" | Name
| width="350" align="LEFT" valign="TOP" | BT search
|-
| width="100" align="LEFT" valign="TOP" | Purpose
| width="350" align="LEFT" valign="TOP" | Searches for available Bluetooth devices
|-
| width="100" align="LEFT" valign="TOP" | Responsibilities and additional requirements
| width="350" align="LEFT" valign="TOP" |
* Bluetooth inquiry
* Checking on offline mode state
|-
| width="100" align="LEFT" valign="TOP" | Concurrent usage
| width="350" align="LEFT" valign="TOP" | N/A
|}

 

{| border="1" cellpadding="3"
| width="100" align="LEFT" valign="TOP" | Name
| width="350" align="LEFT" valign="TOP" | BT service discovery
|-
| width="100" align="LEFT" valign="TOP" | Purpose
| width="350" align="LEFT" valign="TOP" | Checks if a found Bluetooth device is sufficient
|-
| width="100" align="LEFT" valign="TOP" | Responsibilities and additional requirements
| width="350" align="LEFT" valign="TOP" |
* Bluetooth service discovery (SDP)
|-
| width="100" align="LEFT" valign="TOP" | Concurrent usage
| width="350" align="LEFT" valign="TOP" | Not limited (but used by Phone selection UI and Phone connection daemon only)
|}

 

{| border="1" cellpadding="3"
| width="100" align="LEFT" valign="TOP" | Name
| width="350" align="LEFT" valign="TOP" | GW OBEX library
|-
| width="100" align="LEFT" valign="TOP" | Purpose
| width="350" align="LEFT" valign="TOP" | Provides access to OpenOBEX library for the File selector (Gnome VFS) on a higher abstraction level than OpenOBEX itself supports
|-
| width="100" align="LEFT" valign="TOP" | Responsibilities and additional requirements
| width="350" align="LEFT" valign="TOP" |
* Handling OBEX requests
|-
| width="100" align="LEFT" valign="TOP" | Concurrent usage
| width="350" align="LEFT" valign="TOP" | Not limited
|}

 

</div><div align="CENTER"></div>

Maemo Bluetooth also supports HID (keyboard) and OPP (object push file transfer) profiles.

===Internet Access ===
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.

<div align="CENTER"></div><div align="CENTER">

{| border="1" cellpadding="3"
| width="100" align="LEFT" valign="TOP" | Name
| width="350" align="LEFT" valign="TOP" | IC daemon
|-
| width="100" align="LEFT" valign="TOP" | Purpose
| width="350" align="LEFT" valign="TOP" | IC daemon establishes Internet connections over different bearers.
|-
| width="100" align="LEFT" valign="TOP" | Responsibilities and additional requirements
| width="350" align="LEFT" valign="TOP" |
* 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
* Starting IP level services like PPP and DHCP
* Providing statistics about the usage of IAPs to any application
|-
| width="100" align="LEFT" valign="TOP" | Concurrent usage
| width="350" align="LEFT" valign="TOP" | Has multiple clients and limits the connections to one at a time
|}

 

{| border="1" cellpadding="3"
| width="100" align="LEFT" valign="TOP" | Name
| width="350" align="LEFT" valign="TOP" | Internet Connectivity GUI
|-
| width="100" align="LEFT" valign="TOP" | Purpose
| width="350" align="LEFT" valign="TOP" | Has GUI applications for configuring Internet Access Points and WLAN settings.
|-
| width="100" align="LEFT" valign="TOP" | Responsibilities and additional requirements
| width="350" align="LEFT" valign="TOP" |
* Providing the UI for configuring an IAP
* Providing the UI for WLAN settings
* Scanning for available WLAN networks (on request)
* Saving IAP and WLAN settings (excluding EAP settings) to GConf
* Opening up dialogs and displaying notifications
|-
| width="100" align="LEFT" valign="TOP" | Concurrent usage
| width="350" align="LEFT" valign="TOP" | N/A
|}

 

{| border="1" cellpadding="3"
| width="100" align="LEFT" valign="TOP" | Name
| width="350" align="LEFT" valign="TOP" | WLAN connection daemon
|-
| width="100" align="LEFT" valign="TOP" | Purpose
| width="350" align="LEFT" valign="TOP" | Manages WLAN network connections
|-
| width="100" align="LEFT" valign="TOP" | Responsibilities and additional requirements
| width="350" align="LEFT" valign="TOP" |
* Starting WLAN driver with the settings provided; stopping WLAN
* Requesting authentication when necessary
* Relaying WLAN IAP settings from IC daemon to WLAN drivers and authentication requests to EAP
* Relaying WLAN events from WLAN drivers
* Providing WLAN status information
|-
| width="100" align="LEFT" valign="TOP" | Concurrent usage
| width="350" align="LEFT" valign="TOP" | Not limited
|}

 

{| border="1" cellpadding="3"
| width="100" align="LEFT" valign="TOP" | Name
| width="350" align="LEFT" valign="TOP" | EAP UI
|-
| width="100" align="LEFT" valign="TOP" | Purpose
| width="350" align="LEFT" valign="TOP" | User interface for EAP authentication
|-
| width="100" align="LEFT" valign="TOP" | Responsibilities and additional requirements
| width="350" align="LEFT" valign="TOP" |
* Invoking a dialog for an authentication password
* Showing authentication status
|-
| width="100" align="LEFT" valign="TOP" | Concurrent usage
| width="350" align="LEFT" valign="TOP" | N/A
|}

 

{| border="1" cellpadding="3"
| width="100" align="LEFT" valign="TOP" | Name
| width="350" align="LEFT" valign="TOP" | EAP
|-
| width="100" align="LEFT" valign="TOP" | Purpose
| width="350" align="LEFT" valign="TOP" | Provides WLAN security excluding basic WEP settings, which are in Wireless Extensions
|-
| width="100" align="LEFT" valign="TOP" | Responsibilities and additional requirements
| width="350" align="LEFT" valign="TOP" |
* Taking care of the authentication process for the active IAP
* Delivering progress events to IC daemon
* As a special case, controlling the EAP-SIM authentication using the SIM Access Profile
* Providing authentication status
|-
| width="100" align="LEFT" valign="TOP" | Concurrent usage
| width="350" align="LEFT" valign="TOP" | N/A
|}

 

</div><div align="CENTER"></div>

==Internet Connectivity Daemon ==
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.

===Decomposition ===
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'''<nowiki>: Use the connection and update all data. </nowiki>
** '''Connection Lost'''<nowiki>: Go to an idle state silently and wait until a new connection is created. </nowiki>
** '''Connection Changed'''<nowiki>: Use the new connection. </nowiki>
* 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.

=== WLAN ===
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.

==LibConIC Library ==
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 [http://maemo.org/api_refs/5.0/5.0-final/libconic/index.html Internet Connectivity API]

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

* requesting Internet connection
* listening for Internet connection status events
* receiving statistics of Internet connection
* getting proxy settings for the current connection
* getting a list of user-saved connections (IAPs)

 
'''Application Requirements'''
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.

'''Non-Blocking Sockets'''
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.

'''System D-BUS'''
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()''.

N.B. Setting up LibOSSO context connects the application to required D-BUS.

'''GType'''
Libconic API is GObject-basedm, so in order to get the API working, you must initialize GLib's GType properly. To do that, use ''g_type_init()''.

'''No Multiple Threads'''
Libconic API is not thread-safe. If the applications have threads, use Libconic API only from the same context where GMainloop is running.

===Libconic Usage ===

==== Requesting for Connection ====
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:

<tt> gboolean success <nowiki>=</nowiki> FALSE<nowiki>;</nowiki>
''/* Create connection object */''
ConIcConnection <nowiki>*</nowiki>connection <nowiki>=</nowiki> '''con_ic_connection_new'''();
''/* Connect signal to receive connection events */''
'''g_signal_connect'''('''G_OBJECT'''(connection), "connection-event",
'''G_CALLBACK'''(my_connection_handler), NULL);
''/* Request connection and check for the result */''
success <nowiki>=</nowiki> '''con_ic_connection_connect'''(connection, CON_IC_CONNECT_FLAG_NONE);
'''if''' (!success) '''g_warning'''("Request for connection failed");</tt>

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:

<tt>'''static''' void '''my_connection_handler'''(ConIcConnection <nowiki>*</nowiki>connection,
ConIcConnectionEvent <nowiki>*</nowiki>event,
gpointer user_data)
{
ConIcConnectionStatus status <nowiki>=</nowiki> '''con_ic_connection_event_get_status'''(event);
ConIcConnectionError error<nowiki>;</nowiki>
'''const''' gchar <nowiki>*</nowiki>iap_id <nowiki>=</nowiki> '''con_ic_event_get_iap_id'''('''CON_IC_EVENT'''(event));
'''const''' gchar <nowiki>*</nowiki>bearer <nowiki>=</nowiki> '''con_ic_event_get_bearer_type'''('''CON_IC_EVENT'''(event));
'''switch'''(status) {
'''case''' CON_IC_STATUS_CONNECTED<nowiki>:</nowiki>
'''g_debug'''("Hey, we are connected to IAP %s with bearer %s!", iap_id, bearer);
'''break'''<nowiki>;</nowiki>
'''case''' CON_IC_STATUS_DISCONNECTING<nowiki>:</nowiki>
'''g_debug'''("We are disconnecting...");
'''break'''<nowiki>;</nowiki>
'''case''' CON_IC_STATUS_DISCONNECTED<nowiki>:</nowiki>
'''g_debug'''("And we are disconnected. Let's see what went wrong...");
error <nowiki>=</nowiki> '''con_ic_connection_event_get_error'''(event);
'''switch'''(error) {
'''case''' CON_IC_CONNECTION_ERROR_NONE<nowiki>:</nowiki>
'''g_debug'''("Libconic thinks there was nothing wrong.");
'''break'''<nowiki>;</nowiki>
'''case''' CON_IC_CONNECTION_ERROR_INVALID_IAP<nowiki>:</nowiki>
'''g_debug'''("Invalid (non-existing?) IAP was requested.");
'''break'''<nowiki>;</nowiki>
'''case''' CON_IC_CONNECTION_ERROR_CONNECTION_FAILED<nowiki>:</nowiki>
'''g_debug'''("Connection just failed.");
'''break'''<nowiki>;</nowiki>
'''case''' CON_IC_CONNECTION_ERROR_USER_CANCELED<nowiki>:</nowiki>
'''g_debug'''("User canceled the connection attempt");
'''break'''<nowiki>;</nowiki>
}
'''break'''<nowiki>;</nowiki>
'''default'''<nowiki>:</nowiki>
'''g_debug'''("Unknown connection status received");
}
}</tt>

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

<tt> ''/* Create connection object */''
ConIcConnection <nowiki>*</nowiki>connection <nowiki>=</nowiki> '''con_ic_connection_new'''();
''/* Connect signal to receive connection events */''
'''g_signal_connect'''('''G_OBJECT'''(connection), "connection-event",
'''G_CALLBACK'''(my_connection_handler), NULL);
''/* Set automatic events */''
'''g_object_set'''('''G_OBJECT'''(connection), "automatic-connection-events", TRUE, NULL);</tt>

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 reiterated in order to receive the event. If you need the connection status information synchronously, you can iterate the main loop yourself:

<tt>'''static''' void '''connection_info'''(ConIcConnection <nowiki>*</nowiki>connection,
ConIcConnectionEvent <nowiki>*</nowiki>event,
gpointer user_data)
{
ConIcConnectionStatus status <nowiki>=</nowiki> '''con_ic_connection_event_get_status'''(event);
ConIcConnectionStatus <nowiki>*</nowiki>status_ptr <nowiki>=</nowiki> (ConIcConnectionStatus<nowiki>*)</nowiki>user_data<nowiki>;</nowiki>
<nowiki>*</nowiki>status_ptr <nowiki>=</nowiki> status<nowiki>;</nowiki>
}
''/* ... */''
''/* Create connection object and set on automatic events (see previous snippet) ... */''
'''static''' ConIcConnectionStatus status <nowiki>=</nowiki> 0xFFFF<nowiki>;</nowiki>
ConIcConnection <nowiki>*</nowiki>connection <nowiki>=</nowiki> '''con_ic_connection_new'''();
'''g_signal_connect'''('''G_OBJECT'''(connection), "connection-event",
'''G_CALLBACK'''(connection_info), &status);
'''g_object_set'''('''G_OBJECT'''(Connection), "automatic-connection-events", TRUE, NULL);
''/* Iterate main loop for the first connection event */''
'''while''' (status <nowiki>==</nowiki> 0xFFFF) '''g_main_context_iteration'''(NULL, TRUE);
'''if''' (status <nowiki>==</nowiki> CON_IC_STATUS_CONNECTED)
'''g_debug'''("We are connected!");
'''else'''
'''g_debug'''("We are not connected!");</tt>

==== Receiving Statistics of Connection ====
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.

<tt>'''static''' void '''connection_statistics'''(ConIcConnection <nowiki>*</nowiki>connection,
ConIcStatisticsEvent <nowiki>*</nowiki>event,
gpointer user_data)
{
'''g_debug'''("Here are all kind of nice statistics about the connection:");
'''g_debug'''("Time active: %u, signal strength: %u, received packets: %llu, "
"sent packets: %llu, received bytes: %llu, sent bytes: %llu",
'''con_ic_statistics_event_get_time_active'''(event),
'''con_ic_statistics_event_get_signal_strength'''(event),
'''con_ic_statistics_event_get_rx_packets'''(event),
'''con_ic_statistics_event_get_tx_packets'''(event),
'''con_ic_statistics_event_get_rx_bytes'''(event),
'''con_ic_statistics_event_get_tx_bytes'''(event));
}
''/* ... */''
''/* ConIcConnection object named "connection" has already been created */''
'''g_signal_connect'''('''G_OBJECT'''(connection), "statistics",
'''G_CALLBACK'''(connection_statistics), NULL);
'''if''' (!'''con_ic_connection_statistics'''(connection ,NULL))
'''g_warning'''("Requesting connection statistics failed!");</tt>

==== Getting Proxy Settings ====
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.
** Use of auto configuration URL is explained in [http://en.wikipedia.org/wiki/Proxy_auto-config Wikipedia]

In this example, the "connection-event" handler is modified to print HTTP proxy settings when establishing connection:

<tt>'''static''' void '''my_connection_handler'''(ConIcConnection <nowiki>*</nowiki>connection,
ConIcConnectionEvent <nowiki>*</nowiki>event,
gpointer user_data)
{
ConIcConnectionStatus status <nowiki>=</nowiki> '''con_ic_connection_event_get_status'''(event);
GSList <nowiki>*</nowiki>ignore_hosts<nowiki>;</nowiki>

'''if''' (status <nowiki>==</nowiki> CON_IC_STATUS_CONNECTED) {
'''g_debug'''("We are connected! \
Let's see what kind of settings we have for HTTP proxy...");

''/* Do things based on specified proxy mode */''
'''switch''' ('''con_ic_connection_get_proxy_mode'''(connection)) {

'''case''' CON_IC_PROXY_MODE_NONE<nowiki>:</nowiki>
'''g_debug'''("No proxies defined, it is direct connection");
'''break'''<nowiki>;</nowiki>

'''case''' CON_IC_PROXY_MODE_MANUAL<nowiki>:</nowiki>
'''g_debug'''("HTTP proxy %s:%d in use",
'''con_ic_connection_get_proxy_host'''(connection, CON_IC_PROXY_PROTOCOL_HTTP),
'''con_ic_connection_get_proxy_port'''(connection, CON_IC_PROXY_PROTOCOL_HTTP));

'''g_debug'''("List of hosts, for which proxy should not be used:");
ignore_hosts <nowiki>=</nowiki> '''con_ic_connection_proxy_ignore_hosts'''(connection);
'''for''' (GSList <nowiki>*</nowiki>iter <nowiki>=</nowiki> ignore_hosts<nowiki>;</nowiki> iter <nowiki>!=</nowiki> NULL<nowiki>;</nowiki> iter <nowiki>=</nowiki> '''g_slist_next'''(iter))
{
'''g_debug'''("%s", (gchar <nowiki>*)</nowiki>iter->data);
'''g_free'''(iter->data);
}
'''g_slist_free'''(ignore_hosts);
'''break'''<nowiki>;</nowiki>

'''case''' CON_IC_PROXY_MODE_AUTO<nowiki>:</nowiki>
'''g_debug'''("Proxy auto-config URL %s should be used",
'''con_ic_connection_get_proxy_autoconfig_url'''(connection));
'''break'''<nowiki>;</nowiki>
}
}
}</tt>

Proxy functions also exist for each individual protocol (like ''con_ic_connection_get_proxy_ftp_host()''), but these functions are deprecated. Avoid them in newly-written code.

====Getting List of User-Saved Connections ====
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:

<tt> ''/* ConIcConnection object named "connection" has already been created */''
GSList <nowiki>*</nowiki>saved_iaps <nowiki>=</nowiki> '''con_ic_connection_get_all_iaps'''(connection);
'''g_debug'''("The following connections have been saved by the user:");
'''for''' (GSList <nowiki>*</nowiki>iter <nowiki>=</nowiki> saved_iaps<nowiki>;</nowiki> iter <nowiki>!=</nowiki> NULL<nowiki>;</nowiki> iter <nowiki>=</nowiki> '''g_slist_next'''(iter)) {
''/* Get IAP object and print some information about it */''
ConIcIap <nowiki>*</nowiki>iap <nowiki>=</nowiki> (ConIcIap <nowiki>*)</nowiki>iter->data<nowiki>;</nowiki>
'''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);</tt>

==== Porting Application from OSSO IC API to Libconic ====
* If the application does not have GType, GLib or D-BUS configured, set them up:
<tt> DBusConnection <nowiki>*</nowiki>system_dbus<nowiki>;</nowiki>
GMainLoop <nowiki>*</nowiki>main_loop<nowiki>;</nowiki>
'''g_type_init'''();
main_loop <nowiki>=</nowiki> '''g_main_loop_new'''(NULL, FALSE);
system_dbus <nowiki>=</nowiki> '''dbus_bus_get'''(DBUS_BUS_SYSTEM, NULL);
'''dbus_connection_setup_with_g_main'''(system_dbus, NULL);</tt>
* Include the correct header file:
<tt>''' #include''' <osso-ic.h>
<nowiki>===></nowiki>
''' #include''' <conic.h></tt>
* Set up ''ConIcConnection'' object and "connection-event" handler instead of ''osso_iap_cb_t'' callback:
<tt> '''static''' void '''my_connection_cb'''('''struct''' iap_event_t <nowiki>*</nowiki>event, void <nowiki>*</nowiki>arg)
{
''/* ... */''
}
''/* ... */''
'''osso_iap_cb'''(my_connection_cb);
<nowiki>===></nowiki>
'''static''' void '''my_connection_cb'''(ConIcConnection <nowiki>*</nowiki>connection,
ConIcConnectionEvent <nowiki>*</nowiki>event,
gpointer user_data)
{
''/* ... */''
}
''/* ... */''
ConIcConnection <nowiki>*</nowiki>connection <nowiki>=</nowiki> '''con_ic_connection_new'''();
'''g_signal_connect'''('''G_OBJECT'''(connection), "connection-event",
'''G_CALLBACK'''(my_connection_cb), app_data);</tt>
* Manage connections through ''ConIcConnection'' API instead of ''osso_iap_connect()'' and ''osso_iap_disconnect()''<nowiki>: </nowiki>
<tt> '''osso_iap_connect'''(OSSO_IAP_ANY, OSSO_IAP_REQUESTED_CONNECT, app_data);
'''osso_iap_disconnect'''(iap_name, app_data);
<nowiki>===></nowiki>
'''con_ic_connection_connect'''(connection, CON_IC_CONNECT_FLAG_NONE);
'''con_ic_connection_disconnect'''(connection);</tt>
* Request statistics with ''con_ic_connection_statistics()'' instead of ''osso_iap_get_statistics()''.
* List all available IAPs with ''con_ic_connection_get_all_iaps()'' instead of ''osso_iap_get_configured_iaps()''.
* Configure autoconf to use Libconic instead of OSSO IC API:
<tt> PKG_CHECK_MODULES(OSSOIC, osso-ic)
AC_SUBST(OSSOIC_CFLAGS)
AC_SUBST(OSSOIC_LIBS)
<nowiki>===></nowiki>
PKG_CHECK_MODULES(CONIC, conic)
AC_SUBST(CONIC_CFLAGS)
AC_SUBST(CONIC_LIBS)</tt>
* In debian/control file "Build-Depends" section, depend on libconic0-dev instead of osso-ic-dev.

==Bluetooth Libraries ==
This section explains how maemo Bluetooth libraries work internally. The following subsections explain the behavior and the decomposition of the Bluetooth library components in detail.

=== Libgwobex ===
Libgwobex provides access to libopenobex functionality by providing a helper/wrapper interface. Libopenobex is explained in detail in the following section.

The interface to libgwobex is available at [http://maemo.org/api_refs/4.1/osso-gwobex-0.60/index.html GW OBEX Library Documentation].

===Creating Connection ===
The connection with libgwobex is established using the gw_obex_setup_dev function, setting up the connection. gw-obex.h

<tt>'''<nowiki>#define</nowiki>''' OBEX_FTP_UUID \
"\xF9\xEC\x7B\xC4\x95\x3C\x11\xD2\x98\x4E\x52\x54\x00\xDC\x9E\x09"
'''<nowiki>#define</nowiki>''' OBEX_FTP_UUID_LEN 16

''/* ... */''

GwObex<nowiki>*</nowiki> '''gw_obex_setup_dev''' ('''const''' gchar <nowiki>*</nowiki> device, '''const''' gchar <nowiki>*</nowiki> uuid, gint uuid_len,
GMainContext <nowiki>*</nowiki> context, gint <nowiki>*</nowiki> error )</tt>

The following code snippet illustrates how to open a handle using gw_obex_setup_dev.

<tt>'''if''' (ctx->rfcomm_dev) {
'''if''' (ctx->use_ftp)
ctx->obex <nowiki>=</nowiki> '''gw_obex_setup_dev'''(ctx->rfcomm_dev,
OBEX_FTP_UUID, OBEX_FTP_UUID_LEN,
NULL, &err);
'''else'''
ctx->obex <nowiki>=</nowiki> '''gw_obex_setup_dev'''(ctx->rfcomm_dev, NULL,
0, NULL, &err);

'''if''' (ctx->obex <nowiki>==</nowiki> NULL)
'''printf'''("OBEX setup failed: %s\n", '''response_to_string'''(err));
}</tt>

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.

===Closing Connection ===
To close a gwobex connection, use the following function: gw-obex.h

<tt>void '''gw_obex_close''' ( GwObex <nowiki>*</nowiki> ctx );</tt>

The following code demonstrates this usage.

<tt>'''if''' (ctx->obex) {
'''gw_obex_close'''(ctx->obex);
ctx->obex <nowiki>=</nowiki> NULL<nowiki>;</nowiki>
}</tt>

If ctx->obex is not NULL, it is simply passed as an argument to gw_obex_close().

===Using Connection ===
The libgwobex library provides general file handling functionality, including reading directory structure, browsing in different folders and getting files.

To read entries from an opened directory, use the following function: gw-obex.h

<tt>gboolean '''gw_obex_read_dir''' (GwObex <nowiki>*</nowiki> ctx,
'''const''' gchar <nowiki>*</nowiki> dir,
gchar <nowiki>**</nowiki> buf,
gint <nowiki>*</nowiki> buf_size,
gint <nowiki>*</nowiki> error );</tt>

gw_obex_read_dir reads an entry from the selected folder and returns the result in the buf argument given to the function.

<tt>gboolean ret<nowiki>;</nowiki>
''/* ... */''
ret <nowiki>=</nowiki> '''gw_obex_read_dir'''(ctx->obex, dir, buf, buf_size, err);</tt>

This reads an entry from the directory dir (char *) and returns it in buf (char **).

To change the current directory, use the following function: gw-obex.h

<tt>gboolean '''gw_obex_chdir''' (GwObex <nowiki>*</nowiki> ctx, '''const''' gchar <nowiki>*</nowiki> dir, gint <nowiki>*</nowiki> error );</tt>

which changes the directory of the FTP connection. Below is a code example using this function.

<tt>''/* Ignore parent dir pointers */''
'''if''' ('''g_str_equal'''(name, ".."))
'''return''' TRUE<nowiki>;</nowiki>

'''if''' (!'''gw_obex_chdir'''(ctx->obex, name, err)) {
'''printf'''("Could not chdir to %s\n", name);
'''return''' FALSE<nowiki>;</nowiki>
}</tt>

To retrieve files over the OBEX connection, use the gw_obex_get_file function: gw-obex.h

<tt>gboolean '''gw_obex_get_file''' (GwObex <nowiki>*</nowiki> ctx,
'''const''' gchar <nowiki>*</nowiki> local,
'''const''' gchar <nowiki>*</nowiki> remote,
'''const''' gchar <nowiki>*</nowiki> type,
gint <nowiki>*</nowiki> error);
</tt>

gw_obex_get_file uses the ctx context for retrieving the remote file to local file.

<tt>gboolean ret<nowiki>;</nowiki>
ret <nowiki>=</nowiki> '''gw_obex_get_file'''(ctx->obex, name, name, err);</tt>

Using the libwobex wrapper directly allows you to perform many more functions. For more information, see the [hhttp://maemo.org/api_refs/5.0/beta/osso-gwobex/ API document].

===Libopenobex ===
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/ http://www.irda.org]<nowiki>; select the Developer->Specifications category. OBEX resembles the HTTP protocol, expect for a few differences: </nowiki>

* 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.

For more information on OBEX, see the summary available at http://en.wikipedia.org/wiki/OBEX.

For libopenobex code samples, see http://openobex.triq.net/downloads<nowiki>; the samples are in the example apps package. </nowiki>

===Using BlueZ D-Bus API ===
The BlueZ system exports a D-Bus API that can be employed instead of OSSO Bluetooth tools. See the following documents:

* [http://git.kernel.org/?p=bluetooth/bluez.git;a=tree;f=doc;hb=HEAD BlueZ D-Bus API documentation]

==Connectivity UI ==

===UI Components ===
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.

===D-Bus Connectivity UI Interface ===
If the user must provide information about the IAP that the system is about to connect to, you can use the following method:

<div class="graybox">

Service: com.nokia.icd_ui
Interfaces: com.nokia.icd_ui
Object paths: /com/nokia/icd_ui

</div>

The Internet Connectivity UIs implement the following D-Bus API used by the ICd and EAP.

<div class="graybox">

Method: show_conn_dlg
Parameters: 1. boolean When TRUE the dialog is requested because
there were no saved connections (i.e. auto
connect was tried before invoking the dialog)
Return parameters: none
Errors: com.nokia.icd_ui.error.flight_mode:
Flight mode enabled, dialog not shown
Description: Shows the Connect Dialog where the user can choose an IAP.

</div>

<div class="graybox">

Method: show_disconnect_dlg
Parameters: none

Return Parameters: none
Errors: com.nokia.icd_ui.error.flight_mode:
Flight mode enabled, dialog not shown

Description: Shows the disconnect dialog.

</div>

<div class="graybox">

Method: show_retry_dlg
Parameters: 1. string Bluetooth address of the device used with SAP
2. string Name of the connection attempt error which
selects the retry dialog type.

Return Parameters: none
Errors: com.nokia.icd_ui.error.flight_mode:
Flight mode enabled, dialog not shown

Description: Shows the retry dialog.

</div>

<div class="graybox">

Method: show_change_dlg
Parameters: 1. string Name of the currently active IAP
2. string Name of the IAP to be activated

Return Parameters: none
Errors: com.nokia.icd_ui.error.flight_mode:
Flight mode enabled, dialog not shown

Description: Shows the Change IAP Dialog

</div>

<div class="graybox">

Method: show_passwd_dlg
Parameters: 1. string Username supplied by ICd
2. string Password supplied by ICd
3. string Name of the IAP

Return Parameters: none
Errors: com.nokia.icd_ui.error.flight_mode:
Flight mode enabled, dialog not shown

Description: Shows the username/password dialog.

</div>

<div class="graybox">

Method: show_gtc_dlg
Parameters: 1. string GTC challenge string

Return Parameters: none
Errors: com.nokia.icd_ui.error.flight_mode:
Flight mode enabled, dialog not shown

Description: Shows EAP GTC challenge dialog.

</div>

<div class="graybox">

Method: show_mschap_change_dlg
Parameters: 1. string Supplied username
2. string Old password that is to be changed
3. string Name of the IAP

Return Parameters: none
Errors: com.nokia.icd_ui.error.flight_mode:
Flight mode enabled, dialog not shown

Description: Shows EAP MSCHAPv2 change password dialog.

</div>

<div class="graybox">

Method: show_private_key_passwd_dlg
Parameters: 1. byte array Certificate ID

Return Parameters: none
Errors: com.nokia.icd_ui.error.flight_mode:
Flight mode enabled, dialog not shown

Description: Shows EAP private key password dialog

</div>

<div class="graybox">

Method: show_server_cert_dlg
Parameters: 1. string Certificate name
2. string Certificate serial
3. boolean TRUE if certificate is expired, FALSE otherwise
4. boolean TRUE if root CA is unknown or self-signed
certificate, FALSE otherwise

Return Parameters: none
Errors: com.nokia.icd_ui.error.flight_mode:
Flight mode enabled, dialog not shown

Description: 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.

</div>

<div class="graybox">

Method: strong_bt_req
Parameters: 1. string Bluetooth address of the device to pair with
2. boolean TRUE if strong authentication enabled, FALSE
if strong authentication is disabled

Return Parameters: none
Errors: com.nokia.icd_ui.error.flight_mode:
Flight mode enabled, dialog not shown

Description: Requests strong (16 digit) BT PIN dialog for a BT device

</div>

<div class="graybox">

Method: show_sim_pin_dlg
Parameters: 1. string Bluetooth address of the device used with SAP
2. boolean TRUE if PIN was incorrect and retry dialog
should be displayed before asking PIN. FALSE
if this is the first PIN request.

Return Parameters: none
Errors: com.nokia.icd_ui.error.flight_mode:
Flight mode enabled, dialog not shown

Description: Shows SIM PIN dialog

</div>

The code example for the application to show the connect dialog using show_conn_dlg is following. Note the use of the macro.

<tt>'''<nowiki>#include</nowiki>''' <osso-ic-ui-dbus.h>
''/* ... */''
''/* in our code somewhere, where we need the Connect Dialog*/''
DBusMessage <nowiki>*</nowiki>uimsg<nowiki>;</nowiki>
''/* construct the message for Connect Dialog request*/''
uimsg <nowiki>=</nowiki>
'''dbus_message_new_method_call'''(ICD_UI_DBUS_SERVICE,
ICD_UI_DBUS_PATH,
ICD_UI_DBUS_INTERFACE,
''/*macro for show_conn_dlg */''
ICD_UI_SHOW_CONNDLG_REQ);
''/* send the message */''
reply <nowiki>=</nowiki>
'''dbus_connection_send_with_reply_and_block'''(connection,
uimsg,
reply_timeout,
&error);
'''if''' (reply <nowiki>==</nowiki> NULL) {
'''DLOG_ERR'''("Failed to show connect dialog: %s", uierror.message);
'''dbus_error_free'''(&uierror);
}
'''dbus_message_unref'''(uimsg);
'''dbus_message_unref'''(reply);
''/* ... */''</tt>

The signals emitted from com.nokia.icd_ui interface are listed below.

<div class="graybox">

Signal: disconnect
Parameters: 1. boolean TRUE if "disconnect" pressed, FALSE if "cancel"

Description: Signal emitted from UI when disconnect dialog has been closed.

</div>

<div class="graybox">

Signal: retry
Parameters: 1. string The IAP that is to be retried
2. boolean TRUE if "retry" pressed, FALSE if "cancel"

Description: Signal emitted from UI when the retry dialog has been closed.

</div>

 

<div class="graybox">

Signal: change
Parameters: 1. string Old IAP to change from
2. string New IAP to change to
3. boolean Change to the new IAP If TRUE, keep old if FALSE

Description: Signal emitted from UI when change connection dialog has
been closed.

</div>

<div class="graybox">

Signal: passwd
Parameters: 1. string Username supplied or modified by the user
2. string Password supplied or modified by the user
3. string IAP name
4. boolean TRUE if "ok" pressed, FALSE if "cancel"

Description: Signal emitted from UI when the username/password dialog has
been closed

</div>

<div class="graybox">

Signal: gtc_response
Parameters: 1. string Response to the given challenge or empty string
if cancelled
2. boolean TRUE if "ok" pressed, FALSE if "cancel"

Description: Signal emitted from UI when the EAP GTC challenge dialog has
been closed.

</div>

<div class="graybox">

Signal: mschap_change
Parameters: 1. string Supplied username
2. string The new password or empty string if cancelled
3. string IAP name
4. boolean TRUE if "ok" pressed, FALSE if "cancel"

Description: Signal emitted from UI when the MSCHAPv2 password has been
changed

</div>

<div class="graybox">

Signal: private_key_passwd
Parameters: 1. byte array Certificate ID
2. string Password for the private key or empty string if none
3. boolean TRUE if "ok" pressed, FALSE if "cancel"

Description: Signal emitted from UI when the private key password dialog
has been closed

</div>

<div class="graybox">

Signal: server_cert
Parameters: 1. boolean TRUE if strong PIN entered, FALSE if strong
PIN dialog was canceled

Description: Signal emitted from UI when the server certificate error
dialog has been closed

</div>

 

<div class="graybox">

Signal: strong_bt
Parameters: 1. boolean TRUE if strong PIN entered, FALSE if strong
PIN dialog was cancelled

Description: Signal emitted from UI when the strong (16 digit) BT PIN
has been entered

</div>

<div class="graybox">

Signal: sim_pin
Parameters: 1. string SIM PIN code or empty string if cancelled
2. boolean TRUE if "ok" pressed, FALSE if "cancel"

Description: Signal emitted from UI when the SIM PIN has been entered.

</div>

===Bluetooth DBUS UI dialogs ===

conbtdialogs-dbus.h

<tt>''/** ''
'' Example of use (command line):''
'' ''
'' dbus-send --system --print-reply \''
'' --dest='com.nokia.icd_ui' /com/nokia/bt_ui \''
'' com.nokia.bt_ui.show_send_file_dlg \''
'' array:string:''file:///home/user/MyDocs/.documents/testing.txt
'' ''
'' dbus-send --system --print-reply \''
'' --dest=com.nokia.bt_ui /com/nokia/bt_ui ''
'' com.nokia.bt_ui.show_search_dlg \''
'' string: string: array:string: string:''
''<nowiki>*/</nowiki>''

'''<nowiki>#ifndef</nowiki>''' CONBTDIALOGS_DBUS_H
'''<nowiki>#define</nowiki>''' CONBTDIALOGS_DBUS_H

'''<nowiki>#ifdef</nowiki>''' __cplusplus
'''extern''' "C" {
'''<nowiki>#endif</nowiki>'''

''/** Conbtdialogs service, resides in system dbus */''
'''<nowiki>#define</nowiki>''' CONBTDIALOGS_DBUS_SERVICE "com.nokia.bt_ui"
''/** Conbtdialogs interface */''
'''<nowiki>#define</nowiki>''' CONBTDIALOGS_DBUS_INTERFACE "com.nokia.bt_ui"
''/** Conbtdialogs path */''
'''<nowiki>#define</nowiki>''' CONBTDIALOGS_DBUS_PATH "/com/nokia/bt_ui"

''/** ''
'' Show send file dialog''
'' ''
'' Arguments:''
'' ''
'' uris: DBUS_TYPE_ARRAY Array of strings representing the URIs of the''
'' files to send.''
'' ''
'' Returns:''
'' ''
'' DBUS_TYPE_BOOLEAN TRUE, if dialog was shown successfully.''
'' */''
'''<nowiki>#define</nowiki>''' CONBTDIALOGS_SEND_FILE_REQ "show_send_file_dlg"

''/** ''
'' File sending result signal''
'' ''
'' Arguments:''
'' ''
'' success: DBUS_TYPE_BOOLEAN TRUE, if all files were sent successfully or''
'' FALSE, if error occurred or sending was ''
'' canceled.''
'' */''
'''<nowiki>#define</nowiki>''' CONBTDIALOGS_SEND_FILE_SIG "send_file"

''/** ''
'' Show BT device search dialog''
'' ''
'' Arguments:''
'' ''
'' major_class: DBUS_TYPE_STRING To set filtering based on major_class or''
'' "". Possible major class values are:''
'' ''
'' "miscellaneous", "computer", "phone", ''
'' "access point", "audio/video", ''
'' "peripheral", "imaging", "wearable",''
'' "toy" and "uncategorized".''
'' ''
'' minor_class: DBUS_TYPE_STRING To set filtering based on minor_class or "".''
'' Possible minor class values are:''
'' ''
'' - Minor classes for "computer": ''
'' "uncategorized", "desktop", "server",''
'' "laptop", "handheld", "palm", "wearable"''

'' - Minor classes for "phone": "uncategorized",''
'' "cellular", "cordless", "smart phone",''
'' "modem", "isdn"''
'' ''
'' service_classes: DBUS_TYPE_ARRAY To set filtering based on service classes.''
'' Supported classes include "positioning", ''
'' "networking", "rendering", "capturing",''
'' "object transfer", "audio", "telephony", ''
'' "information". Can be empty list, when no''
'' service class filtering is performed.''
'' ''
'' bonding: DBUS_TYPE_STRING Bonding mode for found and selected device:''
'' ''
'' "require" for requiring a bonding from a''
'' selected device (i.e. bond device if it has not''
'' been bonded before). ''
'' ''
'' "force" to always bond (i.e. device will be''
'' bonded even if bonded before).''
'' ''
'' Any other string will allow to search and''
'' select device without bonding it.''
'' ''
'' Returns:''
'' ''
'' DBUS_TYPE_BOOLEAN TRUE, if dialog was shown successfully.''
'' */''
'''<nowiki>#define</nowiki>''' CONBTDIALOGS_SEARCH_REQ "show_search_dlg"

''/** ''
'' Bluetooth search result signal''
'' ''
'' Arguments:''
'' ''
'' address: DBUS_TYPE_STRING Bluetooth address of the selected device, or ""''
'' if search dialog was cancelled.''
'' ''
'' name: DBUS_TYPE_STRING Name of the device.''
'' ''
'' icon: DBUS_TYPE_STRING Logical name for the icon describing the ''
'' device.''
'' ''
'' major_class: DBUS_TYPE_STRING Major class of the device.''
'' ''
'' minor_class: DBUS_TYPE_STRING Minor class of the device.''
'' ''
'' trusted: DBUS_TYPE_BOOLEAN Defines whether the device is marked as a trusted device.''
'' ''
'' services: DBUS_TYPE_ARRAY List of strings describing the service classes''
'' and SDP-based services provided by the device.''
'' */''
'''<nowiki>#define</nowiki>''' CONBTDIALOGS_SEARCH_SIG "search_result"
</tt>

 

<tt>''/**''
'' Bluetooth UI Library for maemo''

'' Copyright (C) 2006 Nokia. All rights reserved.''
'' ''
'' This sample demonstrates the use of conbtdialogs API and especially ''
'' send_file function. Compile the program with conbtdialogs and dbus:''
'' ''
'' gcc -Wall `pkg-config -libs -cflags dbus-glib-1 conbtdialogs` \''
''-o send_file conbtdialogs_send_file.c''
'' ''
'' Run with list of URLS:''
'' ''
'' ./send_file ''file:///home/user/MyDocs/.sounds/Everyday.mp3
''<nowiki>*/</nowiki>''

'''<nowiki>#define</nowiki>''' DBUS_API_SUBJECT_TO_CHANGE

'''<nowiki>#include</nowiki>''' <glib.h>
'''<nowiki>#include</nowiki>''' <conbtdialogs-dbus.h>
'''<nowiki>#include</nowiki>''' <dbus/dbus.h>
'''<nowiki>#include</nowiki>''' <dbus/dbus-glib.h>

DBusGConnection <nowiki>*</nowiki>connection <nowiki>=</nowiki> NULL<nowiki>;</nowiki>
GMainLoop <nowiki>*</nowiki>mainloop <nowiki>=</nowiki> NULL<nowiki>;</nowiki>

'''static''' gboolean '''initialize'''(void)
{
GError <nowiki>*</nowiki>error <nowiki>=</nowiki> NULL<nowiki>;</nowiki>

'''g_type_init''' ();

''/* Create main loop */''
mainloop <nowiki>=</nowiki> '''g_main_loop_new'''(NULL, TRUE);
'''if''' ( mainloop <nowiki>==</nowiki> NULL ) '''return''' FALSE<nowiki>;</nowiki>

''/* Create DBUS connection */''
connection <nowiki>=</nowiki> '''dbus_g_bus_get'''(DBUS_BUS_SYSTEM, &error);

'''if''' (connection <nowiki>==</nowiki> NULL )
{
'''g_print''' ("Error: %s\n", error->message);
'''g_clear_error''' (&error);
'''return''' FALSE<nowiki>;</nowiki>
}

'''return''' TRUE<nowiki>;</nowiki>
}

'''static''' gboolean '''uninitialize'''(void)
{
''/* Quit main loop and unref it */''
'''if''' (mainloop <nowiki>!=</nowiki> NULL)
{
'''g_main_loop_quit'''(mainloop);
'''g_main_loop_unref'''(mainloop);
}

'''return''' TRUE<nowiki>;</nowiki>
}

'''static''' DBusHandlerResult '''file_sent_signal''' ( DBusConnection <nowiki>*</nowiki>connection,
DBusMessage <nowiki>*</nowiki>message,
void <nowiki>*</nowiki>data )
{
gboolean success <nowiki>=</nowiki> FALSE<nowiki>;</nowiki>

''/* check signal */''
'''if''' (!'''dbus_message_is_signal'''(message,
CONBTDIALOGS_DBUS_INTERFACE,
CONBTDIALOGS_SEND_FILE_SIG))
'''return''' DBUS_HANDLER_RESULT_NOT_YET_HANDLED<nowiki>;</nowiki>

''/* get args */''
'''if''' ( <nowiki>!</nowiki>'''dbus_message_get_args''' ( message, NULL,
DBUS_TYPE_BOOLEAN, &success,
DBUS_TYPE_INVALID ) )
'''return''' DBUS_HANDLER_RESULT_NOT_YET_HANDLED<nowiki>;</nowiki>

''/* print if file sending was success or failure */''
'''g_print''' ( "File sending was a " );

'''if''' (success) '''g_print'''("success\n"); '''else''' '''g_print'''("failure\n");
'''dbus_connection_close'''(connection);
'''uninitialize'''();

'''return''' DBUS_HANDLER_RESULT_HANDLED<nowiki>;</nowiki>
}

gint '''main'''(gint argc, gchar <nowiki>**</nowiki>argv)
{
GError <nowiki>*</nowiki>error <nowiki>=</nowiki> NULL<nowiki>;</nowiki>
gchar <nowiki>**</nowiki>files <nowiki>=</nowiki> NULL<nowiki>;</nowiki>
gint idx <nowiki>=</nowiki> 0<nowiki>;</nowiki>
DBusGProxy <nowiki>*</nowiki>proxy<nowiki>;</nowiki>
DBusConnection <nowiki>*</nowiki>sys_conn<nowiki>;</nowiki>
gchar <nowiki>*</nowiki>filter_string <nowiki>=</nowiki> NULL<nowiki>;</nowiki>

'''if''' (argc < 2) '''return''' 1<nowiki>;</nowiki>

'''if''' ('''initialize'''() <nowiki>==</nowiki> FALSE) {
'''uninitialize'''();
'''return''' 1<nowiki>;</nowiki>
}

''/* Copy urls to GLib compatible char array */''
files <nowiki>=</nowiki> '''g_new0'''(gchar<nowiki>*,</nowiki> argc);

'''for''' (idx <nowiki>=</nowiki> 1<nowiki>;</nowiki> idx < argc<nowiki>;</nowiki> idx++)
files[idx-1] <nowiki>=</nowiki> '''g_strdup'''(argv[idx]);

files[argc-1] <nowiki>=</nowiki> NULL<nowiki>;</nowiki>

''/* Open connection for btdialogs service */''
proxy <nowiki>=</nowiki> '''dbus_g_proxy_new_for_name'''(connection,
CONBTDIALOGS_DBUS_SERVICE,
CONBTDIALOGS_DBUS_PATH,
CONBTDIALOGS_DBUS_INTERFACE);

''/* Send send file request to btdialogs service */''
'''if''' (!'''dbus_g_proxy_call'''(proxy, CONBTDIALOGS_SEND_FILE_REQ,
&error,
G_TYPE_STRV, files, G_TYPE_INVALID,
G_TYPE_INVALID))
{
'''g_print'''("Error: %s\n", error->message);
'''g_clear_error'''(&error);
'''g_strfreev''' (files);
'''g_object_unref'''('''G_OBJECT'''(proxy));
'''uninitialize'''();
'''return''' 1<nowiki>;</nowiki>
}
'''g_strfreev''' (files);
files <nowiki>=</nowiki> NULL<nowiki>;</nowiki>

'''g_object_unref'''('''G_OBJECT'''(proxy));

''/* Now wait for file sent signal, use low level bindings as glib ''
'' bindings require signal marshaller registered */''
sys_conn <nowiki>=</nowiki> '''dbus_bus_get'''(DBUS_BUS_SYSTEM, NULL);
'''g_assert'''('''dbus_connection_add_filter'''(sys_conn,
file_sent_signal,
NULL,
NULL ));
filter_string <nowiki>=</nowiki>
'''g_strdup_printf''' ("type='signal',interface='%s'", CONBTDIALOGS_DBUS_INTERFACE);

'''dbus_bus_add_match'''(sys_conn, filter_string, NULL);
'''dbus_connection_unref'''(sys_conn);

''/* Run mainloop */''
'''g_main_loop_run'''(mainloop);

'''return''' 0<nowiki>;</nowiki>
}</tt>

Documentation/Maemo 5 Developer Guide/Using Connectivity Components/Maemo Connectivity

2010-01-27T11:23:36Z

80.242.16.1: /* Listening for Connection Events */

= Maemo Connectivity =

==Introduction==
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.

===Components of the maemo connectivity architecture===
'''Maemo connectivity UI''' - User Interface parts of the connectivity. This includes Control Panel applets and several different dialogs.

'''Maemo connectivity daemon (ICd)''' - [http://maemo.org/api_refs/5.0/beta/libconic/ LibConIC] API works together with [http://maemo.org/api_refs/5.0/beta/icd2/ ICd], handling all Internet Access Points (IAPs). IC daemon handles both WLAN and GPRS connections.

'''OBEX wrapper''' - Interface to OBEX services. The primary target user of this library is the OBEX gnome-vfs module.

'''OpenOBEX''' - Open source implementation of the Object Exchange (OBEX) protocol. For more information on OpenOBEX, visit http://triq.net/obex/

'''BlueZ Bluetooth stack''' - The de-facto implementation of Bluetooth for Linux. For more information on BlueZ, visit [http://www.bluez.org/ http://www.bluez.org]

'''[http://git.kernel.org/?p=bluetooth/bluez.git;a=tree;f=doc;hb=HEAD BlueZ D-Bus API]''' - BlueZ accepts commands via D-Bus.

'''WLAN connectivity daemon''' - The daemon controlling WLAN connections.

'''WLAN device driver''' - mac80211 from Linux and wl12xx driver implemented by Nokia, licensed under GPLv2.

===Internet Access Points (IAP)===
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.

==Connectivity Subsystem ==
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.

In offline mode, none of the radios must be active. The Device System Management Entity (DSME) of maemo provides information about the transitions to and from the offline mode.

<div align="CENTER">

{| border="1" cellpadding="3"
| width="100" align="LEFT" valign="TOP" | Name
| width="350" align="LEFT" valign="TOP" | Connectivity UI
|-
| width="100" align="LEFT" valign="TOP" | Purpose
| width="350" align="LEFT" valign="TOP" | Provides the UI for managing phone and Internet connections. Available as a Control Panel applet, and from the Status Bar.
|-
| width="100" align="LEFT" valign="TOP" | Responsibilities and additional requirements
| width="350" align="LEFT" valign="TOP" |
* Displaying active connections with statistics
* Updating status indicators
* Providing dialogs for changing and disconnecting connections
|-
| width="100" align="LEFT" valign="TOP" | Concurrent usage
| width="350" align="LEFT" valign="TOP" | (N/A)
|}

 

{| border="1" cellpadding="3"
| width="100" align="LEFT" valign="TOP" | Name
| width="350" align="LEFT" valign="TOP" | Phone Access
|-
| width="100" align="LEFT" valign="TOP" | Purpose
| width="350" align="LEFT" valign="TOP" | Provides connections to phones with different Bluetooth profiles
|-
| width="100" align="LEFT" valign="TOP" | Responsibilities and additional requirements
| width="350" align="LEFT" valign="TOP" |
* Searching for phones and inquiring their services
* Keeping phone register
* Providing status of the phone connections for Connectivity UI
* Binding RFCOMM devices to Bluetooth services on the phone
* Providing easy access to OpenOBEX
|-
| width="100" align="LEFT" valign="TOP" | Concurrent usage
| width="350" align="LEFT" valign="TOP" | Number of clients not limited by maemo. However, some phones may not support more than one Bluetooth profile at a time.
|}

 

{| border="1" cellpadding="3"
| width="100" align="LEFT" valign="TOP" | Name
| width="350" align="LEFT" valign="TOP" | Internet Access
|-
| width="100" align="LEFT" valign="TOP" | Purpose
| width="350" align="LEFT" valign="TOP" | Provides Internet connections over different bearers.
|-
| width="100" align="LEFT" valign="TOP" | Responsibilities and additional requirements
| width="350" align="LEFT" valign="TOP" |
* Providing means for configuration and management of IAP settings
* Providing API for Internet connections over different bearers (e.g. WLAN, GPRS)
* Providing status of Internet connections for Connectivity UI
|-
| width="100" align="LEFT" valign="TOP" | Concurrent usage
| width="350" align="LEFT" valign="TOP" | Number of clients not limited, but only one connection to the Internet can exist at any given time
|}

</div>

Phone and Internet connections are quite different by nature and behavior. These are introduced in more detail in the following sections.

===Phone Access ===
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.

<div align="CENTER"></div><div align="CENTER">

{| border="1" cellpadding="3"
| width="100" align="LEFT" valign="TOP" | Name
| width="350" align="LEFT" valign="TOP" | General Bluetooth UI
|-
| width="100" align="LEFT" valign="TOP" | Purpose
| width="350" align="LEFT" valign="TOP" | User interface for managing all paired BT devices
|-
| width="100" align="LEFT" valign="TOP" | Responsibilities and additional requirements
| width="350" align="LEFT" valign="TOP" |
* Keeping a list of all paired devices (not only phones)
|-
| width="100" align="LEFT" valign="TOP" | Concurrent usage
| width="350" align="LEFT" valign="TOP" | N/A
|}

 

{| border="1" cellpadding="3"
| width="100" align="LEFT" valign="TOP" | Name
| width="350" align="LEFT" valign="TOP" | BT search
|-
| width="100" align="LEFT" valign="TOP" | Purpose
| width="350" align="LEFT" valign="TOP" | Searches for available Bluetooth devices
|-
| width="100" align="LEFT" valign="TOP" | Responsibilities and additional requirements
| width="350" align="LEFT" valign="TOP" |
* Bluetooth inquiry
* Checking on offline mode state
|-
| width="100" align="LEFT" valign="TOP" | Concurrent usage
| width="350" align="LEFT" valign="TOP" | N/A
|}

 

{| border="1" cellpadding="3"
| width="100" align="LEFT" valign="TOP" | Name
| width="350" align="LEFT" valign="TOP" | BT service discovery
|-
| width="100" align="LEFT" valign="TOP" | Purpose
| width="350" align="LEFT" valign="TOP" | Checks if a found Bluetooth device is sufficient
|-
| width="100" align="LEFT" valign="TOP" | Responsibilities and additional requirements
| width="350" align="LEFT" valign="TOP" |
* Bluetooth service discovery (SDP)
|-
| width="100" align="LEFT" valign="TOP" | Concurrent usage
| width="350" align="LEFT" valign="TOP" | Not limited (but used by Phone selection UI and Phone connection daemon only)
|}

 

{| border="1" cellpadding="3"
| width="100" align="LEFT" valign="TOP" | Name
| width="350" align="LEFT" valign="TOP" | GW OBEX library
|-
| width="100" align="LEFT" valign="TOP" | Purpose
| width="350" align="LEFT" valign="TOP" | Provides access to OpenOBEX library for the File selector (Gnome VFS) on a higher abstraction level than OpenOBEX itself supports
|-
| width="100" align="LEFT" valign="TOP" | Responsibilities and additional requirements
| width="350" align="LEFT" valign="TOP" |
* Handling OBEX requests
|-
| width="100" align="LEFT" valign="TOP" | Concurrent usage
| width="350" align="LEFT" valign="TOP" | Not limited
|}

 

</div><div align="CENTER"></div>

Maemo Bluetooth also supports HID (keyboard) and OPP (object push file transfer) profiles.

===Internet Access ===
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.

<div align="CENTER"></div><div align="CENTER">

{| border="1" cellpadding="3"
| width="100" align="LEFT" valign="TOP" | Name
| width="350" align="LEFT" valign="TOP" | IC daemon
|-
| width="100" align="LEFT" valign="TOP" | Purpose
| width="350" align="LEFT" valign="TOP" | IC daemon establishes Internet connections over different bearers.
|-
| width="100" align="LEFT" valign="TOP" | Responsibilities and additional requirements
| width="350" align="LEFT" valign="TOP" |
* 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
* Starting IP level services like PPP and DHCP
* Providing statistics about the usage of IAPs to any application
|-
| width="100" align="LEFT" valign="TOP" | Concurrent usage
| width="350" align="LEFT" valign="TOP" | Has multiple clients and limits the connections to one at a time
|}

 

{| border="1" cellpadding="3"
| width="100" align="LEFT" valign="TOP" | Name
| width="350" align="LEFT" valign="TOP" | Internet Connectivity GUI
|-
| width="100" align="LEFT" valign="TOP" | Purpose
| width="350" align="LEFT" valign="TOP" | Has GUI applications for configuring Internet Access Points and WLAN settings.
|-
| width="100" align="LEFT" valign="TOP" | Responsibilities and additional requirements
| width="350" align="LEFT" valign="TOP" |
* Providing the UI for configuring an IAP
* Providing the UI for WLAN settings
* Scanning for available WLAN networks (on request)
* Saving IAP and WLAN settings (excluding EAP settings) to GConf
* Opening up dialogs and displaying notifications
|-
| width="100" align="LEFT" valign="TOP" | Concurrent usage
| width="350" align="LEFT" valign="TOP" | N/A
|}

 

{| border="1" cellpadding="3"
| width="100" align="LEFT" valign="TOP" | Name
| width="350" align="LEFT" valign="TOP" | WLAN connection daemon
|-
| width="100" align="LEFT" valign="TOP" | Purpose
| width="350" align="LEFT" valign="TOP" | Manages WLAN network connections
|-
| width="100" align="LEFT" valign="TOP" | Responsibilities and additional requirements
| width="350" align="LEFT" valign="TOP" |
* Starting WLAN driver with the settings provided; stopping WLAN
* Requesting authentication when necessary
* Relaying WLAN IAP settings from IC daemon to WLAN drivers and authentication requests to EAP
* Relaying WLAN events from WLAN drivers
* Providing WLAN status information
|-
| width="100" align="LEFT" valign="TOP" | Concurrent usage
| width="350" align="LEFT" valign="TOP" | Not limited
|}

 

{| border="1" cellpadding="3"
| width="100" align="LEFT" valign="TOP" | Name
| width="350" align="LEFT" valign="TOP" | EAP UI
|-
| width="100" align="LEFT" valign="TOP" | Purpose
| width="350" align="LEFT" valign="TOP" | User interface for EAP authentication
|-
| width="100" align="LEFT" valign="TOP" | Responsibilities and additional requirements
| width="350" align="LEFT" valign="TOP" |
* Invoking a dialog for an authentication password
* Showing authentication status
|-
| width="100" align="LEFT" valign="TOP" | Concurrent usage
| width="350" align="LEFT" valign="TOP" | N/A
|}

 

{| border="1" cellpadding="3"
| width="100" align="LEFT" valign="TOP" | Name
| width="350" align="LEFT" valign="TOP" | EAP
|-
| width="100" align="LEFT" valign="TOP" | Purpose
| width="350" align="LEFT" valign="TOP" | Provides WLAN security excluding basic WEP settings, which are in Wireless Extensions
|-
| width="100" align="LEFT" valign="TOP" | Responsibilities and additional requirements
| width="350" align="LEFT" valign="TOP" |
* Taking care of the authentication process for the active IAP
* Delivering progress events to IC daemon
* As a special case, controlling the EAP-SIM authentication using the SIM Access Profile
* Providing authentication status
|-
| width="100" align="LEFT" valign="TOP" | Concurrent usage
| width="350" align="LEFT" valign="TOP" | N/A
|}

 

</div><div align="CENTER"></div>

==Internet Connectivity Daemon ==
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.

===Decomposition ===
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'''<nowiki>: Use the connection and update all data. </nowiki>
** '''Connection Lost'''<nowiki>: Go to an idle state silently and wait until a new connection is created. </nowiki>
** '''Connection Changed'''<nowiki>: Use the new connection. </nowiki>
* 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.

=== WLAN ===
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.

==LibConIC Library ==
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 [http://maemo.org/api_refs/4.1/libconic-0.16/index.html Internet Connectivity API]

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

* requesting Internet connection
* listening for Internet connection status events
* receiving statistics of Internet connection
* getting proxy settings for the current connection
* getting a list of user-saved connections (IAPs)

 
'''Application Requirements'''
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.

'''Non-Blocking Sockets'''
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.

'''System D-BUS'''
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()''.

N.B. Setting up LibOSSO context connects the application to required D-BUS.

'''GType'''
Libconic API is GObject-basedm, so in order to get the API working, you must initialize GLib's GType properly. To do that, use ''g_type_init()''.

'''No Multiple Threads'''
Libconic API is not thread-safe. If the applications have threads, use Libconic API only from the same context where GMainloop is running.

===Libconic Usage ===

==== Requesting for Connection ====
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:

<tt> gboolean success <nowiki>=</nowiki> FALSE<nowiki>;</nowiki>
''/* Create connection object */''
ConIcConnection <nowiki>*</nowiki>connection <nowiki>=</nowiki> '''con_ic_connection_new'''();
''/* Connect signal to receive connection events */''
'''g_signal_connect'''('''G_OBJECT'''(connection), "connection-event",
'''G_CALLBACK'''(my_connection_handler), NULL);
''/* Request connection and check for the result */''
success <nowiki>=</nowiki> '''con_ic_connection_connect'''(connection, CON_IC_CONNECT_FLAG_NONE);
'''if''' (!success) '''g_warning'''("Request for connection failed");</tt>

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:

<tt>'''static''' void '''my_connection_handler'''(ConIcConnection <nowiki>*</nowiki>connection,
ConIcConnectionEvent <nowiki>*</nowiki>event,
gpointer user_data)
{
ConIcConnectionStatus status <nowiki>=</nowiki> '''con_ic_connection_event_get_status'''(event);
ConIcConnectionError error<nowiki>;</nowiki>
'''const''' gchar <nowiki>*</nowiki>iap_id <nowiki>=</nowiki> '''con_ic_event_get_iap_id'''('''CON_IC_EVENT'''(event));
'''const''' gchar <nowiki>*</nowiki>bearer <nowiki>=</nowiki> '''con_ic_event_get_bearer_type'''('''CON_IC_EVENT'''(event));
'''switch'''(status) {
'''case''' CON_IC_STATUS_CONNECTED<nowiki>:</nowiki>
'''g_debug'''("Hey, we are connected to IAP %s with bearer %s!", iap_id, bearer);
'''break'''<nowiki>;</nowiki>
'''case''' CON_IC_STATUS_DISCONNECTING<nowiki>:</nowiki>
'''g_debug'''("We are disconnecting...");
'''break'''<nowiki>;</nowiki>
'''case''' CON_IC_STATUS_DISCONNECTED<nowiki>:</nowiki>
'''g_debug'''("And we are disconnected. Let's see what went wrong...");
error <nowiki>=</nowiki> '''con_ic_connection_event_get_error'''(event);
'''switch'''(error) {
'''case''' CON_IC_CONNECTION_ERROR_NONE<nowiki>:</nowiki>
'''g_debug'''("Libconic thinks there was nothing wrong.");
'''break'''<nowiki>;</nowiki>
'''case''' CON_IC_CONNECTION_ERROR_INVALID_IAP<nowiki>:</nowiki>
'''g_debug'''("Invalid (non-existing?) IAP was requested.");
'''break'''<nowiki>;</nowiki>
'''case''' CON_IC_CONNECTION_ERROR_CONNECTION_FAILED<nowiki>:</nowiki>
'''g_debug'''("Connection just failed.");
'''break'''<nowiki>;</nowiki>
'''case''' CON_IC_CONNECTION_ERROR_USER_CANCELED<nowiki>:</nowiki>
'''g_debug'''("User canceled the connection attempt");
'''break'''<nowiki>;</nowiki>
}
'''break'''<nowiki>;</nowiki>
'''default'''<nowiki>:</nowiki>
'''g_debug'''("Unknown connection status received");
}
}</tt>

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

<tt> ''/* Create connection object */''
ConIcConnection <nowiki>*</nowiki>connection <nowiki>=</nowiki> '''con_ic_connection_new'''();
''/* Connect signal to receive connection events */''
'''g_signal_connect'''('''G_OBJECT'''(connection), "connection-event",
'''G_CALLBACK'''(my_connection_handler), NULL);
''/* Set automatic events */''
'''g_object_set'''('''G_OBJECT'''(connection), "automatic-connection-events", TRUE, NULL);</tt>

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 reiterated in order to receive the event. If you need the connection status information synchronously, you can iterate the main loop yourself:

<tt>'''static''' void '''connection_info'''(ConIcConnection <nowiki>*</nowiki>connection,
ConIcConnectionEvent <nowiki>*</nowiki>event,
gpointer user_data)
{
ConIcConnectionStatus status <nowiki>=</nowiki> '''con_ic_connection_event_get_status'''(event);
ConIcConnectionStatus <nowiki>*</nowiki>status_ptr <nowiki>=</nowiki> (ConIcConnectionStatus<nowiki>*)</nowiki>user_data<nowiki>;</nowiki>
<nowiki>*</nowiki>status_ptr <nowiki>=</nowiki> status<nowiki>;</nowiki>
}
''/* ... */''
''/* Create connection object and set on automatic events (see previous snippet) ... */''
'''static''' ConIcConnectionStatus status <nowiki>=</nowiki> 0xFFFF<nowiki>;</nowiki>
ConIcConnection <nowiki>*</nowiki>connection <nowiki>=</nowiki> '''con_ic_connection_new'''();
'''g_signal_connect'''('''G_OBJECT'''(connection), "connection-event",
'''G_CALLBACK'''(connection_info), &status);
'''g_object_set'''('''G_OBJECT'''(Connection), "automatic-connection-events", TRUE, NULL);
''/* Iterate main loop for the first connection event */''
'''while''' (status <nowiki>==</nowiki> 0xFFFF) '''g_main_context_iteration'''(NULL, TRUE);
'''if''' (status <nowiki>==</nowiki> CON_IC_STATUS_CONNECTED)
'''g_debug'''("We are connected!");
'''else'''
'''g_debug'''("We are not connected!");</tt>

==== Receiving Statistics of Connection ====
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.

<tt>'''static''' void '''connection_statistics'''(ConIcConnection <nowiki>*</nowiki>connection,
ConIcStatisticsEvent <nowiki>*</nowiki>event,
gpointer user_data)
{
'''g_debug'''("Here are all kind of nice statistics about the connection:");
'''g_debug'''("Time active: %u, signal strength: %u, received packets: %llu, "
"sent packets: %llu, received bytes: %llu, sent bytes: %llu",
'''con_ic_statistics_event_get_time_active'''(event),
'''con_ic_statistics_event_get_signal_strength'''(event),
'''con_ic_statistics_event_get_rx_packets'''(event),
'''con_ic_statistics_event_get_tx_packets'''(event),
'''con_ic_statistics_event_get_rx_bytes'''(event),
'''con_ic_statistics_event_get_tx_bytes'''(event));
}
''/* ... */''
''/* ConIcConnection object named "connection" has already been created */''
'''g_signal_connect'''('''G_OBJECT'''(connection), "statistics",
'''G_CALLBACK'''(connection_statistics), NULL);
'''if''' (!'''con_ic_connection_statistics'''(connection ,NULL))
'''g_warning'''("Requesting connection statistics failed!");</tt>

==== Getting Proxy Settings ====
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.
** Use of auto configuration URL is explained in [http://en.wikipedia.org/wiki/Proxy_auto-config Wikipedia]

In this example, the "connection-event" handler is modified to print HTTP proxy settings when establishing connection:

<tt>'''static''' void '''my_connection_handler'''(ConIcConnection <nowiki>*</nowiki>connection,
ConIcConnectionEvent <nowiki>*</nowiki>event,
gpointer user_data)
{
ConIcConnectionStatus status <nowiki>=</nowiki> '''con_ic_connection_event_get_status'''(event);
GSList <nowiki>*</nowiki>ignore_hosts<nowiki>;</nowiki>

'''if''' (status <nowiki>==</nowiki> CON_IC_STATUS_CONNECTED) {
'''g_debug'''("We are connected! \
Let's see what kind of settings we have for HTTP proxy...");

''/* Do things based on specified proxy mode */''
'''switch''' ('''con_ic_connection_get_proxy_mode'''(connection)) {

'''case''' CON_IC_PROXY_MODE_NONE<nowiki>:</nowiki>
'''g_debug'''("No proxies defined, it is direct connection");
'''break'''<nowiki>;</nowiki>

'''case''' CON_IC_PROXY_MODE_MANUAL<nowiki>:</nowiki>
'''g_debug'''("HTTP proxy %s:%d in use",
'''con_ic_connection_get_proxy_host'''(connection, CON_IC_PROXY_PROTOCOL_HTTP),
'''con_ic_connection_get_proxy_port'''(connection, CON_IC_PROXY_PROTOCOL_HTTP));

'''g_debug'''("List of hosts, for which proxy should not be used:");
ignore_hosts <nowiki>=</nowiki> '''con_ic_connection_proxy_ignore_hosts'''(connection);
'''for''' (GSList <nowiki>*</nowiki>iter <nowiki>=</nowiki> ignore_hosts<nowiki>;</nowiki> iter <nowiki>!=</nowiki> NULL<nowiki>;</nowiki> iter <nowiki>=</nowiki> '''g_slist_next'''(iter))
{
'''g_debug'''("%s", (gchar <nowiki>*)</nowiki>iter->data);
'''g_free'''(iter->data);
}
'''g_slist_free'''(ignore_hosts);
'''break'''<nowiki>;</nowiki>

'''case''' CON_IC_PROXY_MODE_AUTO<nowiki>:</nowiki>
'''g_debug'''("Proxy auto-config URL %s should be used",
'''con_ic_connection_get_proxy_autoconfig_url'''(connection));
'''break'''<nowiki>;</nowiki>
}
}
}</tt>

Proxy functions also exist for each individual protocol (like ''con_ic_connection_get_proxy_ftp_host()''), but these functions are deprecated. Avoid them in newly-written code.

====Getting List of User-Saved Connections ====
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:

<tt> ''/* ConIcConnection object named "connection" has already been created */''
GSList <nowiki>*</nowiki>saved_iaps <nowiki>=</nowiki> '''con_ic_connection_get_all_iaps'''(connection);
'''g_debug'''("The following connections have been saved by the user:");
'''for''' (GSList <nowiki>*</nowiki>iter <nowiki>=</nowiki> saved_iaps<nowiki>;</nowiki> iter <nowiki>!=</nowiki> NULL<nowiki>;</nowiki> iter <nowiki>=</nowiki> '''g_slist_next'''(iter)) {
''/* Get IAP object and print some information about it */''
ConIcIap <nowiki>*</nowiki>iap <nowiki>=</nowiki> (ConIcIap <nowiki>*)</nowiki>iter->data<nowiki>;</nowiki>
'''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);</tt>

==== Porting Application from OSSO IC API to Libconic ====
* If the application does not have GType, GLib or D-BUS configured, set them up:
<tt> DBusConnection <nowiki>*</nowiki>system_dbus<nowiki>;</nowiki>
GMainLoop <nowiki>*</nowiki>main_loop<nowiki>;</nowiki>
'''g_type_init'''();
main_loop <nowiki>=</nowiki> '''g_main_loop_new'''(NULL, FALSE);
system_dbus <nowiki>=</nowiki> '''dbus_bus_get'''(DBUS_BUS_SYSTEM, NULL);
'''dbus_connection_setup_with_g_main'''(system_dbus, NULL);</tt>
* Include the correct header file:
<tt>''' #include''' <osso-ic.h>
<nowiki>===></nowiki>
''' #include''' <conic.h></tt>
* Set up ''ConIcConnection'' object and "connection-event" handler instead of ''osso_iap_cb_t'' callback:
<tt> '''static''' void '''my_connection_cb'''('''struct''' iap_event_t <nowiki>*</nowiki>event, void <nowiki>*</nowiki>arg)
{
''/* ... */''
}
''/* ... */''
'''osso_iap_cb'''(my_connection_cb);
<nowiki>===></nowiki>
'''static''' void '''my_connection_cb'''(ConIcConnection <nowiki>*</nowiki>connection,
ConIcConnectionEvent <nowiki>*</nowiki>event,
gpointer user_data)
{
''/* ... */''
}
''/* ... */''
ConIcConnection <nowiki>*</nowiki>connection <nowiki>=</nowiki> '''con_ic_connection_new'''();
'''g_signal_connect'''('''G_OBJECT'''(connection), "connection-event",
'''G_CALLBACK'''(my_connection_cb), app_data);</tt>
* Manage connections through ''ConIcConnection'' API instead of ''osso_iap_connect()'' and ''osso_iap_disconnect()''<nowiki>: </nowiki>
<tt> '''osso_iap_connect'''(OSSO_IAP_ANY, OSSO_IAP_REQUESTED_CONNECT, app_data);
'''osso_iap_disconnect'''(iap_name, app_data);
<nowiki>===></nowiki>
'''con_ic_connection_connect'''(connection, CON_IC_CONNECT_FLAG_NONE);
'''con_ic_connection_disconnect'''(connection);</tt>
* Request statistics with ''con_ic_connection_statistics()'' instead of ''osso_iap_get_statistics()''.
* List all available IAPs with ''con_ic_connection_get_all_iaps()'' instead of ''osso_iap_get_configured_iaps()''.
* Configure autoconf to use Libconic instead of OSSO IC API:
<tt> PKG_CHECK_MODULES(OSSOIC, osso-ic)
AC_SUBST(OSSOIC_CFLAGS)
AC_SUBST(OSSOIC_LIBS)
<nowiki>===></nowiki>
PKG_CHECK_MODULES(CONIC, conic)
AC_SUBST(CONIC_CFLAGS)
AC_SUBST(CONIC_LIBS)</tt>
* In debian/control file "Build-Depends" section, depend on libconic0-dev instead of osso-ic-dev.

==Bluetooth Libraries ==
This section explains how maemo Bluetooth libraries work internally. The following subsections explain the behavior and the decomposition of the Bluetooth library components in detail.

=== Libgwobex ===
Libgwobex provides access to libopenobex functionality by providing a helper/wrapper interface. Libopenobex is explained in detail in the following section.

The interface to libgwobex is available at [http://maemo.org/api_refs/4.1/osso-gwobex-0.60/index.html GW OBEX Library Documentation].

===Creating Connection ===
The connection with libgwobex is established using the gw_obex_setup_dev function, setting up the connection. gw-obex.h

<tt>'''<nowiki>#define</nowiki>''' OBEX_FTP_UUID \
"\xF9\xEC\x7B\xC4\x95\x3C\x11\xD2\x98\x4E\x52\x54\x00\xDC\x9E\x09"
'''<nowiki>#define</nowiki>''' OBEX_FTP_UUID_LEN 16

''/* ... */''

GwObex<nowiki>*</nowiki> '''gw_obex_setup_dev''' ('''const''' gchar <nowiki>*</nowiki> device, '''const''' gchar <nowiki>*</nowiki> uuid, gint uuid_len,
GMainContext <nowiki>*</nowiki> context, gint <nowiki>*</nowiki> error )</tt>

The following code snippet illustrates how to open a handle using gw_obex_setup_dev.

<tt>'''if''' (ctx->rfcomm_dev) {
'''if''' (ctx->use_ftp)
ctx->obex <nowiki>=</nowiki> '''gw_obex_setup_dev'''(ctx->rfcomm_dev,
OBEX_FTP_UUID, OBEX_FTP_UUID_LEN,
NULL, &err);
'''else'''
ctx->obex <nowiki>=</nowiki> '''gw_obex_setup_dev'''(ctx->rfcomm_dev, NULL,
0, NULL, &err);

'''if''' (ctx->obex <nowiki>==</nowiki> NULL)
'''printf'''("OBEX setup failed: %s\n", '''response_to_string'''(err));
}</tt>

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.

===Closing Connection ===
To close a gwobex connection, use the following function: gw-obex.h

<tt>void '''gw_obex_close''' ( GwObex <nowiki>*</nowiki> ctx );</tt>

The following code demonstrates this usage.

<tt>'''if''' (ctx->obex) {
'''gw_obex_close'''(ctx->obex);
ctx->obex <nowiki>=</nowiki> NULL<nowiki>;</nowiki>
}</tt>

If ctx->obex is not NULL, it is simply passed as an argument to gw_obex_close().

===Using Connection ===
The libgwobex library provides general file handling functionality, including reading directory structure, browsing in different folders and getting files.

To read entries from an opened directory, use the following function: gw-obex.h

<tt>gboolean '''gw_obex_read_dir''' (GwObex <nowiki>*</nowiki> ctx,
'''const''' gchar <nowiki>*</nowiki> dir,
gchar <nowiki>**</nowiki> buf,
gint <nowiki>*</nowiki> buf_size,
gint <nowiki>*</nowiki> error );</tt>

gw_obex_read_dir reads an entry from the selected folder and returns the result in the buf argument given to the function.

<tt>gboolean ret<nowiki>;</nowiki>
''/* ... */''
ret <nowiki>=</nowiki> '''gw_obex_read_dir'''(ctx->obex, dir, buf, buf_size, err);</tt>

This reads an entry from the directory dir (char *) and returns it in buf (char **).

To change the current directory, use the following function: gw-obex.h

<tt>gboolean '''gw_obex_chdir''' (GwObex <nowiki>*</nowiki> ctx, '''const''' gchar <nowiki>*</nowiki> dir, gint <nowiki>*</nowiki> error );</tt>

which changes the directory of the FTP connection. Below is a code example using this function.

<tt>''/* Ignore parent dir pointers */''
'''if''' ('''g_str_equal'''(name, ".."))
'''return''' TRUE<nowiki>;</nowiki>

'''if''' (!'''gw_obex_chdir'''(ctx->obex, name, err)) {
'''printf'''("Could not chdir to %s\n", name);
'''return''' FALSE<nowiki>;</nowiki>
}</tt>

To retrieve files over the OBEX connection, use the gw_obex_get_file function: gw-obex.h

<tt>gboolean '''gw_obex_get_file''' (GwObex <nowiki>*</nowiki> ctx,
'''const''' gchar <nowiki>*</nowiki> local,
'''const''' gchar <nowiki>*</nowiki> remote,
'''const''' gchar <nowiki>*</nowiki> type,
gint <nowiki>*</nowiki> error);
</tt>

gw_obex_get_file uses the ctx context for retrieving the remote file to local file.

<tt>gboolean ret<nowiki>;</nowiki>
ret <nowiki>=</nowiki> '''gw_obex_get_file'''(ctx->obex, name, name, err);</tt>

Using the libwobex wrapper directly allows you to perform many more functions. For more information, see the [hhttp://maemo.org/api_refs/5.0/beta/osso-gwobex/ API document].

===Libopenobex ===
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/ http://www.irda.org]<nowiki>; select the Developer->Specifications category. OBEX resembles the HTTP protocol, expect for a few differences: </nowiki>

* 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.

For more information on OBEX, see the summary available at http://en.wikipedia.org/wiki/OBEX.

For libopenobex code samples, see http://openobex.triq.net/downloads<nowiki>; the samples are in the example apps package. </nowiki>

===Using BlueZ D-Bus API ===
The BlueZ system exports a D-Bus API that can be employed instead of OSSO Bluetooth tools. See the following documents:

* [http://git.kernel.org/?p=bluetooth/bluez.git;a=tree;f=doc;hb=HEAD BlueZ D-Bus API documentation]

==Connectivity UI ==

===UI Components ===
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.

===D-Bus Connectivity UI Interface ===
If the user must provide information about the IAP that the system is about to connect to, you can use the following method:

<div class="graybox">

Service: com.nokia.icd_ui
Interfaces: com.nokia.icd_ui
Object paths: /com/nokia/icd_ui

</div>

The Internet Connectivity UIs implement the following D-Bus API used by the ICd and EAP.

<div class="graybox">

Method: show_conn_dlg
Parameters: 1. boolean When TRUE the dialog is requested because
there were no saved connections (i.e. auto
connect was tried before invoking the dialog)
Return parameters: none
Errors: com.nokia.icd_ui.error.flight_mode:
Flight mode enabled, dialog not shown
Description: Shows the Connect Dialog where the user can choose an IAP.

</div>

<div class="graybox">

Method: show_disconnect_dlg
Parameters: none

Return Parameters: none
Errors: com.nokia.icd_ui.error.flight_mode:
Flight mode enabled, dialog not shown

Description: Shows the disconnect dialog.

</div>

<div class="graybox">

Method: show_retry_dlg
Parameters: 1. string Bluetooth address of the device used with SAP
2. string Name of the connection attempt error which
selects the retry dialog type.

Return Parameters: none
Errors: com.nokia.icd_ui.error.flight_mode:
Flight mode enabled, dialog not shown

Description: Shows the retry dialog.

</div>

<div class="graybox">

Method: show_change_dlg
Parameters: 1. string Name of the currently active IAP
2. string Name of the IAP to be activated

Return Parameters: none
Errors: com.nokia.icd_ui.error.flight_mode:
Flight mode enabled, dialog not shown

Description: Shows the Change IAP Dialog

</div>

<div class="graybox">

Method: show_passwd_dlg
Parameters: 1. string Username supplied by ICd
2. string Password supplied by ICd
3. string Name of the IAP

Return Parameters: none
Errors: com.nokia.icd_ui.error.flight_mode:
Flight mode enabled, dialog not shown

Description: Shows the username/password dialog.

</div>

<div class="graybox">

Method: show_gtc_dlg
Parameters: 1. string GTC challenge string

Return Parameters: none
Errors: com.nokia.icd_ui.error.flight_mode:
Flight mode enabled, dialog not shown

Description: Shows EAP GTC challenge dialog.

</div>

<div class="graybox">

Method: show_mschap_change_dlg
Parameters: 1. string Supplied username
2. string Old password that is to be changed
3. string Name of the IAP

Return Parameters: none
Errors: com.nokia.icd_ui.error.flight_mode:
Flight mode enabled, dialog not shown

Description: Shows EAP MSCHAPv2 change password dialog.

</div>

<div class="graybox">

Method: show_private_key_passwd_dlg
Parameters: 1. byte array Certificate ID

Return Parameters: none
Errors: com.nokia.icd_ui.error.flight_mode:
Flight mode enabled, dialog not shown

Description: Shows EAP private key password dialog

</div>

<div class="graybox">

Method: show_server_cert_dlg
Parameters: 1. string Certificate name
2. string Certificate serial
3. boolean TRUE if certificate is expired, FALSE otherwise
4. boolean TRUE if root CA is unknown or self-signed
certificate, FALSE otherwise

Return Parameters: none
Errors: com.nokia.icd_ui.error.flight_mode:
Flight mode enabled, dialog not shown

Description: 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.

</div>

<div class="graybox">

Method: strong_bt_req
Parameters: 1. string Bluetooth address of the device to pair with
2. boolean TRUE if strong authentication enabled, FALSE
if strong authentication is disabled

Return Parameters: none
Errors: com.nokia.icd_ui.error.flight_mode:
Flight mode enabled, dialog not shown

Description: Requests strong (16 digit) BT PIN dialog for a BT device

</div>

<div class="graybox">

Method: show_sim_pin_dlg
Parameters: 1. string Bluetooth address of the device used with SAP
2. boolean TRUE if PIN was incorrect and retry dialog
should be displayed before asking PIN. FALSE
if this is the first PIN request.

Return Parameters: none
Errors: com.nokia.icd_ui.error.flight_mode:
Flight mode enabled, dialog not shown

Description: Shows SIM PIN dialog

</div>

The code example for the application to show the connect dialog using show_conn_dlg is following. Note the use of the macro.

<tt>'''<nowiki>#include</nowiki>''' <osso-ic-ui-dbus.h>
''/* ... */''
''/* in our code somewhere, where we need the Connect Dialog*/''
DBusMessage <nowiki>*</nowiki>uimsg<nowiki>;</nowiki>
''/* construct the message for Connect Dialog request*/''
uimsg <nowiki>=</nowiki>
'''dbus_message_new_method_call'''(ICD_UI_DBUS_SERVICE,
ICD_UI_DBUS_PATH,
ICD_UI_DBUS_INTERFACE,
''/*macro for show_conn_dlg */''
ICD_UI_SHOW_CONNDLG_REQ);
''/* send the message */''
reply <nowiki>=</nowiki>
'''dbus_connection_send_with_reply_and_block'''(connection,
uimsg,
reply_timeout,
&error);
'''if''' (reply <nowiki>==</nowiki> NULL) {
'''DLOG_ERR'''("Failed to show connect dialog: %s", uierror.message);
'''dbus_error_free'''(&uierror);
}
'''dbus_message_unref'''(uimsg);
'''dbus_message_unref'''(reply);
''/* ... */''</tt>

The signals emitted from com.nokia.icd_ui interface are listed below.

<div class="graybox">

Signal: disconnect
Parameters: 1. boolean TRUE if "disconnect" pressed, FALSE if "cancel"

Description: Signal emitted from UI when disconnect dialog has been closed.

</div>

<div class="graybox">

Signal: retry
Parameters: 1. string The IAP that is to be retried
2. boolean TRUE if "retry" pressed, FALSE if "cancel"

Description: Signal emitted from UI when the retry dialog has been closed.

</div>

 

<div class="graybox">

Signal: change
Parameters: 1. string Old IAP to change from
2. string New IAP to change to
3. boolean Change to the new IAP If TRUE, keep old if FALSE

Description: Signal emitted from UI when change connection dialog has
been closed.

</div>

<div class="graybox">

Signal: passwd
Parameters: 1. string Username supplied or modified by the user
2. string Password supplied or modified by the user
3. string IAP name
4. boolean TRUE if "ok" pressed, FALSE if "cancel"

Description: Signal emitted from UI when the username/password dialog has
been closed

</div>

<div class="graybox">

Signal: gtc_response
Parameters: 1. string Response to the given challenge or empty string
if cancelled
2. boolean TRUE if "ok" pressed, FALSE if "cancel"

Description: Signal emitted from UI when the EAP GTC challenge dialog has
been closed.

</div>

<div class="graybox">

Signal: mschap_change
Parameters: 1. string Supplied username
2. string The new password or empty string if cancelled
3. string IAP name
4. boolean TRUE if "ok" pressed, FALSE if "cancel"

Description: Signal emitted from UI when the MSCHAPv2 password has been
changed

</div>

<div class="graybox">

Signal: private_key_passwd
Parameters: 1. byte array Certificate ID
2. string Password for the private key or empty string if none
3. boolean TRUE if "ok" pressed, FALSE if "cancel"

Description: Signal emitted from UI when the private key password dialog
has been closed

</div>

<div class="graybox">

Signal: server_cert
Parameters: 1. boolean TRUE if strong PIN entered, FALSE if strong
PIN dialog was canceled

Description: Signal emitted from UI when the server certificate error
dialog has been closed

</div>

 

<div class="graybox">

Signal: strong_bt
Parameters: 1. boolean TRUE if strong PIN entered, FALSE if strong
PIN dialog was cancelled

Description: Signal emitted from UI when the strong (16 digit) BT PIN
has been entered

</div>

<div class="graybox">

Signal: sim_pin
Parameters: 1. string SIM PIN code or empty string if cancelled
2. boolean TRUE if "ok" pressed, FALSE if "cancel"

Description: Signal emitted from UI when the SIM PIN has been entered.

</div>

===Bluetooth DBUS UI dialogs ===

conbtdialogs-dbus.h

<tt>''/** ''
'' Example of use (command line):''
'' ''
'' dbus-send --system --print-reply \''
'' --dest='com.nokia.icd_ui' /com/nokia/bt_ui \''
'' com.nokia.bt_ui.show_send_file_dlg \''
'' array:string:''file:///home/user/MyDocs/.documents/testing.txt
'' ''
'' dbus-send --system --print-reply \''
'' --dest=com.nokia.bt_ui /com/nokia/bt_ui ''
'' com.nokia.bt_ui.show_search_dlg \''
'' string: string: array:string: string:''
''<nowiki>*/</nowiki>''

'''<nowiki>#ifndef</nowiki>''' CONBTDIALOGS_DBUS_H
'''<nowiki>#define</nowiki>''' CONBTDIALOGS_DBUS_H

'''<nowiki>#ifdef</nowiki>''' __cplusplus
'''extern''' "C" {
'''<nowiki>#endif</nowiki>'''

''/** Conbtdialogs service, resides in system dbus */''
'''<nowiki>#define</nowiki>''' CONBTDIALOGS_DBUS_SERVICE "com.nokia.bt_ui"
''/** Conbtdialogs interface */''
'''<nowiki>#define</nowiki>''' CONBTDIALOGS_DBUS_INTERFACE "com.nokia.bt_ui"
''/** Conbtdialogs path */''
'''<nowiki>#define</nowiki>''' CONBTDIALOGS_DBUS_PATH "/com/nokia/bt_ui"

''/** ''
'' Show send file dialog''
'' ''
'' Arguments:''
'' ''
'' uris: DBUS_TYPE_ARRAY Array of strings representing the URIs of the''
'' files to send.''
'' ''
'' Returns:''
'' ''
'' DBUS_TYPE_BOOLEAN TRUE, if dialog was shown successfully.''
'' */''
'''<nowiki>#define</nowiki>''' CONBTDIALOGS_SEND_FILE_REQ "show_send_file_dlg"

''/** ''
'' File sending result signal''
'' ''
'' Arguments:''
'' ''
'' success: DBUS_TYPE_BOOLEAN TRUE, if all files were sent successfully or''
'' FALSE, if error occurred or sending was ''
'' canceled.''
'' */''
'''<nowiki>#define</nowiki>''' CONBTDIALOGS_SEND_FILE_SIG "send_file"

''/** ''
'' Show BT device search dialog''
'' ''
'' Arguments:''
'' ''
'' major_class: DBUS_TYPE_STRING To set filtering based on major_class or''
'' "". Possible major class values are:''
'' ''
'' "miscellaneous", "computer", "phone", ''
'' "access point", "audio/video", ''
'' "peripheral", "imaging", "wearable",''
'' "toy" and "uncategorized".''
'' ''
'' minor_class: DBUS_TYPE_STRING To set filtering based on minor_class or "".''
'' Possible minor class values are:''
'' ''
'' - Minor classes for "computer": ''
'' "uncategorized", "desktop", "server",''
'' "laptop", "handheld", "palm", "wearable"''

'' - Minor classes for "phone": "uncategorized",''
'' "cellular", "cordless", "smart phone",''
'' "modem", "isdn"''
'' ''
'' service_classes: DBUS_TYPE_ARRAY To set filtering based on service classes.''
'' Supported classes include "positioning", ''
'' "networking", "rendering", "capturing",''
'' "object transfer", "audio", "telephony", ''
'' "information". Can be empty list, when no''
'' service class filtering is performed.''
'' ''
'' bonding: DBUS_TYPE_STRING Bonding mode for found and selected device:''
'' ''
'' "require" for requiring a bonding from a''
'' selected device (i.e. bond device if it has not''
'' been bonded before). ''
'' ''
'' "force" to always bond (i.e. device will be''
'' bonded even if bonded before).''
'' ''
'' Any other string will allow to search and''
'' select device without bonding it.''
'' ''
'' Returns:''
'' ''
'' DBUS_TYPE_BOOLEAN TRUE, if dialog was shown successfully.''
'' */''
'''<nowiki>#define</nowiki>''' CONBTDIALOGS_SEARCH_REQ "show_search_dlg"

''/** ''
'' Bluetooth search result signal''
'' ''
'' Arguments:''
'' ''
'' address: DBUS_TYPE_STRING Bluetooth address of the selected device, or ""''
'' if search dialog was cancelled.''
'' ''
'' name: DBUS_TYPE_STRING Name of the device.''
'' ''
'' icon: DBUS_TYPE_STRING Logical name for the icon describing the ''
'' device.''
'' ''
'' major_class: DBUS_TYPE_STRING Major class of the device.''
'' ''
'' minor_class: DBUS_TYPE_STRING Minor class of the device.''
'' ''
'' trusted: DBUS_TYPE_BOOLEAN Defines whether the device is marked as a trusted device.''
'' ''
'' services: DBUS_TYPE_ARRAY List of strings describing the service classes''
'' and SDP-based services provided by the device.''
'' */''
'''<nowiki>#define</nowiki>''' CONBTDIALOGS_SEARCH_SIG "search_result"
</tt>

 

<tt>''/**''
'' Bluetooth UI Library for maemo''

'' Copyright (C) 2006 Nokia. All rights reserved.''
'' ''
'' This sample demonstrates the use of conbtdialogs API and especially ''
'' send_file function. Compile the program with conbtdialogs and dbus:''
'' ''
'' gcc -Wall `pkg-config -libs -cflags dbus-glib-1 conbtdialogs` \''
''-o send_file conbtdialogs_send_file.c''
'' ''
'' Run with list of URLS:''
'' ''
'' ./send_file ''file:///home/user/MyDocs/.sounds/Everyday.mp3
''<nowiki>*/</nowiki>''

'''<nowiki>#define</nowiki>''' DBUS_API_SUBJECT_TO_CHANGE

'''<nowiki>#include</nowiki>''' <glib.h>
'''<nowiki>#include</nowiki>''' <conbtdialogs-dbus.h>
'''<nowiki>#include</nowiki>''' <dbus/dbus.h>
'''<nowiki>#include</nowiki>''' <dbus/dbus-glib.h>

DBusGConnection <nowiki>*</nowiki>connection <nowiki>=</nowiki> NULL<nowiki>;</nowiki>
GMainLoop <nowiki>*</nowiki>mainloop <nowiki>=</nowiki> NULL<nowiki>;</nowiki>

'''static''' gboolean '''initialize'''(void)
{
GError <nowiki>*</nowiki>error <nowiki>=</nowiki> NULL<nowiki>;</nowiki>

'''g_type_init''' ();

''/* Create main loop */''
mainloop <nowiki>=</nowiki> '''g_main_loop_new'''(NULL, TRUE);
'''if''' ( mainloop <nowiki>==</nowiki> NULL ) '''return''' FALSE<nowiki>;</nowiki>

''/* Create DBUS connection */''
connection <nowiki>=</nowiki> '''dbus_g_bus_get'''(DBUS_BUS_SYSTEM, &error);

'''if''' (connection <nowiki>==</nowiki> NULL )
{
'''g_print''' ("Error: %s\n", error->message);
'''g_clear_error''' (&error);
'''return''' FALSE<nowiki>;</nowiki>
}

'''return''' TRUE<nowiki>;</nowiki>
}

'''static''' gboolean '''uninitialize'''(void)
{
''/* Quit main loop and unref it */''
'''if''' (mainloop <nowiki>!=</nowiki> NULL)
{
'''g_main_loop_quit'''(mainloop);
'''g_main_loop_unref'''(mainloop);
}

'''return''' TRUE<nowiki>;</nowiki>
}

'''static''' DBusHandlerResult '''file_sent_signal''' ( DBusConnection <nowiki>*</nowiki>connection,
DBusMessage <nowiki>*</nowiki>message,
void <nowiki>*</nowiki>data )
{
gboolean success <nowiki>=</nowiki> FALSE<nowiki>;</nowiki>

''/* check signal */''
'''if''' (!'''dbus_message_is_signal'''(message,
CONBTDIALOGS_DBUS_INTERFACE,
CONBTDIALOGS_SEND_FILE_SIG))
'''return''' DBUS_HANDLER_RESULT_NOT_YET_HANDLED<nowiki>;</nowiki>

''/* get args */''
'''if''' ( <nowiki>!</nowiki>'''dbus_message_get_args''' ( message, NULL,
DBUS_TYPE_BOOLEAN, &success,
DBUS_TYPE_INVALID ) )
'''return''' DBUS_HANDLER_RESULT_NOT_YET_HANDLED<nowiki>;</nowiki>

''/* print if file sending was success or failure */''
'''g_print''' ( "File sending was a " );

'''if''' (success) '''g_print'''("success\n"); '''else''' '''g_print'''("failure\n");
'''dbus_connection_close'''(connection);
'''uninitialize'''();

'''return''' DBUS_HANDLER_RESULT_HANDLED<nowiki>;</nowiki>
}

gint '''main'''(gint argc, gchar <nowiki>**</nowiki>argv)
{
GError <nowiki>*</nowiki>error <nowiki>=</nowiki> NULL<nowiki>;</nowiki>
gchar <nowiki>**</nowiki>files <nowiki>=</nowiki> NULL<nowiki>;</nowiki>
gint idx <nowiki>=</nowiki> 0<nowiki>;</nowiki>
DBusGProxy <nowiki>*</nowiki>proxy<nowiki>;</nowiki>
DBusConnection <nowiki>*</nowiki>sys_conn<nowiki>;</nowiki>
gchar <nowiki>*</nowiki>filter_string <nowiki>=</nowiki> NULL<nowiki>;</nowiki>

'''if''' (argc < 2) '''return''' 1<nowiki>;</nowiki>

'''if''' ('''initialize'''() <nowiki>==</nowiki> FALSE) {
'''uninitialize'''();
'''return''' 1<nowiki>;</nowiki>
}

''/* Copy urls to GLib compatible char array */''
files <nowiki>=</nowiki> '''g_new0'''(gchar<nowiki>*,</nowiki> argc);

'''for''' (idx <nowiki>=</nowiki> 1<nowiki>;</nowiki> idx < argc<nowiki>;</nowiki> idx++)
files[idx-1] <nowiki>=</nowiki> '''g_strdup'''(argv[idx]);

files[argc-1] <nowiki>=</nowiki> NULL<nowiki>;</nowiki>

''/* Open connection for btdialogs service */''
proxy <nowiki>=</nowiki> '''dbus_g_proxy_new_for_name'''(connection,
CONBTDIALOGS_DBUS_SERVICE,
CONBTDIALOGS_DBUS_PATH,
CONBTDIALOGS_DBUS_INTERFACE);

''/* Send send file request to btdialogs service */''
'''if''' (!'''dbus_g_proxy_call'''(proxy, CONBTDIALOGS_SEND_FILE_REQ,
&error,
G_TYPE_STRV, files, G_TYPE_INVALID,
G_TYPE_INVALID))
{
'''g_print'''("Error: %s\n", error->message);
'''g_clear_error'''(&error);
'''g_strfreev''' (files);
'''g_object_unref'''('''G_OBJECT'''(proxy));
'''uninitialize'''();
'''return''' 1<nowiki>;</nowiki>
}
'''g_strfreev''' (files);
files <nowiki>=</nowiki> NULL<nowiki>;</nowiki>

'''g_object_unref'''('''G_OBJECT'''(proxy));

''/* Now wait for file sent signal, use low level bindings as glib ''
'' bindings require signal marshaller registered */''
sys_conn <nowiki>=</nowiki> '''dbus_bus_get'''(DBUS_BUS_SYSTEM, NULL);
'''g_assert'''('''dbus_connection_add_filter'''(sys_conn,
file_sent_signal,
NULL,
NULL ));
filter_string <nowiki>=</nowiki>
'''g_strdup_printf''' ("type='signal',interface='%s'", CONBTDIALOGS_DBUS_INTERFACE);

'''dbus_bus_add_match'''(sys_conn, filter_string, NULL);
'''dbus_connection_unref'''(sys_conn);

''/* Run mainloop */''
'''g_main_loop_run'''(mainloop);

'''return''' 0<nowiki>;</nowiki>
}</tt>

Maemo Summit 2009/Schedule/Day 1

2009-10-07T05:06:30Z

80.242.16.1: /* Feedservice and plug-ins development in Maemo 5 */

=== Maemo 5 and the Nokia N900 ===
* Presenter: Ari Jaaksi, VP Maemo Devices, Nokia

* Abstract: Maemo 5 is a major milestone of the evolution of Maemo. Maemo 5 delivers computer experiences to pocket-sized devices. It is about six weeks ago that the Nokia N900 was launched and it is time to take a look where we are now with the N900. For newcomers in the community, Ari will summarize the evolution of Maemo. He will tell how we built the N900, together with the community, giving insight to what happened behind the scenes in the last 18 months. Ari will outline on what we focused on when we redesigned the user experience from Maemo 4 to Maemo 5.

=== Changing PC & Mobile Landscape; Why Linux will play a Critical Role ===
* Presenter: Jim Zemlin, Executive Director of the Linux Foundation

* Abstract: Jim Zemlin will discuss how the PC and mobile market are merging and how Linux is ideally suited for the new range of devices that are coming to a converged world.
: In addition he will speak about how the PC and mobile device industry is switching towards a service economy and how utilizing open source allows organizations to reap profits in a range of services. Finally, he will address the kind of user experiences that Linux is ideal for enabling. He will cover the need for social networking API's to be mapped out by the community on a region by region basis in order to enable a better web experience on Linux devices and how the web can be integrated into a native UI with Linux and provide an entirely new take on how we define the PC.

=== Nokia Nseries Devices on Maemo===
* Presenter: Jose-Luis Martinez Merino, VP, Marketing, Nokia

* Abstract: Jose-Luis will explain which role Maemo-based Nseries devices play in Nokia's portfolio.

=== Harmattan Highlights - Developer Opportunities ===
* Presenter: Janne Heikkinen, Director Maemo Product Planning, Nokia

* Abstract: Janne will go through what developer opportunities do exist for Maemo 5 and the N900. He will explain what tools are available and which means there are to get innovations to consumers. He will explain which key platform technologies the Harmattan release will include giving application and platform developers an insight on how to contribute to and benefit from the Harmattan release.

=== Why the Maemo Community matters to Nokia ===
* Inteviewer: Alan "qole" Bruce of the 2nd & 3rd Maemo Community Councils
* Interviewee: Ari Jaaksi, VP Maemo Devices, Nokia

* Abstract: This relaxed, informal interview will focus on how Nokia sees the current community contribution and engagement with Maemo Devices evolving in the next years. Questions on what could work better and what the community needs from Nokia will spice up this interview.

=== UI design of Maemo 5 apps ===
* Presenter: Digia/User Experience Team

* Abstract: coming soon

=== Developing widgets on Maemo 5 - showcase Foreca Weather ===
* Presenter: Juha Järvi, Software Designer, Foreca

* Abstract: This talk will go over some of the design considerations, development process and testing methodology for a Fremantle desktop widget and other software communicating with it. As an example, Foreca's desktop weather widget has been ported from Diablo to Fremantle with a new more complicated underlying architecture. Several parts need to communicate reacting to settings changes and receiving online data. Particularly power usage, certain regional settings and keeping all parts synchronized were new challenges. Some problems and solutions are shared for others to also learn from the experience.

=== Developing apps with Qt for Maemo5 ===
* Presenter: Kate Alhola, Forum Nokia, Chief Guru on Maemo

* Abstract: coming soon

=== Developing apps with Qt on Harmattan ===
* Presenter: Ville Lavonius, Product Manager Developer Offering, Nokia

* Abstract: coming soon

=== Developing apps with Nokia Web Runtime ===
* Presenter: Santtu Ahonen, Head of Developer Offering, Nokia

* Abstract: coming soon

=== Developer Support for Maemo by Forum Nokia ===
* Presenter: Matt Collins, Director, Forum Nokia Marketing

* Abstract: Forum Nokia is the world's largest mobile developer community; and is now embarking on a new and exciting transformation. Nokia is introducing Qt to both Symbian and Maemo platforms and, in addition, strengthening its leading Web Runtime (WRT) offering through Ovi services. Maemo developers will hear how Forum Nokia wikis, discussion boards, blogs and programs such as Champions and Launchpad will provide them the resources to learn Qt and also publish their applications to Ovi Store. This presentation will outline Forum Nokia's offerings, and our promise to developers for fostering an open cross-platform ecosystem.

=== UX panel ===
* Moderator: Tim Samoff, 2nd Maemo Community Council
* Panelists: Harri Kiljander, Director Maemo UX Design and Martin Schüle, Principal Designer Maemo 5

* Abstract: An interactive panel, discussing the User Experience in general, as well as User Experience on Maemo. Harri and Martin will discuss the goals of Maemo5 UI, and comment on the future UI directions for Maemo.

* Tim Samoff: Tim is an award-winning filmmaker and designer who has been working in various industries for almost 20 years. He's produced computer games, created brand identities, participated in several open source software projects, and designed innumerable websites. He has also played with several bands and has recorded three CDs, one that became the number one electronic album on mp3.com. Tim came to Maemo sometime between the 770 and the N800 and quickly became involved in helping users and developers in a variety of tablet-related issues. His first major contribution to the community was a document entitled, "An Unofficial Guide to Creating a Most Excellent Maemo User Interface." Since then, he has designed icons, logos, and user interfaces for Maemo-related projects. He also served two terms as a Maemo Community Council member.

* Harri Kiljander is leading the user experience design team in Maemo Devices in Nokia. Harri is a computer scientist who then moved into information visualization and human-computer interaction. Prior to this role, Harri has been responsible for Nokia's corporate user experience strategy, and working in various UX design management and research positions in Nokia's internet services, research and development, and brand management teams in Finland and in the USA. In Maemo, Harri has been driving the bridging of agile software development with human-centered design in product creation. Harri holds a Master's degree in Computer Science and a Ph.D. in Interactive Digital Media from Helsinki University of Technology, and he is a co-editor of the book "Mobile Usability: How Nokia Changed the Face of the Mobile Phone".

=== Firefox on Maemo ===
* Presenter: Stuart Parmenter, Director of Engineering, Mozilla

* Abstract: coming soon

=== Present and future of Maemo digital marketing ===
* Presenter: Isko Salminen, Production Manager, Activeark and Jussi Mäkinen, Maemo Marketing, Nokia

* Abstract: coming soon

=== Biz apps on Maemo ===
* Presenter: Kari Pikkarainen, Product Manager Productivity, Nokia

* Abstract: coming soon

=== Skype on Maemo ===
* Presenter: Mark Douglas, Mobile Product Manager, Skype

* Abstract: coming soon

=== Cross-platform with Qt - live ===
* Presenter: Ariya Hidayat, Software Engineer, Nokia

Ariya is a software engineer at Nokia, Qt Development Frameworks in Oslo. He is an open-source advocate for almost a decade, his code can be found in various projects such as KDE, WebKit, and of course Qt.

* Abstract:
As a powerful framework, Qt offers tons of modules and classes for building your applications. This talk highlight few practical cross-platform examples of what Qt can do with a fairly few lines of code, ranging from kinetic scrolling, weather service, OpenStreetMap, parallax effect, flight tracking, WYSIWYG HTML editor, and many more. All examples will be accompanied with corresponding '''live demos'''.

=== Mer - how the community innovates ===
* Presenter: Carsten Munk, Lead Developer, Mer project

* Abstract: As well as being a Fremantle backport for Nokia N8x0, Mer has been a project where we have tried to develop an organization inside the community with the aim of making the community an equal part in developing the Maemo platform. This talk will be about the methods used, challenges had and results made in creating this organization as well as how to motivate developers to contribute and keeping them motivated. Future role of Mer will also be discussed and suggestions how to step up the cooperation.

=== Your foundation for open-source innovation: TI’s OMAP processor-based Zoom platform ===
* Presenter: Ameet Suri, Marketing Manager, OMAP™ Mobile Communication and Computing Business Line, Wireless Business Unit, Texas Instruments.

As a marketing manager for the Texas Instruments Incorporated (TI) OMAP™ mobile communications and computing business line, Ameet Suri manages efforts surrounding TI’s OMAP processor strategy for the mobile communication and computing spaces. Suri and his team identify key trends to better define TI’s OMAP processors’ leading presence in a broad range of markets, including smartphones, mobile Internet devices (MIDs), tablets, net-tops and netbooks.

TI’s broad product portfolio provides the full range of power-optimized tools required to achieve success in the emerging mobile communication and computing markets – from applications processors, mobile connectivity solutions and analog components, to software solutions that deliver a compelling user experience. Suri and the OMAP processor team help customers best utilize those tools to deliver complete, differentiated products.

Suri began his career with TI in 2003. Recruited for his rich graphics expertise, he established the graphics software team for OMAP technologies at the beginning of his time with the company. In this position, Suri worked in OMAP software research and development, and contributed to the development of 3D software solutions for OMAP processors.

Suri previously held engineering positions at Samsung and Mastech. At these companies, he gained experience developing and architecting various software technologies for handsets.

Suri earned a bachelor’s degree in computer science from MGM College of Engineering and Technology in India.

* Abstract: As consumers increasingly demand “no-compromise” mobile Internet experiences and feature-packed devices, the role of the operating system continues to grow in importance, as does the presence of open architectures that spur innovative thinking. The Maemo platform continues to show itself as a solid, open foundation for this innovation, answering consumers’ demands for top-notch mobile experiences.

In this session, TI’s Ameet Suri will discuss Maemo’s presence in the open source world, and how TI’s Zoom OMAP34x-II Mobile Development Platform is a strong foundation for creating Maemo-based features and applications. Suri will also highlight the full tool set needed to reduce risks and grow investments with Maemo, and will touch on TI’s unique relationship with the Maemo community.

=== Feedservice and plug-ins development in Maemo 5 ===
* Presenter: Mikko Levonmaa, Ixonos

* Abstract: Present the feedservice ecosystem and how it will enable efficient authoring of home screen widgets for social networks feeds and other information sources that exist in the internet. The framework provides an abstraction layer for the plugins and utility services for the most common functionality. From the device point of view it will provide a single point of control for the feeds, it will determine, with the help from a plugin, when a feed should be run. The feedservice will also monitor the device states, such as network connection and screen activity. This enables the feedservice to optimize the user experience in terms of up-to-date feeds and power managemet.

=== Harmattan Architecture Overview ===
* Presenter: Juha Tukkinen, Principal Engineer, Architecture and Sys, Nokia

* Abstract: coming soon

=== Porting an OpenGL game to GL ES ===
* Presenter: Oliver Mcfadden, Software Engineer, Nokia

* Abstract: Presentation focusing on the challenges of porting OpenGL games to GL ES, including challenges above and beyond merely porting and optimizing the rendering engine. Quake 3 will be used as an example.

Mozilla Maemo Danish Weekend/Accommodation

2009-05-28T09:03:35Z

80.242.16.1:

We have booked 40 rooms (single or shared) at the [http://www.cabinn.com/english/kbh/scandinavia/sca.html Hotel Cabinn Scandinavia].

The sponsored participants (markd with a * ) are hosted in this hotel. The organization recommends to share rooms in order to have more budget available for further sponsorships. Other participants are encouraged to book here your rooms as well.

If you are listed alone in a room and you prefer to share it with another listed participant just edit the wiki page and do the change (providing your room mate is fine with the change). If you are alone in a room but welcoming a room mate please add a "-" next to your name. We really appreciate your efforts sharing rooms and allowing to have more beds sponsored within our budget.

If the rooms here are fully booked there is more information on alternative places to [[Mozilla Maemo Danish Weekend#Accommodation|stay]].

# Munk Carsten Valdemar
# Vasiliev Vlad
# Harbaum Till
# Võsandi Lauri
# Savola Sampo
# Henrichs Claudius
# Lima Eduardo -
# Mirestean Andrei - Popelo Andrey
# Bloom John - Harwell Adam
# Quim Gil - David Greaves
# Thomas Perl
# Marcell Lengyel
# Niels Breet
# Soumya Bijjal
# Garcia Alberto
# Janne Johansson
# Andre Klapper -
# Nicolas Belloni - Mattias Rost
# Vesa Pikki
# -
# -
# -
# -
# -
# -
# -
# -
# -
# -
# -

Mozilla Maemo Danish Weekend/Participants

2009-05-28T08:57:56Z

80.242.16.1:

This is a manual export of [http://events.mozilla-europe.org/event/?id=6 registered] participants of the [[Mozilla Maemo Danish Weekend]]. You can edit your own entry providing more information and links about you and your projects.

{| class="wikitable sortable"
|-
! #
! Name
! Organisation / Project
! Country
|-
| 1 || Chevrel Pascal || Mozilla Europe || France
|-
| 2 || foster jeremiah * || maemo.org team || Sweden
|-
| 3 || Munk Carsten Valdemar * || The Mer Project || Denmark
|-
| 4 || Combee Ben || Mozilla || United States
|-
| 5 || Gil Quim || Maemo SW @ Nokia || Finland
|-
| 6 || Ciesielska Malgorzata || CBS || Poland
|-
| 7 || Jongenburger Kees * || maemo.org council || Netherlands
|-
| 8 || Birkett Gary || liqbase || United Kingdom
|-
| 9 || Knudsen Lars || Nokia || Denmark
|-
| 10 || Camacho Ernesto || || Denmark
|-
| 11 || Hueppe Barbara || Mozilla / PR || Germany
|-
| 12 || Turquette Mike || || United States
|-
| 13 || Vasiliev Vlad * || OMWeather || Belarus
|-
| 14 || Klapper Andre || maemo.org / Openismus || Czech Republic
|-
| 15 || Breet Niels || maemo.org || Netherlands
|-
| 16 || Parmenter Stuart || Mozilla || United States
|-
| 17 || Quiviger William || Mozilla || France
|-
| 18 || Rouget Paul || Mozilla / Tech Evangelism || France
|-
| 19 || Harbaum Till * || OSM2Go || Germany
|-
| 20 || Greaves David * || Mer || United Kingdom
|-
| 21 || Schneider Peter || Maemo Marketing || Finland
|-
| 22 || Zolotarev Leonid || Nokia || Finland
|-
| 23 || Lepikhov Konstantin || Russian Mozilla Team || Russia
|-
| 24 || Gladkov Alexey || Mozilla Russia Team || Russia
|-
| 25 || Petrov Andrey || Nokia/Fennec || Finland
|-
| 26 || Cook James || || United Kingdom
|-
| 27 || Romashin Oleg || Nokia || Finland
|-
| 28 || Bergius Henri || Nemein - Midgard, GeoClue || Finland
|-
| 29 || Võsandi Lauri * || Maemo || Estonia
|-
| 30 || Savola Sampo * || eCoach || Finland
|-
| 31 || Garcia Alberto * || Vagalume || Spain
|-
| 32 || Henrichs Claudius * || Mer, OMWeather, OSM2Go || Germany
|-
| 33 || Lima Eduardo * || openBossa / Canola || Brazil
|-
| 34 || Mohring Martin || opensuse.org || Germany
|-
| 35 || Mirestean Andrei * || Maemo - Picasa plugin for Canola - GSoC Project || Romania
|-
| 36 || Popelo Andrey * || Maemo - GSoC project for Canola || Ukraine
|-
| 37 || Bloom John * || Mer || United States
|-
| 38 || Harwell Adam * || Maemo || United States
|-
| 39 || Kristoffersen Mike || Mozilla || Denmark
|-
| 40 || Iancu Mihai * || mYTube || Romania
|-
| 41 || Sejersen Christian || Mozilla Corp. || Denmark
|-
| 42 || Larsen Jakob Eg || Technical University of Denmark || Denmark
|-
| 43 || Lach Kamil || IHK/Mozilla Add-ons || Poland
|-
| 44 || Gemal Henrik || Mozilla Denmark || Denmark
|-
| 45 || Perl Thomas * || GPodder || Austria
|-
| 46 || King Brian * || Briks Software / Mozdev || Slovenia
|-
| 47 || Lengyel Marcell || Nokia || Finland
|-
| 48 || doe john || || null
|-
| 49 || Pawlak Blazej || Technical University of Denmark ||| Denmark
|-
| 50 || Cielecki Tomasz || || Denmark
|-
| 51 || Stopczynski Arkadiusz || DTU || Poland
|-
| 52 || Karpantschof David Ruben || PortaPlay || Denmark
|-
| 53 || Hansen Jesper || MozillaDanmark|| Denmark
|-
| 54 || Alring Fini || Deducta || Denmark
|-
| 55 || Sørensen Finn || MozillaDanmark / Babelzilla || Denmark
|-
| 56 || Pihlgren Petri || Ixonos || Denmark
|-
| 57 || Skokan Radek || || Czech Republic
|-
| 58 || Parodi Federico * || DownThemAll! || Italy
|-
| 59 || Maier Nils * || DownThemAll! || Germany
|-
| 60 || Dworzynski Piotr || || Poland
|-
| 61 || timeless || || Finland
|-
| 62 || Nagineni Sudarsana || Nokia || Finland
|-
| 63 || Søren Munk Skrøder || MozillaDanmark - l10n || Denmark
|-
| 64 || Bailleux Benoit * || project autoOpenID || France
|-
| 65 || Kristensen Jesper || MozillaDanmark || Denmark
|-
| 66 || Walling Bjarke || || Denmark
|-
| 67 || Hansen Klaus || || Denmark
|-
| 68 || Desré Fabrice * || || France
|-
| 69 || Neale Chris || || United Kingdom
|-
| 70 || Crowder Brian || Mozilla/Mobile || United States
|-
| 71 || Orosa Christinne || Student || Denmark
|-
| 72 || Thomas Adrian || || Denmark
|-
| 73 || Ngite René || IHK || null
|-
| 74 || Rost Mattias || Mobile Life || Sweden
|-
| 75 || von Klitzing Richard || Teleca Germany || Germany
|-
| 76 || Bauer Andreas || Teleca Germany || Germany
|-
| 77 || Zwart Marien || RadialContext-mz || Netherlands
|-
| 78 || Enros Madhava || Mozilla || Canada
|-
| 79 || Bijjal Soumya || Nokia || Finland
|-
| 80 || Johansson Janne || Nokia/Maemo || Finland
|-
| 81 || Bengoa David || Mozilla hispano || Spain
|-
| 82 || Kolodziejczyk Grzegorz || || Denmark
|-
| 83 || Bajor Jacek || || Poland
|-
| 84 || Slodkowicz Greg || || Denmark
|-
| 85 || Meshkova Tatiana || || Finland
|-
| 86 || Jensen Rene || || Denmark
|-
| 87 || Nicolas Belloni || Mobile Life Centre || Sweden
|-
| 88 || Pikki Vesa || Ixonos || Finland
|}

(*) Sponsored participants.