ConnMan is the connectivity daemon used in MeeGo, used to manage and monitor the state of network connections. It is an extremely flexible, extensible and developer-friendly product.
This tutorial explains how to interact programmatically with the ConnMan connectivity daemon via its D-Bus interface. It doesn't cover specifics of interacting with D-Bus APIs, as that topic is generic enough to be covered separately. However, it does introduce the D-Bus API as exposed by ConnMan.
ConnMan differs from most D-Bus APIs in that the objects it exposes don't implement the org.freedesktop.DBus.Properties interface. Instead, the interfaces defined by ConnMan implement their own GetProperties and SetProperty methods. This is so that the properties can provide change notification via signals (which is not possbile using the standard D-Bus Properties interface).
The components of ConnMan's D-Bus API are described in the following sub-sections.
Contents |
The Service API defines high-level network services implemented through the org.moblin.connman.Manager and org.moblin.connman.Service interfaces. It is possible to write a complete connectivity UI using the Service API, as is done in the MeeGo Netbook UX.
A single object implementing the Manager interface exists on the connman path, through this one can retrieve a list of Service objects (as well as Devices, Profiles and Connections as discussed later).
The Manager interface defines many methods, signals and properties, but the most important ones are:
State (read-only): Global state of the system (online, connected or offline).
AvailableTechnologies (read-only): Array of technologies available on the system (wifi, ethernet, wimax, cellular, bluetooth).
EnabledTechnologies (read-only): Array of enabled technologies (a subset of AvailableTechnologies).
ConnectedTechnologies (read-only): Array of technologies with an active connection (a subset of AvailableTechnologies).
OfflineMode (read-write): Boolean representing whether offline mode is enabled.
Services (read-only): Sorted array of object paths of available Services objects.
GetProperties(): Returns a dictionary mapping property names to current values for each property of the object.
SetProperty(string name, variant value): Sets the value for the named property.
GetState(): A convenience method for applications which want to know the daemon state, but don't care about the rest of the properties.
RequestScan(string type): Triggers a network scan for technology type; passing an empty string to this method performs a trigger scan on all supported technologies.
EnableTechnology(string type) / DisableTechnology(string type): Used to enable/disable technologies. The argument passed to this method specifies the type of technology to enable/disable. This method will also appropriately set the powered state of the device.
ConnectService(dict network): Connect to a service as specified by the properties in the network dictionary. Typically used for connecting to hidden networks. For example, to connect to a hidden WiFi network, the network argument passed in might look like this:
{
'Type':'wifi', 'Mode':'managed', 'SSID':'ssid', 'Security':'WEP', 'Passphrase':'secret'
}
PropertyChanged: Signal emitted when one of the object's properties has changed.
StateChanged: A convenience signal implemented solely to notify when the State property changes. Useful if an application only cares about whether the system is online or not, but needs to be notified when that state changes.
The Service interface provides a high-level network object with methods for setting up, connecting and disconnecting. The most notable methods, properties and signals of the Service interface are:
State (read-only): The status of the service as a string. Possible values are "idle", "failure", "association", "configuration", and "ready". The State is "ready" when the service is usable for connectivity.
Error (read-only): When the service state is "failure", this property may contain a string explaining the cause of the failure.
Security (read-only): The type of security for a wireless network. Possible values are "none", "wep", "wpa", and "rsn".
Passphrase (read-write): The passphrase of the service.
GetProperties(): Returns a dictionary mapping property names to current values for each property of the object.
SetProperty(string name, variant value): Sets the value for the named property.
Connect() / Disconnect(): Connect or disconnect the service. For services which require configuration (secure wifi, cellular, etc.), configuration must be set before a call to Connect will succeed.
Connect method is a blocking method, so it may be wise to set a long timeout on these calls.
Remove(): Removes the service's saved state such that it will need configuration before it can be connected again. Disconnects the network (if required), clears the favourite and autoconnect flags, and clears any stored passphrase.
MoveBefore(object service): To prioritise one connected Service over another, call the MoveBefore method, passing in the object path of another Service object you want this Service object to have priority over.
PropertyChanged: Signal emitted when one of the object's properties has changed.
The Manager interface provides access to Devices, Connections and Profiles, if you need lower-level access than that provided by the Service API. These low-level interfaces are exposed, much like Services, as arrays of object paths in the Manager interface's properties.
Apart from writing full connectivity UIs, the ConnMan API can be used by other applications to find out about the state of network connections and types of connections available.
For this purpose you can use the GetState() method and StateChanged signals of the org.moblin.connman.Manager interface.
An example showing the former (but not the latter) can be seen in the dbus-glib example on this wiki.