doc/overview-api.txt

   1 Application programming interface
   2 *********************************
   3
   4
   5 Application basics
   6 ==================
   7
   8 All applications should use D-Bus to communicate with Connection Manager. The
   9 main entry point is the manager object. Currently the manager object is
  10 located at "/", but this might change to allow full namespacing of the API
  11 in the future. The manager interface is documented in manager-api.txt and
  12 contains a set of global properties and methods.
  13
  14 A simple way to retrieve all global properties looks like this:
  15
  16         bus = dbus.SystemBus()
  17
  18         manager = dbus.Interface(bus.get_object("org.moblin.connman", "/"),
  19                                                 "org.moblin.connman.Manager")
  20
  21         properties = manager.GetProperties()
  22
  23 Changing a global property is also pretty simple. For example enabling the
  24 so called offline mode (aka flight mode) it is enough to just set that
  25 property:
  26
  27         manager.SetProperty("OfflineMode", dbus.Boolean(1))
  28
  29 The manager object contains references to profiles, devices, services and
  30 connections. All these references represent other interfaces that allow
  31 detailed control of Connection Manager. The profiles and devices interfaces
  32 are more for advanced features and most applications don't need them at all.
  33
  34 The services are represented as a list of object paths. Every of these object
  35 paths contains a service interface. A service is a global collection for
  36 Ethernet devices, WiFi networks, Bluetooth services, WiMAX providers etc. and
  37 all these different types are treated equally.
  38
  39 Every local Ethernet card will show up as exactly one service. WiFi networks
  40 will be grouped by SSID, mode and security setting. Bluetooth PAN and DUN
  41 service will show up per remote device. For WiMAX the provider name will
  42 be used for grouping different base stations and access providers. This
  43 creates a simple list that can be directly displayed to the users since these
  44 are the exact details users should care about.
  45
  46         properties = manager.GetProperties()
  47
  48         for path in properties["Services"]:
  49                 service = dbus.Interface(bus.get_object("org.moblin.connman", path),
  50                                                         "org.moblin.connman.Service")
  51
  52                 service_properties = service.GetProperties()
  53
  54 The service interface is documented in service-api.txt and contains common
  55 properties valid for all services. It also contains method to connect or
  56 disconnect a specific service. This allows users to select a specific service.
  57 Connection Manager can also auto-connect services based on his policies or
  58 via external events (like plugging in an Ethernet cable).
  59
  60 Connecting (or disconnecting) a specific service manually is as simple as
  61 just telling it to actually connect:
  62
  63         service.Connect()  or  service.Disconnect()
  64
  65 It is possible to connect multiple service if the underlying technology
  66 allows it. For example it would be possible to connect to a WiFi network
  67 and a Bluetooth service at the same time. Trying to connect to a second WiFi
  68 network with the same WiFi hardware would result in an automatic disconnect
  69 of the currently connected network. Connection Manager handles all of this
  70 for the applications in the background. Trying to connect an Ethernet service
  71 will result in an error if no cable is plugged in. All connection attempts
  72 can fail for one reason or another. Application should be able to handle
  73 such errors and will also be notified of changes via signals.
  74
  75 In future versions Connection Manager will interact with an agent to confirm
  76 certain transaction with the user. This functionality is currently not
  77 implemented.
  78
  79 To monitor the current status of a service the state property can be used. It
  80 gives detailed information about the current progress.
  81
  82         properties = service.GetProperties()
  83
  84         print properties["State"]
  85
  86 All state changes are also send via the PropertyChanged signal on the
  87 service interface. This allows asynchronous monitoring with having to poll
  88 Connection Manager for changes.