diff --git a/ChangeLog b/ChangeLog index bc0478d3ea..e2977378d2 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,18 @@ +2008-02-27 Dan Williams + + Patch from Will Stephenson + + * Makefile.am + configure.in + - Set up spec autogeneration infrastructure + + * docs/NetworkManager DBUS API.txt + - Note how old this doc is and where to look for the canonical + D-Bus specification + + * introspection/* + - Add annotations and comments + 2008-02-27 Dan Williams * src/nm-device-802-11-wireless.c diff --git a/Makefile.am b/Makefile.am index 59a4c1dd3d..b037bef171 100644 --- a/Makefile.am +++ b/Makefile.am @@ -1,3 +1,26 @@ +if WITH_DOCS + +all: + +XSLTPROC = xsltproc --xinclude --nonet + +XMLS = $(wildcard introspection/nm-*.xml) +# Figure out if we need ASYNC_INTROSPECT and add it later + +GENERATED_FILES = \ + docs/spec.html + +docs/spec.html: $(XMLS) introspection/all.xml introspection/generic-types.xml introspection/errors.xml introspection/vpn-errors.xml tools/doc-generator.xsl introspection/generic-types.xml + @install -d docs + $(XSLTPROC) tools/doc-generator.xsl introspection/all.xml > $@ + +all: $(GENERATED_FILES) + +clean: + rm -f $(GENERATED_FILES) + +endif + SUBDIRS = \ libnm-util \ libnm-glib \ diff --git a/configure.in b/configure.in index f300d559c7..8582f2c7e5 100644 --- a/configure.in +++ b/configure.in @@ -52,6 +52,18 @@ AC_DEFINE_UNQUOTED(GETTEXT_PACKAGE,"$GETTEXT_PACKAGE", [Gettext package]) IT_PROG_INTLTOOL([0.35.0]) AM_GLIB_GNU_GETTEXT +dnl +dnl GNOME support +dnl +AC_ARG_WITH(docs, AC_HELP_STRING([--with-docs], [Build NetworkManager documentation])) +AM_CONDITIONAL(WITH_DOCS, test "x$with_docs" = "xyes") +case $with_docs in + yes) ;; + *) + with_docs=no + ;; +esac + dnl dnl Make sha1.c happy on big endian systems dnl @@ -313,3 +325,8 @@ AC_OUTPUT echo echo Distribution targeting: ${with_distro} echo 'if this is not correct, please specifiy your distro with --with-distro=DISTRO' + +echo +echo Building documentation: ${with_docs} +echo + diff --git a/docs/NetworkManager DBUS API.txt b/docs/NetworkManager DBUS API.txt index e6fb359bfb..7a614348f3 100644 --- a/docs/NetworkManager DBUS API.txt +++ b/docs/NetworkManager DBUS API.txt @@ -1,3 +1,9 @@ +********* NOTE ********* +This document is for historical reference only. The autogenerated 'spec.html' is the canonical D-Bus reference. +********* NOTE ********* + + + NetworkManager DBUS API (unstable) ---------------------------------- diff --git a/introspection/all.xml b/introspection/all.xml new file mode 100644 index 0000000000..b65458491f --- /dev/null +++ b/introspection/all.xml @@ -0,0 +1,52 @@ + + +NetworkManager D-Bus Interface Specification +0.7.0 + + +Copyright (C) 2008 Red Hat, Inc. +Copyright (C) 2008 Novell, Inc. + + +

This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or +(at your option) any later version.

+ +

This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +General Public License for more details.

+ +

You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

+ + + + + + + + + + + + + + + + + + + + + diff --git a/introspection/errors.xml b/introspection/errors.xml new file mode 100644 index 0000000000..444b325d5e --- /dev/null +++ b/introspection/errors.xml @@ -0,0 +1,36 @@ + + + Copyright (C) 2008 Novell, Inc. + + + + Connection was not provided by any known settings service. + + + + + + Unknown device. + + + + + + Invalid settings service (not a recognized system or user settings service name). + + + + + + Connection was superseded by a system connection. + + + + + + User does not have the permission to activate this connection. + + + + diff --git a/introspection/generic-types.xml b/introspection/generic-types.xml new file mode 100644 index 0000000000..9a9cf904e8 --- /dev/null +++ b/introspection/generic-types.xml @@ -0,0 +1,47 @@ + + + A mapping from strings to variants representing extra + key-value pairs. + + + + + + A mapping from strings to strings representing extra + key-value pairs. + + + + + + A mapping from strings to a map of string to variant. + + + + + + + + Automatic mode controlled by the driver. + + + Single cell network. + + + Multi cell network, roaming. + + + Synchronisation master or Access Point. + + + Wireless Repeater (forwarder). + + + Secondary master/repeater (backup). + + + Passive monitor (listen only). + + + diff --git a/introspection/nm-access-point.xml b/introspection/nm-access-point.xml index 12e90c47c4..c82eaf9b21 100644 --- a/introspection/nm-access-point.xml +++ b/introspection/nm-access-point.xml @@ -1,20 +1,92 @@ - + - - - - - - - - - + + Flags describing the capabilities of the access point. + + + Flags describing the access point's capabilities according to WPA (Wifi Protected Access). + + + Flags describing the access point's capabilities according to the RSN (Robust Secure Network) protocol. + + + The Service Set Identifier identifying the access point. + + + The radio channel frequency in use by the access point. + + + The hardware address of the access point. + + + + Describes the operating mode of the access point. + + + The bit rate currently achievable to this access point. + + + The current signal strength received from this access point. + - + + + A dictionary mapping property names to variant boxed values + + + + + Flags describing the general capabilities of the access point. + + + Null capability - says nothing about the access point. + + + Access point supports privacy measures. + + + + + Flags describing the security capabilities of the access point. + + + Null flag. + + + Access point supports pairwise 40-bit WEP encryption. + + + Access point supports pairwise 104-bit WEP encryption. + + + Access point supports pairwise TKIP encryption. + + + Access point supports pairwise CCMP encryption. + + + Access point supports a group 40-bit WEP cypher. + + + Access point supports a group 104-bit WEP cypher. + + + Access point supports a group TKIP cypher. + + + Access point supports a group CCMP cypher. + + + Access point supports PSK key management. + + + Access point supports 802.1x key management. + + diff --git a/introspection/nm-device-802-11-wireless.xml b/introspection/nm-device-802-11-wireless.xml index d4d66fe75a..b9b2369fcc 100644 --- a/introspection/nm-device-802-11-wireless.xml +++ b/introspection/nm-device-802-11-wireless.xml @@ -1,29 +1,104 @@ - + - + + + List of access point object paths + + + + Get the list of access points visible to this device. + - - - - - + + + The hardware address of the device. + + + + + The operating mode of the wireless device. + + + + + + The bit rate currently used by the wireless device. FIXME: Why is this not called Rate like for AP? + + + + + Object path of the access point currently used by the wireless device. + + + + + The capabilities of the wireless device. + + - + + + A dictionary containing the FIXME: check changed parameters. + + + + Emitted when the wireless device's properties changed. + - + + + The object path of the newly found access point. + + + + Emitted when a new access point is found by the device. + - + + + The object path of the access point that has disappeared. + + + + Emitted when an access point disappears from view of the device. + + + + Flags describing the capabilities of a wireless device. + + + Null capability - syntactic sugar for no capabilities supported. Do not AND this with other capabilities! + + + The device supports the 40-bit WEP cypher. + + + The device supports the 104-bit WEP cypher. + + + The device supports the TKIP cypher. + + + The device supports the CCMP cypher. + + + The device supports the WPA encryption/authentication protocol. + + + The device supports the RSN encryption/authentication protocol. + + diff --git a/introspection/nm-device-802-3-ethernet.xml b/introspection/nm-device-802-3-ethernet.xml index e055a102ef..7cd23fee37 100644 --- a/introspection/nm-device-802-3-ethernet.xml +++ b/introspection/nm-device-802-3-ethernet.xml @@ -1,8 +1,16 @@ - + - - + + + Hardware address of the device. + + + + + Design speed of the device. + + diff --git a/introspection/nm-device.xml b/introspection/nm-device.xml index cf7007779c..34e0ebc00d 100644 --- a/introspection/nm-device.xml +++ b/introspection/nm-device.xml @@ -1,31 +1,140 @@ - + + + Deactivate the device, removing its routing table entry and IP address + - - - - - - - - + + + HAL UDI for the device. + + + + + The network interface offered by the device. + + + + + The driver handling the device. + + + + + Flags describing the capabilities of the device. + + + + + The IPv4 address bound to the device. FIXME: what about devices with >1 IP address? + + + + + The current state of the device. + + + + + Object path of the Ip4Config object describing the configuration of the device. + + + + + Indicates whether the physical carrier is found (e.g. the device is plugged in or associated to a network). + + - + based on dbus object path only --> + + + + + - + + + The new state of the device. + + - + + + Boolean indicating whether the carrier is now on or off. + + - + + + + The device is in an unknown state. + + + + + The device is down. + + + + + The device is not connected. + + + + + The device is preparing to connect. + + + + + The device is being configured. + + + + + The device is awaiting authorization credentials. + + + + + The IP address of the device is being configured. + + + + + The device is active. + + + + + The device is in a failure state following an attempt to activate it. + + + + + The previous activation attempt on this device was cancelled. + + + + + + Null capability. + + + The device is supported by NetworkManager. + + + The device supports carrier detection. + + diff --git a/introspection/nm-exported-connection.xml b/introspection/nm-exported-connection.xml index 5f838216fc..f2d6837359 100644 --- a/introspection/nm-exported-connection.xml +++ b/introspection/nm-exported-connection.xml @@ -1,42 +1,89 @@ - + - + + + Represents a single network connection configuration. + + + + Obtain the ID of this connection. + + + + + The ID of this connection. + + + - - - - + + + Get the settings maps describing this object. + + + + + The nested settings maps describing this object. + + + - - - - + + + Emitted when some settings changed. + + + + Contains the changed settings. + + + - - - + + + Emitted when this settings object was removed. FIXME: Is this emitted after it was removed or when it is about to be removed? If after removed, then different semantics to Device removed. if prior to removal, should be called AboutToBeRemoved. + + - - + - + + + Secrets have a separate interface so that they can be locked down. + - - + + + Get the secrets encapsulated in this object. + + + + + + Name of the setting to return. + + + + + Array of strings of key names in the Setting for which NM thinks + a secrets may be required.A + + + + + Indicates whether new secrets should be requested or if the request can be fulfilled from storage. + + - - - - - - - - - + + + Map of secrets. + + + - + diff --git a/introspection/nm-ip4-config.xml b/introspection/nm-ip4-config.xml index d887068e47..88671fe202 100644 --- a/introspection/nm-ip4-config.xml +++ b/introspection/nm-ip4-config.xml @@ -1,16 +1,34 @@ - + - - - - - - - - - + + IPv4 address. FIXME: what about multiple addresses? + + + Default gateway. + + + Network mask of this network. + + + Broadcast address of this network. + + + The hostname associated with this IPv4 address. FIXME: what about multiple hostnames? + + + The nameservers in use. + + + A list of domains this address belongs to. + + + The NIS domain this address belongs to. + + + The NIS servers associated with this address. + diff --git a/introspection/nm-manager-client.xml b/introspection/nm-manager-client.xml index 0f5f231764..aeec313025 100644 --- a/introspection/nm-manager-client.xml +++ b/introspection/nm-manager-client.xml @@ -1,10 +1,15 @@ @@ -59,6 +64,5 @@ - diff --git a/introspection/nm-manager.xml b/introspection/nm-manager.xml index ec7c800a3f..a2bb0804e8 100644 --- a/introspection/nm-manager.xml +++ b/introspection/nm-manager.xml @@ -7,72 +7,229 @@ the legacy methods at the end of this file. --> - + + + Get the list of network devices. + - + + + List of object paths of network devices known to the system. + + - - - - + + Activate a device using the supplied connection. + + + + The device to be activated. + + + + + The D-Bus service name of the settings service that provides this connection. + + + + + The connection to activate the devices with. + + + + + The path of a device-type-specific object this activation should use, for example a WiFi access point. + + + + + + + + Another connection is already activating or the same connection is already active. FIXME: check if the error name is correct. FIXME: split into 2 errors? + + + The connection is invalid for this device. + + + - + + + List of active connections + + - + + Control the NetworkManager daemon's sleep state. When asleep, all interfaces that it manages are deactivated. When awake, devices are available to be activated. + + + + Indicates whether the NetworkManager daemon should sleep or wake. + + - - - + + + Indicates if wireless is currently enabled or not. + + + + + + Indicates if the wireless hardware is currently enabled, i.e. the state of the RF kill switch. + + + + + + The overall state of the NetworkManager daemon. + + - + + NetworkManager's state changed. + + + + The new state of NetworkManager. + + - + + NetworkManager's properties changed. + + + + The changed properties. + + - + + A device was added to the system + + + + The object path of the newly added device. + + - + + A device was removed from the system, and is no longer available. + + + + The object path of the device that was just removed. + + + + + Describes the overall state of the daemon. + + + + The NetworkManager daemon is in an unknown state. + + + + + The NetworkManager daemon is asleep and all interfaces managed by it are inactive. + + + + + The NetworkManager daemon is connecting a device. FIXME: What does this mean when one device is active and another is connecting? + + + + + The NetworkManager daemon is connected. + + + + + The NetworkManager daemon is disconnected. + + + + + + + A struct representing an active connection, returned by GetActiveConnections on the NetworkManager interface. + + + + The D-Bus service name of the settings service that provides this connection. + + + + + Object path of the active connection + + + + + Object path of a device-type-specific object this connection uses, for example a specific WiFi access point. + + + + + Array of object paths to the devices this connection is active on. + + + + + + DEPRECATED. Control the NetworkManager daemon's sleep state. When asleep, all interfaces that it manages are deactivated. + + + DEPRECATED. Control the NetworkManager daemon's sleep state. When awake, all known interfaces are available to be activated. + + + DEPRECATED. The overall state of the NetworkManager daemon. + - + diff --git a/introspection/nm-settings.xml b/introspection/nm-settings.xml index 178f9acacb..34ffd80d3d 100644 --- a/introspection/nm-settings.xml +++ b/introspection/nm-settings.xml @@ -1,18 +1,33 @@ - + + + + The NetworkManagerSettings interface is held by a separate process to the daemon and provides settings to the daemon. + + + + List the connections stored by this Settings object. + + + + + List of connections. + + + - + + + Emitted when a new connection has been configured. + + + + Object path of the new connection. + + + - - - - - - - - - - + diff --git a/introspection/nm-vpn-connection.xml b/introspection/nm-vpn-connection.xml index 0fdbda091a..b899d95f13 100644 --- a/introspection/nm-vpn-connection.xml +++ b/introspection/nm-vpn-connection.xml @@ -1,19 +1,136 @@ - + + + Represents a connection to a Virtual Private Network. + + + Disconnect the VPN connection. + - - - + + The name of the VPN connection. + + + The state of the VPN connection. + + + The banner string of the VPN connection. + - - + + Emitted when the state of the VPN connection has changed. + + + + The new state of the VPN connection. + + + + + Reason code describing the change to the new state. + + + + + + The state of the VPN connection is unknown. + + + + + The VPN connection is preparing to connect. + + + + + The VPN connection needs authorization credentials. + + + + + The VPN connection is being established. FIXME: Should be CONNECTING or CONNECTED. + + + + + The VPN connection is getting an IP address. FIXME: Should be an -ING + + + + + The VPN connection is active. + + + + + The VPN connection failed. + + + + + The VPN connection is disconnected. + + + + + + + The reason for the VPN connection state change is unknown. + + + + + No reason was given for the VPN connection state change. + + + + + The VPN connection changed state because the user disconnected it. + + + + + The VPN connection changed state because the device it was using was disconnected. + + + + + The service providing the VPN connection was stopped. + + + + + The IP config of the VPN connection was invalid. + + + + + The connection attempt to the VPN service timed out. + + + + + A timeout occurred while starting the service providing the VPN connection. + + + + + Starting the service starting the service providing the VPN connection failed. + + + + + Necessary secrets for the VPN connection were not provided. + + + diff --git a/introspection/nm-vpn-manager.xml b/introspection/nm-vpn-manager.xml index 3f8d9c5d4b..57665f61a7 100644 --- a/introspection/nm-vpn-manager.xml +++ b/introspection/nm-vpn-manager.xml @@ -1,18 +1,44 @@ - + + + Establish a VPN connection. + - - - - + + + String describing the connection type. + + + + + Object path of the network connection to establish the VPN connection on. + + + + + Object path of the device to establish the VPN connection on. + + + + + Object path of the newly created VPN connection. + + + + Get the list of active VPN connections. + - + + + List of object paths of active VPN connections. + + diff --git a/introspection/nm-vpn-plugin.xml b/introspection/nm-vpn-plugin.xml index 941c9da4cb..e7647e1d6d 100644 --- a/introspection/nm-vpn-plugin.xml +++ b/introspection/nm-vpn-plugin.xml @@ -1,49 +1,132 @@ - + + + This interface is provided by plugins providing VPN services to the NetworkManager daemon. + + + Tells the plugin to connect. + - + + + Describes the connection to be established. + + + + + + + + + + + Asks the plugin whether the provided connection will require secrets to connect successfully. + - - + + + Describes the connection that may need secrets. + + + + + The setting name within the provided connection that requires secrets, if any. + + + + + + + Disconnect the plugin. + + + + + + + Set IPv4 details on the connection. + - + + + Ip4Config details for the conneciton. + + + + Indicate a failure to the plugin. + - + + + The reason for the failure. + + - + + + The state of the plugin. + + - + + Emitted when the plugin state changes. + + + + The new state of the plugin. + + - + + The plugin obtained an IPv4 configuration. + + + + The IPv4 configuration. + + - + + Emitted when the plugin receives a login banner from the VPN service. + + + + The login banner string. + + - + + Emitted when a failure in the VPN plugin occurs. + + + + Reason code for the failure. + + - diff --git a/introspection/vpn-errors.xml b/introspection/vpn-errors.xml new file mode 100644 index 0000000000..0dba7e6fb9 --- /dev/null +++ b/introspection/vpn-errors.xml @@ -0,0 +1,32 @@ + + + + This is a drab, nondescript error. + + + The request could not be processed because the VPN connection is already being started. + + + The request could not be processed because a VPN connection was already active. + + + The request could not be processed because the VPN connection is already being stopped. + + + The request could not be processed because the VPN connection was already stopped. + + + The request could not be processed because the VPN connection is in the wrong state for this type of request. FIXME: too general? + + + Invalid arguments were passed with the request. FIXME: too general. + + + A binary providing the service failed to launch. + + + The request could not be processed because the VPN connection settings were invalid. + + +