NetworkManager/docs/NetworkManager DBUS API.txt

********* 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