docs/NetworkManager DBUS API.txt

   1 ********* NOTE *********
   2 This document is for historical reference only.  The autogenerated 'spec.html' is the canonical D-Bus reference.
   3 ********* NOTE *********
   4
   5
   6
   7 NetworkManager DBUS API (unstable)
   8 ----------------------------------
   9
  10 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.
  11
  12 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).
  13
  14
  15 Object structure:
  16                                   NetworkManager
  17                                   /            \
  18                              Device            Device
  19                              /     \              (no networks)
  20                         Network    Network
  21
  22
  23 The NetworkManager object
  24 -------------------------
  25
  26 The following constants are used to uniquely refer to the NetworkManager object when making DBUS method calls against NetworkManager:
  27
  28 DBUS Service:                   "org.freedesktop.NetworkManager"
  29 DBUS Object Path:               "/org/freedesktop/NetworkManager"
  30 DBUS Interface:         "org.freedesktop.NetworkManager"
  31
  32 Methods:
  33
  34         Name:   getDevices              Get the list of network devices NM knows about
  35         Args:   (none)
  36         Returns:        DBUS String Array                       Each item in the array is the NM identifier of a Device object
  37
  38
  39         Name:   getActiveDevice Return the currently active network device
  40         Args:   (none)
  41         Returns:        DBUS_TYPE_STRING                        The NM identifier of a Device object
  42
  43
  44         Name:   setActiveDevice Force NM to use a particular network device
  45         Args:   1) Device object                        (DBUS_TYPE_STRING) - Network device to switch to
  46                         2) Wireless Network ESSID       (DBUS_TYPE_STRING, optional) - ESSID of the wireless network to switch to
  47         Returns:        (nothing)
  48
  49
  50         Name:   status                  Retrieve status information about the network state
  51         Args:   (none)
  52         Returns:        DBUS_TYPE_STRING                        "connecting"    - there is a pending network connection (waiting for a
  53                                                                                                         DHCP request to complete, waiting for an encryption
  54                                                                                                         key/passphrase, waiting for a wireless network, etc)
  55                                                                         "connected"     - there is an active network connection
  56                                                                         "scanning"      - there is no active network connection, but NetworkManager
  57                                                                                                         is looking for an access point to associate with
  58                                                                         "disconnected"  - there is no network connection
  59
  60 Signals:
  61
  62         Name:   DeviceNoLongerActive            Signals that a network device is no longer active
  63         Args:   1) Device object                        (DBUS_TYPE_STRING)      - The deactivated network device
  64
  65         Name:   DeviceNowActive                 Signals that a network device is newly activated
  66         Args:   1) Device object                        (DBUS_TYPE_STRING)      - The newly activated network device
  67
  68         Name:   DeviceActivating                        Signals that a network device is about to become active
  69         Args:   1) Device object                        (DBUS_TYPE_STRING)      - The device about to become active
  70
  71         Name:   DevicesChanged                          Signals that a device was either added or removed from the system
  72         Args:   1) Device object                        (DBUS_TYPE_STRING)      - The device which was added or removed
  73
  74         Name:   DeviceActivationFailed          Signals that activation for a device could not complete (dhcp failed or so)
  75         Args:   1) Device object                        (DBUS_TYPE_STRING)      - The device for which activation failed
  76                         2) Network name                 (DBUS_TYPE_STRING, optional) - ESSID of failed wireless network
  77
  78         Name:   DeviceStrengthChanged           Signals that the wireless strength percentage for the device has changed.
  79         Args:   1) Device object                        (DBUS_TYPE_STRING)      - The device for which strength changed
  80                         2) Strength                     (DBUS_TYPE_INT32)       - The new strength percentage
  81
  82 NOTE: the following 3 Signals are likely to change in the near future
  83
  84         Name:   DeviceIP4AddressChange          Signals that a device's IPv4 address was changed
  85         Args:   1) Device object                        (DBUS_TYPE_STRING)      - The device whose IPv4 address changed
  86
  87         Name:   WirelessNetworkAppeared         Signals that a device found a new wireless network
  88         Args:   1) Device object                        (DBUS_TYPE_STRING)      - The device which noticed the wireless network
  89                         2) Network object                       (DBUS_TYPE_STRING)      - The new wireless network's identifier
  90
  91         Name:   WirelessNetworkDisappeared      Signals that a device lost a new wireless network
  92         Args:   1) Device object                        (DBUS_TYPE_STRING)      - The device which lost the wireless network
  93                         2) Network object                       (DBUS_TYPE_STRING)      - The no-longer-visible wireless network's identifier
  94
  95
  96
  97
  98 The Device object
  99 -----------------
 100
 101 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:
 102
 103 DBUS Service:                   "org.freedesktop.NetworkManager"
 104 DBUS Interface:         "org.freedesktop.NetworkManager.Devices"
 105
 106 Note that there is no DBUS Object Path listed above, the object path will always the NM Device identfier returned from such methods as "getActiveDevice" and "getDevices".
 107
 108 Methods:
 109
 110         Name:   getName                 Returns the system device name of the Device object (i.e. eth0)
 111         Args:   (none)
 112         Returns:        DBUS_TYPE_STRING                        The system device name
 113
 114
 115         Name:   getType                 Returns the type of the device (ie wired, wireless, isdn, bluetooth, etc)
 116         Args:   (none)
 117         Returns:        DBUS_TYPE_INT32                 0 - unknown type
 118                                                                         1 - Wired ethernet
 119                                                                         2 - Wireless (802.11a/b/g)
 120
 121
 122         Name:   getHalUdi                       Returns the HAL UDI of the device
 123         Args:   (none)
 124         Returns:        DBUS_TYPE_STRING
 125
 126
 127         Name:   getIP4Address           Returns the IPv4 address of the device
 128         Args:   (none)
 129         Returns:        DBUS_TYPE_UINT32                        The IPv4 address in network byte order
 130
 131
 132         Name:   getLinkActive           Returns the link state of the device
 133         Args:   (none)
 134         Returns:        DBUS_TYPE_BOOLEAN                       TRUE - the device has a valid network link
 135                                                                                                 Wired: cable is plugged in
 136                                                                                                 Wireless: good link to a base station
 137                                                                         FALSE - the device has no network link
 138                                                                                                 Wired: no cable plugged in
 139                                                                                                 Wireless: no base station, or bad encryption key
 140
 141         Name:   getActiveNetwork        (Wireless only) Returns the Network object indentifier of the wireless network
 142                                                                 this device is currently associated with, if any
 143         Args:   (none)
 144         Returns:        DBUS_TYPE_STRING
 145
 146
 147         Name:   getNetworks             (Wireless only) Returns a list of Network objects this device knows about
 148         Args:   (none)
 149         Returns:        DBUS String Array                       Each item in the array is a Network object identifier
 150
 151
 152
 153 The Network object
 154 ------------------
 155
 156 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:
 157
 158 DBUS Service:                   "org.freedesktop.NetworkManager"
 159 DBUS Interface:         "org.freedesktop.NetworkManager.Devices"
 160
 161 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.
 162
 163 Methods:
 164
 165         Name:   getName                 Return the name of the network (ESSID)
 166         Args:   (none)
 167         Returns:        DBUS_TYPE_STRING
 168
 169
 170         Name:   getAddress              Returns the hardware address of the base station this wireless network belongs to.
 171                                                                 NOTE: this may change in the near future to an array of addresses.
 172         Args:   (none)
 173         Returns:        DBUS_TYPE_STRING
 174
 175
 176         Name:   getStrength             Return the strength percentage of the current wireless network
 177         Args:   (none)
 178         Returns:        DBUS_TYPE_INT32                 The strength percentage of the current wireless network
 179
 180
 181         Name:   getFrequency            Returns the frequency/channel this wireless network
 182         Args:   (none)
 183         Returns:        DBUS_TYPE_DOUBLE                        A frequency in GHz (i.e. 2.417)
 184
 185
 186         Name:   getRate                 Returns the max data rate this wireless network supports
 187         Args:   (none)
 188         Returns:        DBUS_TYPE_INT32                 The max data rate in Mbps (i.e. 11)
 189
 190
 191         Name:   getEncrypted            Returns whether or not this wireless network requires encryption
 192         Args:   (none)
 193         Returns:        DBUS_TYPE_BOOLEAN
 194
 195