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

(Connectivity UI)
(Connectivity Subsystem: convert tables to definition lists)
 
(32 intermediate revisions not shown)
Line 1: Line 1:
-
= Maemo Connectivity =
+
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.
-
 
+
-
==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.
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===
+
===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)''' - LibConIC API works together with ICd, handling all Internet Access Points (IAPs). IC daemon handles both WLAN and GPRS connections.
+
* '''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.
-
'''OBEX wrapper''' - Interface to OBEX services. The primary target user of this library is the OBEX gnome-vfs module.
+
===Internet Access Points (IAP)===
-
'''OpenOBEX''' - Open source implementation of the Object Exchange (OBEX) protocol. For more information on OpenOBEX, see http://triq.net/obex/
 
-
 
-
'''BlueZ Bluetooth stack''' - The de-facto implementation of Bluetooth for Linux. For more information on BlueZ, see [http://www.bluez.org/ http://www.bluez.org]
 
-
 
-
'''BlueZ D-Bus API''' - BlueZ accepts commands via D-Bus.
 
-
 
-
'''WLAN connectivity daemon''' - The daemon controlling WLAN connections.
 
-
 
-
'''WLAN device driver''' - Device driver for Wireless LAN (IEEE 802.11g). Kernel driver is composed of two parts: a binary part (closed source) and an open source wrapper, binding the binary to the current Linux kernel.
 
-
 
-
 
-
===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.
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 ==
==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.
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.
+
In offline mode, none of the radios must be active. The [[Documentation/Maemo 5 Developer Guide/Architecture/System Software#Device State Management Entity (DSME)|Device System Management Entity (DSME)]] of Maemo provides information about the transitions to and from the offline mode.
-
<div align="CENTER">
+
;Name
 +
: Connectivity UI
 +
;Purpose
 +
: Provides the UI for managing phone and Internet connections. Available as a Control Panel applet, and from the Status Bar.
 +
;Responsibilities and additional requirements
 +
: <ul><li>Displaying active connections with statistics</li><li>Updating status indicators</li><li>Providing dialogs for changing and disconnecting connections</li></ul>
 +
;Concurrent usage
 +
: (N/A)
-
{| border="1" cellpadding="3"
+
;Name
-
| width="100" align="LEFT" valign="TOP" | Name
+
: Phone Access
-
| width="350" align="LEFT" valign="TOP" | Connectivity UI
+
;Purpose
-
|-
+
: Provides connections to phones with different Bluetooth profiles
-
| width="100" align="LEFT" valign="TOP" | Purpose
+
;Responsibilities and additional requirements
-
| 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.
+
: <ul><li>Searching for phones and inquiring their services</li><li>Keeping phone register</li><li>Providing status of the phone connections for Connectivity UI</li><li>Binding RFCOMM devices to Bluetooth services on the phone</li><li>Providing easy access to OpenOBEX</li></ul>
-
|-
+
;Concurrent usage
-
| width="100" align="LEFT" valign="TOP" | Responsibilities and additional requirements
+
: Number of clients not limited by Maemo. However, some phones may not support more than one Bluetooth profile at a time.
-
| 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)
+
-
|}
+
-
<br /><br />
+
;Name
-
 
+
: Internet Access
-
{| border="1" cellpadding="3"
+
;Purpose
-
| width="100" align="LEFT" valign="TOP" | Name
+
: Provides Internet connections over different bearers.
-
| width="350" align="LEFT" valign="TOP" | Phone Access
+
;Responsibilities and additional requirements
-
|-
+
: <ul><li>Providing means for configuration and management of IAP settings</li><li>Providing API for Internet connections over different bearers (e.g. WLAN, GPRS)</li><li>Providing status of Internet connections for Connectivity UI</li></ul>
-
| width="100" align="LEFT" valign="TOP" | Purpose
+
;Concurrent usage
-
| width="350" align="LEFT" valign="TOP" | Provides connections to phones with different Bluetooth profiles
+
: Number of clients not limited, but only one connection to the Internet can exist at any given time
-
|-
+
-
| 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 Connection Manager
+
-
* 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.
+
-
|}
+
-
 
+
-
<br /><br />
+
-
 
+
-
{| 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 Connection Manager
+
-
|-
+
-
| 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 and Internet connections are quite different by nature and behavior. These are introduced in more detail in the following sections.
-
 
===Phone Access ===
===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.
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.
+
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.
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.
-
The Bluetooth SIM Access (SAP) profile is also needed in maemo to perform WLAN authentication using the EAP-SIM authentication method. In this case, the EAP component asks the BT sap component to get session keys from a GSM/UMTS phone.
+
;Name
 +
: General Bluetooth UI
 +
;Purpose
 +
: User interface for managing all paired BT devices
 +
;Responsibilities and additional requirements
 +
: <ul><li>Keeping a list of all paired devices (not only phones)</li></ul>
 +
;Concurrent usage
 +
: N/A
-
<div align="CENTER"></div><div align="CENTER">
+
;Name
 +
: BT search
 +
;Purpose
 +
: Searches for available Bluetooth devices
 +
;Responsibilities and additional requirements
 +
: <ul><li>Bluetooth inquiry</li><li>Checking on offline mode state</li></ul>
 +
;Concurrent usage
 +
: N/A
-
{| border="1" cellpadding="3"
+
;Name
-
| width="100" align="LEFT" valign="TOP" | Name
+
: BT service discovery
-
| width="350" align="LEFT" valign="TOP" | General Bluetooth UI
+
;Purpose
-
|-
+
: Checks if a found Bluetooth device is sufficient
-
| width="100" align="LEFT" valign="TOP" | Purpose
+
;Responsibilities and additional requirements
-
| width="350" align="LEFT" valign="TOP" | User interface for managing all paired BT devices
+
: Bluetooth service discovery (SDP)
-
|-
+
;Concurrent usage
-
| width="100" align="LEFT" valign="TOP" | Responsibilities and additional requirements
+
: Not limited (but used by Phone selection UI and Phone connection daemon only)
-
| 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
+
-
|}
+
-
<br />
+
;Name
-
 
+
: GW OBEX library
-
{| border="1" cellpadding="3"
+
;Purpose
-
| width="100" align="LEFT" valign="TOP" | Name
+
: Provides access to OpenOBEX library for the File selector (Gnome VFS) on a higher abstraction level than OpenOBEX itself supports
-
| width="350" align="LEFT" valign="TOP" | BT search
+
;Responsibilities and additional requirements
-
|-
+
: <ul><li>Handling OBEX requests</li></ul>
-
| width="100" align="LEFT" valign="TOP" | Purpose
+
;Concurrent usage
-
| width="350" align="LEFT" valign="TOP" | Searches for available Bluetooth devices
+
: Not limited
-
|-
+
-
| 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
+
-
|}
+
-
 
+
-
<br />
+
-
 
+
-
{| 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)
+
-
|}
+
-
 
+
-
<br />
+
-
 
+
-
{| 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
+
-
|}
+
-
 
+
-
<br />
+
-
 
+
-
</div><div align="CENTER"></div>
+
Maemo Bluetooth also supports HID (keyboard) and OPP (object push file transfer) profiles.
Maemo Bluetooth also supports HID (keyboard) and OPP (object push file transfer) profiles.
 +
===Internet Access ===
-
===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:
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:
Line 189: Line 108:
For Bluetooth connections, AT commands are applied to establish a PPP link to the cellular modem and the connection to the Internet.
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">
+
;Name
 +
: IC daemon
 +
;Purpose
 +
: IC daemon establishes Internet connections over different bearers.
 +
;Responsibilities and additional requirements
 +
: <ul><li>Controlling that only one Internet connection (one active IAP) can exist at any given time</li><li>Using WLAN or GPRS connection daemon for getting a network device and getting the connection authenticated</li><li>Starting IP level services like PPP and DHCP</li><li>Providing statistics about the usage of IAPs to any application</li></ul>
 +
;Concurrent usage
 +
: Has multiple clients and limits the connections to one at a time
-
{| border="1" cellpadding="3"
+
;Name
-
| width="100" align="LEFT" valign="TOP" | Name
+
: Internet Connectivity GUI
-
| width="350" align="LEFT" valign="TOP" | IC daemon
+
;Purpose
-
|-
+
: Has GUI applications for configuring Internet Access Points and WLAN settings.
-
| width="100" align="LEFT" valign="TOP" | Purpose
+
;Responsibilities and additional requirements
-
| width="350" align="LEFT" valign="TOP" | IC daemon establishes Internet connections over different bearers.
+
: <ul><li>Providing the UI for configuring an IAP</li><li>Providing the UI for WLAN settings</li><li>Scanning for available WLAN networks (on request)</li><li>Saving IAP and WLAN settings (excluding EAP settings) to GConf</li><li>Opening up dialogs and displaying notifications</li></ul>
-
|-
+
;Concurrent usage
-
| width="100" align="LEFT" valign="TOP" | Responsibilities and additional requirements
+
: N/A
-
| 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
+
-
|}
+
-
<br />
+
;Name
 +
: WLAN connection daemon
 +
;Purpose
 +
: Manages WLAN network connections
 +
;Responsibilities and additional requirements
 +
: <ul><li>Starting WLAN driver with the settings provided; stopping WLAN</li><li>Requesting authentication when necessary</li><li>Relaying WLAN IAP settings from IC daemon to WLAN drivers and authentication requests to EAP</li><li>Relaying WLAN events from WLAN drivers</li><li>Providing WLAN status information</li></ul>
 +
;Concurrent usage
 +
: Not limited
-
{| border="1" cellpadding="3"
+
;Name
-
| width="100" align="LEFT" valign="TOP" | Name
+
: EAP UI
-
| width="350" align="LEFT" valign="TOP" | Internet Connectivity GUI
+
;Purpose
-
|-
+
: User interface for EAP authentication
-
| width="100" align="LEFT" valign="TOP" | Purpose
+
;Responsibilities and additional requirements
-
| width="350" align="LEFT" valign="TOP" | Has GUI applications for configuring Internet Access Points and WLAN settings.
+
: <ul><li>Invoking a dialog for an authentication password</li><li>Showing authentication status</li></ul>
-
|-
+
;Concurrent usage
-
| width="100" align="LEFT" valign="TOP" | Responsibilities and additional requirements
+
: N/A
-
| 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
+
-
|}
+
-
<br />
+
;Name
 +
: EAP
 +
;Purpose
 +
: Provides WLAN security excluding basic WEP settings, which are in Wireless Extensions
 +
;Responsibilities and additional requirements
 +
: <ul><li>Taking care of the authentication process for the active IAP</li><li>Delivering progress events to IC daemon</li><li>As a special case, controlling the EAP-SIM authentication using the SIM Access Profile</li><li>Providing authentication status</li></ul>
 +
;Concurrent usage
 +
: N/A
-
{| border="1" cellpadding="3"
+
==Internet Connectivity Daemon ==
-
| 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
+
-
|}
+
-
<br />
 
-
 
-
{| 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
 
-
|}
 
-
 
-
<br />
 
-
 
-
{| 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
 
-
|}
 
-
 
-
<br />
 
-
 
-
</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.
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 ===
===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.
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.
Line 313: Line 175:
* Ensure that the user is aware of updates and can see the time when the data was last updated.
* 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:
* 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 Created''': Use the connection and update all data.
-
** '''Connection Lost'''<nowiki>: Go to an idle state silently and wait until a new connection is created. </nowiki>
+
** '''Connection Lost''': Go to an idle state silently and wait until a new connection is created.
-
** '''Connection Changed'''<nowiki>: Use the new connection. </nowiki>
+
** '''Connection Changed''': Use the new connection.
* Ensure that automatic data updates run in background and silently:
* Ensure that automatic data updates run in background and silently:
** Avoid alarming the user with unnecessary banners or dialogs.
** Avoid alarming the user with unnecessary banners or dialogs.
Line 324: Line 186:
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.
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 ===
-
 
-
==== 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:
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:
Line 334: Line 195:
==LibConIC Library ==
==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]
+
 
 +
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:
Libconic is high level and stable object-oriented API suitable for the following purposes:
Line 344: Line 206:
* getting a list of user-saved connections (IAPs)
* getting a list of user-saved connections (IAPs)
-
<br>
+
=== Application Requirements ===
-
'''Application Requirements'''
+
 
Before applications can use the Libconic API, they must meet the following requirements:
Before applications can use the Libconic API, they must meet the following requirements:
# use non-blocking sockets
# use non-blocking sockets
-
# have the system D-BUS running
+
# have the system D-Bus running
-
# ''g_type_init()'' has to be called
+
# <code>g_type_init()</code> has to be called
# employ no threading support in the Libconic API
# 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.  
+
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, <code>g_type_init()</code> is called as a part of <code>gtk_init()</code>, and probably no extra threads are used.  
 +
=== Non-Blocking Sockets ===
-
'''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 <code>G_IO_FLAG_NONBLOCK</code> flag provide non-blocking way to use 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.  
With threads, blocking sockets can be used, although Libconic API itself is not thread safe.  
 +
=== System D-Bus ===
-
'''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 <code>dbus_connection_setup_with_g_main()</code>.
-
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 <br />''dbus_connection_setup_with_g_main()''.
+
-
N.B. Setting up LibOSSO context connects the application to required D-BUS.  
+
N.B. Setting up LibOSSO context connects the application to required D-Bus.  
 +
=== GType ===
-
'''GType'''
+
Libconic API is <code>GObject</code>-based, so in order to get the API working, you must initialize GLib's <code>GType</code> properly. To do that, use <code>g_type_init()</code>.  
-
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 ===
-
'''No Multiple Threads'''
+
Libconic API is not thread-safe. If the applications has threads, use Libconic API only from the same context where <code>GMainloop</code> is running.
-
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 ===
===Libconic Usage ===
==== Requesting for Connection ====
==== 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 <span><font color="#990000"><nowiki>=</nowiki></font></span> FALSE<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
[http://maemo.org/api_refs/5.0/5.0-final/libconic/ LibConIc] is an asynchronous connection API, which heavily relies on <code>GObject</code> signals. Basically this means that <code>GMainloop</code> must be iterated in order to successfully execute connection requests. After the application is set up, use a <code>ConIcConnection</code> object to request a connection:
-
    <span>''<span><font color="#9A1900">/* Create connection object */</font></span>''</span>
+
-
    ConIcConnection <span><font color="#990000"><nowiki>*</nowiki></font></span>connection <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">con_ic_connection_new</font></span>'''</span><span><font color="#990000">();</font></span>
+
-
    <span>''<span><font color="#9A1900">/* Connect signal to receive connection events */</font></span>''</span>
+
-
    <span>'''<span><font color="#000000">g_signal_connect</font></span>'''</span><span><font color="#990000">(</font></span><span>'''<span><font color="#000000">G_OBJECT</font></span>'''</span><span><font color="#990000">(</font></span>connection<span><font color="#990000">),</font></span> <span><font color="#FF0000">"connection-event"</font></span><span><font color="#990000">,</font></span>
+
-
                      <span>'''<span><font color="#000000">G_CALLBACK</font></span>'''</span><span><font color="#990000">(</font></span>my_connection_handler<span><font color="#990000">),</font></span> NULL<span><font color="#990000">);</font></span>
+
-
    <span>''<span><font color="#9A1900">/* Request connection and check for the result */</font></span>''</span>
+
-
    success <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">con_ic_connection_connect</font></span>'''</span><span><font color="#990000">(</font></span>connection<span><font color="#990000">,</font></span> CON_IC_CONNECT_FLAG_NONE<span><font color="#990000">);</font></span>
+
-
    <span>'''<span><font color="#0000FF">if</font></span>'''</span> <span><font color="#990000">(!</font></span>success<span><font color="#990000">)</font></span> <span>'''<span><font color="#000000">g_warning</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#FF0000">"Request for connection failed"</font></span><span><font color="#990000">);</font></span></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.
+
<source lang="c">
 +
    gboolean success = FALSE;
 +
    /* Create connection object */
 +
    ConIcConnection *connection = 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 = con_ic_connection_connect(connection, CON_IC_CONNECT_FLAG_NONE);
 +
    if (!success) g_warning("Request for connection failed");
 +
</source>
-
The connection handler (''my_connection_handler()'' function registered in the previous snippet) could look like this:
+
At this point, the application does not yet have an Internet connection. A successful return from <code>con_ic_connection_connect()</code> means only that the request was successfully dispatched to the Internet Connectivity daemon. When the daemon has a connection ready, the application receives an [http://maemo.org/api_refs/5.0/5.0-final/libconic/conicconnectionevent_8h.html event] (as an <code>GObject</code> 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.
-
<tt><span>'''<span><font color="#0000FF">static</font></span>'''</span> <span><font color="#009900">void</font></span> <span>'''<span><font color="#000000">my_connection_handler</font></span>'''</span><span><font color="#990000">(</font></span>ConIcConnection <span><font color="#990000"><nowiki>*</nowiki></font></span>connection<span><font color="#990000">,</font></span>
+
The connection handler (<code>my_connection_handler()</code> function registered in the previous snippet) could look like this:
-
                                  ConIcConnectionEvent <span><font color="#990000"><nowiki>*</nowiki></font></span>event<span><font color="#990000">,</font></span>
+
-
                                  gpointer user_data<span><font color="#990000">)</font></span>
+
-
<span><font color="#FF0000">{</font></span>
+
-
    ConIcConnectionStatus status <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">con_ic_connection_event_get_status</font></span>'''</span><span><font color="#990000">(</font></span>event<span><font color="#990000">);</font></span>
+
-
    ConIcConnectionError error<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
    <span>'''<span><font color="#0000FF">const</font></span>'''</span> gchar <span><font color="#990000"><nowiki>*</nowiki></font></span>iap_id <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">con_ic_event_get_iap_id</font></span>'''</span><span><font color="#990000">(</font></span><span>'''<span><font color="#000000">CON_IC_EVENT</font></span>'''</span><span><font color="#990000">(</font></span>event<span><font color="#990000">));</font></span>
+
-
    <span>'''<span><font color="#0000FF">const</font></span>'''</span> gchar <span><font color="#990000"><nowiki>*</nowiki></font></span>bearer <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">con_ic_event_get_bearer_type</font></span>'''</span><span><font color="#990000">(</font></span><span>'''<span><font color="#000000">CON_IC_EVENT</font></span>'''</span><span><font color="#990000">(</font></span>event<span><font color="#990000">));</font></span>
+
-
    <span>'''<span><font color="#0000FF">switch</font></span>'''</span><span><font color="#990000">(</font></span>status<span><font color="#990000">)</font></span> <span><font color="#FF0000">{</font></span>
+
-
        <span>'''<span><font color="#0000FF">case</font></span>'''</span> CON_IC_STATUS_CONNECTED<span><font color="#990000"><nowiki>:</nowiki></font></span>
+
-
            <span>'''<span><font color="#000000">g_debug</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#FF0000">"Hey, we are connected to IAP %s with bearer %s!"</font></span><span><font color="#990000">,</font></span> iap_id<span><font color="#990000">,</font></span> bearer<span><font color="#990000">);</font></span>
+
-
            <span>'''<span><font color="#0000FF">break</font></span>'''</span><span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
        <span>'''<span><font color="#0000FF">case</font></span>'''</span> CON_IC_STATUS_DISCONNECTING<span><font color="#990000"><nowiki>:</nowiki></font></span>
+
-
            <span>'''<span><font color="#000000">g_debug</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#FF0000">"We are disconnecting..."</font></span><span><font color="#990000">);</font></span>
+
-
            <span>'''<span><font color="#0000FF">break</font></span>'''</span><span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
        <span>'''<span><font color="#0000FF">case</font></span>'''</span> CON_IC_STATUS_DISCONNECTED<span><font color="#990000"><nowiki>:</nowiki></font></span>
+
-
            <span>'''<span><font color="#000000">g_debug</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#FF0000">"And we are disconnected. Let's see what went wrong..."</font></span><span><font color="#990000">);</font></span>
+
-
            error <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">con_ic_connection_event_get_error</font></span>'''</span><span><font color="#990000">(</font></span>event<span><font color="#990000">);</font></span>
+
-
            <span>'''<span><font color="#0000FF">switch</font></span>'''</span><span><font color="#990000">(</font></span>error<span><font color="#990000">)</font></span> <span><font color="#FF0000">{</font></span>
+
-
                <span>'''<span><font color="#0000FF">case</font></span>'''</span> CON_IC_CONNECTION_ERROR_NONE<span><font color="#990000"><nowiki>:</nowiki></font></span>
+
-
                    <span>'''<span><font color="#000000">g_debug</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#FF0000">"Libconic thinks there was nothing wrong."</font></span><span><font color="#990000">);</font></span>
+
-
                    <span>'''<span><font color="#0000FF">break</font></span>'''</span><span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
                <span>'''<span><font color="#0000FF">case</font></span>'''</span> CON_IC_CONNECTION_ERROR_INVALID_IAP<span><font color="#990000"><nowiki>:</nowiki></font></span>
+
-
                    <span>'''<span><font color="#000000">g_debug</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#FF0000">"Invalid (non-existing?) IAP was requested."</font></span><span><font color="#990000">);</font></span>
+
-
                    <span>'''<span><font color="#0000FF">break</font></span>'''</span><span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
                <span>'''<span><font color="#0000FF">case</font></span>'''</span> CON_IC_CONNECTION_ERROR_CONNECTION_FAILED<span><font color="#990000"><nowiki>:</nowiki></font></span>
+
-
                    <span>'''<span><font color="#000000">g_debug</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#FF0000">"Connection just failed."</font></span><span><font color="#990000">);</font></span>
+
-
                    <span>'''<span><font color="#0000FF">break</font></span>'''</span><span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
                <span>'''<span><font color="#0000FF">case</font></span>'''</span> CON_IC_CONNECTION_ERROR_USER_CANCELED<span><font color="#990000"><nowiki>:</nowiki></font></span>
+
-
                    <span>'''<span><font color="#000000">g_debug</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#FF0000">"User canceled the connection attempt"</font></span><span><font color="#990000">);</font></span>
+
-
                    <span>'''<span><font color="#0000FF">break</font></span>'''</span><span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
            <span><font color="#FF0000">}</font></span>
+
-
            <span>'''<span><font color="#0000FF">break</font></span>'''</span><span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
        <span>'''<span><font color="#0000FF">default</font></span>'''</span><span><font color="#990000"><nowiki>:</nowiki></font></span>
+
-
            <span>'''<span><font color="#000000">g_debug</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#FF0000">"Unknown connection status received"</font></span><span><font color="#990000">);</font></span>
+
-
    <span><font color="#FF0000">}</font></span>
+
-
<span><font color="#FF0000">}</font></span></tt>
+
 +
<source lang="c">
 +
static void my_connection_handler(ConIcConnection *connection,
 +
                                  ConIcConnectionEvent *event,
 +
                                  gpointer user_data)
 +
{
 +
    ConIcConnectionStatus status = con_ic_connection_event_get_status(event);
 +
    ConIcConnectionError error;
 +
    const gchar *iap_id = con_ic_event_get_iap_id(CON_IC_EVENT(event));
 +
    const gchar *bearer = con_ic_event_get_bearer_type(CON_IC_EVENT(event));
 +
    switch(status) {
 +
        case CON_IC_STATUS_CONNECTED:
 +
            g_debug("Hey, we are connected to IAP %s with bearer %s!", iap_id, bearer);
 +
            break;
 +
        case CON_IC_STATUS_DISCONNECTING:
 +
            g_debug("We are disconnecting...");
 +
            break;
 +
        case CON_IC_STATUS_DISCONNECTED:
 +
            g_debug("And we are disconnected. Let's see what went wrong...");
 +
            error = con_ic_connection_event_get_error(event);
 +
            switch(error) {
 +
                case CON_IC_CONNECTION_ERROR_NONE:
 +
                    g_debug("Libconic thinks there was nothing wrong.");
 +
                    break;
 +
                case CON_IC_CONNECTION_ERROR_INVALID_IAP:
 +
                    g_debug("Invalid (non-existing?) IAP was requested.");
 +
                    break;
 +
                case CON_IC_CONNECTION_ERROR_CONNECTION_FAILED:
 +
                    g_debug("Connection just failed.");
 +
                    break;
 +
                case CON_IC_CONNECTION_ERROR_USER_CANCELED:
 +
                    g_debug("User canceled the connection attempt");
 +
                    break;
 +
            }
 +
            break;
 +
        default:
 +
            g_debug("Unknown connection status received");
 +
    }
 +
}
 +
</source>
====Listening for Connection Events ====
====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-events" GObject property, can achieve this:
 
-
<tt>    <span>''<span><font color="#9A1900">/* Create connection object */</font></span>''</span>
+
Sometimes the application does not actively start connections but needs to detect if the device is online. The Libconic "automatic events" feature, enabled with the <code>automatic-connection-events</code> <code>GObject</code> property, can achieve this:
-
    ConIcConnection <span><font color="#990000"><nowiki>*</nowiki></font></span>connection <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">con_ic_connection_new</font></span>'''</span><span><font color="#990000">();</font></span>
+
-
    <span>''<span><font color="#9A1900">/* Connect signal to receive connection events */</font></span>''</span>
+
-
    <span>'''<span><font color="#000000">g_signal_connect</font></span>'''</span><span><font color="#990000">(</font></span><span>'''<span><font color="#000000">G_OBJECT</font></span>'''</span><span><font color="#990000">(</font></span>connection<span><font color="#990000">),</font></span> <span><font color="#FF0000">"connection-event"</font></span><span><font color="#990000">,</font></span>
+
-
                      <span>'''<span><font color="#000000">G_CALLBACK</font></span>'''</span><span><font color="#990000">(</font></span>my_connection_handler<span><font color="#990000">),</font></span> NULL<span><font color="#990000">);</font></span>
+
-
    <span>''<span><font color="#9A1900">/* Set automatic events */</font></span>''</span>
+
-
    <span>'''<span><font color="#000000">g_object_set</font></span>'''</span><span><font color="#990000">(</font></span><span>'''<span><font color="#000000">G_OBJECT</font></span>'''</span><span><font color="#990000">(</font></span>connection<span><font color="#990000">),</font></span> <span><font color="#FF0000">"automatic-events"</font></span><span><font color="#990000">,</font></span> TRUE<span><font color="#990000">,</font></span> NULL<span><font color="#990000">);</font></span></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.
+
<source lang="c">
 +
    /* Create connection object */
 +
    ConIcConnection *connection = 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);
 +
</source>
-
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:
+
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, <code>ConIcConnectionEvent</code> with status <code>CON_IC_STATUS_DISCONNECTED</code> is emitted. This event has <code>NULL</code> IAP ID and bearer, because there is no IAP getting disconnected, but the event indicates that the device is offline.
-
<tt><span>'''<span><font color="#0000FF">static</font></span>'''</span> <span><font color="#009900">void</font></span> <span>'''<span><font color="#000000">connection_info</font></span>'''</span><span><font color="#990000">(</font></span>ConIcConnection <span><font color="#990000"><nowiki>*</nowiki></font></span>connection<span><font color="#990000">,</font></span>
+
N.B. The main loop must be iterated in order to receive the event. If you need the connection status information synchronously, you can iterate the main loop yourself:
-
                            ConIcConnectionEvent <span><font color="#990000"><nowiki>*</nowiki></font></span>event<span><font color="#990000">,</font></span>
+
-
                            gpointer user_data<span><font color="#990000">)</font></span>
+
-
<span><font color="#FF0000">{</font></span>
+
-
    ConIcConnectionStatus status <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">con_ic_connection_event_get_status</font></span>'''</span><span><font color="#990000">(</font></span>event<span><font color="#990000">);</font></span>
+
-
    ConIcConnectionStatus <span><font color="#990000"><nowiki>*</nowiki></font></span>status_ptr <span><font color="#990000"><nowiki>=</nowiki></font></span> <span><font color="#990000">(</font></span>ConIcConnectionStatus<span><font color="#990000"><nowiki>*)</nowiki></font></span>user_data<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
    <span><font color="#990000"><nowiki>*</nowiki></font></span>status_ptr <span><font color="#990000"><nowiki>=</nowiki></font></span> status<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
<span><font color="#FF0000">}</font></span>
+
-
<span>''<span><font color="#9A1900">/* ... */</font></span>''</span>
+
-
    <span>''<span><font color="#9A1900">/* Create connection object and set on automatic events (see previous snippet) ... */</font></span>''</span>
+
-
    <span>'''<span><font color="#0000FF">static</font></span>'''</span> ConIcConnectionStatus status <span><font color="#990000"><nowiki>=</nowiki></font></span> <span><font color="#993399">0xFFFF</font></span><span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
    ConIcConnection <span><font color="#990000"><nowiki>*</nowiki></font></span>connection <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">con_ic_connection_new</font></span>'''</span><span><font color="#990000">();</font></span>
+
-
    <span>'''<span><font color="#000000">g_signal_connect</font></span>'''</span><span><font color="#990000">(</font></span><span>'''<span><font color="#000000">G_OBJECT</font></span>'''</span><span><font color="#990000">(</font></span>connection<span><font color="#990000">),</font></span> <span><font color="#FF0000">"connection-event"</font></span><span><font color="#990000">,</font></span>
+
-
                      <span>'''<span><font color="#000000">G_CALLBACK</font></span>'''</span><span><font color="#990000">(</font></span>connection_info<span><font color="#990000">),</font></span> <span><font color="#990000">&amp;</font></span>status<span><font color="#990000">);</font></span>
+
-
    <span>'''<span><font color="#000000">g_object_set</font></span>'''</span><span><font color="#990000">(</font></span><span>'''<span><font color="#000000">G_OBJECT</font></span>'''</span><span><font color="#990000">(</font></span>Connection<span><font color="#990000">),</font></span> <span><font color="#FF0000">"automatic-events"</font></span><span><font color="#990000">,</font></span> TRUE<span><font color="#990000">,</font></span> NULL<span><font color="#990000">);</font></span>
+
-
    <span>''<span><font color="#9A1900">/* Iterate main loop for the first connection event */</font></span>''</span>
+
-
    <span>'''<span><font color="#0000FF">while</font></span>'''</span> <span><font color="#990000">(</font></span>status <span><font color="#990000"><nowiki>==</nowiki></font></span> <span><font color="#993399">0xFFFF</font></span><span><font color="#990000">)</font></span> <span>'''<span><font color="#000000">g_main_context_iteration</font></span>'''</span><span><font color="#990000">(</font></span>NULL<span><font color="#990000">,</font></span> TRUE<span><font color="#990000">);</font></span>
+
-
    <span>'''<span><font color="#0000FF">if</font></span>'''</span> <span><font color="#990000">(</font></span>status <span><font color="#990000"><nowiki>==</nowiki></font></span> CON_IC_STATUS_CONNECTED<span><font color="#990000">)</font></span>
+
-
        <span>'''<span><font color="#000000">g_debug</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#FF0000">"We are connected!"</font></span><span><font color="#990000">);</font></span>
+
-
    <span>'''<span><font color="#0000FF">else</font></span>'''</span>
+
-
        <span>'''<span><font color="#000000">g_debug</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#FF0000">"We are not connected!"</font></span><span><font color="#990000">);</font></span></tt>
+
 +
<source lang="c">
 +
static void connection_info(ConIcConnection *connection,
 +
                            ConIcConnectionEvent *event,
 +
                            gpointer user_data)
 +
{
 +
    ConIcConnectionStatus status = con_ic_connection_event_get_status(event);
 +
    ConIcConnectionStatus *status_ptr = (ConIcConnectionStatus*)user_data;
 +
    *status_ptr = status;
 +
}
 +
/* ... */
 +
    /* Create connection object and set on automatic events (see previous snippet) ... */
 +
    static ConIcConnectionStatus status = 0xFFFF;
 +
    ConIcConnection *connection = 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 == 0xFFFF) g_main_context_iteration(NULL, TRUE);
 +
    if (status == CON_IC_STATUS_CONNECTED)
 +
        g_debug("We are connected!");
 +
    else
 +
        g_debug("We are not connected!");
 +
</source>
==== Receiving Statistics of Connection ====
==== 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><span>'''<span><font color="#0000FF">static</font></span>'''</span> <span><font color="#009900">void</font></span> <span>'''<span><font color="#000000">connection_statistics</font></span>'''</span><span><font color="#990000">(</font></span>ConIcConnection <span><font color="#990000"><nowiki>*</nowiki></font></span>connection<span><font color="#990000">,</font></span>
+
To receive statistics of the current Internet connection, use the <code>con_ic_connection_statistics()</code> 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 <code>NULL</code>.
-
                                  ConIcStatisticsEvent <span><font color="#990000"><nowiki>*</nowiki></font></span>event<span><font color="#990000">,</font></span>
+
 
-
                                  gpointer user_data<span><font color="#990000">)</font></span>
+
<source lang="c">
-
<span><font color="#FF0000">{</font></span>
+
static void connection_statistics(ConIcConnection *connection,
-
    <span>'''<span><font color="#000000">g_debug</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#FF0000">"Here are all kind of nice statistics about the connection:"</font></span><span><font color="#990000">);</font></span>
+
                                  ConIcStatisticsEvent *event,
-
    <span>'''<span><font color="#000000">g_debug</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#FF0000">"Time active: %u, signal strength: %u, received packets: %llu, "</font></span>
+
                                  gpointer user_data)
-
            <span><font color="#FF0000">"sent packets: %llu, received bytes: %llu, sent bytes: %llu"</font></span><span><font color="#990000">,</font></span>
+
{
-
            <span>'''<span><font color="#000000">con_ic_statistics_event_get_time_active</font></span>'''</span><span><font color="#990000">(</font></span>event<span><font color="#990000">),</font></span>
+
    g_debug("Here are all kind of nice statistics about the connection:");
-
            <span>'''<span><font color="#000000">con_ic_statistics_event_get_signal_strength</font></span>'''</span><span><font color="#990000">(</font></span>event<span><font color="#990000">),</font></span>
+
    g_debug("Time active: %u, signal strength: %u, received packets: %llu, "
-
            <span>'''<span><font color="#000000">con_ic_statistics_event_get_rx_packets</font></span>'''</span><span><font color="#990000">(</font></span>event<span><font color="#990000">),</font></span>
+
            "sent packets: %llu, received bytes: %llu, sent bytes: %llu",
-
            <span>'''<span><font color="#000000">con_ic_statistics_event_get_tx_packets</font></span>'''</span><span><font color="#990000">(</font></span>event<span><font color="#990000">),</font></span>
+
            con_ic_statistics_event_get_time_active(event),
-
            <span>'''<span><font color="#000000">con_ic_statistics_event_get_rx_bytes</font></span>'''</span><span><font color="#990000">(</font></span>event<span><font color="#990000">),</font></span>
+
            con_ic_statistics_event_get_signal_strength(event),
-
            <span>'''<span><font color="#000000">con_ic_statistics_event_get_tx_bytes</font></span>'''</span><span><font color="#990000">(</font></span>event<span><font color="#990000">));</font></span>
+
            con_ic_statistics_event_get_rx_packets(event),
-
<span><font color="#FF0000">}</font></span>
+
            con_ic_statistics_event_get_tx_packets(event),
-
<span>''<span><font color="#9A1900">/* ... */</font></span>''</span>
+
            con_ic_statistics_event_get_rx_bytes(event),
-
    <span>''<span><font color="#9A1900">/* ConIcConnection object named "connection" has already been created */</font></span>''</span>
+
            con_ic_statistics_event_get_tx_bytes(event));
-
    <span>'''<span><font color="#000000">g_signal_connect</font></span>'''</span><span><font color="#990000">(</font></span><span>'''<span><font color="#000000">G_OBJECT</font></span>'''</span><span><font color="#990000">(</font></span>connection<span><font color="#990000">),</font></span> <span><font color="#FF0000">"statistics"</font></span><span><font color="#990000">,</font></span>
+
}
-
                      <span>'''<span><font color="#000000">G_CALLBACK</font></span>'''</span><span><font color="#990000">(</font></span>connection_statistics<span><font color="#990000">),</font></span> NULL<span><font color="#990000">);</font></span>
+
/* ... */
-
    <span>'''<span><font color="#0000FF">if</font></span>'''</span> <span><font color="#990000">(!</font></span><span>'''<span><font color="#000000">con_ic_connection_statistics</font></span>'''</span><span><font color="#990000">(</font></span>connection <span><font color="#990000">,</font></span>NULL<span><font color="#990000">))</font></span>
+
    /* ConIcConnection object named "connection" has already been created */
-
        <span>'''<span><font color="#000000">g_warning</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#FF0000">"Requesting connection statistics failed!"</font></span><span><font color="#990000">);</font></span></tt>
+
    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!");
 +
</source>
==== Getting Proxy Settings ====
==== 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.
+
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 <code>con_ic_connection_get_proxy_mode()</code> function. Next, use the following functions to get the actual proxy settings:
-
* 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 <br /> 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:
+
* If proxy mode is <code>CON_IC_PROXY_MODE_NONE</code>, do not use any proxies.
 +
* If proxy mode is <code>CON_IC_PROXY_MODE_MANUAL</code>, use the following functions to query proxy settings:
 +
** <code>con_ic_connection_get_proxy_host()</code> to get the proxy host
 +
** <code>con_ic_connection_get_proxy_port()</code> to get the proxy port
 +
** <code>con_ic_connection_get_proxy_ignore_hosts()</code> to get a list of hosts for which the proxy should not be used.
 +
* If proxy mode is <code>CON_IC_PROXY_MODE_AUTO</code>, use <code>con_ic_connection_get_proxy_autoconfig_url()</code> to get a proxy auto configuration URL.
 +
** Use of auto configuration URL is explained in [[:wikipedia:Proxy_auto-config|Wikipedia]]
-
<tt><span>'''<span><font color="#0000FF">static</font></span>'''</span> <span><font color="#009900">void</font></span> <span>'''<span><font color="#000000">my_connection_handler</font></span>'''</span><span><font color="#990000">(</font></span>ConIcConnection <span><font color="#990000"><nowiki>*</nowiki></font></span>connection<span><font color="#990000">,</font></span>
+
In this example, the <code>connection-event</code> handler is modified to print HTTP proxy settings when establishing connection:
-
                                  ConIcConnectionEvent <span><font color="#990000"><nowiki>*</nowiki></font></span>event<span><font color="#990000">,</font></span>
+
 
-
                                  gpointer user_data<span><font color="#990000">)</font></span>
+
<source lang="c">
-
<span><font color="#FF0000">{</font></span>
+
static void my_connection_handler(ConIcConnection *connection,
-
    ConIcConnectionStatus status <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">con_ic_connection_event_get_status</font></span>'''</span><span><font color="#990000">(</font></span>event<span><font color="#990000">);</font></span>
+
                                  ConIcConnectionEvent *event,
-
    GSList <span><font color="#990000"><nowiki>*</nowiki></font></span>ignore_hosts<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
                                  gpointer user_data)
-
+
{
-
    <span>'''<span><font color="#0000FF">if</font></span>'''</span> <span><font color="#990000">(</font></span>status <span><font color="#990000"><nowiki>==</nowiki></font></span> CON_IC_STATUS_CONNECTED<span><font color="#990000">)</font></span> <span><font color="#FF0000">{</font></span>
+
    ConIcConnectionStatus status = con_ic_connection_event_get_status(event);
-
        <span>'''<span><font color="#000000">g_debug</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#FF0000">"We are connected! \</font></span>
+
    GSList *ignore_hosts;
-
<span><font color="#FF0000">Let's see what kind of settings we have for HTTP proxy..."</font></span><span><font color="#990000">);</font></span>
+
 
-
+
    if (status == CON_IC_STATUS_CONNECTED) {
-
        <span>''<span><font color="#9A1900">/* Do things based on specified proxy mode */</font></span>''</span>
+
        g_debug("We are connected! \
-
        <span>'''<span><font color="#0000FF">switch</font></span>'''</span> <span><font color="#990000">(</font></span><span>'''<span><font color="#000000">con_ic_connection_get_proxy_mode</font></span>'''</span><span><font color="#990000">(</font></span>connection<span><font color="#990000">))</font></span> <span><font color="#FF0000">{</font></span>
+
Let's see what kind of settings we have for HTTP proxy...");
-
+
 
-
            <span>'''<span><font color="#0000FF">case</font></span>'''</span> CON_IC_PROXY_MODE_NONE<span><font color="#990000"><nowiki>:</nowiki></font></span>
+
        /* Do things based on specified proxy mode */
-
                <span>'''<span><font color="#000000">g_debug</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#FF0000">"No proxies defined, it is direct connection"</font></span><span><font color="#990000">);</font></span>
+
        switch (con_ic_connection_get_proxy_mode(connection)) {
-
                <span>'''<span><font color="#0000FF">break</font></span>'''</span><span><font color="#990000"><nowiki>;</nowiki></font></span>
+
 
-
+
            case CON_IC_PROXY_MODE_NONE:
-
            <span>'''<span><font color="#0000FF">case</font></span>'''</span> CON_IC_PROXY_MODE_MANUAL<span><font color="#990000"><nowiki>:</nowiki></font></span>
+
                g_debug("No proxies defined, it is direct connection");
-
                <span>'''<span><font color="#000000">g_debug</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#FF0000">"HTTP proxy %s:%d in use"</font></span><span><font color="#990000">,</font></span>
+
                break;
-
                        <span>'''<span><font color="#000000">con_ic_connection_get_proxy_host</font></span>'''</span><span><font color="#990000">(</font></span>connection<span><font color="#990000">,</font></span> CON_IC_PROXY_PROTOCOL_HTTP<span><font color="#990000">),</font></span>
+
-
                        <span>'''<span><font color="#000000">con_ic_connection_get_proxy_port</font></span>'''</span><span><font color="#990000">(</font></span>connection<span><font color="#990000">,</font></span> CON_IC_PROXY_PROTOCOL_HTTP<span><font color="#990000">));</font></span>
+
-
+
-
                <span>'''<span><font color="#000000">g_debug</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#FF0000">"List of hosts, for which proxy should not be used:"</font></span><span><font color="#990000">);</font></span>
+
-
                ignore_hosts <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">con_ic_connection_proxy_ignore_hosts</font></span>'''</span><span><font color="#990000">(</font></span>connection<span><font color="#990000">);</font></span>
+
-
                <span>'''<span><font color="#0000FF">for</font></span>'''</span> <span><font color="#990000">(</font></span>GSList <span><font color="#990000"><nowiki>*</nowiki></font></span>iter <span><font color="#990000"><nowiki>=</nowiki></font></span> ignore_hosts<span><font color="#990000"><nowiki>;</nowiki></font></span> iter <span><font color="#990000"><nowiki>!=</nowiki></font></span> NULL<span><font color="#990000"><nowiki>;</nowiki></font></span> iter <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">g_slist_next</font></span>'''</span><span><font color="#990000">(</font></span>iter<span><font color="#990000">))</font></span>
+
-
                <span><font color="#FF0000">{</font></span>
+
-
                    <span>'''<span><font color="#000000">g_debug</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#FF0000">"%s"</font></span><span><font color="#990000">,</font></span> <span><font color="#990000">(</font></span>gchar <span><font color="#990000"><nowiki>*)</nowiki></font></span>iter<span><font color="#990000">-&gt;</font></span>data<span><font color="#990000">);</font></span>
+
-
                    <span>'''<span><font color="#000000">g_free</font></span>'''</span><span><font color="#990000">(</font></span>iter<span><font color="#990000">-&gt;</font></span>data<span><font color="#990000">);</font></span>
+
-
                <span><font color="#FF0000">}</font></span>
+
-
                <span>'''<span><font color="#000000">g_slist_free</font></span>'''</span><span><font color="#990000">(</font></span>ignore_hosts<span><font color="#990000">);</font></span>
+
-
                <span>'''<span><font color="#0000FF">break</font></span>'''</span><span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
+
-
            <span>'''<span><font color="#0000FF">case</font></span>'''</span> CON_IC_PROXY_MODE_AUTO<span><font color="#990000"><nowiki>:</nowiki></font></span>
+
-
                <span>'''<span><font color="#000000">g_debug</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#FF0000">"Proxy auto-config URL %s should be used"</font></span><span><font color="#990000">,</font></span>
+
-
                        <span>'''<span><font color="#000000">con_ic_connection_get_proxy_autoconfig_url</font></span>'''</span><span><font color="#990000">(</font></span>connection<span><font color="#990000">));</font></span>
+
-
                <span>'''<span><font color="#0000FF">break</font></span>'''</span><span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
        <span><font color="#FF0000">}</font></span>
+
-
    <span><font color="#FF0000">}</font></span>
+
-
<span><font color="#FF0000">}</font></span></tt>
+
-
Proxy functions also exist for each individual protocol (like <br />''con_ic_connection_get_proxy_ftp_host()''), but these functions are deprecated. Avoid them in newly-written code.
+
            case CON_IC_PROXY_MODE_MANUAL:
 +
                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 = con_ic_connection_proxy_ignore_hosts(connection);
 +
                for (GSList *iter = ignore_hosts; iter != NULL; iter = g_slist_next(iter))
 +
                {
 +
                    g_debug("%s", (gchar *)iter->data);
 +
                    g_free(iter->data);
 +
                }
 +
                g_slist_free(ignore_hosts);
 +
                break;
 +
 
 +
            case CON_IC_PROXY_MODE_AUTO:
 +
                g_debug("Proxy auto-config URL %s should be used",
 +
                        con_ic_connection_get_proxy_autoconfig_url(connection));
 +
                break;
 +
        }
 +
    }
 +
}
 +
</source>
 +
 
 +
Proxy functions also exist for each individual protocol (like <code>con_ic_connection_get_proxy_ftp_host()</code>), but these functions are deprecated. Avoid them in newly-written code.
====Getting List of User-Saved Connections ====
====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>    <span>''<span><font color="#9A1900">/* ConIcConnection object named "connection" has already been created */</font></span>''</span>
+
To query all user-saved connections (IAPs), use the <code>con_ic_connection_get_all_iaps()</code> function. The function returns simply a singly linked list of <code>ConIcIap</code> objects:
-
    GSList <span><font color="#990000"><nowiki>*</nowiki></font></span>saved_iaps <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">con_ic_connection_get_all_iaps</font></span>'''</span><span><font color="#990000">(</font></span>connection<span><font color="#990000">);</font></span>
+
-
    <span>'''<span><font color="#000000">g_debug</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#FF0000">"The following connections have been saved by the user:"</font></span><span><font color="#990000">);</font></span>
+
-
    <span>'''<span><font color="#0000FF">for</font></span>'''</span> <span><font color="#990000">(</font></span>GSList <span><font color="#990000"><nowiki>*</nowiki></font></span>iter <span><font color="#990000"><nowiki>=</nowiki></font></span> saved_iaps<span><font color="#990000"><nowiki>;</nowiki></font></span> iter <span><font color="#990000"><nowiki>!=</nowiki></font></span> NULL<span><font color="#990000"><nowiki>;</nowiki></font></span> iter <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">g_slist_next</font></span>'''</span><span><font color="#990000">(</font></span>iter<span><font color="#990000">))</font></span> <span><font color="#FF0000">{</font></span>
+
-
        <span>''<span><font color="#9A1900">/* Get IAP object and print some information about it */</font></span>''</span>
+
-
        ConIcIap <span><font color="#990000"><nowiki>*</nowiki></font></span>iap <span><font color="#990000"><nowiki>=</nowiki></font></span> <span><font color="#990000">(</font></span>ConIcIap <span><font color="#990000"><nowiki>*)</nowiki></font></span>iter<span><font color="#990000">-&gt;</font></span>data<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
        <span>'''<span><font color="#000000">g_debug</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#FF0000">"Connection %s called '%s' using bearer %s"</font></span><span><font color="#990000">,</font></span>
+
-
                <span>'''<span><font color="#000000">con_ic_iap_get_id</font></span>'''</span><span><font color="#990000">(</font></span>iap<span><font color="#990000">),</font></span> <span>'''<span><font color="#000000">con_ic_iap_get_name</font></span>'''</span><span><font color="#990000">(</font></span>iap<span><font color="#990000">),</font></span>
+
-
                <span>'''<span><font color="#000000">con_ic_iap_get_bearer_type</font></span>'''</span><span><font color="#990000">(</font></span>iap<span><font color="#990000">));</font></span>
+
-
        <span>''<span><font color="#9A1900">/* We unref the IAP object as we are not going to use it anymore */</font></span>''</span>
+
-
        <span>'''<span><font color="#000000">g_object_unref</font></span>'''</span><span><font color="#990000">(</font></span>iap<span><font color="#990000">);</font></span>
+
-
    <span><font color="#FF0000">}</font></span>
+
-
    <span>'''<span><font color="#000000">g_slist_free</font></span>'''</span><span><font color="#990000">(</font></span>saved_iaps<span><font color="#990000">);</font></span></tt>
+
 +
<source lang="c">
 +
    /* ConIcConnection object named "connection" has already been created */
 +
    GSList *saved_iaps = con_ic_connection_get_all_iaps(connection);
 +
    g_debug("The following connections have been saved by the user:");
 +
    for (GSList *iter = saved_iaps; iter != NULL; iter = g_slist_next(iter)) {
 +
        /* Get IAP object and print some information about it */
 +
        ConIcIap *iap = (ConIcIap *)iter->data;
 +
        g_debug("Connection %s called '%s' using bearer %s",
 +
                con_ic_iap_get_id(iap), con_ic_iap_get_name(iap),
 +
                con_ic_iap_get_bearer_type(iap));
 +
        /* We unref the IAP object as we are not going to use it anymore */
 +
        g_object_unref(iap);
 +
    }
 +
    g_slist_free(saved_iaps);
 +
</source>
==== Porting Application from OSSO IC API to Libconic ====
==== 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 <span><font color="#990000"><nowiki>*</nowiki></font></span>system_dbus<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
* If the application does not have <code>GType</code>, GLib or D-Bus configured, set them up:
-
      GMainloop <span><font color="#990000"><nowiki>*</nowiki></font></span>main_loop<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
 
-
      <span>'''<span><font color="#000000">g_type_init</font></span>'''</span><span><font color="#990000">();</font></span>
+
<source lang="c">
-
      main_loop <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">g_main_loop_new</font></span>'''</span><span><font color="#990000">(</font></span>NULL<span><font color="#990000">,</font></span> FALSE<span><font color="#990000">);</font></span>
+
      DBusConnection *system_dbus;
-
      system_dbus <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">dbus_bus_get</font></span>'''</span><span><font color="#990000">(</font></span>DBUS_BUS_SYSTEM<span><font color="#990000">,</font></span> NULL<span><font color="#990000">);</font></span>
+
      GMainLoop *main_loop;
-
      <span>'''<span><font color="#000000">dbus_connection_setup_with_g_main</font></span>'''</span><span><font color="#990000">(</font></span>system_dbus<span><font color="#990000">,</font></span> NULL<span><font color="#990000">);</font></span></tt>
+
      g_type_init();
 +
      main_loop = g_main_loop_new(NULL, FALSE);
 +
      system_dbus = dbus_bus_get(DBUS_BUS_SYSTEM, NULL);
 +
      dbus_connection_setup_with_g_main(system_dbus, NULL);
 +
</source>
 +
 
* Include the correct header file:
* Include the correct header file:
-
<tt><span>'''<span><font color="#000080">     #include</font></span>'''</span> <span><font color="#FF0000">&lt;osso-ic.h&gt;</font></span>
+
 
-
      <span><font color="#990000"><nowiki>===&gt;</nowiki></font></span>
+
<source lang="c">
-
<span>'''<span><font color="#000080">      #include</font></span>'''</span> <span><font color="#FF0000">&lt;conic.h&gt;</font></span></tt>
+
      #include <osso-ic.h>
-
* Set up ''ConIcConnection'' object and "connection-event" handler instead of ''osso_iap_cb_t'' callback:
+
      /* change to: */
-
<tt>      <span>'''<span><font color="#0000FF">static</font></span>'''</span> <span><font color="#009900">void</font></span> <span>'''<span><font color="#000000">my_connection_cb</font></span>'''</span><span><font color="#990000">(</font></span><span>'''<span><font color="#0000FF">struct</font></span>'''</span> <span><font color="#009900">iap_event_t</font></span> <span><font color="#990000"><nowiki>*</nowiki></font></span>event<span><font color="#990000">,</font></span> <span><font color="#009900">void</font></span> <span><font color="#990000"><nowiki>*</nowiki></font></span>arg<span><font color="#990000">)</font></span>
+
      #include <conic.h>
-
      <span><font color="#FF0000">{</font></span>
+
</source>
-
      <span>''<span><font color="#9A1900">/* ... */</font></span>''</span>
+
 
-
      <span><font color="#FF0000">}</font></span>
+
* Set up <code>ConIcConnection</code> object and <code>connection-event</code> handler instead of <code>osso_iap_cb_t</code> callback:
-
      <span>''<span><font color="#9A1900">/* ... */</font></span>''</span>
+
 
-
          <span>'''<span><font color="#000000">osso_iap_cb</font></span>'''</span><span><font color="#990000">(</font></span>my_connection_cb<span><font color="#990000">);</font></span>
+
<source lang="c">
-
      <span><font color="#990000"><nowiki>===&gt;</nowiki></font></span>
+
      static void my_connection_cb(struct iap_event_t *event, void *arg)
-
      <span>'''<span><font color="#0000FF">static</font></span>'''</span> <span><font color="#009900">void</font></span> <span>'''<span><font color="#000000">my_connection_cb</font></span>'''</span><span><font color="#990000">(</font></span>ConIcConnection <span><font color="#990000"><nowiki>*</nowiki></font></span>connection<span><font color="#990000">,</font></span>
+
      {
-
                                    ConIcConnectionEvent <span><font color="#990000"><nowiki>*</nowiki></font></span>event<span><font color="#990000">,</font></span>
+
      /* ... */
-
                                    gpointer user_data<span><font color="#990000">)</font></span>
+
      }
-
      <span><font color="#FF0000">{</font></span>
+
      /* ... */
-
      <span>''<span><font color="#9A1900">/* ... */</font></span>''</span>
+
          osso_iap_cb(my_connection_cb);
-
      <span><font color="#FF0000">}</font></span>
+
      ===>
-
      <span>''<span><font color="#9A1900">/* ... */</font></span>''</span>
+
      static void my_connection_cb(ConIcConnection *connection,
-
          ConIcConnection <span><font color="#990000"><nowiki>*</nowiki></font></span>connection <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">con_ic_connection_new</font></span>'''</span><span><font color="#990000">();</font></span>
+
                                  ConIcConnectionEvent *event,
-
          <span>'''<span><font color="#000000">g_signal_connect</font></span>'''</span><span><font color="#990000">(</font></span><span>'''<span><font color="#000000">G_OBJECT</font></span>'''</span><span><font color="#990000">(</font></span>connection<span><font color="#990000">),</font></span> <span><font color="#FF0000">"connection-event"</font></span><span><font color="#990000">,</font></span>
+
                                  gpointer user_data)
-
                            <span>'''<span><font color="#000000">G_CALLBACK</font></span>'''</span><span><font color="#990000">(</font></span>my_connection_cb<span><font color="#990000">),</font></span> app_data<span><font color="#990000">);</font></span></tt>
+
      {
-
* Manage connections through ''ConIcConnection'' API instead of <br />''osso_iap_connect()'' and ''osso_iap_disconnect()''<nowiki>: </nowiki>
+
      /* ... */
-
<tt>      <span>'''<span><font color="#000000">osso_iap_connect</font></span>'''</span><span><font color="#990000">(</font></span>OSSO_IAP_ANY<span><font color="#990000">,</font></span> OSSO_IAP_REQUESTED_CONNECT<span><font color="#990000">,</font></span> app_data<span><font color="#990000">);</font></span>
+
      }
-
      <span>'''<span><font color="#000000">osso_iap_disconnect</font></span>'''</span><span><font color="#990000">(</font></span>iap_name<span><font color="#990000">,</font></span> app_data<span><font color="#990000">);</font></span>
+
      /* ... */
-
      <span><font color="#990000"><nowiki>===&gt;</nowiki></font></span>
+
          ConIcConnection *connection = con_ic_connection_new();
-
      <span>'''<span><font color="#000000">con_ic_connection_connect</font></span>'''</span><span><font color="#990000">(</font></span>connection<span><font color="#990000">,</font></span> CON_IC_CONNECT_FLAG_NONE<span><font color="#990000">);</font></span>
+
          g_signal_connect(G_OBJECT(connection), "connection-event",
-
      <span>'''<span><font color="#000000">con_ic_connection_disconnect</font></span>'''</span><span><font color="#990000">(</font></span>connection<span><font color="#990000">);</font></span></tt>
+
                          G_CALLBACK(my_connection_cb), app_data);
-
* Request statistics with ''con_ic_connection_statistics()'' instead of <br />''osso_iap_get_statistics()''.
+
</source>
-
* List all available IAPs with ''con_ic_connection_get_all_iaps()'' instead of <br />''osso_iap_get_configured_iaps()''.
+
 
 +
* Request statistics with <code>con_ic_connection_statistics()</code> instead of <code>osso_iap_get_statistics()</code>.
 +
* List all available IAPs with <code>con_ic_connection_get_all_iaps()</code> instead of <code>osso_iap_get_configured_iaps()</code>.
* Configure autoconf to use Libconic instead of OSSO IC API:
* Configure autoconf to use Libconic instead of OSSO IC API:
-
<tt>      PKG_CHECK_MODULES<span><font color="#990000">(</font></span>OSSOIC<span><font color="#990000">,</font></span> osso-ic<span><font color="#990000">)</font></span>
+
<source lang="autoconf">
-
      AC_SUBST<span><font color="#990000">(</font></span>OSSOIC_CFLAGS<span><font color="#990000">)</font></span>
+
PKG_CHECK_MODULES(OSSOIC, osso-ic)
-
      AC_SUBST<span><font color="#990000">(</font></span>OSSOIC_LIBS<span><font color="#990000">)</font></span>
+
AC_SUBST(OSSOIC_CFLAGS)
-
      <span><font color="#990000"><nowiki>===&gt;</nowiki></font></span>
+
AC_SUBST(OSSOIC_LIBS)
-
      PKG_CHECK_MODULES<span><font color="#990000">(</font></span>CONIC<span><font color="#990000">,</font></span> conic<span><font color="#990000">)</font></span>
+
# Change to:
-
      AC_SUBST<span><font color="#990000">(</font></span>CONIC_CFLAGS<span><font color="#990000">)</font></span>
+
PKG_CHECK_MODULES(CONIC, conic)
-
      AC_SUBST<span><font color="#990000">(</font></span>CONIC_LIBS<span><font color="#990000">)</font></span></tt>
+
AC_SUBST(CONIC_CFLAGS)
-
* In debian/control file "Build-Depends" section, depend on libconic0-dev instead of osso-ic-dev.
+
AC_SUBST(CONIC_LIBS)
 +
</source>
 +
* In <code>debian/control</code> file <code>Build-Depends</code> section, depend on <code>libconic0-dev</code> instead of <code>osso-ic-dev</code>.
==Bluetooth Libraries ==
==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.
 
 +
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.
 +
 +
=== Discovering devices ===
 +
 +
Maemo provides a D-Bus interface for displaying a Bluetooth device search dialog (You can find a list of available Bluetooth D-Bus calls [[#D-Bus Connectivity UI Interface|below]]).
 +
 +
Devices can be searched with following steps:
 +
# Set up a D-Bus connection
 +
# call <code>bt_ui.search_req</code> to show the dialog - you can filter the results
 +
# catch <code>bt_ui.search_result</code> signal
 +
# process the results
 +
 +
Here is a working example in C:
 +
 +
<source lang="c">
 +
// Bluetooth discovery example - bluetooth libraries will not work in the SDK!
 +
#include <hildon/hildon-program.h>
 +
#include <dbus/dbus.h>
 +
#include <dbus/dbus-glib.h>
 +
#include <contbtdialogs-dbus.h>
 +
 +
/* structure to hold some info */
 +
typedef struct _AppData AppData;
 +
struct _AppData {
 +
    HildonProgram *program;
 +
    HildonStackableWindow *window;
 +
    DBusGConnection *dbus_conn;
 +
};
 +
 +
static DBusGConnection *dbus_conn = NULL;
 +
static AppData *app = NULL;
 +
 +
gboolean initialize()
 +
{
 +
    GError *error = NULL;
 +
 +
    //connects to system bus - this is where bt_ui resides
 +
    dbus_conn = dbus_g_bus_get(DBUS_BUS_SYSTEM, &error);
 +
    if (dbus_conn == NULL)
 +
    {
 +
        g_print("Initialization failed: %s\n", error->message);
 +
        g_clear_error(&error);
 +
        return FALSE;
 +
    }
 +
 +
    return TRUE;
 +
}
 +
 +
DBusHandlerResult search_done(DBusConnection *con, DBusMessage *msg, void *data)
 +
{
 +
    gchar *device_address;
 +
    gchar *device_name;
 +
    gchar *device_name_logical;
 +
    gchar *device_class_minor;
 +
    gchar *device_class_major;
 +
    gboolean device_trusted = FALSE;
 +
    gchar **device_services;
 +
    gint device_services_len;
 +
    DBusError *err = NULL;
 +
 +
    if (dbus_message_is_signal(msg, CONBTDIALOGS_DBUS_INTERFACE, CONBTDIALOGS_SEARCH_SIG))
 +
    {
 +
        /* this is our message, so get response args */
 +
        if (dbus_message_get_args(msg, err, DBUS_TYPE_STRING, &device_address,
 +
                          DBUS_TYPE_STRING, &device_name,
 +
                          DBUS_TYPE_STRING, &device_name_logical,
 +
                          DBUS_TYPE_STRING, &device_class_major,
 +
                          DBUS_TYPE_STRING, &device_class_minor,
 +
                          DBUS_TYPE_BOOLEAN, &device_trusted,
 +
                          DBUS_TYPE_ARRAY, &device_services,
 +
                          DBUS_TYPE_INT32, &device_services_len,
 +
                          DBUS_TYPE_INVALID))
 +
        {
 +
            g_print(_("Error getting device info: %s\n"), err->message);
 +
            dbus_error_free(err);
 +
 +
            return DBUS_HANDLER_RESULT_NOT_YET_HANDLED;
 +
        }
 +
 +
        g_print("OK");
 +
        /* you can now use args */
 +
        return DBUS_HANDLER_RESULT_HANDLED;
 +
    }
 +
 +
    return DBUS_HANDLER_RESULT_NOT_YET_HANDLED;
 +
}
 +
 +
gboolean searchBtDevices(AppData *app)
 +
{
 +
    GError *error = NULL;
 +
    DBusGProxy *proxy;
 +
    DBusConnection *second_conn;
 +
    gchar *filter_string = NULL;
 +
    gchar **filter = NULL;
 +
 +
    filter = g_new0(gchar*, 1);
 +
    filter[0] = NULL;
 +
 +
    /* Create proxy to bluetooth UI service */
 +
    proxy = dbus_g_proxy_new_for_name( app->dbus_conn,
 +
                                  CONBTDIALOGS_DBUS_SERVICE,
 +
                                  CONBTDIALOGS_DBUS_PATH,
 +
                                  CONBTDIALOGS_DBUS_INTERFACE );
 +
 +
    hildon_banner_show_information( GTK_WIDGET(app->window), NULL, _("Searching BT devices..."));
 +
 +
    /* run the call to show dialog */
 +
    if (!dbus_g_proxy_call( proxy,
 +
                            CONBTDIALOGS_SEARCH_REQ,
 +
                            &error,
 +
                            G_TYPE_STRING, "",
 +
                            G_TYPE_STRING, "",
 +
                            G_TYPE_STRV, &filter,
 +
                            G_TYPE_STRING, "require",
 +
                            G_TYPE_INVALID, G_TYPE_INVALID ))
 +
    {
 +
        g_print(_("Bluetooth discovery failed: %s\n", error->message);
 +
        g_clear_error(&error);
 +
        g_strfreev(filter);
 +
        g_object_unref( G_OBJECT(proxy) );
 +
 +
        return FALSE;
 +
    }
 +
 +
    g_object_unref( G_OBJECT(proxy) );
 +
    g_strfreev(filter);
 +
 +
    /* create second connection to catch our signal */
 +
    second_conn = dbus_bus_get(DBUS_BUS_SYSTEM, NULL);
 +
    /* set search_done as message handler */
 +
    g_assert(dbus_connection_add_filter(second_conn, search_done, NULL, NULL));
 +
    /* we are looking for signal, so accept only signals */
 +
    filter_string = g_strdup_printf("type='signal'");
 +
    dbus_bus_add_match(second_conn, filter_string, NULL);
 +
    dbus_connection_unref(second_conn);
 +
 +
    return TRUE;
 +
}
 +
 +
void search_btn_pressed(HildonButton *btn, gpointer data)
 +
{
 +
    /* data = our AppData struct */
 +
    if (!searchBtDevices(data))
 +
        return FALSE;
 +
    else
 +
        return TRUE;
 +
}
 +
 +
HildonStackableWindow *createMainWindow(AppData *app)
 +
{
 +
    /** Creates window with button that searches bt devices when clicked **/
 +
 +
    HildonStackableWindow *window = HILDON_STACKABLE_WINDOW(hildon_stackable_window_new());
 +
    GtkWidget *search_btn;
 +
   
 +
    search_btn = hildon_button_new( HILDON_SIZE_AUTO_WIDTH | HILDON_SIZE_FINGER_HEIGHT,
 +
HILDON_BUTTON_ARRANGEMENT_VERTICAL );
 +
    hildon_button_set_text (HILDON_BUTTON (search_btn), "Bluetooth example", "BT example");
 +
 +
    /* Add signals */
 +
    g_signal_connect( G_OBJECT(window), "delete_event", G_CALLBACK(gtk_main_quit), NULL;
 +
    g_signal_connect( G_OBJECT(window), "destroy", G_CALLBACK(gtk_main_quit), NULL);
 +
    g_signal_connect( G_OBJECT(search_btn), "clicked", G_CALLBACK(search_btn_pressed), app);
 +
 +
    gtk_widget_show_all( GTK_WIDGET(search_btn) );
 +
 +
    return window;   
 +
}
 +
 +
int main(int argc, char* argv[])
 +
{
 +
    /* Create empty appdata */
 +
    app = g_new0(AppData, 1);
 +
 +
    /* Init localization support */
 +
    locale_init();
 +
 +
    /* Init gtk */
 +
    gtk_init(&argc, &argv);
 +
 +
    if (!initialize())
 +
        return -1;
 +
 +
    /* Create program object */
 +
    app->program = HILDON_PROGRAM(hildon_program_get_instance());
 +
    g_set_application_name("Bluetooth discovery example");
 +
 +
    app->window = createMainWindow();
 +
    if (!window)
 +
        return -1;
 +
   
 +
    app->dbus_conn = dbus_conn;
 +
 +
    gtk_widget_show_all( GTK_WIDGET(window) );
 +
    gtk_main();
 +
 +
    /* just in case */
 +
    if (dbus_conn != NULL)
 +
        dbus_g_connection_unref(dbus_conn);
 +
 +
    return 0;
 +
}
 +
 +
</source>
=== Libgwobex ===
=== Libgwobex ===
-
Libgwobex provides access to libopenobex functionality by providing a <br /> 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].
+
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/5.0/5.0-final/osso-gwobex/ GW OBEX Library Documentation].
===Creating Connection ===
===Creating Connection ===
-
The connection with libgwobex is established using the gw_obex_setup_dev function, setting up the connection. gw-obex.h
 
-
<tt><span>'''<span><font color="#000080"><nowiki>#define</nowiki></font></span>'''</span> OBEX_FTP_UUID <span><font color="#990000">\</font></span>
+
The connection with libgwobex is established using the <code>gw_obex_setup_dev</code> function, setting up the connection. gw-obex.h
-
        <span><font color="#FF0000">"</font></span><span><font color="#CC33CC">\x</font></span><span><font color="#FF0000">F9</font></span><span><font color="#CC33CC">\x</font></span><span><font color="#FF0000">EC</font></span><span><font color="#CC33CC">\x</font></span><span><font color="#FF0000">7B</font></span><span><font color="#CC33CC">\x</font></span><span><font color="#FF0000">C4</font></span><span><font color="#CC33CC">\x</font></span><span><font color="#FF0000">95</font></span><span><font color="#CC33CC">\x</font></span><span><font color="#FF0000">3C</font></span><span><font color="#CC33CC">\x</font></span><span><font color="#FF0000">11</font></span><span><font color="#CC33CC">\x</font></span><span><font color="#FF0000">D2</font></span><span><font color="#CC33CC">\x</font></span><span><font color="#FF0000">98</font></span><span><font color="#CC33CC">\x</font></span><span><font color="#FF0000">4E</font></span><span><font color="#CC33CC">\x</font></span><span><font color="#FF0000">52</font></span><span><font color="#CC33CC">\x</font></span><span><font color="#FF0000">54</font></span><span><font color="#CC33CC">\x</font></span><span><font color="#FF0000">00</font></span><span><font color="#CC33CC">\x</font></span><span><font color="#FF0000">DC</font></span><span><font color="#CC33CC">\x</font></span><span><font color="#FF0000">9E</font></span><span><font color="#CC33CC">\x</font></span><span><font color="#FF0000">09"</font></span>
+
-
<span>'''<span><font color="#000080"><nowiki>#define</nowiki></font></span>'''</span> OBEX_FTP_UUID_LEN <span><font color="#993399">16</font></span>
+
-
+
-
<span>''<span><font color="#9A1900">/* ... */</font></span>''</span>
+
-
+
-
GwObex<span><font color="#990000"><nowiki>*</nowiki></font></span> <span>'''<span><font color="#000000">gw_obex_setup_dev</font></span>'''</span> <span><font color="#990000">(</font></span><span>'''<span><font color="#0000FF">const</font></span>'''</span> gchar <span><font color="#990000"><nowiki>*</nowiki></font></span> device<span><font color="#990000">,</font></span> <span>'''<span><font color="#0000FF">const</font></span>'''</span> gchar <span><font color="#990000"><nowiki>*</nowiki></font></span> uuid<span><font color="#990000">,</font></span> gint uuid_len<span><font color="#990000">,</font></span>
+
-
                            GMainContext <span><font color="#990000"><nowiki>*</nowiki></font></span> context<span><font color="#990000">,</font></span> gint <span><font color="#990000"><nowiki>*</nowiki></font></span> error <span><font color="#990000">)</font></span></tt>
+
-
The following code snippet illustrates how to open a handle using gw_obex_setup_dev.
+
<source lang="c">
 +
#define OBEX_FTP_UUID \
 +
        "\xF9\xEC\x7B\xC4\x95\x3C\x11\xD2\x98\x4E\x52\x54\x00\xDC\x9E\x09"
 +
#define OBEX_FTP_UUID_LEN 16
-
<tt><span>'''<span><font color="#0000FF">if</font></span>'''</span> <span><font color="#990000">(</font></span>ctx<span><font color="#990000">-&gt;</font></span>rfcomm_dev<span><font color="#990000">)</font></span> <span><font color="#FF0000">{</font></span>
+
/* ... */
-
        <span>'''<span><font color="#0000FF">if</font></span>'''</span> <span><font color="#990000">(</font></span>ctx<span><font color="#990000">-&gt;</font></span>use_ftp<span><font color="#990000">)</font></span>
+
-
                ctx<span><font color="#990000">-&gt;</font></span>obex <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">gw_obex_setup_dev</font></span>'''</span><span><font color="#990000">(</font></span>ctx<span><font color="#990000">-&gt;</font></span>rfcomm_dev<span><font color="#990000">,</font></span>
+
-
                        OBEX_FTP_UUID<span><font color="#990000">,</font></span> OBEX_FTP_UUID_LEN<span><font color="#990000">,</font></span>
+
-
                        NULL<span><font color="#990000">,</font></span> <span><font color="#990000">&amp;</font></span>err<span><font color="#990000">);</font></span>
+
-
        <span>'''<span><font color="#0000FF">else</font></span>'''</span>
+
-
                ctx<span><font color="#990000">-&gt;</font></span>obex <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">gw_obex_setup_dev</font></span>'''</span><span><font color="#990000">(</font></span>ctx<span><font color="#990000">-&gt;</font></span>rfcomm_dev<span><font color="#990000">,</font></span> NULL<span><font color="#990000">,</font></span>
+
-
                        <span><font color="#993399">0</font></span><span><font color="#990000">,</font></span> NULL<span><font color="#990000">,</font></span> <span><font color="#990000">&amp;</font></span>err<span><font color="#990000">);</font></span>
+
-
+
-
        <span>'''<span><font color="#0000FF">if</font></span>'''</span> <span><font color="#990000">(</font></span>ctx<span><font color="#990000">-&gt;</font></span>obex <span><font color="#990000"><nowiki>==</nowiki></font></span> NULL<span><font color="#990000">)</font></span>
+
-
                <span>'''<span><font color="#000000">printf</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#FF0000">"OBEX setup failed: %s</font></span><span><font color="#CC33CC">\n</font></span><span><font color="#FF0000">"</font></span><span><font color="#990000">,</font></span> <span>'''<span><font color="#000000">response_to_string</font></span>'''</span><span><font color="#990000">(</font></span>err<span><font color="#990000">));</font></span>
+
-
<span><font color="#FF0000">}</font></span></tt>
+
-
In this example, ctx-&gt;rfcomm_dev points to a string containing the device node name (e.g. /dev/rfcomm0). ctx-&gt;use_ftp dictates whether to set up standard folder browsing services. If use_ftp is untrue, then INBOX is connected.
+
GwObex* gw_obex_setup_dev (const gchar * device, const gchar * uuid, gint uuid_len,
 +
                          GMainContext * context, gint * error )
 +
</source>
 +
The following code snippet illustrates how to open a handle using <code>gw_obex_setup_dev</code>.
 +
 +
<source lang="c">
 +
if (ctx->rfcomm_dev) {
 +
        if (ctx->use_ftp)
 +
                ctx->obex = gw_obex_setup_dev(ctx->rfcomm_dev,
 +
                        OBEX_FTP_UUID, OBEX_FTP_UUID_LEN,
 +
                        NULL, &err);
 +
        else
 +
                ctx->obex = gw_obex_setup_dev(ctx->rfcomm_dev, NULL,
 +
                        0, NULL, &err);
 +
 +
        if (ctx->obex == NULL)
 +
                printf("OBEX setup failed: %s\n", response_to_string(err));
 +
}
 +
</source>
 +
 +
In this example, <code>ctx-&gt;rfcomm_dev</code> points to a string containing the device node name (e.g. <code>/dev/rfcomm0</code>). <code>ctx-&gt;use_ftp</code> dictates whether to set up standard folder browsing services. If <code>use_ftp</code> is untrue, then INBOX is connected.
===Closing Connection ===
===Closing Connection ===
 +
To close a gwobex connection, use the following function: gw-obex.h
To close a gwobex connection, use the following function: gw-obex.h
-
<tt><span><font color="#009900">void</font></span> <span>'''<span><font color="#000000">gw_obex_close</font></span>'''</span> <span><font color="#990000">(</font></span> GwObex <span><font color="#990000"><nowiki>*</nowiki></font></span> ctx <span><font color="#990000">);</font></span></tt>
+
<source lang="c">
 +
void gw_obex_close ( GwObex * ctx );
 +
</source>
The following code demonstrates this usage.
The following code demonstrates this usage.
-
<tt><span>'''<span><font color="#0000FF">if</font></span>'''</span> <span><font color="#990000">(</font></span>ctx<span><font color="#990000">-&gt;</font></span>obex<span><font color="#990000">)</font></span> <span><font color="#FF0000">{</font></span>
+
<source lang="c">
-
        <span>'''<span><font color="#000000">gw_obex_close</font></span>'''</span><span><font color="#990000">(</font></span>ctx<span><font color="#990000">-&gt;</font></span>obex<span><font color="#990000">);</font></span>
+
if (ctx->obex) {
-
        ctx<span><font color="#990000">-&gt;</font></span>obex <span><font color="#990000"><nowiki>=</nowiki></font></span> NULL<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
        gw_obex_close(ctx->obex);
-
<span><font color="#FF0000">}</font></span></tt>
+
        ctx->obex = NULL;
-
 
+
}
-
If ctx-&gt;obex is not NULL, it is simply passed as an argument to gw_obex_close().
+
</source>
 +
If <code>ctx-&gt;obex</code> is not <code>NULL</code>, it is simply passed as an argument to <code>gw_obex_close()</code>.
===Using Connection ===
===Using Connection ===
 +
The libgwobex library provides general file handling functionality, including reading directory structure, browsing in different folders and getting files.
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
To read entries from an opened directory, use the following function: gw-obex.h
-
<tt>gboolean <span>'''<span><font color="#000000">gw_obex_read_dir</font></span>'''</span> <span><font color="#990000">(</font></span>GwObex <span><font color="#990000"><nowiki>*</nowiki></font></span> ctx<span><font color="#990000">,</font></span>
+
<source lang="c">
-
                            <span>'''<span><font color="#0000FF">const</font></span>'''</span> gchar <span><font color="#990000"><nowiki>*</nowiki></font></span> dir<span><font color="#990000">,</font></span>
+
gboolean gw_obex_read_dir (GwObex * ctx,
-
                            gchar <span><font color="#990000"><nowiki>**</nowiki></font></span> buf<span><font color="#990000">,</font></span>
+
                          const gchar * dir,
-
                            gint <span><font color="#990000"><nowiki>*</nowiki></font></span> buf_size<span><font color="#990000">,</font></span>
+
                          gchar ** buf,
-
                            gint <span><font color="#990000"><nowiki>*</nowiki></font></span> error <span><font color="#990000">);</font></span></tt>
+
                          gint * buf_size,
 +
                          gint * error );
 +
</source>
-
gw_obex_read_dir reads an entry from the selected folder and returns the result in the buf argument given to the function.
+
<code>gw_obex_read_dir</code> reads an entry from the selected folder and returns the result in the <code>buf</code> argument given to the function.
-
<tt>gboolean ret<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
<source lang="c">
-
<span>''<span><font color="#9A1900">/* ... */</font></span>''</span>
+
gboolean ret;
-
ret <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">gw_obex_read_dir</font></span>'''</span><span><font color="#990000">(</font></span>ctx<span><font color="#990000">-&gt;</font></span>obex<span><font color="#990000">,</font></span> dir<span><font color="#990000">,</font></span> buf<span><font color="#990000">,</font></span> buf_size<span><font color="#990000">,</font></span> err<span><font color="#990000">);</font></span></tt>
+
/* ... */
 +
ret = gw_obex_read_dir(ctx->obex, dir, buf, buf_size, err);
 +
</source>
-
This reads an entry from the directory dir (char *) and returns it in buf (char **).
+
This reads an entry from the directory <code>dir (char *)</code> and returns it in <code>buf (char **)</code>.
To change the current directory, use the following function: gw-obex.h
To change the current directory, use the following function: gw-obex.h
-
<tt>gboolean <span>'''<span><font color="#000000">gw_obex_chdir</font></span>'''</span> <span><font color="#990000">(</font></span>GwObex <span><font color="#990000"><nowiki>*</nowiki></font></span> ctx<span><font color="#990000">,</font></span> <span>'''<span><font color="#0000FF">const</font></span>'''</span> gchar <span><font color="#990000"><nowiki>*</nowiki></font></span> dir<span><font color="#990000">,</font></span> gint <span><font color="#990000"><nowiki>*</nowiki></font></span> error <span><font color="#990000">);</font></span></tt>
+
<source lang="c">
 +
gboolean gw_obex_chdir (GwObex * ctx, const gchar * dir, gint * error );
 +
</source>
which changes the directory of the FTP connection. Below is a code example using this function.
which changes the directory of the FTP connection. Below is a code example using this function.
-
<tt><span>''<span><font color="#9A1900">/* Ignore parent dir pointers */</font></span>''</span>
+
<source lang="c">
-
<span>'''<span><font color="#0000FF">if</font></span>'''</span> <span><font color="#990000">(</font></span><span>'''<span><font color="#000000">g_str_equal</font></span>'''</span><span><font color="#990000">(</font></span>name<span><font color="#990000">,</font></span> <span><font color="#FF0000">".."</font></span><span><font color="#990000">))</font></span>
+
/* Ignore parent dir pointers */
-
        <span>'''<span><font color="#0000FF">return</font></span>'''</span> TRUE<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
if (g_str_equal(name, ".."))
-
+
        return TRUE;
-
<span>'''<span><font color="#0000FF">if</font></span>'''</span> <span><font color="#990000">(!</font></span><span>'''<span><font color="#000000">gw_obex_chdir</font></span>'''</span><span><font color="#990000">(</font></span>ctx<span><font color="#990000">-&gt;</font></span>obex<span><font color="#990000">,</font></span> name<span><font color="#990000">,</font></span> err<span><font color="#990000">))</font></span> <span><font color="#FF0000">{</font></span>
+
-
        <span>'''<span><font color="#000000">printf</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#FF0000">"Could not chdir to %s</font></span><span><font color="#CC33CC">\n</font></span><span><font color="#FF0000">"</font></span><span><font color="#990000">,</font></span> name<span><font color="#990000">);</font></span>
+
-
        <span>'''<span><font color="#0000FF">return</font></span>'''</span> FALSE<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
<span><font color="#FF0000">}</font></span></tt>
+
-
To retrieve files over the OBEX connection, use the gw_obex_get_file function: gw-obex.h
+
if (!gw_obex_chdir(ctx->obex, name, err)) {
 +
        printf("Could not chdir to %s\n", name);
 +
        return FALSE;
 +
}
 +
</source>
-
<tt>gboolean <span>'''<span><font color="#000000">gw_obex_get_file</font></span>'''</span> <span><font color="#990000">(</font></span>GwObex <span><font color="#990000"><nowiki>*</nowiki></font></span> ctx<span><font color="#990000">,</font></span>
+
To retrieve files over the OBEX connection, use the <code>gw_obex_get_file</code> function: gw-obex.h
-
                            <span>'''<span><font color="#0000FF">const</font></span>'''</span> gchar <span><font color="#990000"><nowiki>*</nowiki></font></span> local<span><font color="#990000">,</font></span>
+
-
                            <span>'''<span><font color="#0000FF">const</font></span>'''</span> gchar <span><font color="#990000"><nowiki>*</nowiki></font></span> remote<span><font color="#990000">,</font></span>
+
-
                            <span>'''<span><font color="#0000FF">const</font></span>'''</span> gchar <span><font color="#990000"><nowiki>*</nowiki></font></span> type<span><font color="#990000">,</font></span>
+
-
                            gint <span><font color="#990000"><nowiki>*</nowiki></font></span> error<span><font color="#990000">);</font></span>
+
-
</tt>
+
-
gw_obex_get_file uses the ctx context for retrieving the remote file to local file.
+
<source lang="c">
 +
gboolean gw_obex_get_file (GwObex * ctx,
 +
                          const gchar * local,
 +
                          const gchar * remote,
 +
                          const gchar * type,
 +
                          gint * error);
 +
</source>
-
<tt>gboolean ret<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
<code>gw_obex_get_file</code> uses the <code>ctx</code> context for retrieving the remote file to local file.
-
ret <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">gw_obex_get_file</font></span>'''</span><span><font color="#990000">(</font></span>ctx<span><font color="#990000">-&gt;</font></span>obex<span><font color="#990000">,</font></span> name<span><font color="#990000">,</font></span> name<span><font color="#990000">,</font></span> err<span><font color="#990000">);</font></span></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].
+
<source lang="c">
 +
gboolean ret;
 +
ret = gw_obex_get_file(ctx->obex, name, name, err);
 +
</source>
 +
Using the libwobex wrapper directly allows you to perform many more functions. For more information, see the [http://maemo.org/api_refs/5.0/5.0-final/osso-gwobex/ API document].
===Libopenobex ===
===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-&gt;Specifications category. OBEX resembles the HTTP protocol, expect for a few differences: </nowiki>
+
 
 +
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]; select the Developer-&gt;Specifications category. OBEX resembles the HTTP protocol, expect for a few differences:
* Transports: While HTTP is normally layered above a TCP/IP connection, OBEX is usually transported over IrLAP/IrLMP/Tiny TP (on IrDA) or over Baseband/Link Manager/L2CAP/RFCOMM (on Bluetooth).
* 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).
Line 730: Line 840:
* Session support: HTTP is stateless, while OBEX maintains the connection.
* Session support: HTTP is stateless, while OBEX maintains the connection.
-
For more information on OBEX, see the summary available at <br />http://en.wikipedia.org/wiki/OBEX.
+
For more information on OBEX, see the summary available at the [[:wikipedia:OBject EXchange|Wikipedia article on OBEX]].
-
 
+
-
For libopenobex code samples, see <br />http://openobex.triq.net/downloads<nowiki>; the samples are in the example apps package. </nowiki>
+
 +
For libopenobex code samples, see http://openobex.triq.net/downloads the samples are in the example apps package.
===Using BlueZ D-Bus API ===
===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:
The BlueZ system exports a D-Bus API that can be employed instead of OSSO Bluetooth tools. See the following documents:
-
* [http://bluez.cvs.sourceforge.net/*checkout*/bluez/utils/hcid/dbus-api.txt BlueZ D-Bus API documentation]
+
* [http://git.kernel.org/?p=bluetooth/bluez.git;a=tree;f=doc;hb=HEAD BlueZ D-Bus API documentation]
-
* [http://wiki.bluez.org/ BlueZ Wiki]
+
-
 
+
==Connectivity UI ==
==Connectivity UI ==
===UI Components ===
===UI Components ===
 +
Connectivity UI contains various dialogs and other components used to control the connectivity. The different UI parts are:
Connectivity UI contains various dialogs and other components used to control the connectivity. The different UI parts are:
-
* Connection manager
+
* Connectivity UI
* Connectivity dialogs
* Connectivity dialogs
* Status bar applets
* Status bar applets
Line 753: Line 862:
* Bluetooth UIs
* 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.
+
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 ===
-
===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:
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
 +
: <code>com.nokia.icd_ui</code>
 +
;Interfaces
 +
: <code>com.nokia.icd_ui</code>
 +
;Object paths
 +
: <code>/com/nokia/icd_ui</code>
-
+
The Internet Connectivity UIs implement the following D-Bus API used by the ICd and EAP.
-
Service:          com.nokia.icd_ui
+
-
Interfaces:        com.nokia.icd_ui
+
-
Object paths:      /com/nokia/icd_ui
+
-
</div>
+
==== D-Bus methods ====
 +
===== show_conn_dlg =====
-
The Internet Connectivity UIs implement the following D-Bus API used by the ICd and EAP.
+
;Parameters
 +
: <ol><li>boolean: When <code>TRUE</code> the dialog is requested because there were no saved connections (i.e. autoconnect was tried before invoking the dialog)</li></ol>
 +
;Return parameters
 +
: none
 +
;Errors
 +
: <code>com.nokia.icd_ui.error.flight_mode</code>: Flight mode enabled, dialog not shown
 +
;Description
 +
: Shows the Connect Dialog where the user can choose an IAP.
 +
===== show_disconnect_dlg =====
-
<div class="graybox">
+
;Parameters
 +
: none
 +
;Return Parameters
 +
: none
 +
;Errors
 +
: <code>com.nokia.icd_ui.error.flight_mode</code>: Flight mode enabled, dialog not shown
 +
;Description
 +
: Shows the disconnect dialog.
-
+
===== show_retry_dlg =====
-
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>
+
;Parameters
 +
: <ol><li>string  Bluetooth address of the device used with SAP</li><li>string  Name of the connection attempt error which selects the retry dialog type.</li></ol>
 +
;Return Parameters
 +
: none
 +
;Errors
 +
: <code>com.nokia.icd_ui.error.flight_mode</code>: Flight mode enabled, dialog not shown
 +
;Description
 +
: Shows the retry dialog.
 +
===== show_change_dlg =====
-
<div class="graybox">
+
;Parameters
 +
: <ol><li>string  Name of the currently active IAP</li><li>string  Name of the IAP to be activated</li></ol>
 +
;Return Parameters
 +
: none
 +
;Errors
 +
: <code>com.nokia.icd_ui.error.flight_mode</code>: Flight mode enabled, dialog not shown
 +
;Description
 +
: Shows the Change IAP Dialog
-
+
===== show_passwd_dlg =====
-
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>
+
;Parameters
 +
: <ol><li>string  Username supplied by ICd</li><li>string  Password supplied by ICd</li><li>string  Name of the IAP</li></ol>
 +
;Return Parameters
 +
: none
 +
;Errors
 +
: <code>com.nokia.icd_ui.error.flight_mode</code>: Flight mode enabled, dialog not shown
 +
; Description
 +
: Shows the username/password dialog.
 +
===== show_gtc_dlg =====
-
<div class="graybox">
+
;Parameters
 +
: <ol><li>string  GTC challenge string</li></ol>
 +
;Return Parameters
 +
: none
 +
;Errors
 +
: <code>com.nokia.icd_ui.error.flight_mode</code>: Flight mode enabled, dialog not shown
 +
;Description
 +
: Shows EAP GTC challenge dialog.
-
+
===== show_mschap_change_dlg =====
-
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>
+
;Parameters
 +
: <ol><li>string  Supplied username</li><li>string  Old password that is to be changed</li><li>string  Name of the IAP</li>
 +
;Return Parameters
 +
: none
 +
;Errors
 +
: <code>com.nokia.icd_ui.error.flight_mode</code>: Flight mode enabled, dialog not shown
 +
;Description
 +
: Shows EAP MSCHAPv2 change password dialog.
 +
===== show_private_key_passwd_dlg =====
-
<div class="graybox">
+
;Parameters
 +
: <ol><li>byte array  Certificate ID</ol>
 +
;Return Parameters
 +
: none
 +
;Errors
 +
: <code>com.nokia.icd_ui.error.flight_mode</code>: Flight mode enabled, dialog not shown
 +
;Description
 +
: Shows EAP private key password dialog
-
+
===== show_server_cert_dlg =====
-
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>
+
;Parameters
 +
: <ol><li>string  Certificate name</li><li>string  Certificate serial</li><li>boolean <code>TRUE</code> if certificate is expired, <code>FALSE</code> otherwise</li><li>boolean <code>TRUE</code> if root CA is unknown or self-signed certificate, <code>FALSE</code> otherwise</li></ol>
 +
;Return Parameters
 +
: none
 +
;Errors
 +
: <code>com.nokia.icd_ui.error.flight_mode</code>: 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.
 +
===== strong_bt_req =====
-
<div class="graybox">
+
;Parameters
 +
: <ol><li>string  Bluetooth address of the device to pair with</li><li>boolean  <code>TRUE</code> if strong authentication enabled, <code>FALSE</code> if strong authentication is disabled</li></ol>
 +
;Return Parameters
 +
: none
 +
;Errors
 +
: <code>com.nokia.icd_ui.error.flight_mode</code>: Flight mode enabled, dialog not shown
 +
;Description
 +
: Requests strong (16 digit) BT PIN dialog for a BT device
-
+
===== show_sim_pin_dlg =====
-
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>
+
;Parameters
 +
: <ol><li>string  Bluetooth address of the device used with SAP</li><li>boolean  <code>TRUE</code> if PIN was incorrect and retry dialog should be displayed before asking PIN. <code>FALSE</code> if this is the first PIN request.</li></ol>
 +
;Return Parameters
 +
: none
 +
;Errors
 +
: <code>com.nokia.icd_ui.error.flight_mode</code>: Flight mode enabled, dialog not shown
 +
;Description
 +
: Shows SIM PIN dialog
 +
The code example for the application to show the connect dialog using <code>show_conn_dlg</code> is following. Note the use of the macro.
-
<div class="graybox">
+
<source lang="c">
 +
#include <osso-ic-ui-dbus.h>
 +
/* ... */
 +
/* in our code somewhere, where we need the Connect Dialog*/
 +
DBusMessage *uimsg;
 +
/* construct the message for Connect Dialog request*/
 +
uimsg =
 +
  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 =
 +
  dbus_connection_send_with_reply_and_block(connection,
 +
                                    uimsg,
 +
                                  reply_timeout,
 +
                                  &error);
 +
if (reply == NULL) {
 +
    DLOG_ERR("Failed to show connect dialog: %s", uierror.message);
 +
    dbus_error_free(&uierror);
 +
}
 +
dbus_message_unref(uimsg);
 +
dbus_message_unref(reply);
 +
/* ... */
 +
</source>
-
+
==== D-Bus signals ====
-
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>
+
The signals emitted from <code>com.nokia.icd_ui</code> interface are listed below.
 +
===== disconnect =====
-
<div class="graybox">
+
;Parameters
 +
: <ol><li>boolean  <code>TRUE</code> if "disconnect" pressed, <code>FALSE</code> if "cancel"</li></ol>
 +
;Description
 +
: Signal emitted from UI when disconnect dialog has been closed.
-
 
-
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>
+
===== retry =====
 +
;Parameters
 +
: <ol><li>string  The IAP that is to be retried</li><li>boolean  <code>TRUE</code> if "retry" pressed, <code>FALSE</code> if "cancel"</li></ol>
 +
;Description
 +
: Signal emitted from UI when the retry dialog has been closed.
-
<div class="graybox">
+
===== change =====
-
+
;Parameters
-
Method:           show_private_key_passwd_dlg
+
: <ol><li>string Old IAP to change from</li><li>string New IAP to change to</li><li>boolean Change to the new IAP If <code>TRUE</code>, keep old if <code>FALSE</code></li></ol>
-
  Parameters:        1. byte array Certificate ID
+
;Description
-
   
+
: Signal emitted from UI when change connection dialog has been closed.
-
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>
+
===== passwd =====
 +
;Parameters
 +
: <ol><li>string  Username supplied or modified by the user</li><li>string  Password supplied or modified by the user</li><li>string  IAP name</li><li>boolean  <code>TRUE</code> if "ok" pressed, <code>FALSE</code> if "cancel"</li></ol>
 +
;Description
 +
: Signal emitted from UI when the username/password dialog has been closed
-
<div class="graybox">
 
-
+
===== gtc_response =====
-
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>
+
;Parameters
 +
: <ol><li>string  Response to the given challenge or empty string if cancelled</li><li>boolean  <code>TRUE</code> if "ok" pressed, <code>FALSE</code> if "cancel"</li></ol>
 +
;Description
 +
: Signal emitted from UI when the EAP GTC challenge dialog has been closed.
 +
===== mschap_change =====
-
<div class="graybox">
+
;Parameters
 +
: <ol><li>string  Supplied username</li><li>string  The new password or empty string if cancelled</li><li>string  IAP name</li><li>boolean  <code>TRUE</code> if "ok" pressed, <code>FALSE</code> if "cancel"</li></ol>
 +
;Description
 +
: Signal emitted from UI when the MSCHAPv2 password has been changed
-
+
===== private_key_passwd =====
-
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>
+
;Parameters
 +
: <ol><li>byte array  Certificate ID</li><li>string  Password for the private key or empty string if none</li><li>boolean  <code>TRUE</code> if "ok" pressed, <code>FALSE</code> if "cancel"</li>
 +
;Description
 +
: Signal emitted from UI when the private key password dialog has been closed
 +
===== server_cert =====
-
<div class="graybox">
+
;Parameters
 +
: <ol><li>boolean  <code>TRUE</code> if strong PIN entered, <code>FALSE</code> if strong PIN dialog was canceled</li></ol>
 +
;Description
 +
: Signal emitted from UI when the server certificate error dialog has been closed
-
+
===== strong_bt =====
-
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>
+
;Parameters
 +
: <ol><li>boolean  <code>TRUE</code> if strong PIN entered, <code>FALSE</code> if strong PIN dialog was cancelled</li></ol>
 +
;Description
 +
: Signal emitted from UI when the strong (16 digit) BT PIN has been entered
 +
===== sim_pin =====
-
The code example for the application to show the connect dialog using show_conn_dlg is following. Note the use of the macro.
+
;Parameters
 +
: <ol><li>string  SIM PIN code or empty string if  cancelled</li><li>boolean  <code>TRUE</code> if "ok" pressed, <code>FALSE</code> if "cancel"</li></ol>
 +
;Description
 +
: Signal emitted from UI when the SIM PIN has been entered.
-
<tt><span>'''<span><font color="#000080"><nowiki>#include</nowiki></font></span>'''</span> <span><font color="#FF0000">&lt;osso-ic-ui-dbus.h&gt;</font></span>
+
===Bluetooth D-Bus UI dialogs ===
-
<span>''<span><font color="#9A1900">/* ... */</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">/* in our code somewhere, where we need the Connect Dialog*/</font></span>''</span>
+
-
DBusMessage <span><font color="#990000"><nowiki>*</nowiki></font></span>uimsg<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
<span>''<span><font color="#9A1900">/* construct the message for Connect Dialog request*/</font></span>''</span>
+
-
uimsg <span><font color="#990000"><nowiki>=</nowiki></font></span>
+
-
  <span>'''<span><font color="#000000">dbus_message_new_method_call</font></span>'''</span><span><font color="#990000">(</font></span>ICD_UI_DBUS_SERVICE<span><font color="#990000">,</font></span>
+
-
                              ICD_UI_DBUS_PATH<span><font color="#990000">,</font></span>
+
-
                            ICD_UI_DBUS_INTERFACE<span><font color="#990000">,</font></span>
+
-
                          <span>''<span><font color="#9A1900">/*macro for show_conn_dlg */</font></span>''</span>
+
-
                                ICD_UI_SHOW_CONNDLG_REQ<span><font color="#990000">);</font></span>
+
-
<span>''<span><font color="#9A1900">/* send the message */</font></span>''</span>
+
-
reply <span><font color="#990000"><nowiki>=</nowiki></font></span>
+
-
  <span>'''<span><font color="#000000">dbus_connection_send_with_reply_and_block</font></span>'''</span><span><font color="#990000">(</font></span>connection<span><font color="#990000">,</font></span>
+
-
                                    uimsg<span><font color="#990000">,</font></span>
+
-
                                    reply_timeout<span><font color="#990000">,</font></span>
+
-
                                    <span><font color="#990000">&amp;</font></span>error<span><font color="#990000">);</font></span>
+
-
<span>'''<span><font color="#0000FF">if</font></span>'''</span> <span><font color="#990000">(</font></span>reply <span><font color="#990000"><nowiki>==</nowiki></font></span> NULL<span><font color="#990000">)</font></span> <span><font color="#FF0000">{</font></span>
+
-
    <span>'''<span><font color="#000000">DLOG_ERR</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#FF0000">"Failed to show connect dialog: %s"</font></span><span><font color="#990000">,</font></span> uierror<span><font color="#990000">.</font></span>message<span><font color="#990000">);</font></span>
+
-
    <span>'''<span><font color="#000000">dbus_error_free</font></span>'''</span><span><font color="#990000">(&amp;</font></span>uierror<span><font color="#990000">);</font></span>
+
-
<span><font color="#FF0000">}</font></span>
+
-
<span>'''<span><font color="#000000">dbus_message_unref</font></span>'''</span><span><font color="#990000">(</font></span>uimsg<span><font color="#990000">);</font></span>
+
-
<span>'''<span><font color="#000000">dbus_message_unref</font></span>'''</span><span><font color="#990000">(</font></span>reply<span><font color="#990000">);</font></span>
+
-
<span>''<span><font color="#9A1900">/* ... */</font></span>''</span></tt>
+
-
The signals emitted from com.nokia.icd_ui interface are listed below.
+
conbtdialogs-dbus.h
 +
<source lang="c">
 +
/**
 +
  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:
 +
*/
-
<div class="graybox">
+
#ifndef CONBTDIALOGS_DBUS_H
 +
#define CONBTDIALOGS_DBUS_H
-
+
#ifdef __cplusplus
-
Signal:        disconnect
+
extern "C" {
-
Parameters:    1. boolean  TRUE if "disconnect" pressed, FALSE if "cancel"
+
#endif
-
+
-
Description:  Signal emitted from UI when disconnect dialog has been closed.
+
-
</div>
+
/** Conbtdialogs service, resides in system dbus */
 +
#define CONBTDIALOGS_DBUS_SERVICE                "com.nokia.bt_ui"
 +
/** Conbtdialogs interface */
 +
#define CONBTDIALOGS_DBUS_INTERFACE                "com.nokia.bt_ui"
 +
/** Conbtdialogs path */
 +
#define 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.
 +
*/
 +
#define CONBTDIALOGS_SEND_FILE_REQ                "show_send_file_dlg"
-
<div class="graybox">
+
/**
-
 
+
  File sending result signal
   
   
-
Signal:       retry
+
  Arguments:
-
Parameters:    1. string  The IAP that is to be retried
+
 
-
                2. boolean  TRUE if "retry" pressed, FALSE if "cancel"
+
  success: DBUS_TYPE_BOOLEAN        TRUE, if all files were sent successfully or
 +
                                FALSE, if error occurred or sending was
 +
                                canceled.
 +
*/
 +
#define CONBTDIALOGS_SEND_FILE_SIG                "send_file"
 +
 
 +
/**
 +
  Show BT device search dialog
   
   
-
DescriptionSignal emitted from UI when the retry dialog has been closed.
+
  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"
-
</div>
+
                                - 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.
 +
*/
 +
#define CONBTDIALOGS_SEARCH_REQ                "show_search_dlg"
-
<br /><br />
+
/**
-
 
+
  Bluetooth search result signal
-
<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
+
   
   
-
DescriptionSignal emitted from UI when change connection dialog has
+
  Arguments:
-
                been closed.
+
    
 +
  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.
 +
*/
 +
#define CONBTDIALOGS_SEARCH_SIG                "search_result"
 +
</source>
-
</div>
+
<source lang="c">
 +
/**
 +
  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
 +
*/
-
<div class="graybox">
+
#define DBUS_API_SUBJECT_TO_CHANGE
-
+
#include <glib.h>
-
Signal:        passwd
+
#include <conbtdialogs-dbus.h>
-
Parameters:    1. string  Username supplied or modified by the user
+
#include <dbus/dbus.h>
-
                2. string  Password supplied or modified by the user
+
#include <dbus/dbus-glib.h>
-
                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>
+
DBusGConnection *connection = NULL;
 +
GMainLoop *mainloop = NULL;
 +
static gboolean initialize(void)
 +
{
 +
    GError *error = NULL;
-
<div class="graybox">
+
    g_type_init ();
-
+
    /* Create main loop */
-
Signal:        gtc_response
+
    mainloop = g_main_loop_new(NULL, TRUE);
-
Parameters:    1. string  Response to the given challenge or empty string
+
    if ( mainloop == NULL ) return FALSE;
-
                            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>
+
    /* Create DBUS connection */
 +
    connection = dbus_g_bus_get(DBUS_BUS_SYSTEM, &error);
 +
    if (connection == NULL )
 +
    {
 +
        g_print ("Error: %s\n", error->message);
 +
        g_clear_error (&error);
 +
        return FALSE;
 +
    }
-
<div class="graybox">
+
    return TRUE;
 +
}
-
+
static gboolean uninitialize(void)
-
Signal:        mschap_change
+
{
-
Parameters:    1. string  Supplied username
+
    /* Quit main loop and unref it */
-
                2. string  The new password or empty string if cancelled
+
    if (mainloop != NULL)
-
                3. string  IAP name
+
    {
-
                4. boolean  TRUE if "ok" pressed, FALSE if "cancel"
+
        g_main_loop_quit(mainloop);
-
+
        g_main_loop_unref(mainloop);
-
Description:  Signal emitted from UI when the MSCHAPv2 password has been
+
    }
-
                changed
+
-
</div>
+
    return TRUE;
 +
}
 +
static DBusHandlerResult file_sent_signal ( DBusConnection *connection,
 +
                                            DBusMessage *message,
 +
                                            void *data )
 +
{
 +
    gboolean success = FALSE;
-
<div class="graybox">
+
    /* check signal */
 +
    if (!dbus_message_is_signal(message,
 +
                                CONBTDIALOGS_DBUS_INTERFACE,
 +
                                CONBTDIALOGS_SEND_FILE_SIG))
 +
        return DBUS_HANDLER_RESULT_NOT_YET_HANDLED;
-
+
    /* get args */
-
Signal:        private_key_passwd
+
    if ( !dbus_message_get_args ( message, NULL,
-
Parameters:    1. byte array  Certificate ID
+
                                  DBUS_TYPE_BOOLEAN, &success,
-
                2. string  Password for the private key or empty string if none
+
                                  DBUS_TYPE_INVALID ) )
-
                3. boolean  TRUE if "ok" pressed, FALSE if "cancel"
+
      return DBUS_HANDLER_RESULT_NOT_YET_HANDLED;
-
+
-
Description:  Signal emitted from UI when the private key password dialog
+
-
                has been closed
+
-
</div>
+
    /* 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();
-
<div class="graybox">
+
    return DBUS_HANDLER_RESULT_HANDLED;
 +
}
-
+
gint main(gint argc, gchar **argv)
-
Signal:        server_cert
+
{
-
Parameters:    1. boolean  TRUE if strong PIN entered, FALSE if strong
+
    GError *error = NULL;
-
                            PIN dialog was canceled
+
    gchar **files = NULL;
-
+
    gint idx = 0;
-
Description:  Signal emitted from UI when the server certificate error
+
    DBusGProxy *proxy;
-
                dialog has been closed
+
    DBusConnection *sys_conn;
 +
    gchar *filter_string = NULL;
-
</div>
+
    if (argc < 2) return 1;
-
<br /><br />
+
    if (initialize() == FALSE) {
 +
        uninitialize();
 +
        return 1;
 +
    }
-
<div class="graybox">
+
    /* Copy urls to GLib compatible char array */
 +
    files = g_new0(gchar*, argc);
-
+
    for (idx = 1; idx < argc; idx++)
-
Signal:        strong_bt
+
        files[idx-1] = g_strdup(argv[idx]);
-
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>
+
    files[argc-1] = NULL;
 +
    /* Open connection for btdialogs service */
 +
    proxy = dbus_g_proxy_new_for_name(connection,
 +
                                      CONBTDIALOGS_DBUS_SERVICE,
 +
                                      CONBTDIALOGS_DBUS_PATH,
 +
                                      CONBTDIALOGS_DBUS_INTERFACE);
-
<div class="graybox">
+
    /* 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;
 +
    }
 +
    g_strfreev (files);
 +
    files = NULL;
-
+
    g_object_unref(G_OBJECT(proxy));
-
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>
+
    /* Now wait for file sent signal, use low level bindings as glib
 +
      bindings require signal marshaller registered */
 +
    sys_conn = dbus_bus_get(DBUS_BUS_SYSTEM, NULL);
 +
    g_assert(dbus_connection_add_filter(sys_conn,
 +
                                        file_sent_signal,
 +
                                        NULL,
 +
                                        NULL ));
 +
    filter_string =
 +
      g_strdup_printf ("type='signal',interface='%s'", CONBTDIALOGS_DBUS_INTERFACE);
-
===Bluetooth DBUS UI dialogs ===
+
    dbus_bus_add_match(sys_conn, filter_string, NULL);
 +
    dbus_connection_unref(sys_conn);
-
conbtdialogs-dbus.h
+
    /* Run mainloop */
 +
    g_main_loop_run(mainloop);
-
<tt><span>''<span><font color="#9A1900">/** </font></span>''</span>
+
     return 0;
-
<span>''<span><font color="#9A1900">  Example of use (command line):</font></span>''</span>
+
}
-
<span>''<span><font color="#9A1900">  </font></span>''</span>
+
</source>
-
<span>''<span><font color="#9A1900">  dbus-send -system -print-reply \</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">    -dest='com.nokia.icd_ui' /com/nokia/bt_ui \</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">    com.nokia.bt_ui.show_send_file_dlg \</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">    array:string:</font></span>''</span><span><u><span><font color="#0000FF">file:///home/user/MyDocs/.documents/testing.txt</font></span></u></span>
+
-
<span>''<span><font color="#9A1900">    </font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  dbus-send -system -print-reply \</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">    -dest=com.nokia.bt_ui  /com/nokia/bt_ui </font></span>''</span>
+
-
<span>''<span><font color="#9A1900">    com.nokia.bt_ui.show_search_dlg \</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">    string: string: array:string: boolean:true</font></span>''</span>
+
-
<span>''<span><font color="#9A1900"><nowiki>*/</nowiki></font></span>''</span>
+
-
+
-
<span>'''<span><font color="#000080"><nowiki>#ifndef</nowiki></font></span>'''</span> CONBTDIALOGS_DBUS_H
+
-
<span>'''<span><font color="#000080"><nowiki>#define</nowiki></font></span>'''</span> CONBTDIALOGS_DBUS_H
+
-
+
-
<span>'''<span><font color="#000080"><nowiki>#ifdef</nowiki></font></span>'''</span> __cplusplus
+
-
<span>'''<span><font color="#0000FF">extern</font></span>'''</span> <span><font color="#FF0000">"C"</font></span> <span><font color="#FF0000">{</font></span>
+
-
<span>'''<span><font color="#000080"><nowiki>#endif</nowiki></font></span>'''</span>
+
-
+
-
<span>''<span><font color="#9A1900">/** Conbtdialogs service, resides in system dbus */</font></span>''</span>
+
-
<span>'''<span><font color="#000080"><nowiki>#define</nowiki></font></span>'''</span> CONBTDIALOGS_DBUS_SERVICE                <span><font color="#FF0000">"com.nokia.bt_ui"</font></span>
+
-
<span>''<span><font color="#9A1900">/** Conbtdialogs interface */</font></span>''</span>
+
-
<span>'''<span><font color="#000080"><nowiki>#define</nowiki></font></span>'''</span> CONBTDIALOGS_DBUS_INTERFACE                <span><font color="#FF0000">"com.nokia.bt_ui"</font></span>
+
-
<span>''<span><font color="#9A1900">/** Conbtdialogs path */</font></span>''</span>
+
-
<span>'''<span><font color="#000080"><nowiki>#define</nowiki></font></span>'''</span> CONBTDIALOGS_DBUS_PATH                        <span><font color="#FF0000">"/com/nokia/bt_ui"</font></span>
+
-
+
-
<span>''<span><font color="#9A1900">/** </font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  Show send file dialog</font></span>''</span>
+
-
<span>''<span><font color="#9A1900"> </font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  Arguments:</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  </font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  uris: DBUS_TYPE_ARRAY                Array of strings representing the URIs of the</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">                                files to send.</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  </font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  Returns:</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  </font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  DBUS_TYPE_BOOLEAN            TRUE, if dialog was shown successfully.</font></span>''</span>
+
-
<span>''<span><font color="#9A1900"> */</font></span>''</span>
+
-
<span>'''<span><font color="#000080"><nowiki>#define</nowiki></font></span>'''</span> CONBTDIALOGS_SEND_FILE_REQ                <span><font color="#FF0000">"show_send_file_dlg"</font></span>
+
-
+
-
<span>''<span><font color="#9A1900">/** </font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  File sending result signal</font></span>''</span>
+
-
<span>''<span><font color="#9A1900"> </font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  Arguments:</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  </font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  success: DBUS_TYPE_BOOLEAN        TRUE, if all files were sent successfully or</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">                                FALSE, if error occurred or sending was </font></span>''</span>
+
-
<span>''<span><font color="#9A1900">                                canceled.</font></span>''</span>
+
-
<span>''<span><font color="#9A1900"> */</font></span>''</span>
+
-
<span>'''<span><font color="#000080"><nowiki>#define</nowiki></font></span>'''</span> CONBTDIALOGS_SEND_FILE_SIG                <span><font color="#FF0000">"send_file"</font></span>
+
-
+
-
<span>''<span><font color="#9A1900">/** </font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  Show BT device search dialog</font></span>''</span>
+
-
<span>''<span><font color="#9A1900"> </font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  Arguments:</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  </font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  major_class: DBUS_TYPE_STRING To set filtering based on major_class or</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">                                "". Possible major class values are:</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">                                </font></span>''</span>
+
-
<span>''<span><font color="#9A1900">                                "miscellaneous", "computer", "phone", </font></span>''</span>
+
-
<span>''<span><font color="#9A1900">                                "access point", "audio/video", </font></span>''</span>
+
-
<span>''<span><font color="#9A1900">                                "peripheral", "imaging", "wearable",</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">                                "toy" and "uncategorized".</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  </font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  minor_class: DBUS_TYPE_STRING To set filtering based on minor_class or "".</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">                                Possible minor class values are:</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">                        </font></span>''</span>
+
-
<span>''<span><font color="#9A1900">                                - Minor classes for "computer": </font></span>''</span>
+
-
<span>''<span><font color="#9A1900">                                  "uncategorized", "desktop", "server",</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">                                  "laptop", "handheld", "palm", "wearable"</font></span>''</span>
+
-
+
-
<span>''<span><font color="#9A1900">                                - Minor classes for "phone": "uncategorized",</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">                                  "cellular", "cordless", "smart phone",</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">                                  "modem", "isdn"</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  </font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  service_classes: DBUS_TYPE_ARRAY To set filtering based on service classes.</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">                                  Supported classes include "positioning", </font></span>''</span>
+
-
<span>''<span><font color="#9A1900">                                  "networking", "rendering", "capturing",</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">                                  "object transfer", "audio", "telephony", </font></span>''</span>
+
-
<span>''<span><font color="#9A1900">                                  "information". Can be empty list, when no</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">                                  service class filtering is performed.</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  </font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  bonding: DBUS_TYPE_STRING     Bonding mode for found and selected device:</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">                                </font></span>''</span>
+
-
<span>''<span><font color="#9A1900">                                "require" for requiring a bonding from a</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">                                selected device (i.e. bond device if it has not</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">                                been bonded before). </font></span>''</span>
+
-
<span>''<span><font color="#9A1900">                                </font></span>''</span>
+
-
<span>''<span><font color="#9A1900">                                "force" to always bond (i.e. device will be</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">                                bonded even if bonded before).</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">                                </font></span>''</span>
+
-
<span>''<span><font color="#9A1900">                                Any other string will allow to search and</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">                                select device without bonding it.</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">                                </font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  Returns:</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  </font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  DBUS_TYPE_BOOLEAN            TRUE, if dialog was shown successfully.</font></span>''</span>
+
-
<span>''<span><font color="#9A1900"> */</font></span>''</span>
+
-
<span>'''<span><font color="#000080"><nowiki>#define</nowiki></font></span>'''</span> CONBTDIALOGS_SEARCH_REQ                <span><font color="#FF0000">"show_search_dlg"</font></span>
+
-
+
-
<span>''<span><font color="#9A1900">/** </font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  Bluetooth search result signal</font></span>''</span>
+
-
<span>''<span><font color="#9A1900"> </font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  Arguments:</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  </font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  address: DBUS_TYPE_STRING    Bluetooth address of the selected device, or ""</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">                                if search dialog was cancelled.</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  </font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  name: DBUS_TYPE_STRING        Name of the device.</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  </font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  icon: DBUS_TYPE_STRING        Logical name for the icon describing the </font></span>''</span>
+
-
<span>''<span><font color="#9A1900">                                device.</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  </font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  major_class: DBUS_TYPE_STRING Major class of the device.</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  </font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  minor_class: DBUS_TYPE_STRING Minor class of the device.</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  </font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  trusted: DBUS_TYPE_BOOLEAN    Defines whether the device is marked as a trusted device.</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  </font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  services: DBUS_TYPE_ARRAY    List of strings describing the service classes</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">                                and SDP-based services provided by the device.</font></span>''</span>
+
-
<span>''<span><font color="#9A1900"> */</font></span>''</span>
+
-
<span>'''<span><font color="#000080"><nowiki>#define</nowiki></font></span>'''</span> CONBTDIALOGS_SEARCH_SIG                <span><font color="#FF0000">"search_result"</font></span>
+
-
</tt>
+
-
<br>
+
[[Category:Development]]
-
 
+
[[Category:Documentation]]
-
<tt><span>''<span><font color="#9A1900">/**</font></span>''</span>
+
[[Category:Fremantle]]
-
<span>''<span><font color="#9A1900">  Bluetooth UI Library for maemo</font></span>''</span>
+
-
+
-
<span>''<span><font color="#9A1900">  Copyright (C) 2006 Nokia. All rights reserved.</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  </font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  This sample demonstrates the use of conbtdialogs API and especially </font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  send_file function. Compile the program with conbtdialogs and dbus:</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  </font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  gcc -Wall `pkg-config -libs -cflags dbus-glib-1 conbtdialogs` \</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">-o send_file conbtdialogs_send_file.c</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  </font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  Run with list of URLS:</font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  </font></span>''</span>
+
-
<span>''<span><font color="#9A1900">  ./send_file </font></span>''</span><span><u><span><font color="#0000FF">file:///home/user/MyDocs/.sounds/Everyday.mp3</font></span></u></span>
+
-
<span>''<span><font color="#9A1900"><nowiki>*/</nowiki></font></span>''</span>
+
-
+
-
<span>'''<span><font color="#000080"><nowiki>#define</nowiki></font></span>'''</span> DBUS_API_SUBJECT_TO_CHANGE
+
-
+
-
<span>'''<span><font color="#000080"><nowiki>#include</nowiki></font></span>'''</span> <span><font color="#FF0000">&lt;glib.h&gt;</font></span>
+
-
<span>'''<span><font color="#000080"><nowiki>#include</nowiki></font></span>'''</span> <span><font color="#FF0000">&lt;conbtdialogs-dbus.h&gt;</font></span>
+
-
<span>'''<span><font color="#000080"><nowiki>#include</nowiki></font></span>'''</span> <span><font color="#FF0000">&lt;dbus/dbus.h&gt;</font></span>
+
-
<span>'''<span><font color="#000080"><nowiki>#include</nowiki></font></span>'''</span> <span><font color="#FF0000">&lt;dbus/dbus-glib.h&gt;</font></span>
+
-
+
-
DBusGConnection <span><font color="#990000"><nowiki>*</nowiki></font></span>connection <span><font color="#990000"><nowiki>=</nowiki></font></span> NULL<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
GMainLoop <span><font color="#990000"><nowiki>*</nowiki></font></span>mainloop <span><font color="#990000"><nowiki>=</nowiki></font></span> NULL<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
+
-
<span>'''<span><font color="#0000FF">static</font></span>'''</span> gboolean <span>'''<span><font color="#000000">initialize</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#009900">void</font></span><span><font color="#990000">)</font></span>
+
-
<span><font color="#FF0000">{</font></span>
+
-
    GError <span><font color="#990000"><nowiki>*</nowiki></font></span>error <span><font color="#990000"><nowiki>=</nowiki></font></span> NULL<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
+
-
    <span>'''<span><font color="#000000">g_type_init</font></span>'''</span> <span><font color="#990000">();</font></span>
+
-
+
-
    <span>''<span><font color="#9A1900">/* Create main loop */</font></span>''</span>
+
-
    mainloop <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">g_main_loop_new</font></span>'''</span><span><font color="#990000">(</font></span>NULL<span><font color="#990000">,</font></span> TRUE<span><font color="#990000">);</font></span>
+
-
    <span>'''<span><font color="#0000FF">if</font></span>'''</span> <span><font color="#990000">(</font></span> mainloop <span><font color="#990000"><nowiki>==</nowiki></font></span> NULL <span><font color="#990000">)</font></span> <span>'''<span><font color="#0000FF">return</font></span>'''</span> FALSE<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
+
-
    <span>''<span><font color="#9A1900">/* Create DBUS connection */</font></span>''</span>
+
-
    connection <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">dbus_g_bus_get</font></span>'''</span><span><font color="#990000">(</font></span>DBUS_BUS_SYSTEM<span><font color="#990000">,</font></span> <span><font color="#990000">&amp;</font></span>error<span><font color="#990000">);</font></span>
+
-
+
-
    <span>'''<span><font color="#0000FF">if</font></span>'''</span> <span><font color="#990000">(</font></span>connection <span><font color="#990000"><nowiki>==</nowiki></font></span> NULL <span><font color="#990000">)</font></span>
+
-
    <span><font color="#FF0000">{</font></span>
+
-
        <span>'''<span><font color="#000000">g_print</font></span>'''</span> <span><font color="#990000">(</font></span><span><font color="#FF0000">"Error: %s</font></span><span><font color="#CC33CC">\n</font></span><span><font color="#FF0000">"</font></span><span><font color="#990000">,</font></span> error<span><font color="#990000">-&gt;</font></span>message<span><font color="#990000">);</font></span>
+
-
        <span>'''<span><font color="#000000">g_clear_error</font></span>'''</span> <span><font color="#990000">(&amp;</font></span>error<span><font color="#990000">);</font></span>
+
-
        <span>'''<span><font color="#0000FF">return</font></span>'''</span> FALSE<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
    <span><font color="#FF0000">}</font></span>
+
-
+
-
    <span>'''<span><font color="#0000FF">return</font></span>'''</span> TRUE<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
<span><font color="#FF0000">}</font></span>
+
-
+
-
<span>'''<span><font color="#0000FF">static</font></span>'''</span> gboolean <span>'''<span><font color="#000000">uninitialize</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#009900">void</font></span><span><font color="#990000">)</font></span>
+
-
<span><font color="#FF0000">{</font></span>
+
-
    <span>''<span><font color="#9A1900">/* Quit main loop and unref it */</font></span>''</span>
+
-
    <span>'''<span><font color="#0000FF">if</font></span>'''</span> <span><font color="#990000">(</font></span>mainloop <span><font color="#990000"><nowiki>!=</nowiki></font></span> NULL<span><font color="#990000">)</font></span>
+
-
    <span><font color="#FF0000">{</font></span>
+
-
        <span>'''<span><font color="#000000">g_main_loop_quit</font></span>'''</span><span><font color="#990000">(</font></span>mainloop<span><font color="#990000">);</font></span>
+
-
        <span>'''<span><font color="#000000">g_main_loop_unref</font></span>'''</span><span><font color="#990000">(</font></span>mainloop<span><font color="#990000">);</font></span>
+
-
    <span><font color="#FF0000">}</font></span>
+
-
+
-
    <span>'''<span><font color="#0000FF">return</font></span>'''</span> TRUE<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
<span><font color="#FF0000">}</font></span>
+
-
+
-
<span>'''<span><font color="#0000FF">static</font></span>'''</span> DBusHandlerResult <span>'''<span><font color="#000000">file_sent_signal</font></span>'''</span> <span><font color="#990000">(</font></span> DBusConnection <span><font color="#990000"><nowiki>*</nowiki></font></span>connection<span><font color="#990000">,</font></span>
+
-
                                            DBusMessage <span><font color="#990000"><nowiki>*</nowiki></font></span>message<span><font color="#990000">,</font></span>
+
-
                                            <span><font color="#009900">void</font></span> <span><font color="#990000"><nowiki>*</nowiki></font></span>data <span><font color="#990000">)</font></span>
+
-
<span><font color="#FF0000">{</font></span>
+
-
    gboolean success <span><font color="#990000"><nowiki>=</nowiki></font></span> FALSE<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
+
-
    <span>''<span><font color="#9A1900">/* check signal */</font></span>''</span>
+
-
    <span>'''<span><font color="#0000FF">if</font></span>'''</span> <span><font color="#990000">(!</font></span><span>'''<span><font color="#000000">dbus_message_is_signal</font></span>'''</span><span><font color="#990000">(</font></span>message<span><font color="#990000">,</font></span>
+
-
                                CONBTDIALOGS_DBUS_INTERFACE<span><font color="#990000">,</font></span>
+
-
                                CONBTDIALOGS_SEND_FILE_SIG<span><font color="#990000">))</font></span>
+
-
        <span>'''<span><font color="#0000FF">return</font></span>'''</span> DBUS_HANDLER_RESULT_NOT_YET_HANDLED<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
+
-
    <span>''<span><font color="#9A1900">/* get args */</font></span>''</span>
+
-
    <span>'''<span><font color="#0000FF">if</font></span>'''</span> <span><font color="#990000">(</font></span> <span><font color="#990000"><nowiki>!</nowiki></font></span><span>'''<span><font color="#000000">dbus_message_get_args</font></span>'''</span> <span><font color="#990000">(</font></span> message<span><font color="#990000">,</font></span> NULL<span><font color="#990000">,</font></span>
+
-
                                  DBUS_TYPE_BOOLEAN<span><font color="#990000">,</font></span> <span><font color="#990000">&amp;</font></span>success<span><font color="#990000">,</font></span>
+
-
                                  DBUS_TYPE_INVALID <span><font color="#990000">)</font></span> <span><font color="#990000">)</font></span>
+
-
      <span>'''<span><font color="#0000FF">return</font></span>'''</span> DBUS_HANDLER_RESULT_NOT_YET_HANDLED<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
+
-
    <span>''<span><font color="#9A1900">/* print if file sending was success or failure */</font></span>''</span>
+
-
    <span>'''<span><font color="#000000">g_print</font></span>'''</span> <span><font color="#990000">(</font></span> <span><font color="#FF0000">"File sending was a "</font></span> <span><font color="#990000">);</font></span>
+
-
+
-
    <span>'''<span><font color="#0000FF">if</font></span>'''</span> <span><font color="#990000">(</font></span>success<span><font color="#990000">)</font></span> <span>'''<span><font color="#000000">g_print</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#FF0000">"success</font></span><span><font color="#CC33CC">\n</font></span><span><font color="#FF0000">"</font></span><span><font color="#990000">);</font></span> <span>'''<span><font color="#0000FF">else</font></span>'''</span> <span>'''<span><font color="#000000">g_print</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#FF0000">"failure</font></span><span><font color="#CC33CC">\n</font></span><span><font color="#FF0000">"</font></span><span><font color="#990000">);</font></span>
+
-
    <span>'''<span><font color="#000000">dbus_connection_close</font></span>'''</span><span><font color="#990000">(</font></span>connection<span><font color="#990000">);</font></span>
+
-
    <span>'''<span><font color="#000000">uninitialize</font></span>'''</span><span><font color="#990000">();</font></span>
+
-
+
-
    <span>'''<span><font color="#0000FF">return</font></span>'''</span> DBUS_HANDLER_RESULT_HANDLED<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
<span><font color="#FF0000">}</font></span>
+
-
+
-
gint <span>'''<span><font color="#000000">main</font></span>'''</span><span><font color="#990000">(</font></span>gint argc<span><font color="#990000">,</font></span> gchar <span><font color="#990000"><nowiki>**</nowiki></font></span>argv<span><font color="#990000">)</font></span>
+
-
<span><font color="#FF0000">{</font></span>
+
-
    GError <span><font color="#990000"><nowiki>*</nowiki></font></span>error <span><font color="#990000"><nowiki>=</nowiki></font></span> NULL<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
    gchar <span><font color="#990000"><nowiki>**</nowiki></font></span>files <span><font color="#990000"><nowiki>=</nowiki></font></span> NULL<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
    gint idx <span><font color="#990000"><nowiki>=</nowiki></font></span> <span><font color="#993399">0</font></span><span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
    DBusGProxy <span><font color="#990000"><nowiki>*</nowiki></font></span>proxy<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
    DBusConnection <span><font color="#990000"><nowiki>*</nowiki></font></span>sys_conn<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
    gchar <span><font color="#990000"><nowiki>*</nowiki></font></span>filter_string <span><font color="#990000"><nowiki>=</nowiki></font></span> NULL<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
+
-
    <span>'''<span><font color="#0000FF">if</font></span>'''</span> <span><font color="#990000">(</font></span>argc <span><font color="#990000">&lt;</font></span> <span><font color="#993399">2</font></span><span><font color="#990000">)</font></span> <span>'''<span><font color="#0000FF">return</font></span>'''</span> <span><font color="#993399">1</font></span><span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
+
-
    <span>'''<span><font color="#0000FF">if</font></span>'''</span> <span><font color="#990000">(</font></span><span>'''<span><font color="#000000">initialize</font></span>'''</span><span><font color="#990000">()</font></span> <span><font color="#990000"><nowiki>==</nowiki></font></span> FALSE<span><font color="#990000">)</font></span> <span><font color="#FF0000">{</font></span>
+
-
        <span>'''<span><font color="#000000">uninitialize</font></span>'''</span><span><font color="#990000">();</font></span>
+
-
        <span>'''<span><font color="#0000FF">return</font></span>'''</span> <span><font color="#993399">1</font></span><span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
    <span><font color="#FF0000">}</font></span>
+
-
+
-
    <span>''<span><font color="#9A1900">/* Copy urls to GLib compatible char array */</font></span>''</span>
+
-
    files <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">g_new0</font></span>'''</span><span><font color="#990000">(</font></span>gchar<span><font color="#990000"><nowiki>*,</nowiki></font></span> argc<span><font color="#990000">);</font></span>
+
-
+
-
    <span>'''<span><font color="#0000FF">for</font></span>'''</span> <span><font color="#990000">(</font></span>idx <span><font color="#990000"><nowiki>=</nowiki></font></span> <span><font color="#993399">1</font></span><span><font color="#990000"><nowiki>;</nowiki></font></span> idx <span><font color="#990000">&lt;</font></span> argc<span><font color="#990000"><nowiki>;</nowiki></font></span> idx<span><font color="#990000">++)</font></span>
+
-
        files<span><font color="#990000">[</font></span>idx<span><font color="#990000">-</font></span><span><font color="#993399">1</font></span><span><font color="#990000">]</font></span> <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">g_strdup</font></span>'''</span><span><font color="#990000">(</font></span>argv<span><font color="#990000">[</font></span>idx<span><font color="#990000">]);</font></span>
+
-
+
-
    files<span><font color="#990000">[</font></span>argc<span><font color="#990000">-</font></span><span><font color="#993399">1</font></span><span><font color="#990000">]</font></span> <span><font color="#990000"><nowiki>=</nowiki></font></span> NULL<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
+
-
    <span>''<span><font color="#9A1900">/* Open connection for btdialogs service */</font></span>''</span>
+
-
    proxy <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">dbus_g_proxy_new_for_name</font></span>'''</span><span><font color="#990000">(</font></span>connection<span><font color="#990000">,</font></span>
+
-
                                      CONBTDIALOGS_DBUS_SERVICE<span><font color="#990000">,</font></span>
+
-
                                      CONBTDIALOGS_DBUS_PATH<span><font color="#990000">,</font></span>
+
-
                                      CONBTDIALOGS_DBUS_INTERFACE<span><font color="#990000">);</font></span>
+
-
+
-
    <span>''<span><font color="#9A1900">/* Send send file request to btdialogs service */</font></span>''</span>
+
-
    <span>'''<span><font color="#0000FF">if</font></span>'''</span> <span><font color="#990000">(!</font></span><span>'''<span><font color="#000000">dbus_g_proxy_call</font></span>'''</span><span><font color="#990000">(</font></span>proxy<span><font color="#990000">,</font></span> CONBTDIALOGS_SEND_FILE_REQ<span><font color="#990000">,</font></span>
+
-
                            <span><font color="#990000">&amp;</font></span>error<span><font color="#990000">,</font></span>
+
-
                            G_TYPE_STRV<span><font color="#990000">,</font></span> files<span><font color="#990000">,</font></span> G_TYPE_INVALID<span><font color="#990000">,</font></span>
+
-
                            G_TYPE_INVALID<span><font color="#990000">))</font></span>
+
-
    <span><font color="#FF0000">{</font></span>
+
-
        <span>'''<span><font color="#000000">g_print</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#FF0000">"Error: %s</font></span><span><font color="#CC33CC">\n</font></span><span><font color="#FF0000">"</font></span><span><font color="#990000">,</font></span> error<span><font color="#990000">-&gt;</font></span>message<span><font color="#990000">);</font></span>
+
-
        <span>'''<span><font color="#000000">g_clear_error</font></span>'''</span><span><font color="#990000">(&amp;</font></span>error<span><font color="#990000">);</font></span>
+
-
        <span>'''<span><font color="#000000">g_strfreev</font></span>'''</span> <span><font color="#990000">(</font></span>files<span><font color="#990000">);</font></span>
+
-
        <span>'''<span><font color="#000000">g_object_unref</font></span>'''</span><span><font color="#990000">(</font></span><span>'''<span><font color="#000000">G_OBJECT</font></span>'''</span><span><font color="#990000">(</font></span>proxy<span><font color="#990000">));</font></span>
+
-
        <span>'''<span><font color="#000000">uninitialize</font></span>'''</span><span><font color="#990000">();</font></span>
+
-
        <span>'''<span><font color="#0000FF">return</font></span>'''</span> <span><font color="#993399">1</font></span><span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
    <span><font color="#FF0000">}</font></span>
+
-
    <span>'''<span><font color="#000000">g_strfreev</font></span>'''</span> <span><font color="#990000">(</font></span>files<span><font color="#990000">);</font></span>
+
-
    files <span><font color="#990000"><nowiki>=</nowiki></font></span> NULL<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
+
-
    <span>'''<span><font color="#000000">g_object_unref</font></span>'''</span><span><font color="#990000">(</font></span><span>'''<span><font color="#000000">G_OBJECT</font></span>'''</span><span><font color="#990000">(</font></span>proxy<span><font color="#990000">));</font></span>
+
-
+
-
    <span>''<span><font color="#9A1900">/* Now wait for file sent signal, use low level bindings as glib </font></span>''</span>
+
-
<span>''<span><font color="#9A1900">      bindings require signal marshaller registered */</font></span>''</span>
+
-
    sys_conn <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">dbus_bus_get</font></span>'''</span><span><font color="#990000">(</font></span>DBUS_BUS_SYSTEM<span><font color="#990000">,</font></span> NULL<span><font color="#990000">);</font></span>
+
-
    <span>'''<span><font color="#000000">g_assert</font></span>'''</span><span><font color="#990000">(</font></span><span>'''<span><font color="#000000">dbus_connection_add_filter</font></span>'''</span><span><font color="#990000">(</font></span>sys_conn<span><font color="#990000">,</font></span>
+
-
                                        file_sent_signal<span><font color="#990000">,</font></span>
+
-
                                        NULL<span><font color="#990000">,</font></span>
+
-
                                        NULL <span><font color="#990000">));</font></span>
+
-
    filter_string <span><font color="#990000"><nowiki>=</nowiki></font></span>
+
-
        <span>'''<span><font color="#000000">g_strdup_printf</font></span>'''</span> <span><font color="#990000">(</font></span><span><font color="#FF0000">"type='signal',interface='%s'"</font></span><span><font color="#990000">,</font></span> CONBTDIALOGS_DBUS_INTERFACE<span><font color="#990000">);</font></span>
+
-
+
-
    <span>'''<span><font color="#000000">dbus_bus_add_match</font></span>'''</span><span><font color="#990000">(</font></span>sys_conn<span><font color="#990000">,</font></span> filter_string<span><font color="#990000">,</font></span> NULL<span><font color="#990000">);</font></span>
+
-
    <span>'''<span><font color="#000000">dbus_connection_unref</font></span>'''</span><span><font color="#990000">(</font></span>sys_conn<span><font color="#990000">);</font></span>
+
-
+
-
    <span>''<span><font color="#9A1900">/* Run mainloop */</font></span>''</span>
+
-
    <span>'''<span><font color="#000000">g_main_loop_run</font></span>'''</span><span><font color="#990000">(</font></span>mainloop<span><font color="#990000">);</font></span>
+
-
+
-
    <span>'''<span><font color="#0000FF">return</font></span>'''</span> <span><font color="#993399">0</font></span><span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
<span><font color="#FF0000">}</font></span></tt>
+

Latest revision as of 13:56, 1 March 2011

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.

Contents

[edit] 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) - LibConIC API works together with 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
  • 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.

[edit] 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.

[edit] 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.

Name
Connectivity UI
Purpose
Provides the UI for managing phone and Internet connections. Available as a Control Panel applet, and from the Status Bar.
Responsibilities and additional requirements
  • Displaying active connections with statistics
  • Updating status indicators
  • Providing dialogs for changing and disconnecting connections
Concurrent usage
(N/A)
Name
Phone Access
Purpose
Provides connections to phones with different Bluetooth profiles
Responsibilities and additional requirements
  • 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
Concurrent usage
Number of clients not limited by Maemo. However, some phones may not support more than one Bluetooth profile at a time.
Name
Internet Access
Purpose
Provides Internet connections over different bearers.
Responsibilities and additional requirements
  • 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
Concurrent usage
Number of clients not limited, but only one connection to the Internet can exist at any given time

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

[edit] 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.

Name
General Bluetooth UI
Purpose
User interface for managing all paired BT devices
Responsibilities and additional requirements
  • Keeping a list of all paired devices (not only phones)
Concurrent usage
N/A
Name
BT search
Purpose
Searches for available Bluetooth devices
Responsibilities and additional requirements
  • Bluetooth inquiry
  • Checking on offline mode state
Concurrent usage
N/A
Name
BT service discovery
Purpose
Checks if a found Bluetooth device is sufficient
Responsibilities and additional requirements
Bluetooth service discovery (SDP)
Concurrent usage
Not limited (but used by Phone selection UI and Phone connection daemon only)
Name
GW OBEX library
Purpose
Provides access to OpenOBEX library for the File selector (Gnome VFS) on a higher abstraction level than OpenOBEX itself supports
Responsibilities and additional requirements
  • Handling OBEX requests
Concurrent usage
Not limited

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

[edit] 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.

Name
IC daemon
Purpose
IC daemon establishes Internet connections over different bearers.
Responsibilities and additional requirements
  • Controlling that only one Internet connection (one active IAP) can exist at any given time
  • Using WLAN or GPRS connection daemon for getting a network device and getting the connection authenticated
  • Starting IP level services like PPP and DHCP
  • Providing statistics about the usage of IAPs to any application
Concurrent usage
Has multiple clients and limits the connections to one at a time
Name
Internet Connectivity GUI
Purpose
Has GUI applications for configuring Internet Access Points and WLAN settings.
Responsibilities and additional requirements
  • 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
Concurrent usage
N/A
Name
WLAN connection daemon
Purpose
Manages WLAN network connections
Responsibilities and additional requirements
  • 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
Concurrent usage
Not limited
Name
EAP UI
Purpose
User interface for EAP authentication
Responsibilities and additional requirements
  • Invoking a dialog for an authentication password
  • Showing authentication status
Concurrent usage
N/A
Name
EAP
Purpose
Provides WLAN security excluding basic WEP settings, which are in Wireless Extensions
Responsibilities and additional requirements
  • 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
Concurrent usage
N/A

[edit] 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.

[edit] 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: Use the connection and update all data.
    • Connection Lost: Go to an idle state silently and wait until a new connection is created.
    • Connection Changed: Use the new connection.
  • Ensure that automatic data updates run in background and silently:
    • Avoid alarming the user with unnecessary banners or dialogs.
    • Ensure that usernames and passwords are saved so that automatic updates can be performed without prompts.
    • During and after updates, ensure that no failures display error notifications.
  • The connectivity infrastructure must take care of error situations in a centralized way.

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

[edit] 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.

[edit] 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 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)

[edit] Application Requirements

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

  1. use non-blocking sockets
  2. have the system D-Bus running
  3. g_type_init() has to be called
  4. 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.

[edit] 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.

[edit] 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.

[edit] GType

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

[edit] No Multiple Threads

Libconic API is not thread-safe. If the applications has threads, use Libconic API only from the same context where GMainloop is running.

[edit] Libconic Usage

[edit] 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:

    gboolean success = FALSE;
    /* Create connection object */
    ConIcConnection *connection = 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 = con_ic_connection_connect(connection, CON_IC_CONNECT_FLAG_NONE);
    if (!success) g_warning("Request for connection failed");

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:

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

[edit] 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 the automatic-connection-events GObject property, can achieve this:

    /* Create connection object */
    ConIcConnection *connection = 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);

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

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

static void connection_info(ConIcConnection *connection,
                            ConIcConnectionEvent *event,
                            gpointer user_data)
{
    ConIcConnectionStatus status = con_ic_connection_event_get_status(event);
    ConIcConnectionStatus *status_ptr = (ConIcConnectionStatus*)user_data;
    *status_ptr = status;
}
/* ... */
    /* Create connection object and set on automatic events (see previous snippet) ... */
    static ConIcConnectionStatus status = 0xFFFF;
    ConIcConnection *connection = 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 == 0xFFFF) g_main_context_iteration(NULL, TRUE);
    if (status == CON_IC_STATUS_CONNECTED)
        g_debug("We are connected!");
    else
        g_debug("We are not connected!");

[edit] 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.

static void connection_statistics(ConIcConnection *connection,
                                  ConIcStatisticsEvent *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!");

[edit] 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 Wikipedia

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

static void my_connection_handler(ConIcConnection *connection,
                                  ConIcConnectionEvent *event,
                                  gpointer user_data)
{
    ConIcConnectionStatus status = con_ic_connection_event_get_status(event);
    GSList *ignore_hosts;
 
    if (status == 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:
                g_debug("No proxies defined, it is direct connection");
                break;
 
            case CON_IC_PROXY_MODE_MANUAL:
                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 = con_ic_connection_proxy_ignore_hosts(connection);
                for (GSList *iter = ignore_hosts; iter != NULL; iter = g_slist_next(iter))
                {
                    g_debug("%s", (gchar *)iter->data);
                    g_free(iter->data);
                }
                g_slist_free(ignore_hosts);
                break;
 
            case CON_IC_PROXY_MODE_AUTO:
                g_debug("Proxy auto-config URL %s should be used",
                        con_ic_connection_get_proxy_autoconfig_url(connection));
                break;
        }
    }
}

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.

[edit] 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:

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

[edit] Porting Application from OSSO IC API to Libconic

  • If the application does not have GType, GLib or D-Bus configured, set them up:
      DBusConnection *system_dbus;
      GMainLoop *main_loop;
      g_type_init();
      main_loop = g_main_loop_new(NULL, FALSE);
      system_dbus = dbus_bus_get(DBUS_BUS_SYSTEM, NULL);
      dbus_connection_setup_with_g_main(system_dbus, NULL);
  • Include the correct header file:
      #include <osso-ic.h>
      /* change to: */
      #include <conic.h>
  • Set up ConIcConnection object and connection-event handler instead of osso_iap_cb_t callback:
      static void my_connection_cb(struct iap_event_t *event, void *arg)
      {
      /* ... */
      }
      /* ... */
          osso_iap_cb(my_connection_cb);
      ===>
      static void my_connection_cb(ConIcConnection *connection,
                                   ConIcConnectionEvent *event,
                                   gpointer user_data)
      {
      /* ... */
      }
      /* ... */
          ConIcConnection *connection = con_ic_connection_new();
          g_signal_connect(G_OBJECT(connection), "connection-event",
                           G_CALLBACK(my_connection_cb), app_data);
  • 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:


GeSHi Error: GeSHi could not find the language autoconf (using path /usr/share/php-geshi/geshi/) (code 2)

You need to specify a language like this: <source lang="html4strict">...</source>

Supported languages for syntax highlighting:

abap, actionscript, actionscript3, ada, apache, applescript, apt_sources, asm, asp, autoit, avisynth, bash, basic4gl, bf, bibtex, blitzbasic, bnf, boo, c, c_mac, caddcl, cadlisp, cfdg, cfm, cil, cmake, cobol, cpp, cpp-qt, csharp, css, d, dcs, delphi, diff, div, dos, dot, eiffel, email, erlang, fo, fortran, freebasic, genero, gettext, glsl, gml, gnuplot, groovy, haskell, hq9plus, html4strict, idl, ini, inno, intercal, io, java, java5, javascript, kixtart, klonec, klonecpp, latex, lisp, locobasic, lolcode, lotusformulas, lotusscript, lscript, lsl2, lua, m68k, make, matlab, mirc, modula3, mpasm, mxml, mysql, nsis, oberon2, objc, ocaml, ocaml-brief, oobas, oracle11, oracle8, pascal, per, perl, php, php-brief, pic16, pixelbender, plsql, povray, powershell, progress, prolog, properties, providex, python, qbasic, rails, rebol, reg, robots, ruby, sas, scala, scheme, scilab, sdlbasic, smalltalk, smarty, sql, tcl, teraterm, text, thinbasic, tsql, typoscript, vb, vbnet, verilog, vhdl, vim, visualfoxpro, visualprolog, whitespace, whois, winbatch, xml, xorg_conf, xpp, z80

  • In debian/control file Build-Depends section, depend on libconic0-dev instead of osso-ic-dev.

[edit] 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.

[edit] Discovering devices

Maemo provides a D-Bus interface for displaying a Bluetooth device search dialog (You can find a list of available Bluetooth D-Bus calls below).

Devices can be searched with following steps:

  1. Set up a D-Bus connection
  2. call bt_ui.search_req to show the dialog - you can filter the results
  3. catch bt_ui.search_result signal
  4. process the results

Here is a working example in C:

// Bluetooth discovery example - bluetooth libraries will not work in the SDK!
#include <hildon/hildon-program.h>
#include <dbus/dbus.h>
#include <dbus/dbus-glib.h>
#include <contbtdialogs-dbus.h>
 
/* structure to hold some info */
typedef struct _AppData AppData;
struct _AppData {
    HildonProgram *program;
    HildonStackableWindow *window;
    DBusGConnection *dbus_conn;
};
 
static DBusGConnection *dbus_conn = NULL;
static AppData *app = NULL;
 
gboolean initialize()
{
    GError *error = NULL; 
 
    //connects to system bus - this is where bt_ui resides
    dbus_conn = dbus_g_bus_get(DBUS_BUS_SYSTEM, &error);
    if (dbus_conn == NULL)
    {
        g_print("Initialization failed: %s\n", error->message);
        g_clear_error(&error);
        return FALSE;
    }
 
    return TRUE;
}
 
DBusHandlerResult search_done(DBusConnection *con, DBusMessage *msg, void *data)
{
    gchar *device_address;
    gchar *device_name;
    gchar *device_name_logical;
    gchar *device_class_minor;
    gchar *device_class_major;
    gboolean device_trusted = FALSE;
    gchar **device_services;
    gint device_services_len;
    DBusError *err = NULL;
 
    if (dbus_message_is_signal(msg, CONBTDIALOGS_DBUS_INTERFACE, CONBTDIALOGS_SEARCH_SIG))
    {
        /* this is our message, so get response args */
        if (dbus_message_get_args(msg, err, DBUS_TYPE_STRING, &device_address,
                          DBUS_TYPE_STRING, &device_name,
                          DBUS_TYPE_STRING, &device_name_logical,
                          DBUS_TYPE_STRING, &device_class_major,
                          DBUS_TYPE_STRING, &device_class_minor,
                          DBUS_TYPE_BOOLEAN, &device_trusted,
                          DBUS_TYPE_ARRAY, &device_services,
                          DBUS_TYPE_INT32, &device_services_len,
                          DBUS_TYPE_INVALID))
        {
            g_print(_("Error getting device info: %s\n"), err->message);
            dbus_error_free(err);
 
            return DBUS_HANDLER_RESULT_NOT_YET_HANDLED;
        }
 
        g_print("OK");
        /* you can now use args */
        return DBUS_HANDLER_RESULT_HANDLED;
    }
 
    return DBUS_HANDLER_RESULT_NOT_YET_HANDLED;
}
 
gboolean searchBtDevices(AppData *app)
{
    GError *error = NULL;
    DBusGProxy *proxy;
    DBusConnection *second_conn;
    gchar *filter_string = NULL;
    gchar **filter = NULL;
 
    filter = g_new0(gchar*, 1);
    filter[0] = NULL;
 
    /* Create proxy to bluetooth UI service */
    proxy = dbus_g_proxy_new_for_name( app->dbus_conn,
                                   CONBTDIALOGS_DBUS_SERVICE,
                                   CONBTDIALOGS_DBUS_PATH,
                                   CONBTDIALOGS_DBUS_INTERFACE );
 
    hildon_banner_show_information( GTK_WIDGET(app->window), NULL, _("Searching BT devices..."));
 
    /* run the call to show dialog */
    if (!dbus_g_proxy_call( proxy,
                            CONBTDIALOGS_SEARCH_REQ,
                            &error,
                            G_TYPE_STRING, "",
                            G_TYPE_STRING, "",
                            G_TYPE_STRV, &filter,
                            G_TYPE_STRING, "require",
                            G_TYPE_INVALID, G_TYPE_INVALID ))
    {
        g_print(_("Bluetooth discovery failed: %s\n", error->message);
        g_clear_error(&error);
        g_strfreev(filter);
        g_object_unref( G_OBJECT(proxy) );
 
        return FALSE;
    }
 
    g_object_unref( G_OBJECT(proxy) );
    g_strfreev(filter);
 
    /* create second connection to catch our signal */
    second_conn = dbus_bus_get(DBUS_BUS_SYSTEM, NULL);
    /* set search_done as message handler */
    g_assert(dbus_connection_add_filter(second_conn, search_done, NULL, NULL));
    /* we are looking for signal, so accept only signals */
    filter_string = g_strdup_printf("type='signal'");
    dbus_bus_add_match(second_conn, filter_string, NULL);
    dbus_connection_unref(second_conn);
 
    return TRUE;
}
 
void search_btn_pressed(HildonButton *btn, gpointer data)
{
    /* data = our AppData struct */
    if (!searchBtDevices(data))
        return FALSE;
    else
        return TRUE;
}
 
HildonStackableWindow *createMainWindow(AppData *app)
{
    /** Creates window with button that searches bt devices when clicked **/
 
    HildonStackableWindow *window = HILDON_STACKABLE_WINDOW(hildon_stackable_window_new());
    GtkWidget *search_btn;
 
    search_btn = hildon_button_new( HILDON_SIZE_AUTO_WIDTH | HILDON_SIZE_FINGER_HEIGHT,
 HILDON_BUTTON_ARRANGEMENT_VERTICAL );
    hildon_button_set_text (HILDON_BUTTON (search_btn), "Bluetooth example", "BT example");
 
    /* Add signals */
    g_signal_connect( G_OBJECT(window), "delete_event", G_CALLBACK(gtk_main_quit), NULL;
    g_signal_connect( G_OBJECT(window), "destroy", G_CALLBACK(gtk_main_quit), NULL);
    g_signal_connect( G_OBJECT(search_btn), "clicked", G_CALLBACK(search_btn_pressed), app);
 
    gtk_widget_show_all( GTK_WIDGET(search_btn) );
 
    return window;     
}
 
int main(int argc, char* argv[])
{
    /* Create empty appdata */
    app = g_new0(AppData, 1);
 
    /* Init localization support */
    locale_init();
 
    /* Init gtk */
    gtk_init(&argc, &argv);
 
    if (!initialize())
        return -1;
 
    /* Create program object */
    app->program = HILDON_PROGRAM(hildon_program_get_instance());
    g_set_application_name("Bluetooth discovery example");
 
    app->window = createMainWindow();
    if (!window)
        return -1;
 
    app->dbus_conn = dbus_conn;
 
    gtk_widget_show_all( GTK_WIDGET(window) );
    gtk_main();
 
    /* just in case */
    if (dbus_conn != NULL)
        dbus_g_connection_unref(dbus_conn);
 
    return 0;
}

[edit] 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 GW OBEX Library Documentation.

[edit] Creating Connection

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

#define OBEX_FTP_UUID \
        "\xF9\xEC\x7B\xC4\x95\x3C\x11\xD2\x98\x4E\x52\x54\x00\xDC\x9E\x09"
#define OBEX_FTP_UUID_LEN 16
 
/* ... */
 
GwObex* gw_obex_setup_dev (const gchar * device, const gchar * uuid, gint uuid_len,
                           GMainContext * context, gint * error )

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

if (ctx->rfcomm_dev) {
        if (ctx->use_ftp)
                ctx->obex = gw_obex_setup_dev(ctx->rfcomm_dev,
                        OBEX_FTP_UUID, OBEX_FTP_UUID_LEN,
                        NULL, &err);
        else
                ctx->obex = gw_obex_setup_dev(ctx->rfcomm_dev, NULL,
                        0, NULL, &err);
 
        if (ctx->obex == NULL)
                printf("OBEX setup failed: %s\n", response_to_string(err));
}

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.

[edit] Closing Connection

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

void gw_obex_close ( GwObex * ctx );

The following code demonstrates this usage.

if (ctx->obex) {
        gw_obex_close(ctx->obex);
        ctx->obex = NULL;
}

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

[edit] 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

gboolean gw_obex_read_dir (GwObex * ctx,
                           const gchar * dir,
                           gchar ** buf,
                           gint * buf_size,
                           gint * error );

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

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

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

gboolean gw_obex_chdir (GwObex * ctx, const gchar * dir, gint * error );

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

/* Ignore parent dir pointers */
if (g_str_equal(name, ".."))
        return TRUE;
 
if (!gw_obex_chdir(ctx->obex, name, err)) {
        printf("Could not chdir to %s\n", name);
        return FALSE;
}

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

gboolean gw_obex_get_file (GwObex * ctx,
                           const gchar * local,
                           const gchar * remote,
                           const gchar * type,
                           gint * error);

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

gboolean ret;
ret = gw_obex_get_file(ctx->obex, name, name, err);

Using the libwobex wrapper directly allows you to perform many more functions. For more information, see the API document.

[edit] 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; select the Developer->Specifications category. OBEX resembles the HTTP protocol, expect for a few differences:

  • Transports: While HTTP is normally layered above a TCP/IP connection, OBEX is usually transported over IrLAP/IrLMP/Tiny TP (on IrDA) or over Baseband/Link Manager/L2CAP/RFCOMM (on Bluetooth).
  • Binary transmissions: OBEX communicates using binary transmissions, as HTTP is transmitted in a human-readable XML-based format.
  • Session support: HTTP is stateless, while OBEX maintains the connection.

For more information on OBEX, see the summary available at the Wikipedia article on OBEX.

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

[edit] 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:

[edit] Connectivity UI

[edit] 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.

[edit] 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:

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

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

[edit] D-Bus methods

[edit] show_conn_dlg
Parameters
  1. boolean: When TRUE the dialog is requested because there were no saved connections (i.e. autoconnect 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.
[edit] 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.
[edit] 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.
[edit] 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
[edit] 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.
[edit] 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.
[edit] 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.
[edit] 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
[edit] 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.
[edit] 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
[edit] 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

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

#include <osso-ic-ui-dbus.h>
/* ... */
/* in our code somewhere, where we need the Connect Dialog*/
DBusMessage *uimsg;
/* construct the message for Connect Dialog request*/
uimsg =
  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 =
  dbus_connection_send_with_reply_and_block(connection,
                                    uimsg,
                                   reply_timeout,
                                   &error);
if (reply == NULL) {
    DLOG_ERR("Failed to show connect dialog: %s", uierror.message);
    dbus_error_free(&uierror);
}
dbus_message_unref(uimsg);
dbus_message_unref(reply);
/* ... */

[edit] D-Bus signals

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

[edit] disconnect
Parameters
  1. boolean TRUE if "disconnect" pressed, FALSE if "cancel"
Description
Signal emitted from UI when disconnect dialog has been closed.


[edit] 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.
[edit] 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.
[edit] 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


[edit] 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.
[edit] 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
[edit] 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
[edit] 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
[edit] 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
[edit] 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.

[edit] Bluetooth D-Bus UI dialogs

conbtdialogs-dbus.h

/** 
  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:
*/
 
#ifndef CONBTDIALOGS_DBUS_H
#define CONBTDIALOGS_DBUS_H
 
#ifdef __cplusplus
extern "C" {
#endif
 
/** Conbtdialogs service, resides in system dbus */
#define CONBTDIALOGS_DBUS_SERVICE                "com.nokia.bt_ui"
/** Conbtdialogs interface */
#define CONBTDIALOGS_DBUS_INTERFACE                "com.nokia.bt_ui"
/** Conbtdialogs path */
#define 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.
 */
#define 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.
 */
#define 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.
 */
#define 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.
 */
#define CONBTDIALOGS_SEARCH_SIG                 "search_result"
/**
  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
*/
 
#define DBUS_API_SUBJECT_TO_CHANGE
 
#include <glib.h>
#include <conbtdialogs-dbus.h>
#include <dbus/dbus.h>
#include <dbus/dbus-glib.h>
 
DBusGConnection *connection = NULL;
GMainLoop *mainloop = NULL;
 
static gboolean initialize(void)
{
    GError *error = NULL;
 
    g_type_init ();
 
    /* Create main loop */
    mainloop = g_main_loop_new(NULL, TRUE);
    if ( mainloop == NULL ) return FALSE;
 
    /* Create DBUS connection */
    connection = dbus_g_bus_get(DBUS_BUS_SYSTEM, &error);
 
    if (connection == NULL )
    {
        g_print ("Error: %s\n", error->message);
        g_clear_error (&error);
        return FALSE;
    }
 
    return TRUE;
}
 
static gboolean uninitialize(void)
{
    /* Quit main loop and unref it */
    if (mainloop != NULL)
    {
        g_main_loop_quit(mainloop);
        g_main_loop_unref(mainloop);
    }
 
    return TRUE;
}
 
static DBusHandlerResult file_sent_signal ( DBusConnection *connection,
                                            DBusMessage *message,
                                            void *data )
{
    gboolean success = FALSE;
 
    /* check signal */
    if (!dbus_message_is_signal(message,
                                CONBTDIALOGS_DBUS_INTERFACE,
                                CONBTDIALOGS_SEND_FILE_SIG))
        return DBUS_HANDLER_RESULT_NOT_YET_HANDLED;
 
    /* get args */
    if ( !dbus_message_get_args ( message, NULL,
                                  DBUS_TYPE_BOOLEAN, &success,
                                  DBUS_TYPE_INVALID ) )
      return DBUS_HANDLER_RESULT_NOT_YET_HANDLED;
 
    /* 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;
}
 
gint main(gint argc, gchar **argv)
{
    GError *error = NULL;
    gchar **files = NULL;
    gint idx = 0;
    DBusGProxy *proxy;
    DBusConnection *sys_conn;
    gchar *filter_string = NULL;
 
    if (argc < 2) return 1;
 
    if (initialize() == FALSE) {
        uninitialize();
        return 1;
    }
 
    /* Copy urls to GLib compatible char array */
    files = g_new0(gchar*, argc);
 
    for (idx = 1; idx < argc; idx++)
        files[idx-1] = g_strdup(argv[idx]);
 
    files[argc-1] = NULL;
 
    /* Open connection for btdialogs service */
    proxy = 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;
    }
    g_strfreev (files);
    files = NULL;
 
    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 = dbus_bus_get(DBUS_BUS_SYSTEM, NULL);
    g_assert(dbus_connection_add_filter(sys_conn,
                                        file_sent_signal,
                                        NULL,
                                        NULL ));
    filter_string =
       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;
}