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