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 service from the list
 103
 104         +---------------------------------------+
 105         | Ethernet with cable                   |  order=1 - favorite=yes
 106         +---------------------------------------+
 107         | Guest            (strength 90, none)  |  order=0
 108         +---------------------------------------+
 109         |                                       |
 110
 111 This means that all services with an order > 0 have favorite=yes and all
 112 others have favorite=no setting. The favorite setting is exposed via a
 113 property over the service interface. As mentioned above, the order number
 114 is only used internally.
 115
 116 Within Connection Manager many services can be connected at the same time and
 117 also have an IP assignment. However only one can have the default route. The
 118 service with the default route will always be sorted at the top of the
 119 list.
 120
 121         +---------------------------------------+
 122         | Ethernet                              |  order=2 - connected=yes
 123         +---------------------------------------+
 124         | My WiFi AP       (strength 80, rsn)   |  order=1 - connected=yes
 125         +---------------------------------------+
 126         | Guest            (strength 90, none)  |  order=0
 127         +---------------------------------------+
 128         |                                       |
 129
 130 To change the default connection to your access point, the user needs to
 131 manually drag the access point service to the top of the list. Connection
 132 Manager will not take down default routes if there is no reason to do so.
 133 A working connection is considered top priority.
 134
 135         +---------------------------------------+
 136         | My WiFi AP       (strength 80, rsn)   |  order=2 - connected=yes
 137         +---------------------------------------+
 138         | Ethernet                              |  order=1 - connected=yes
 139         +---------------------------------------+
 140         | Guest            (strength 90, none)  |  order=0
 141         +---------------------------------------+
 142         |                                       |
 143
 144 Another possible user interaction would be to disconnect the Ethernet service
 145 and in this case the service falls back down in the list.
 146
 147         +---------------------------------------+
 148         | My WiFi AP       (strength 80, rsn)   |  order=1 - connected=yes
 149         +---------------------------------------+
 150         | Ethernet                              |  order=1 - connected=no
 151         +---------------------------------------+
 152         | Guest            (strength 90, none)  |  order=0
 153         +---------------------------------------+
 154         |                                       |
 155
 156 If the service on the top of the list changes the default route will be
 157 automatically adjusted as needed. The user can trigger this by disconnecting
 158 from a network, if the network becomes unavailable (out of range) or if the
 159 cable gets unplugged.
 160
 161 As described above, the pure case of disconnecting from a network will not
 162 remove the favorite setting. So previously selected networks are still present
 163 and are sorted above all others.
 164
 165         +---------------------------------------+
 166         | Ethernet                              |  order=2 - connected=yes
 167         +---------------------------------------+
 168         | My WiFi AP       (strength 80, rsn)   |  order=1 - connected=no
 169         +---------------------------------------+
 170         | Guest            (strength 90, none)  |  order=0
 171         +---------------------------------------+
 172         |                                       |
 173
 174 Unplugging the Ethernet cable will remove the Ethernet service.
 175
 176         +---------------------------------------+
 177         | My WiFi AP       (strength 80, rsn)   |  order=1 - connected=no
 178         +---------------------------------------+
 179         | Guest            (strength 90, none)  |  order=0
 180         +---------------------------------------+
 181         |                                       |
 182
 183
 184 Service tweaks
 185 ==============
 186
 187 The interfaces of Connection Manager will always export all services that are
 188 currently known. The Ethernet devices with no cable plugged are actually not
 189 included in this list. They will only show up once a carrier is detected.
 190
 191 The service interface is not meant for basic device configuration task. So
 192 switching a device on and off (via RFKILL for example) should be done via
 193 the technology interface. See "Technology interfaces" chapter in this document.
 194
 195 Due to limited screen size of small devices and the big amount of WiFi
 196 access points that are deployed right now it might be sensible to not show
 197 certain WiFi networks in the user interface.
 198
 199 The choice to hide a WiFi network from the user interface should be purely
 200 done by the signal strength. The optimal cut-off value here still has to be
 201 determined, but in the end that is a user interface policy.
 202
 203
 204 Service naming
 205 ==============
 206
 207 Every service will have a name property that allows the user interface to
 208 display them directly. All names will be already converted into UTF-8. It
 209 derives from the netork details.
 210
 211 In case of WiFi this will be the SSID value. The SSID is a binary array and
 212 will be converted into printable form. Unprintable characters are replaced
 213 with spaces.
 214
 215 In addition to WiFi naming, WiFi networks are subject to a grouping policy
 216 performed around SSID and security type. This means that one service will be
 217 seen for N WiFi networks providing the same SSID and the same security metod.
 218 For instance, if 5 APs are servicing an SSID called "TEST" with WPA2
 219 authentication and 3 APs are servicing the same SSID with open authentication
 220 method, the user will see only two services listed with the name "TEST"
 221 differentiated by their security type, which are "psk" and "none". Such
 222 policy is also applied to hidden networks, where hidden services will have an
 223 empty name and will be differentiated by the security type. The user has then
 224 to select the one with the right security and the Agent API will request any
 225 required information such as the SSID for the network (See "Application
 226 basics" below).
 227
 228 For Bluetooth the device alias is used. The alias is different since it
 229 can be overwritten by the user via the Bluetooth service. The identification
 230 is still done based on its address, but the display name might change. In
 231 most cases the alias is equal to the Bluetooth remote friendly name.
 232
 233 For Ethernet device no name will be provided. The type property will indicate
 234 that this service is Ethernet and then it is up to the user interface to
 235 provide a proper localized name for it.
 236
 237
 238 Service states
 239 ==============
 240
 241 Every service can have multiple states that indicate what is currently
 242 going on with it. The choice to have multiple states instead of a simple
 243 connected yes/no value comes from the fact that it is important to let the
 244 user interface name if a service is in process of connecting/disconnecting.
 245
 246 The basic state of every service is "idle". This means that this service
 247 is not in use at all at the moment. It also is not attempting to connect
 248 or do anything else.
 249
 250 The "association" state indicates that this service tries to establish a
 251 low-level connection to the network. For example associating/connecting
 252 with a WiFi access point.
 253
 254 With the "configuration" state the service indicates that it is trying
 255 to retrieve/configure IP settings.
 256
 257 The "ready" state signals a successful connected device. This doesn't mean
 258 it has the default route, but basic IP operations will succeed.
 259
 260 With the "disconnect" state a service indicates that it is going to terminate
 261 the current connection and will return to the "idle" state.
 262
 263 In addition a "failure" state indicates a wrong behavior. It is similar to
 264 the "idle" state since the service is not connected.
 265
 266                 +---------------+
 267                 | idle          |<-------------------------------+
 268                 +---------------+                                |
 269                       |                                          |
 270                       |                      +-------------+     |
 271                       +----------------------| failure     |     |
 272                       | service.Connect()    +-------------+     |
 273                       V                           A              |
 274                 +---------------+                 |              |
 275                 | association   |-----------------+              |
 276                 +---------------+      error      |              |
 277                       |                           |              |
 278                       | success                   |              |
 279                       V                           |              |
 280                 +---------------+                 |              |
 281                 | configuration |-----------------+              |
 282                 +---------------+      error                     |
 283                       |                                          |
 284                       | success                                  |
 285                       V                                          |
 286                 +---------------+                                |
 287                 | ready         |                                |
 288                 +---------------+                                |
 289                       |                                          |
 290                       | success                                  |
 291                       |                                          |
 292                       V                                          |
 293                 +---------------+                                |
 294                 | online        |<----------------+              |
 295                 +---------------+                 |              |
 296                       |                           |              |
 297                       | service.Disconnect()      |              |
 298                       V                           |              |
 299                 +---------------+                 |              |
 300                 | disconnect    |-----------------+              |
 301                 +---------------+      error                     |
 302                       |                                          |
 303                       +------------------------------------------+
 304
 305 The different states should no be used by the user interface to trigger
 306 advanced actions. The state transitions are provided for the sole purpose
 307 to give the user feedback on what is currently going on. Especially in
 308 cases where networks are flaky or DHCP servers take a long time these
 309 information are helpful for the user.
 310
 311 Some services might require special authentication procedure like a web
 312 based confirmation. The LoginRequired property should be used to check
 313 for this.
 314
 315
 316 Application basics
 317 ==================
 318
 319 All applications should use D-Bus to communicate with Connection Manager. The
 320 main entry point is the manager object. Currently the manager object is
 321 located at "/", but this might change to allow full namespacing of the API
 322 in the future. The manager interface is documented in manager-api.txt and
 323 contains a set of global properties and methods.
 324
 325 A simple way to retrieve all global properties looks like this:
 326
 327         bus = dbus.SystemBus()
 328
 329         manager = dbus.Interface(bus.get_object("net.connman", "/"),
 330                                                 "net.connman.Manager")
 331
 332         properties = manager.GetProperties()
 333
 334 Changing a global property is also pretty simple. For example enabling the
 335 so called offline mode (aka flight mode) it is enough to just set that
 336 property:
 337
 338         manager.SetProperty("OfflineMode", dbus.Boolean(1))
 339
 340 The manager object contains references to profiles, devices, services and
 341 connections. All these references represent other interfaces that allow
 342 detailed control of Connection Manager. The profiles and devices interfaces
 343 are more for advanced features and most applications don't need them at all.
 344
 345 The services are represented as a list of object paths. Every of these object
 346 paths contains a service interface. A service is a global collection for
 347 Ethernet devices, WiFi networks, Bluetooth services etc. and all these
 348 different types are treated equally.
 349
 350 Every local Ethernet card will show up as exactly one service. WiFi networks
 351 will be grouped by SSID, mode and security setting. Bluetooth PAN and DUN
 352 service will show up per remote device. This creates a simple list that can
 353 be directly displayed to the users since these are the exact details users
 354 should care about.
 355
 356         properties = manager.GetProperties()
 357
 358         for path in properties["Services"]:
 359                 service = dbus.Interface(bus.get_object("net.connman", path),
 360                                                         "net.connman.Service")
 361
 362                 service_properties = service.GetProperties()
 363
 364 The service interface is documented in service-api.txt and contains common
 365 properties valid for all services. It also contains method to connect or
 366 disconnect a specific service. This allows users to select a specific service.
 367 Connection Manager can also auto-connect services based on his policies or
 368 via external events (like plugging in an Ethernet cable).
 369
 370 Connecting (or disconnecting) a specific service manually is as simple as
 371 just telling it to actually connect:
 372
 373         service.Connect()  or  service.Disconnect()
 374
 375 It is possible to connect multiple services if the underlying technology
 376 allows it. For example it would be possible to connect to a WiFi network
 377 and a Bluetooth service at the same time. Trying to connect to a second WiFi
 378 network with the same WiFi hardware would result in an automatic disconnect
 379 of the currently connected network. Connection Manager handles all of this
 380 for the applications in the background. Trying to connect an Ethernet service
 381 will result in an error if no cable is plugged in. All connection attempts
 382 can fail for one reason or another. Application should be able to handle
 383 such errors and will also be notified of changes via signals.
 384
 385 Connection Manager will interact with an agent via the Agent API to confirm
 386 certain transactions with the user. If Connection Manager needs extra
 387 information, it will ask the user for exactly the information it requires,
 388 i.e. passphrase, network's name (for hidden WiFi networks) and more depending
 389 on the use case (e.g. WPS, EAP). Therefore an application environment using
 390 Connection Manager should implement one dedicated Connection Manager agent
 391 according to the Agent API in order to interact with the user. Please see
 392 agent-api.txt for implementation details.
 393
 394 To monitor the current status of a service the state property can be used. It
 395 gives detailed information about the current progress.
 396
 397         properties = service.GetProperties()
 398
 399         print properties["State"]
 400
 401 All state changes are also sent via the PropertyChanged signal on the
 402 service interface. This allows asynchronous monitoring without having to poll
 403 Connection Manager for changes.
 404
 405
 406 Technology interfaces
 407 =====================
 408
 409 When ConnMan is started first time, all technologies except ethernet are
 410 powered off by default. The reason is that the user needs to decide which
 411 technologies are relevant to him and what bearers the user wants to use.
 412 User can use the Technology Powered property to turn on or off a given
 413 technology. See doc/technology-api.txt document for details.
 414
 415 User can activate offline (flight) mode via Manager OfflineMode property.
 416 While in offline mode, all the technologies including ethernet are
 417 powered off. During the offline mode, the user can temporarily activate
 418 individual technologies by using the Technology Powered property or by
 419 using the rfkill command or Fn-Fx key combination found in some laptops.
 420
 421 If the host supports rfkill switch, then all the radios can be turned off
 422 by the kernel when the switch is activated. ConnMan will notice this and
 423 remove corresponding technologies from D-Bus. Technologies cannot be
 424 activated while rfkill switch is turned on. When rfkill switch is turned
 425 off (radios are activated), then ConnMan restores the original Powered
 426 status for each activated technology.
 427
 428 User can use the rfkill command from command line or indirectly via
 429 some UI component to activate/deactivate individual radios found in
 430 the host. ConnMan will listen these rfkill events and set the Powered
 431 property accordingly. ConnMan will not save the rfkill status it has
 432 received. This means that after restarting ConnMan, the original and
 433 saved technology status is used when deciding which technologies should
 434 be powered. If the user uses the Technology D-Bus API to set the Powered
 435 property, then that information is saved and used when ConnMan is restarted.