NetworkManager DBUS API (unstable) ---------------------------------- NetworkManager (NM) exposes a DBUS service and API for two purposes: for programs to obtain information about the network state and network devices, and for programs or users to alter the network state in limited ways. This API is currently unstable and is likely to change in the future. Any methods or objects NOT described in this document are not part of the official API, are not meant for general use, and are not supported in any way. There are three types of "objects" that NM allows other programs to interact with: the NetworkManager object, Device objects, and Network objects. There is only one NetworkManager object as it performs system-wide networking functions and controls each Device. There can be a arbitrary number of Devices, including no Devices at all, each of which represent a network device present in the system. A Network is the representation of a wireless network, of which each Device object may have an arbitrary number (as long as it is a wireless device). Object structure: NetworkManager / \ Device Device / \ (no networks) Network Network The NetworkManager object ------------------------- The following constants are used to uniquely refer to the NetworkManager object when making DBUS method calls against NetworkManager: DBUS Service: "org.freedesktop.NetworkManager" DBUS Object Path: "/org/freedesktop/NetworkManager" DBUS Interface: "org.freedesktop.NetworkManager" Methods: Name: getDevices Get the list of network devices NM knows about Args: (none) Returns: DBUS String Array Each item in the array is the NM identifier of a Device object Name: getActiveDevice Return the currently active network device Args: (none) Returns: DBUS_TYPE_STRING The NM identifier of a Device object Name: setActiveDevice Force NM to use a particular network device Args: 1) Device object (DBUS_TYPE_STRING) - Network device to switch to 2) Wireless Network ESSID (DBUS_TYPE_STRING, optional) - ESSID of the wireless network to switch to Returns: (nothing) Name: status Retrieve status information about the network state Args: (none) Returns: DBUS_TYPE_STRING "connecting" - there is a pending network connection (waiting for a DHCP request to complete, waiting for an encryption key/passphrase, waiting for a wireless network, etc) "connected" - there is an active network connection "scanning" - there is no active network connection, but NetworkManager is looking for an access point to associate with "disconnected" - there is no network connection Signals: Name: DeviceNoLongerActive Signals that a network device is no longer active Args: 1) Device object (DBUS_TYPE_STRING) - The deactivated network device Name: DeviceNowActive Signals that a network device is newly activated Args: 1) Device object (DBUS_TYPE_STRING) - The newly activated network device Name: DeviceActivating Signals that a network device is about to become active Args: 1) Device object (DBUS_TYPE_STRING) - The device about to become active Name: DevicesChanged Signals that a device was either added or removed from the system Args: 1) Device object (DBUS_TYPE_STRING) - The device which was added or removed NOTE: the following 3 Signals are likely to change in the near future Name: DeviceIP4AddressChange Signals that a device's IPv4 address was changed Args: 1) Device object (DBUS_TYPE_STRING) - The device whose IPv4 address changed Name: WirelessNetworkAppeared Signals that a device found a new wireless network Args: 1) Device object (DBUS_TYPE_STRING) - The device which noticed the wireless network 2) Network object (DBUS_TYPE_STRING) - The new wireless network's identifier Name: WirelessNetworkDisappeared Signals that a device lost a new wireless network Args: 1) Device object (DBUS_TYPE_STRING) - The device which lost the wireless network 2) Network object (DBUS_TYPE_STRING) - The no-longer-visible wireless network's identifier The Device object ----------------- The Device object is the NM representation of a network device. To refer to a NM Device, you must use the following constants when creating your DBUS message: DBUS Service: "org.freedesktop.NetworkManager" DBUS Interface: "org.freedesktop.NetworkManager.Devices" Note that there is no DBUS Object Path listed above, the object path will always the the NM Device identfier returned from such methods as "getActiveDevice" and "getDevices". Methods: Name: getName Returns the system device name of the Device object (i.e. eth0) Args: (none) Returns: DBUS_TYPE_STRING The system device name Name: getType Returns the type of the device (ie wired, wireless, isdn, bluetooth, etc) Args: (none) Returns: DBUS_TYPE_INT32 0 - unknown type 1 - Wired ethernet 2 - Wireless (802.11a/b/g) Name: getHalUdi Returns the HAL UDI of the device Args: (none) Returns: DBUS_TYPE_STRING Name: getIP4Address Returns the IPv4 address of the device Args: (none) Returns: DBUS_TYPE_UINT32 The IPv4 address in network byte order Name: getLinkActive Returns the link state of the device Args: (none) Returns: DBUS_TYPE_BOOLEAN TRUE - the device has a valid network link Wired: cable is plugged in Wireless: good link to a base station FALSE - the device has no network link Wired: no cable plugged in Wireless: no base station, or bad encryption key Name: getStrength (Wireless only) Return the strength percentage of the current wireless network Args: (none) Returns: DBUS_TYPE_INT32 The strength percentage of the current wireless network Name: getActiveNetwork (Wireless only) Returns the Network object indentifier of the wireless network this device is currently associated with, if any Args: (none) Returns: DBUS_TYPE_STRING Name: getNetworks (Wireless only) Returns a list of Network objects this device knows about Args: (none) Returns: DBUS String Array Each item in the array is a Network object identifier The Network object ------------------ Each Device object that is of type 2 (Wireless device) keeps a list of Network objects that it knows about. Use the following constants to specify a Network object when creating DBUS method calls: DBUS Service: "org.freedesktop.NetworkManager" DBUS Interface: "org.freedesktop.NetworkManager.Devices" Again, note that there is no DBUS Object Path above, since the object path used for the method call will be the Network object indentifier returned from a Device object's "getActiveNetwork" or "getNetworks" methods. Methods: Name: getName Return the name of the network (ESSID) Args: (none) Returns: DBUS_TYPE_STRING Name: getAddress Returns the hardware address of the base station this wireless network belongs to. NOTE: this may change in the near future to an array of addresses. Args: (none) Returns: DBUS_TYPE_STRING Name: getStrength Return the strength percentage of the current wireless network Args: (none) Returns: DBUS_TYPE_INT32 The strength percentage of the current wireless network Name: getFrequency Returns the frequency/channel this wireless network Args: (none) Returns: DBUS_TYPE_DOUBLE A frequency in GHz (i.e. 2.417) Name: getRate Returns the max data rate this wireless network supports Args: (none) Returns: DBUS_TYPE_INT32 The max data rate in Mbps (i.e. 11) Name: getEncrypted Returns whether or not this wireless network requires encryption Args: (none) Returns: DBUS_TYPE_BOOLEAN