Commit 7b4fccac authored by Dan Williams's avatar Dan Williams

2004-09-11 Dan Williams <dcbw@redhat.com>

	* docs/NetworkManager DBUS API.txt
		- Add an explanation of NM's API

	* src/NetworkManagerDbus.c
		- Free some more DBusErrors if needed


git-svn-id: http://svn-archive.gnome.org/svn/NetworkManager/trunk@150 4912f4e0-d625-0410-9fb7-b9a5a253dbdc
parent ae080994
2004-09-11 Dan Williams <dcbw@redhat.com>
* docs/NetworkManager DBUS API.txt
- Add an explanation of NM's API
* src/NetworkManagerDbus.c
- Free some more DBusErrors if needed
2004-09-11 Dan Williams <dcbw@redhat.com>
* panel-applet/NMWirelessApplet.c
......
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
"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: getMaxQuality (Wireless only) Returns the maximum quality level of the wireless device, from
which a program may calculate a signal strength percentage based on this
number and the quality of an individual Network object
Args: (none)
Returns: DBUS_TYPE_UINT32 The maximum quality any wireless network can have
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: getQuality Returns the quality of this wirless network
Args: (none)
Returns: DBUS_TYPE_INT32 A number between 0 and the device's Maximum Quality
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
......@@ -1366,11 +1366,15 @@ void nm_dbus_devices_unregister_handler (DBusConnection *connection, void *user_
gboolean nm_dbus_is_info_daemon_running (DBusConnection *connection)
{
DBusError error;
gboolean running = FALSE;
g_return_val_if_fail (connection != NULL, FALSE);
dbus_error_init (&error);
return (dbus_bus_service_exists (connection, NMI_DBUS_SERVICE, &error));
running = dbus_bus_service_exists (connection, NMI_DBUS_SERVICE, &error);
if (dbus_error_is_set (&error))
dbus_error_free (&error);
return (running);
}
......@@ -1392,9 +1396,11 @@ DBusConnection *nm_dbus_init (NMData *data)
dbus_error_init (&dbus_error);
connection = dbus_bus_get (DBUS_BUS_SYSTEM, &dbus_error);
if (connection == NULL)
if ((connection == NULL) || dbus_error_is_set (&error))
{
syslog (LOG_ERR, "nm_dbus_init() could not get the system bus. Make sure the message bus daemon is running?");
if (dbus_error_is_set (&error))
dbus_error_free (&error);
return (NULL);
}
......@@ -1435,6 +1441,7 @@ DBusConnection *nm_dbus_init (NMData *data)
if (dbus_error_is_set (&dbus_error))
{
syslog (LOG_ERR, "nm_dbus_init() could not acquire its service. dbus_bus_acquire_service() says: '%s'", dbus_error.message);
dbus_error_free (&error);
return (NULL);
}
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment