[platform/upstream/connman.git] / doc / overview-api.txt

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 favorite selection.

        +---------------------------------------+
        | Ethernet with cable                   |  order=1 - favorite=yes
        +---------------------------------------+
        | Ethernet without cable                |  order=0 - favorite=no
        +---------------------------------------+
        | 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 unplug the Ethernet cable and
in this case the favorite setting will be removed and the service falls back
down in the list.

        +---------------------------------------+
        | My WiFi AP       (strength 80, rsn)   |  order=1 - connected=yes
        +---------------------------------------+
        | Ethernet                              |  order=0
        +---------------------------------------+
        | 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 favorite setting, but due to
the basic ordering of services it will be at the top of the services with an
order number of 0 (directly after all favorite services).

        +---------------------------------------+
        | My WiFi AP       (strength 80, rsn)   |  order=1 - connected=no
        +---------------------------------------+
        | Ethernet                              |  order=0 - 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.

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          |<-------------------------------+
                +---------------+                                |
                      |                                          |
                      |                      +-------------+     |
                      +----------------------| failure     |     |
                      | service.Connect()    +-------------+     |
                      V                           A              |
                +---------------+                 |              |
                | association   |-----------------+              |
                +---------------+      error      |              |
                      |                           |              |
                      | success                   |              |
                      V                           |              |
                +---------------+                 |              |
                | configuration |-----------------+              |
                +---------------+      error                     |
                      |                                          |
                      | success                                  |
                      V                                          |
                +---------------+                                |
                | ready         |                                |
                +---------------+                                |
                      |                                          |
                      | success                                  |
                      |                                          |
                      V                                          |
                +---------------+                                |
                | online        |<----------------+              |
                +---------------+                 |              |
                      |                           |              |
                      | service.Disconnect()      |              |
                      V                           |              |
                +---------------+                 |              |
                | disconnect    |-----------------+              |
                +---------------+      error                     |
                      |                                          |
                      +------------------------------------------+

The different states should no be used by the user interface to trigger
advanced actions. The state transitions are provided for the sole purpose
to give the user feedback on what is currently going on. Especially in
cases where networks are flaky or DHCP servers take a long time these
information are helpful for the user.

Some services might require special authentication procedure like a web
based confirmation. The LoginRequired property should be used to check
for this.


Application basics
==================

All applications should use D-Bus to communicate with Connection Manager. The
main entry point is the manager object. Currently the manager object is
located at "/", but this might change to allow full namespacing of the API
in the future. The manager interface is documented in manager-api.txt and
contains a set of global properties and methods.

A simple way to retrieve all global properties looks like this:

        bus = dbus.SystemBus()

        manager = dbus.Interface(bus.get_object("net.connman", "/"),
                                                "net.connman.Manager")

        properties = manager.GetProperties()

Changing a global property is also pretty simple. For example enabling the
so called offline mode (aka flight mode) it is enough to just set that
property:

        manager.SetProperty("OfflineMode", dbus.Boolean(1))

The manager object contains references to profiles, devices, services and
connections. All these references represent other interfaces that allow
detailed control of Connection Manager. The profiles and devices interfaces
are more for advanced features and most applications don't need them at all.

The services are represented as a list of object paths. Every of these object
paths contains a service interface. A service is a global collection for
Ethernet devices, WiFi networks, Bluetooth services etc. and all these
different types are treated equally.

Every local Ethernet card will show up as exactly one service. WiFi networks
will be grouped by SSID, mode and security setting. Bluetooth PAN and DUN
service will show up per remote device. This creates a simple list that can
be directly displayed to the users since these are the exact details users
should care about.

        properties = manager.GetProperties()

        for path in properties["Services"]:
                service = dbus.Interface(bus.get_object("net.connman", path),
                                                        "net.connman.Service")

                service_properties = service.GetProperties()

The service interface is documented in service-api.txt and contains common
properties valid for all services. It also contains method to connect or
disconnect a specific service. This allows users to select a specific service.
Connection Manager can also auto-connect services based on his policies or
via external events (like plugging in an Ethernet cable).

Connecting (or disconnecting) a specific service manually is as simple as
just telling it to actually connect:

        service.Connect()  or  service.Disconnect()

It is possible to connect multiple services if the underlying technology
allows it. For example it would be possible to connect to a WiFi network
and a Bluetooth service at the same time. Trying to connect to a second WiFi
network with the same WiFi hardware would result in an automatic disconnect
of the currently connected network. Connection Manager handles all of this
for the applications in the background. Trying to connect an Ethernet service
will result in an error if no cable is plugged in. All connection attempts
can fail for one reason or another. Application should be able to handle
such errors and will also be notified of changes via signals.

Connection Manager will interact with an agent via the Agent API to confirm
certain transactions with the user. If Connection Manager needs extra
information, it will ask the user for exactly the information it requires,
i.e. passphrase, network's name (for hidden WiFi networks) and more depending
on the use case (e.g. WPS, EAP). Therefore an application environment using
Connection Manager should implement one dedicated Connection Manager agent
according to the Agent API in order to interact with the user. Please see
agent-api.txt for implementation details.

To monitor the current status of a service the state property can be used. It
gives detailed information about the current progress.

        properties = service.GetProperties()

        print properties["State"]

All state changes are also sent via the PropertyChanged signal on the
service interface. This allows asynchronous monitoring without having to poll
Connection Manager for changes.