Application programming interface
*********************************
Service basics
==============
Inside Connection Manager there exists one advanced interface to allow the
user interface an easy access to networking details and user chosen
preferences. This is the service list and interface.
The basic idea is that Connection Manager maintains a single flat and sorted
list of all available, preferred or previously used services. A service here
can be either a Ethernet device, a WiFi network or a remote Bluetooth device
(for example a mobile phone).
This list of service is sorted by Connection Manager and there is no need
for the user interface to implement its own sorting. User decisions will
need to be done via Connection Manager and it is then responsible to update
the order of services in this list.
+---------------------------------------+
| Ethernet |
+---------------------------------------+
| Bluetooth phone |
+---------------------------------------+
| Guest (strength 90, none) |
+---------------------------------------+
| My WiFi AP (strength 80, rsn) |
+---------------------------------------+
| Other AP (strength 70, rsn) |
+---------------------------------------+
| Friends AP (strength 70, wep) |
+---------------------------------------+
If none of the services has been used before the sorting order will be done
with these priorities:
1. Ethernet (lower index numbers first)
2. Bluetooth (last used devices first)
3. GSM/UTMS/3G (if SIM card is present, activated and not roaming)
3. WiFi (signal strength first, then more secure network
first)
The Ethernet devices are always sorted first since they are physically built
into the system and will be always present. In cases they are switched off
manually they will not be showing in this list.
Since every Bluetooth device has to be configured/paired first, the user
already made a choice here that these are important. Connection Manager will
only show devices with PAN or DUN profile support. While Bluetooth devices
do have a signal strength, it is mostly unknown since background scanning
in Bluetooth is too expensive. The choice here is to sort the last used
Bluetooth device before the others.
WiFi networks closer in the proximity should be shown first since it is more
likely they are selected. The signal strength value is normalized to 0-100
(effectively a percentage) and allows an easy sorting.
WiFi networks with the same signal strength are then sorted by their security
setting. WPA2 encrypted networks should be preferred over WPA/WEP and also
unencrypted ones. After that they will be sorted by the SSID in alphabetical
order.
In the case the WiFi network uses WPS for setup and it is clearly detectable
that a network waits for Connection Manager to connect to it (for example via
a push-to-connect button press on the AP), then this network should be shown
first before any other WiFi networks. The reason here is that the user already
made a choice via the access point. However this depends on technical details
if it is possible to detect these situations.
Service order
=============
All unused services will have the internal order number of 0 and then will
be sorted according to the rules above. For Bluetooth the user already made
the decision to setup their device and by that means select it. However
until the first connection attempt it might have been setup for total
different reason (like audio usage) and thus it still counts as unused from
a networking point of view.
Selecting the "My WiFi AP" and successfully connecting to it makes it a
favorite device and it will become an order number bigger than 0. All
order numbers are internally. They are given only to service that are marked
as favorite. For WiFi and Bluetooth a successful connection attempt makes
these services automatically a favorite. For Ethernet the plugging of a cable
makes it a favorite. Disconnecting from a network doesn't remove the favorite
setting. It is a manual operation and is equal to users pressing
delete/remove button.
+---------------------------------------+
| My WiFi AP (strength 80, rsn) | order=1 - favorite=yes
+---------------------------------------+
| Ethernet | order=0
+---------------------------------------+
| Guest (strength 90, none) | order=0
+---------------------------------------+
| |
Ethernet is special here since the unplugging of the network cable will
remove the service from the list
+---------------------------------------+
| Ethernet with cable | order=1 - favorite=yes
+---------------------------------------+
| Guest (strength 90, none) | order=0
+---------------------------------------+
| |
This means that all services with an order > 0 have favorite=yes and all
others have favorite=no setting. The favorite setting is exposed via a
property over the service interface. As mentioned above, the order number
is only used internally.
Within Connection Manager many services can be connected at the same time and
also have an IP assignment. However only one can have the default route. The
service with the default route will always be sorted at the top of the
list.
+---------------------------------------+
| Ethernet | order=2 - connected=yes
+---------------------------------------+
| My WiFi AP (strength 80, rsn) | order=1 - connected=yes
+---------------------------------------+
| Guest (strength 90, none) | order=0
+---------------------------------------+
| |
To change the default connection to your access point, the user needs to
manually drag the access point service to the top of the list. Connection
Manager will not take down default routes if there is no reason to do so.
A working connection is considered top priority.
+---------------------------------------+
| My WiFi AP (strength 80, rsn) | order=2 - connected=yes
+---------------------------------------+
| Ethernet | order=1 - connected=yes
+---------------------------------------+
| Guest (strength 90, none) | order=0
+---------------------------------------+
| |
Another possible user interaction would be to disconnect the Ethernet service
and in this case the service falls back down in the list.
+---------------------------------------+
| My WiFi AP (strength 80, rsn) | order=1 - connected=yes
+---------------------------------------+
| Ethernet | order=1 - connected=no
+---------------------------------------+
| Guest (strength 90, none) | order=0
+---------------------------------------+
| |
If the service on the top of the list changes the default route will be
automatically adjusted as needed. The user can trigger this by disconnecting
from a network, if the network becomes unavailable (out of range) or if the
cable gets unplugged.
As described above, the pure case of disconnecting from a network will not
remove the favorite setting. So previously selected networks are still present
and are sorted above all others.
+---------------------------------------+
| Ethernet | order=2 - connected=yes
+---------------------------------------+
| My WiFi AP (strength 80, rsn) | order=1 - connected=no
+---------------------------------------+
| Guest (strength 90, none) | order=0
+---------------------------------------+
| |
Unplugging the Ethernet cable will remove the Ethernet service.
+---------------------------------------+
| My WiFi AP (strength 80, rsn) | order=1 - connected=no
+---------------------------------------+
| Guest (strength 90, none) | order=0
+---------------------------------------+
| |
Service tweaks
==============
The interfaces of Connection Manager will always export all services that are
currently known. The Ethernet devices with no cable plugged are actually not
included in this list. They will only show up once a carrier is detected.
The service interface is not meant for basic device configuration task. So
switching a device on and off (via RFKILL for example) should be done via
the technology interface. See "Technology interfaces" chapter in this document.
Due to limited screen size of small devices and the big amount of WiFi
access points that are deployed right now it might be sensible to not show
certain WiFi networks in the user interface.
The choice to hide a WiFi network from the user interface should be purely
done by the signal strength. The optimal cut-off value here still has to be
determined, but in the end that is a user interface policy.
Service naming
==============
Every service will have a name property that allows the user interface to
display them directly. All names will be already converted into UTF-8. It
derives from the netork details.
In case of WiFi this will be the SSID value. The SSID is a binary array and
will be converted into printable form. Unprintable characters are replaced
with spaces.
In addition to WiFi naming, WiFi networks are subject to a grouping policy
performed around SSID and security type. This means that one service will be
seen for N WiFi networks providing the same SSID and the same security metod.
For instance, if 5 APs are servicing an SSID called "TEST" with WPA2
authentication and 3 APs are servicing the same SSID with open authentication
method, the user will see only two services listed with the name "TEST"
differentiated by their security type, which are "psk" and "none". Such
policy is also applied to hidden networks, where hidden services will have an
empty name and will be differentiated by the security type. The user has then
to select the one with the right security and the Agent API will request any
required information such as the SSID for the network (See "Application
basics" below).
For Bluetooth the device alias is used. The alias is different since it
can be overwritten by the user via the Bluetooth service. The identification
is still done based on its address, but the display name might change. In
most cases the alias is equal to the Bluetooth remote friendly name.
For Ethernet device no name will be provided. The type property will indicate
that this service is Ethernet and then it is up to the user interface to
provide a proper localized name for it.
Service states
==============
Every service can have multiple states that indicate what is currently
going on with it. The choice to have multiple states instead of a simple
connected yes/no value comes from the fact that it is important to let the
user interface name if a service is in process of connecting/disconnecting.
The basic state of every service is "idle". This means that this service
is not in use at all at the moment. It also is not attempting to connect
or do anything else.
The "association" state indicates that this service tries to establish a
low-level connection to the network. For example associating/connecting
with a WiFi access point.
With the "configuration" state the service indicates that it is trying
to retrieve/configure IP settings.
The "ready" state signals a successful connected device. This doesn't mean
it has the default route, but basic IP operations will succeed.
With the "disconnect" state a service indicates that it is going to terminate
the current connection and will return to the "idle" state.
In addition a "failure" state indicates a wrong behavior. It is similar to
the "idle" state since the service is not connected.
+---------------+
| idle |
