Maemo Connectivity Architecture

Connectivity Subsystem

This section describes the system decomposition of the Connectivity subsystem. The diagram below shows the logical entities of the subsystem, dependencies between them, provided interfaces and required external interfaces. External dependencies are shown with dotted arrows.

The Phone Access subsystem is responsible for the local connections to the phone. The Internet Access subsystem manages the remote connections using the IP protocol. The Connection Manager has the user interface for monitoring the connections and shutting them down. Internet Access contains the user interface for configuring the settings for Internet Access Points.

Maemo applications can open Internet connections by using the IC API or its socket counterpart IC socket. The Internet Access subsystem will take care of the connection to the phone, if it is necessary, by using the services of the Phone Access subsystem. If an application needs to gain access to the phone's files, then the File selector will consult the Phone Access subsystem.

During the flight mode the WLAN and Bluetooth radios (at least the latter) must not be active. The Device System Management Entity (DSME) of maemo provides information about the transitions to and from the flight mode.

Figure 1. Decomposition of maemo connectivity subsystem

Phone and Internet connections are quite different from their nature and behavior. The next chapters will introduce these some more.

Phone access

Phone Access is the subsystem that handles connections to a mobile phone. It has a search utility for finding potential phones and inquiring the services they can offer. This is based on standard Bluetooth service discovery mechanism. Phone Access also keeps a record of phones having been 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 mobile phone supporting Bluetooth Service Discovery Protocol (SDP), Dial-up Networking profile (DUN) and File Transfer Profile (FTP) can be connected to maemo. However, there is variation especially in the level of file transfer services and OBEX in different mobile phones. Some products limit the 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, which can be used to get more specific information about the file system on the phone.

Maemo connects to a phone on-damand basis, that is, when an application requires a connection. As an example, when the Internet browser is about to open a URL, it will request the Phone Access to establish a connection to the phone. This makes Phone Access to bind an RFCOMM device to the requested service (in this case DUN) 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 done with GnomeVFS layer to get transparent access to phone 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 will ask the BT sap component to get session keys from a GSM/UMTS phone.

Figure 2. Decomposition of maemo phone access

Name	Phone selection UI
Purpose	User interface for managing phone operations. Supports Connection Manager.
Responsibilities and additional requirements	Keeps a list of phones Stores the Bluetooth device addresses of phones to GConf Invokes device search and capability query.
Concurrent usage	N/A
Name	BT search
Purpose	Searches for available Bluetooth devices.
Responsibilities and additional requirements	Bluetooth inquiry Checks on flight 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	BT connection daemon
Purpose	Manages the phone connections.
Responsibilities and additional requirements	Binds the device to the selected phone with the selected Bluetooth profile Keeps book about the existing connections between applications and the phone, which is based on the events received from the Bluetooth HCI Knows if the phone is reachable Checks on flight mode state.
Concurrent usage	Not limited.
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	Handles OBEX requests.
Concurrent usage	Not limited
Name	BT SAP
Purpose	Obtains session keys for EAP-SIM authentication from the phone.
Responsibilities and additional requirements	SIM/PIN entry Connects to the phone with SIM Access Profile Delivers the session keys to EAP.
Concurrent usage	N/A

Internet access

The Internet Access subsystem manages connections to the Internet over both WLAN and cellular dial-up. It is also responsible for the configuration and management of Internet Access Points. The Internet Access provides applications with TCP/IP connections. They can be established with:

• WLAN connection to some wireless access point.
• Bluetooth connection through phone using Point-to-Point Protocol (PPP) and a cellular modem (in the phone).

In the latter case AT commands are applied to establish a PPP link to the cellular modem and the connection to the Internet.

Figure 3. Decomposition of maemo Internet Access

Name	IC daemon
Purpose	IC daemon establishes Internet connections over WLAN and Bluetooth DUN on the request of IC library.
Responsibilities and additional requirements	Provides the IC library with means to activate/deactivates IAPs. Controls that only one Internet connection (one active IAP) can exist at a time Uses Phone Access for getting a character device for a dial-up connection and WLAN connection daemon for getting a network device and getting the connection authenticated. Starts IP level services like PPP and DHCP Provides statistics about the usage of IAPs to any application.
Concurrent usage	Has only one client and limits the connections to one at a time.
Name	IC library
Purpose	IC library is a shared library that handles requests about activating and deactivating IAPs and provides statistical information about them.
Responsibilities and additional requirements	Provides the IC API for requesting activation and deactivation of Internet connections, getting statistical information of them and a list of available IAPs. An application shall obtain an IAP before opening sockets for a network connection. Provides counterparts of BSD socket functions for applications that do not know (have not been modified to use) the IC API. This is implemented as a preloaded library. The library first activates an IAP and then opens a socket. Disconnects an IAP once the last socket associated to it has been closed.
Concurrent usage	Not limited.
Name	Internet Connectivity GUI
Purpose	This package has the GUI applications for configuring Internet Access Points and WLAN settings. Note that the Connection Manager is a separate application.
Responsibilities and additional requirements	Provides the UI for configuring an IAP Provides the UI for WLAN settings Scans for available WLAN networks (on request) Saves IAP and WLAN settings (excluding EAP settings) to GConf Opens up dialogs and displays notifications
Concurrent usage	N/A
Name	WLAN connection daemon
Purpose	Manages WLAN network connections.
Responsibilities and additional requirements	Starts WLAN driver with the settings provided; stops WLAN Requests authentication when necessary Relays WLAN IAP settings from IC daemon to WLAN drivers and authentication requests to EAP Relays WLAN events from WLAN drivers Provides WLAN status information
Concurrent usage	Not limited.
Name	EAP UI
Purpose	User interface for EAP authentication
Responsibilities and additional requirements	Invokes a dialog for an authentication password Shows 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	Takes care of the authentication process for the active IAP Delivers progress events to IC daemon As a special case, controls the EAP-SIM authentication using the SIM Access Profile Provides authentication status
Concurrent usage	N/A

Interfaces

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

Method:            connect
Parameters:        1. string - Name of the IAP
                   2. uint32 - Whether this is a timed event (e.g. automatic
                               fetching of emails) or a user requested event
                               (all others).
                   3. uint32 (optional) - Process ID of the application,
                               supplied only by the preloaded library
Return Parameters: nothing
Errors:            com.nokia.icq.error.invalid_iap:
                   The specific IAP does not exist
                   com.nokia.icd.error.unable_to_activate_iap:
                   Activation of the specific IAP failed

Description:       Activates or changes the active IAP and records the D-BUS
                   base service name of the caller. If requested IAP is
                   different from currently active IAP then the current IAP
                   will be first deactivated.
				

Method:            disconnect
Parameters:        string - Name of the IAP
Return Parameters: none
Errors:            com.nokia.icd.error.iap_in_use:
                   The IAP was not disconnected since other applications are
                   still using it.

Description:       Removes the D-BUS base service name of the caller from list
                   of applications using the IAP. Deactivates the IAP if the
                   disconnecting application is the last one using the IAP.
				

Method:            get_statistics
Parameters:        none
Return Parameters: 1. string - Name of the current IAP
                   2. uint32 - Active time of IAP
                   3. uint32 - Signal strength of the wireless medium.
                   4. uint32 - Number of packets received
                   5. uint32 - Number of packets sent
                   6. uint32 - Number of bytes reveiced
                   7. uint32 - Number of bytes sent.
Errors:            none

Description:       Gets the statistics of currently active IAP.
				

Method:            get_ipinfo
Parameters:        none
Return Parameters: 1. string - Name of the current IAP
                   2. string - IP address of the interface
                   3. string - Netmask
                   4. stinrg - IP address of the default gateway
Errors:            none

Description:       Gets the IP address of the currently active IAP.
				

Signal:            status_changed
Parameters:        1. string - Name of the current active IAP or empty
                   2. string - Type of IAP, same as in GConf or empty
                   3. string - Status of the IAP connection:
                               IDLE, CONNECTING, CONNECTED,
                               DISCONNECTING, SWITCHING.

Description:       Status of the currently active IAP.
				

#include 
#include 
...
/* Callback for the internet connection 'status_changed' signal sent by icd */
static DBusHandlerResult
get_connection_status_signal_cb ( DBusConnection *connection,
                                  DBusMessage *message,
                                  void *user_data )
{
  ...
  /* check signal */
  if (!dbus_message_is_signal ( message,
                                ICD_DBUS_INTERFACE,
                                ICD_STATUS_CHANGED_SIG ))
    return DBUS_HANDLER_RESULT_NOT_YET_HANDLED;

  /*
   * get args:
   *   iap_name:    name of the current active IAP or empty
   *   iap_nw_type: type of IAP
   *   iap_state:   status of the IAP connection
   */
  dbus_error_init (&dbus_error);
  if ( !dbus_message_get_args ( message, &dbus_error,
                                DBUS_TYPE_STRING, &iap_name,
                                DBUS_TYPE_STRING, &iap_nw_type,
                                DBUS_TYPE_STRING, &iap_state,
                                DBUS_TYPE_INVALID ) )
    {
      return DBUS_HANDLER_RESULT_NOT_YET_HANDLED;
    }

  switch ( new_state )
    {
    case INET_IDLE:
      ...
      break;
    case INET_CONNECTED:
      ...
      break;
    case INET_CONNECTING:
      ...
      break;
    case INET_SWITCHING:
      ...
      break;
    case INET_DISCONNECTING:
      ...
      break;
    default:
      ...
    }
  return DBUS_HANDLER_RESULT_HANDLED;
}
...
/* add D-BUS signal handler for 'status_changed' */
filter_string = g_strdup_printf ("interface=%s", ICD_DBUS_INTERFACE,);

/* add match */
dbus_error_init (&error);
dbus_bus_add_match(dbus_connection, filter_string, &error);

g_free (filter_string);
if (dbus_error_is_set(&error))
{
  /* handle the error */
}
dbus_error_free(&error);

/* add the callback */
if (dbus_connection_add_filter( dbus_connection,
                                get_connection_status_signal_cb,
                                user_data,
                                NULL ) == FALSE)
{
  /* handle the error */
}
...
				

Service            com.nokia.icd.autoconf
Interfaces         com.nokia.icd.autoconf
Object paths       /com/nokia/icd/autoconf

Signal:            autoconf_changed
Parameters:        1. string - Name of the interface used
                   2. string - Name of the autoconfiguration program i.e. ppp
                               or udhcpd.

Description:       Report from the autoconfiguration program on the status of
                   the IAP.
				

Connectivity daemon Settings

Each IAPs' connection configuration (connection type, authentication information, etc.) are stored in GConf under the path /system/osso/connectivity/IAP/<name of IAP>. These configuration variables are set and mostly used by ICd, so we can easily reconnect to an already configured IAP any other time. Although by default all configuration variables are readable and writable by all applications unless otherwise stated, if an application needs information about the currently connected IAP, first it should try to get it through D-BUS method call to the ICd and if it's not available there it shall read them out from the GConf.

Changing the values of the these variables by any other application is not recommended, since it will most probably lead to inconsistent states.

The full list of connectivity GConf settings can be found from Appendix 1, separated to subsections based on their usage. Below is an example of how to use GConf to read these settings, it shows how to get the proxy settings for our application:

#include 
...
/*
The gconf keys set by icd are:
  /system/proxy/mode: (string) values are none, manual or auto
  /system/proxy/ftp_host: (string)
  /system/proxy/ftp_port: (int)
  /system/proxy/secure_host: (string)
  /system/proxy/secure_port: (int)
  /system/proxy/socks_host: (string)
  /system/proxy/socks_port: (int)
  /system/proxy/autoconfig_url: (string)
  /system/http_proxy/use_http_proxy: (bool)
  /system/http_proxy/host: (string)
  /system/http_proxy/port: (int)
  /system/http_proxy/ignore_hosts: (list of strings)
*/

static void get_proxy_settings(GConfClient *gc_client, ProxySettings *pset) {
	gchar *p_str;

	/* should we use proxy at all? */
 	p_str = gconf_client_get_string(gc_client,
				/system/proxy/mode, NULL);

	if (strcmp(p_str, none) == 0)
		/* there's no proxy settings */
	else if (strcmp(p_str, auto) == 0) {
		/* get autoconfiguration url */
		pset->auto_url =
		  gconf_client_get_string(gc_client,
				     /system/proxy/autoconfig_url, 				     NULL);
	} else {
		/* manual */
		pset->ftp_host =
		   gconf_client_get_string(gc_client,
				     /system/proxy/ftp_host, 				     	     NULL);
		pset->port =
		    gconf_client_get_int(gc_client,
				    /system/proxy/ftp_port, 				     	    NULL);
		.../* get the rest */ ...
	}

	g_free(p_str);

	/* we can get the same way the http_proxy settings from GConf*/
}
...
/* Get the proxy settings to ProxySettings struct */
get_proxy_settings (gc_client, &pset);
...
			    

Connectivity API functionality

Creating the connection

For requesting an Internet connection in our application we shall use the osso_iap_connect function provided by IC API. This will forward our request by sending the connect D-BUS method call to ICd. The detailed IAP activation sequence is shown in Figure 5.

Figure 5. IAP activation using IC API

The function itself:

gint osso_iap_connect (const char *iap, dbus_uint32_t  flags, void *arg);
				    

const char *iap

The name of the IAP. Also OSSO_IAP_ANY (for using any kind of already available connection) and OSSO_IAP_ASK (asking the user to choose an IAP from a list [see]) IAP meta names can be used.

dbus_uint32_t flags

Flags used with the connection, it is either OSSO_IAP_REQUESTED_CONNECT or OSSO_IAP_TIMED_CONNECT.

void *arg

The Parameter passed for callback function (user_data)

The function returns OSSO_OK for success or OSSO_ERROR for an error. Successful invocation of this function will always generate an event. It can be either OSSO_IAP_CONNECTED or OSSO_IAP_ERROR.

Before invoking connection we shall register a

typedef void (*osso_iap_cb_t)(struct iap_event_t *event, void *arg);
				    

callback function for handling IAP events like OSSO_IAP_CONNECTED, which indicates that the connection established successfully or OSSO_IAP_DISCONNECTED, which shows that the IAP connection has been torn down for some reason.

An example of requesting for Internet connection in an application:

#include 
...
static void iap_callback(struct iap_event_t *event, void *arg)
{
/* event handler for OSSO_IAP_CONNECTED and OSSO_IAP_DISCONNECTED  */
}
...
/* Register a callback function for IAP related events. */
if (osso_iap_cb(iap_callback) != OSSO_OK) {
      printf("osso_iap_cb failed");
      exit(1);
}
/* establish Internet connection. */
if (osso_iap_connect(OSSO_IAP_ANY, OSSO_IAP_REQUESTED_CONNECT, &user_data)
            != OSSO_OK) {
                printf("osso_iap_connect failed");
                exit(1);
}
...
				    

...
struct addrinfo *addrinfo;

fd = socket(addrinfo->ai_family, addrinfo->ai_socktype,
            addrinfo->ai_protocol);
if (fd == -1) {
   perror("socket error");
   exit(1);
}

if (connect(fd, addrinfo->ai_addr, addrinfo->ai_addrlen) == -1) {
   close(fd);
   freeaddrinfo(addrinfo);
   perror("could not connect");
}

freeaddrinfo(addrinfo);
...
				    

gint osso_iap_get_statistics (const char *iap, void *arg)
				    

/**
 * Callback for IC API events.
 * @param ev Event data.
 * @param arg Data to associate events for specific requests.
 */
static void iap_callback(struct iap_event_t *ev, void *arg)
{
	if( (long) arg == 0xF00BA4)
	     printf("Callback for our statistics request: ");

	/* check for the event type and print out the statistics */
	if( ev->type == OSSO_IAP_STATISTICS)
                printf(", time_active=%d, signal_strength=%d"
                       ", rx_packets=%d, tx_packets=%d"
                       ", rx_bytes=%d, tx_bytes=%d",
                       ev->u.statistics.time_active,
                       ev->u.statistics.signal_strength,
                       ev->u.statistics.rx_packets,
                       ev->u.statistics.tx_packets,
                       ev->u.statistics.rx_bytes,
                       ev->u.statistics.tx_bytes);
}

...
    /* after making the connection successfully
       we call this function in our code somewhere for basic statistics.
       0xF00BA4 is an example parameter pointer which in real case would be
       something more sensible.
     */
    osso_iap_get_statistics(iap_name, (void*) 0xF00BA4);
...
				    

Closing the connection

When an application using the IC library API stops using the network it calls osso_iap_disconnect() to inform the IC subsystem that the network can be disconnected. The preloaded library providing socket functions used by unmodified applications will track active sockets, and when the last socket is closed the IAP will be disconnected. Closing the network connection is described in Figure 6 and Figure 7.

If the IAP is disconnected forcefully from the Connection Manager, the device moves outside the network range, or an idle timeout has been reached, sockets associated with the disconnected IAP need to be closed as well. Applications using the IC library API will be notified of the IAP disconnection via their registered callback functions. Sockets of unmodified applications that activated the IAP network connection via the preloaded functions of the IC library will be forcefully shut down by the IC library when the library receives D-BUS messages indicating IAP disconnection. If the unmodified application at any later time tries to read or write data from or to the socket, it will receive a socket error from the C library. It is then up to the logic of the unmodified application to decide on how to proceed with a disconnected network socket. This action sequence is illustrated in Figure 6.

Figure 6. IAP disconnection activated by the IC preloaded library

Figure 7. IAP deactivation initiated by Connection Manager, network error/loss or idle timeout

Libopenobex

LibOpenOBEX library implements a generic OBEX Session Protocol. It does not implement the OBEX Application Framework. OBEX is a protocol designed to allow interchanging of data between different kinds of connections (for example Bluetooth, IrDA). Specific information about the OBEX protocol can be found at http://www.irda.org, by selecting the Developer->Specifications category. OBEX is similar to 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.

A pretty good overlook of OBEX can be found at http://en.wikipedia.org/wiki/OBEX.

Code examples for libopenobex can be obtained from http://openobex.triq.net/downloads from the example apps package.

Osso-gwconnect

Osso-gwconnect provides a D-BUS interface to different parts of Bluetooth functionality:

• Bluetooth Connection Daemon (btcond)
• Bluetooth SDP (btsdp)
• Bluetooth Search (btsearch)

The interface is a well defined D-BUS message API. Details on the provided interface can be found from osso-gwconnect howto: http://maemo.org/platform/docs/osso-gwconnect.html.

Service:
com.nokia.btcond

Interfaces:
com.nokia.btcond.request
com.nokia.btcond.signal

Object paths:
/com/nokia/btcond/request
/com/nokia/btcond/signal
				    

gboolean ret;
DBusConnection *c;

c = dbus_bus_get(DBUS_BUS_SYSTEM, NULL);
if (c == NULL) {
	fprintf(stderr, "Unable to connect to the system D-BUS\n");
	return FALSE;
}

ret = dbus_bus_service_exists(c, BTCOND_SERVICE, NULL);
if (!ret)
	printf("btcond is not connected to the system D-BUS\n");

return ret;
				    

Service:
        com.nokia.btsdp

Interfaces:
        com.nokia.btsdp.request

Object paths:
        /com/nokia/btsdp/request
				    

"DUN"  (Dialup Networking Profile)
"FTP"  (OBEX File Transfer Profile)
"NFTP" (Nokia OBEX Filetransfer Profile)
"OPP"  (OBEX Object Push Profile)
"SAP"  (SIM Access Profile)
"SPP"  (Serial Port Profile)
				    

D-BUS Connectivity UI interface

If we need some information from the user about the IAP we are about to connect we can use the below mentioned ones for this purpose.

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

The Internet Connectivity UIs implements the following D-BUS API used by ICd and EAP.

Method:            show_conn_dlg
Parameters:        none
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.
			    

Method:            show_disconnect_dlg
Parameters:        none

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

Description:       Show the disconnect dialog.
			    

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.
			    

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
			    

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.
			    

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:       Show EAP GTC challenge dialog.
			    

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:       Show EAP MSCHAPv2 change password dialog.
			    

Method:            show_private_key_passwd_dlg
Parameters:        1. uint32  The private key ID

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

Description:       Show EAP private key password dialog
			    

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

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:       Request strong (16 digit) BT PIN dialog for a BT device
                            

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:       Show SIM PIN dialog
                            

Example code for our application to show the connect dialog using show_conn_dlg is following. Please note the usage of macro for doing this.

#include 
...
/* 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);
...
                            

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

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

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

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

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

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

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

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

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

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

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

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

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

Signal:        private_key_passwd
Parameters:    1. uint32  The id of the private key
               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
                            

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

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

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

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

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.
                            

Bluetooth settings

The following table lists the Bluetooth DUN settings for each IAP listed under the GConf path /system/osso/connectivity/IAP/<name of IAP>:

Note that settings prefixed with dun_ps_ and dun_cs_ are only applicable to that specific connection type, other settings are shared by all dial-up connection types. Currently no specific settings exist for CDMA connection types.

In addition the following items are added to /system/bluetooth/<BT address>:

WLAN settings

The following table lists the WLAN settings for each IAP listed under the GConf path /system/osso/connectivity/IAP/<name of IAP>:

Additional configuration entries for EAP authentication software. Note that the TLS and PEAP settings are named the same way. The selected EAP type chooses whether the settings are TLS or PEAP settings.

Proxy settings

The following table lists the proxy settings for each IAP listed under the GConf path /system/osso/connectivity/IAP/<name of IAP>:

The application should not read directly the proxy settings from here, the ICd will set them automatically in /system/http_proxy and /system/proxy after establishing the connection with the selected IAP.