mirror of
https://gitlab.freedesktop.org/NetworkManager/NetworkManager
synced 2024-07-21 10:14:41 +00:00
196 lines
8.2 KiB
Plaintext
196 lines
8.2 KiB
Plaintext
********* NOTE *********
|
|
This document is for historical reference only. The autogenerated 'spec.html' is the canonical D-Bus reference.
|
|
********* NOTE *********
|
|
|
|
|
|
|
|
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
|
|
|
|
Name: DeviceActivationFailed Signals that activation for a device could not complete (dhcp failed or so)
|
|
Args: 1) Device object (DBUS_TYPE_STRING) - The device for which activation failed
|
|
2) Network name (DBUS_TYPE_STRING, optional) - ESSID of failed wireless network
|
|
|
|
Name: DeviceStrengthChanged Signals that the wireless strength percentage for the device has changed.
|
|
Args: 1) Device object (DBUS_TYPE_STRING) - The device for which strength changed
|
|
2) Strength (DBUS_TYPE_INT32) - The new strength percentage
|
|
|
|
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 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: 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
|
|
|
|
|