doc/overview-api.txt

   1 Application programming interface
   2 *********************************
   3
   4
   5 Service basics
   6 ==============
   7
   8 Inside Connection Manager there exists one advanced interface to allow the
   9 user interface an easy access to networking details and user chosen
  10 preferences. This is the service list and interface.
  11
  12 The basic idea is that Connection Manager maintains a single flat and sorted
  13 list of all available, preferred or previously used services. A service here
  14 can be either a Ethernet device, a WiFi network or a remote Bluetooth device
  15 (for example a mobile phone).
  16
  17 This list of service is sorted by Connection Manager and there is no need
  18 for the user interface to implement its own sorting. User decisions will
  19 need to be done via Connection Manager and it is then responsible to update
  20 the order of services in this list.
  21
  22         +---------------------------------------+
  23         | Ethernet                              |
  24         +---------------------------------------+
  25         | Bluetooth phone                       |
  26         +---------------------------------------+
  27         | Guest            (strength 90, none)  |
  28         +---------------------------------------+
  29         | My WiFi AP       (strength 80, rsn)   |
  30         +---------------------------------------+
  31         | Other AP         (strength 70, rsn)   |
  32         +---------------------------------------+
  33         | Friends AP       (strength 70, wep)   |
  34         +---------------------------------------+
  35
  36 If none of the services has been used before the sorting order will be done
  37 with these priorities:
  38
  39         1. Ethernet     (lower index numbers first)
  40         2. Bluetooth    (last used devices first)
  41         3. GSM/UTMS/3G  (if SIM card is present, activated and not roaming)
  42         3. WiFi         (signal strength first, then more secure network
  43                         first)
  44
  45 The Ethernet devices are always sorted first since they are physically built
  46 into the system and will be always present. In cases they are switched off
  47 manually they will not be showing in this list.
  48
  49 Since every Bluetooth device has to be configured/paired first, the user
  50 already made a choice here that these are important. Connection Manager will
  51 only show devices with PAN or DUN profile support. While Bluetooth devices
  52 do have a signal strength, it is mostly unknown since background scanning
  53 in Bluetooth is too expensive. The choice here is to sort the last used
  54 Bluetooth device before the others.
  55
  56 WiFi networks closer in the proximity should be shown first since it is more
  57 likely they are selected. The signal strength value is normalized to 0-100
  58 (effectively a percentage) and allows an easy sorting.
  59
  60 WiFi networks with the same signal strength are then sorted by their security
  61 setting. WPA2 encrypted networks should be preferred over WPA/WEP and also
  62 unencrypted ones. After that they will be sorted by the SSID in alphabetical
  63 order.
  64
  65 In the case the WiFi network uses WPS for setup and it is clearly detectable
  66 that a network waits for Connection Manager to connect to it (for example via
  67 a push-to-connect button press on the AP), then this network should be shown
  68 first before any other WiFi networks. The reason here is that the user already
  69 made a choice via the access point. However this depends on technical details
  70 if it is possible to detect these situations.
  71
  72
  73 Service order
  74 =============
  75
  76 All unused services will have the internal order number of 0 and then will
  77 be sorted according to the rules above. For Bluetooth the user already made
  78 the decision to setup their device and by that means select it. However
  79 until the first connection attempt it might have been setup for total
  80 different reason (like audio usage) and thus it still counts as unused from
  81 a networking point of view.
  82
  83 Selecting the "My WiFi AP" and successfully connecting to it makes it a
  84 favorite device and it will become an order number bigger than 0. All
  85 order numbers are internally. They are given only to service that are marked
  86 as favorite. For WiFi and Bluetooth a successful connection attempt makes
  87 these services automatically a favorite. For Ethernet the plugging of a cable
  88 makes it a favorite. Disconnecting from a network doesn't remove the favorite
  89 setting. It is a manual operation and is equal to users pressing
  90 delete/remove button.
  91
  92         +---------------------------------------+
  93         | My WiFi AP       (strength 80, rsn)   |  order=1 - favorite=yes
  94         +---------------------------------------+
  95         | Ethernet                              |  order=0
  96         +---------------------------------------+
  97         | Guest            (strength 90, none)  |  order=0
  98         +---------------------------------------+
  99         |                                       |
 100
 101 Ethernet is special here since the unplugging of the network cable will
 102 remove the favorite selection.
 103
 104         +---------------------------------------+
 105         | Ethernet with cable                   |  order=1 - favorite=yes
 106         +---------------------------------------+
 107         | Ethernet without cable                |  order=0 - favorite=no
 108         +---------------------------------------+
 109         | Guest            (strength 90, none)  |  order=0
 110         +---------------------------------------+
 111         |                                       |
 112
 113 This means that all services with an order > 0 have favorite=yes and all
 114 others have favorite=no setting. The favorite setting is exposed via a
 115 property over the service interface. As mentioned above, the order number
 116 is only used internally.
 117
 118 Within Connection Manager many services can be connected at the same time and
 119 also have an IP assignment. However only one can have the default route. The
 120 service with the default route will always be sorted at the top of the
 121 list.
 122
 123         +---------------------------------------+
 124         | Ethernet                              |  order=2 - connected=yes
 125         +---------------------------------------+
 126         | My WiFi AP       (strength 80, rsn)   |  order=1 - connected=yes
 127         +---------------------------------------+
 128         | Guest            (strength 90, none)  |  order=0
 129         +---------------------------------------+
 130         |                                       |
 131
 132 To change the default connection to your access point, the user needs to
 133 manually drag the access point service to the top of the list. Connection
 134 Manager will not take down default routes if there is no reason to do so.
 135 A working connection is considered top priority.
 136
 137         +---------------------------------------+
 138         | My WiFi AP       (strength 80, rsn)   |  order=2 - connected=yes
 139         +---------------------------------------+
 140         | Ethernet                              |  order=1 - connected=yes
 141         +---------------------------------------+
 142         | Guest            (strength 90, none)  |  order=0
 143         +---------------------------------------+
 144         |                                       |
 145
 146 Another possible user interaction would be to unplug the Ethernet cable and
 147 in this case the favorite setting will be removed and the service falls back
 148 down in the list.
 149
 150         +---------------------------------------+
 151         | My WiFi AP       (strength 80, rsn)   |  order=1 - connected=yes
 152         +---------------------------------------+
 153         | Ethernet                              |  order=0
 154         +---------------------------------------+
 155         | Guest            (strength 90, none)  |  order=0
 156         +---------------------------------------+
 157         |                                       |
 158
 159 If the service on the top of the list changes the default route will be
 160 automatically adjusted as needed. The user can trigger this by disconnecting
 161 from a network, if the network becomes unavailable (out of range) or if the
 162 cable gets unplugged.
 163
 164 As described above, the pure case of disconnecting from a network will not
 165 remove the favorite setting. So previously selected networks are still present
 166 and are sorted above all others.
 167
 168         +---------------------------------------+
 169         | Ethernet                              |  order=2 - connected=yes
 170         +---------------------------------------+
 171         | My WiFi AP       (strength 80, rsn)   |  order=1 - connected=no
 172         +---------------------------------------+
 173         | Guest            (strength 90, none)  |  order=0
 174         +---------------------------------------+
 175         |                                       |
 176
 177 Unplugging the Ethernet cable will remove the favorite setting, but due to
 178 the basic ordering of services it will be at the top of the services with an
 179 order number of 0 (directly after all favorite services).
 180
 181         +---------------------------------------+
 182         | My WiFi AP       (strength 80, rsn)   |  order=1 - connected=no
 183         +---------------------------------------+
 184         | Ethernet                              |  order=0 - connected=no
 185         +---------------------------------------+
 186         | Guest            (strength 90, none)  |  order=0
 187         +---------------------------------------+
 188         |                                       |
 189
 190
 191 Service tweaks
 192 ==============
 193
 194 The interfaces of Connection Manager will always export all services that are
 195 currently known. The Ethernet devices with no cable plugged are actually not
 196 included in this list. They will only show up once a carrier is detected.
 197
 198 The service interface is not meant for basic device configuration task. So
 199 switching a device on and off (via RFKILL for example) should be done via
 200 the device interface.
 201
 202 Due to limited screen size of small devices and the big amount of WiFi
 203 access points that are deployed right now it might be sensible to not show
 204 certain WiFi networks in the user interface.
 205
 206 The choice to hide a WiFi network from the user interface should be purely
 207 done by the signal strength. The optimal cut-off value here still has to be
 208 determined, but in the end that is a user interface policy.
 209
 210
 211 Service naming
 212 ==============
 213
 214 Every service will have a name property that allows the user interface to
 215 display them directly. All names will be already converted into UTF-8. It
 216 derives from the netork details.
 217
 218 In case of WiFi this will be the SSID value. The SSID is a binary array and
 219 will be converted into printable form. Unprintable characters are replaced
 220 with spaces.
 221
 222 For Bluetooth the device alias is used. The alias is different since it
 223 can be overwritten by the user via the Bluetooth service. The identification
 224 is still done based on its address, but the display name might change. In
 225 most cases the alias is equal to the Bluetooth remote friendly name.
 226
 227 For Ethernet device no name will be provided. The type property will indicate
 228 that this service is Ethernet and then it is up to the user interface to
 229 provide a proper localized name for it.
 230
 231
 232 Service states
 233 ==============
 234
 235 Every service can have multiple states that indicate what is currently
 236 going on with it. The choice to have multiple states instead of a simple
 237 connected yes/no value comes from the fact that it is important to let the
 238 user interface name if a service is in process of connecting/disconnecting.
 239
 240 The basic state of every service is "idle". This means that this service
 241 is not in use at all at the moment. It also is not attempting to connect
 242 or do anything else.
 243
 244 The "association" state indicates that this service tries to establish a
 245 low-level connection to the network. For example associating/connecting
 246 with a WiFi access point.
 247
 248 With the "configuration" state the service indicates that it is trying
 249 to retrieve/configure IP settings.
 250
 251 The "ready" state signals a successful connected device. This doesn't mean
 252 it has the default route, but basic IP operations will succeed.
 253
 254 With the "disconnect" state a service indicates that it is going to terminate
 255 the current connection and will return to the "idle" state.
 256
 257 In addition a "failure" state indicates a wrong behavior. It is similar to
 258 the "idle" state since the service is not connected.
 259
 260                 +---------------+
 261                 | idle          |<-------------------------------+
 262                 +---------------+                                |
 263                       |                                          |
 264                       |                      +-------------+     |
 265                       +----------------------| failure     |     |
 266                       | service.Connect()    +-------------+     |
 267                       V                           A              |
 268                 +---------------+                 |              |
 269                 | association   |-----------------+              |
 270                 +---------------+      error      |              |
 271                       |                           |              |
 272                       | success                   |              |
 273                       V                           |              |
 274                 +---------------+                 |              |
 275                 | configuration |-----------------+              |
 276                 +---------------+      error                     |
 277                       |                                          |
 278                       | success                                  |
 279                       V                                          |
 280                 +---------------+                                |
 281                 | ready         |                                |
 282                 +---------------+                                |
 283                       |                                          |
 284                       | success                                  |
 285                       |                                          |
 286                       V                                          |
 287                 +---------------+                                |
 288                 | online        |<----------------+              |
 289                 +---------------+                 |              |
 290                       |                           |              |
 291                       | service.Disconnect()      |              |
 292                       V                           |              |
 293                 +---------------+                 |              |
 294                 | disconnect    |-----------------+              |
 295                 +---------------+      error                     |
 296                       |                                          |
 297                       +------------------------------------------+
 298
 299 The different states should no be used by the user interface to trigger
 300 advanced actions. The state transitions are provided for the sole purpose
 301 to give the user feedback on what is currently going on. Especially in
 302 cases where networks are flaky or DHCP servers take a long time these
 303 information are helpful for the user.
 304
 305 Some services might require special authentication procedure like a web
 306 based confirmation. The LoginRequired property should be used to check
 307 for this.
 308
 309
 310 Application basics
 311 ==================
 312
 313 All applications should use D-Bus to communicate with Connection Manager. The
 314 main entry point is the manager object. Currently the manager object is
 315 located at "/", but this might change to allow full namespacing of the API
 316 in the future. The manager interface is documented in manager-api.txt and
 317 contains a set of global properties and methods.
 318
 319 A simple way to retrieve all global properties looks like this:
 320
 321         bus = dbus.SystemBus()
 322
 323         manager = dbus.Interface(bus.get_object("net.connman", "/"),
 324                                                 "net.connman.Manager")
 325
 326         properties = manager.GetProperties()
 327
 328 Changing a global property is also pretty simple. For example enabling the
 329 so called offline mode (aka flight mode) it is enough to just set that
 330 property:
 331
 332         manager.SetProperty("OfflineMode", dbus.Boolean(1))
 333
 334 The manager object contains references to profiles, devices, services and
 335 connections. All these references represent other interfaces that allow
 336 detailed control of Connection Manager. The profiles and devices interfaces
 337 are more for advanced features and most applications don't need them at all.
 338
 339 The services are represented as a list of object paths. Every of these object
 340 paths contains a service interface. A service is a global collection for
 341 Ethernet devices, WiFi networks, Bluetooth services etc. and all these
 342 different types are treated equally.
 343
 344 Every local Ethernet card will show up as exactly one service. WiFi networks
 345 will be grouped by SSID, mode and security setting. Bluetooth PAN and DUN
 346 service will show up per remote device. This creates a simple list that can
 347 be directly displayed to the users since these are the exact details users
 348 should care about.
 349
 350         properties = manager.GetProperties()
 351
 352         for path in properties["Services"]:
 353                 service = dbus.Interface(bus.get_object("net.connman", path),
 354                                                         "net.connman.Service")
 355
 356                 service_properties = service.GetProperties()
 357
 358 The service interface is documented in service-api.txt and contains common
 359 properties valid for all services. It also contains method to connect or
 360 disconnect a specific service. This allows users to select a specific service.
 361 Connection Manager can also auto-connect services based on his policies or
 362 via external events (like plugging in an Ethernet cable).
 363
 364 Connecting (or disconnecting) a specific service manually is as simple as
 365 just telling it to actually connect:
 366
 367         service.Connect()  or  service.Disconnect()
 368
 369 It is possible to connect multiple services if the underlying technology
 370 allows it. For example it would be possible to connect to a WiFi network
 371 and a Bluetooth service at the same time. Trying to connect to a second WiFi
 372 network with the same WiFi hardware would result in an automatic disconnect
 373 of the currently connected network. Connection Manager handles all of this
 374 for the applications in the background. Trying to connect an Ethernet service
 375 will result in an error if no cable is plugged in. All connection attempts
 376 can fail for one reason or another. Application should be able to handle
 377 such errors and will also be notified of changes via signals.
 378
 379 In future versions Connection Manager will interact with an agent to confirm
 380 certain transactions with the user. This functionality is currently not
 381 implemented.
 382
 383 To monitor the current status of a service the state property can be used. It
 384 gives detailed information about the current progress.
 385
 386         properties = service.GetProperties()
 387
 388         print properties["State"]
 389
 390 All state changes are also sent via the PropertyChanged signal on the
 391 service interface. This allows asynchronous monitoring without having to poll
 392 Connection Manager for changes.