Commit 8ffe21b6 authored by Dan Williams's avatar Dan Williams

2008-02-27 Dan Williams <dcbw@redhat.com>

	Patch from Will Stephenson <wstephenson@kde.org>

	* 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



git-svn-id: http://svn-archive.gnome.org/svn/NetworkManager/trunk@3345 4912f4e0-d625-0410-9fb7-b9a5a253dbdc
parent 036e09cb
2008-02-27 Dan Williams <dcbw@redhat.com>
Patch from Will Stephenson <wstephenson@kde.org>
* 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 <dcbw@redhat.com>
* src/nm-device-802-11-wireless.c
......
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 \
......
......@@ -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
********* NOTE *********
This document is for historical reference only. The autogenerated 'spec.html' is the canonical D-Bus reference.
********* NOTE *********
NetworkManager DBUS API (unstable)
----------------------------------
......
<tp:spec
xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"
xmlns:xi="http://www.w3.org/2001/XInclude">
<tp:title>NetworkManager D-Bus Interface Specification</tp:title>
<tp:version>0.7.0</tp:version>
<tp:copyright>Copyright (C) 2008 Red Hat, Inc.</tp:copyright>
<tp:copyright>Copyright (C) 2008 Novell, Inc.</tp:copyright>
<tp:license xmlns="http://www.w3.org/1999/xhtml">
<p>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.</p>
<p>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.</p>
<p>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.</p>
</tp:license>
<xi:include href="nm-manager.xml"/>
<xi:include href="nm-access-point.xml"/>
<xi:include href="nm-device.xml"/>
<xi:include href="nm-device-802-3-ethernet.xml"/>
<xi:include href="nm-device-802-11-wireless.xml"/>
<xi:include href="nm-ip4-config.xml"/>
<xi:include href="nm-settings.xml"/>
<xi:include href="nm-exported-connection.xml"/>
<xi:include href="nm-vpn-manager.xml"/>
<xi:include href="nm-vpn-connection.xml"/>
<xi:include href="nm-vpn-plugin.xml"/>
<xi:include href="errors.xml"/>
<xi:include href="vpn-errors.xml"/>
<xi:include href="generic-types.xml"/>
<!--
<xi:include href="extensions.xml">
<xi:fallback>
<!- - absence of non-spec extensions is OK - ->
</xi:fallback>
</xi:include>
-->
</tp:spec>
<?xml version="1.0" ?>
<tp:errors xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"
namespace="org.freedesktop.NetworkManager.Error">
<tp:copyright>Copyright (C) 2008 Novell, Inc.</tp:copyright>
<tp:error name="Unknown Connection">
<tp:docstring>
Connection was not provided by any known settings service.
</tp:docstring>
</tp:error>
<tp:error name="Unknown Device">
<tp:docstring>
Unknown device.
</tp:docstring>
</tp:error>
<tp:error name="Invalid Service">
<tp:docstring>
Invalid settings service (not a recognized system or user settings service name).
</tp:docstring>
</tp:error>
<tp:error name="System Connection">
<tp:docstring>
Connection was superseded by a system connection.
</tp:docstring>
</tp:error>
<tp:error name="Permission Denied">
<tp:docstring>
User does not have the permission to activate this connection.
</tp:docstring>
</tp:error>
</tp:errors>
<tp:generic-types
xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
<tp:mapping name="String_Variant_Map">
<tp:docstring>A mapping from strings to variants representing extra
key-value pairs.</tp:docstring>
<tp:member type="s" name="Key"/>
<tp:member type="v" name="Value"/>
</tp:mapping>
<tp:mapping name="String_String_Map">
<tp:docstring>A mapping from strings to strings representing extra
key-value pairs.</tp:docstring>
<tp:member type="s" name="Key"/>
<tp:member type="s" name="Value"/>
</tp:mapping>
<tp:mapping name="String_String_Variant_Map_Map">
<tp:docstring>A mapping from strings to a map of string to variant.</tp:docstring>
<tp:member type="s" name="Key"/>
<tp:member type="a{sv}" name="Value" tp:type="String_Variant_Map"/>
</tp:mapping>
<tp:enum name="IW_MODE" type="i">
<tp:docstring></tp:docstring>
<tp:enumvalue suffix="AUTO" value="0">
<tp:docstring>Automatic mode controlled by the driver.</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="ADHOC" value="1">
<tp:docstring>Single cell network.</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="INFRA" value="2">
<tp:docstring>Multi cell network, roaming.</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="MASTER" value="3">
<tp:docstring>Synchronisation master or Access Point.</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="REPEAT" value="4">
<tp:docstring>Wireless Repeater (forwarder).</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="SECOND" value="5">
<tp:docstring>Secondary master/repeater (backup).</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="MONITOR" value="6">
<tp:docstring>Passive monitor (listen only).</tp:docstring>
</tp:enumvalue>
</tp:enum>
</tp:generic-types>
<?xml version="1.0" encoding="UTF-8" ?>
<node name="/">
<node name="/" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
<interface name="org.freedesktop.NetworkManager.AccessPoint">
<property name="Flags" type="u" access="read"/>
<property name="WpaFlags" type="u" access="read"/>
<property name="RsnFlags" type="u" access="read"/>
<property name="Ssid" type="ay" access="read"/>
<property name="Frequency" type="u" access="read"/>
<property name="HwAddress" type="s" access="read"/>
<property name="Mode" type="i" access="read"/>
<property name="Rate" type="u" access="read"/>
<property name="Strength" type="y" access="read"/>
<property name="Flags" type="u" access="read" tp:type="NM_802_11_AP_FLAGS">
<tp:docstring>Flags describing the capabilities of the access point.</tp:docstring>
</property>
<property name="WpaFlags" type="u" access="read" tp:type="NM_802_11_AP_SEC">
<tp:docstring>Flags describing the access point's capabilities according to WPA (Wifi Protected Access).</tp:docstring>
</property>
<property name="RsnFlags" type="u" access="read" tp:type="NM_802_11_AP_SEC">
<tp:docstring>Flags describing the access point's capabilities according to the RSN (Robust Secure Network) protocol.</tp:docstring>
</property>
<property name="Ssid" type="ay" access="read">
<tp:docstring>The Service Set Identifier identifying the access point.</tp:docstring>
</property>
<property name="Frequency" type="u" access="read">
<tp:docstring>The radio channel frequency in use by the access point.</tp:docstring>
</property>
<property name="HwAddress" type="s" access="read">
<tp:docstring>The hardware address of the access point.</tp:docstring>
</property>
<property name="Mode" type="i" access="read" tp:type="IW_MODE">
<tp:docstring>Describes the operating mode of the access point.</tp:docstring>
</property>
<property name="Rate" type="u" access="read">
<tp:docstring>The bit rate currently achievable to this access point.</tp:docstring>
</property>
<property name="Strength" type="y" access="read">
<tp:docstring>The current signal strength received from this access point.</tp:docstring>
</property>
<signal name="PropertiesChanged">
<arg name="properties" type="a{sv}"/>
<arg name="properties" type="a{sv}" tp:type="String_Variant_Map">
<tp:docstring>
A dictionary mapping property names to variant boxed values
</tp:docstring>
</arg>
</signal>
<tp:flags name="NM_802_11_AP_FLAGS" value-prefix="NM_802_11_AP_FLAGS" type="u">
<tp:docstring>
Flags describing the general capabilities of the access point.
</tp:docstring>
<tp:flag suffix="NONE" value="0x0">
<tp:docstring>Null capability - says nothing about the access point.</tp:docstring>
</tp:flag>
<tp:flag suffix="PRIVACY" value="0x1">
<tp:docstring>Access point supports privacy measures.</tp:docstring>
</tp:flag>
</tp:flags>
<tp:flags name="NM_802_11_AP_SEC" value-prefix="NM_802_11_AP_SEC" type="u">
<tp:docstring>
Flags describing the security capabilities of the access point.
</tp:docstring>
<tp:flag suffix="NONE" value="0x0">
<tp:docstring>Null flag.</tp:docstring>
</tp:flag>
<tp:flag suffix="PAIR_WEP40" value="0x1">
<tp:docstring>Access point supports pairwise 40-bit WEP encryption.</tp:docstring>
</tp:flag>
<tp:flag suffix="PAIR_WEP104" value="0x2">
<tp:docstring>Access point supports pairwise 104-bit WEP encryption.</tp:docstring>
</tp:flag>
<tp:flag suffix="PAIR_TKIP" value="0x4">
<tp:docstring>Access point supports pairwise TKIP encryption.</tp:docstring>
</tp:flag>
<tp:flag suffix="PAIR_CCMP" value="0x8">
<tp:docstring>Access point supports pairwise CCMP encryption.</tp:docstring>
</tp:flag>
<tp:flag suffix="GROUP_WEP40" value="0x10">
<tp:docstring>Access point supports a group 40-bit WEP cypher.</tp:docstring>
</tp:flag>
<tp:flag suffix="GROUP_WEP104" value="0x20">
<tp:docstring>Access point supports a group 104-bit WEP cypher.</tp:docstring>
</tp:flag>
<tp:flag suffix="GROUP_TKIP" value="0x40">
<tp:docstring>Access point supports a group TKIP cypher.</tp:docstring>
</tp:flag>
<tp:flag suffix="GROUP_CCMP" value="0x80">
<tp:docstring>Access point supports a group CCMP cypher.</tp:docstring>
</tp:flag>
<tp:flag suffix="KEY_MGMT_PSK" value="0x100">
<tp:docstring>Access point supports PSK key management.</tp:docstring>
</tp:flag>
<tp:flag suffix="KEY_MGMT_802_1X" value="0x200">
<tp:docstring>Access point supports 802.1x key management.</tp:docstring>
</tp:flag>
</tp:flags>
</interface>
</node>
<?xml version="1.0" encoding="UTF-8" ?>
<node name="/">
<node name="/" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
<interface name="org.freedesktop.NetworkManager.Device.Wireless">
<method name="GetAccessPoints">
<annotation name="org.freedesktop.DBus.GLib.CSymbol" value="impl_device_get_access_points"/>
<arg name="access_points" type="ao" direction="out"/>
<arg name="access_points" type="ao" direction="out">
<tp:docstring>
List of access point object paths
</tp:docstring>
</arg>
<tp:docstring>
Get the list of access points visible to this device.
</tp:docstring>
</method>
<property name="HwAddress" type="s" access="read"/>
<property name="Mode" type="i" access="read"/>
<property name="Bitrate" type="u" access="read"/>
<property name="ActiveAccessPoint" type="o" access="read"/>
<property name="WirelessCapabilities" type="u" access="read"/>
<property name="HwAddress" type="s" access="read">
<tp:docstring>
The hardware address of the device.
</tp:docstring>
</property>
<property name="Mode" type="i" access="read" tp:type="IW_MODE">
<tp:docstring>
The operating mode of the wireless device.
</tp:docstring>
</property>
<property name="Bitrate" type="u" access="read">
<tp:docstring>
The bit rate currently used by the wireless device. FIXME: Why is this not called Rate like for AP?
</tp:docstring>
</property>
<property name="ActiveAccessPoint" type="o" access="read">
<tp:docstring>
Object path of the access point currently used by the wireless device.
</tp:docstring>
</property>
<property name="WirelessCapabilities" type="u" access="read" tp:type="NM_802_11_DEVICE_CAP">
<tp:docstring>
The capabilities of the wireless device.
</tp:docstring>
</property>
<signal name="PropertiesChanged">
<arg name="properties" type="a{sv}"/>
<arg name="properties" type="a{sv}" tp:type="String_Variant_Map">
<tp:docstring>
A dictionary containing the FIXME: check changed parameters.
</tp:docstring>
</arg>
<tp:docstring>
Emitted when the wireless device's properties changed.
</tp:docstring>
</signal>
<signal name="AccessPointAdded">
<arg name="access_point" type="o"/>
<arg name="access_point" type="o">
<tp:docstring>
The object path of the newly found access point.
</tp:docstring>
</arg>
<tp:docstring>
Emitted when a new access point is found by the device.
</tp:docstring>
</signal>
<signal name="AccessPointRemoved">
<arg name="access_point" type="o"/>
<arg name="access_point" type="o">
<tp:docstring>
The object path of the access point that has disappeared.
</tp:docstring>
</arg>
<tp:docstring>
Emitted when an access point disappears from view of the device.
</tp:docstring>
</signal>
<tp:flags name="NM_802_11_DEVICE_CAP" type="u">
<tp:docstring>
Flags describing the capabilities of a wireless device.
</tp:docstring>
<tp:flag suffix="NONE" value="0x0">
<tp:docstring>Null capability - syntactic sugar for no capabilities supported. Do not AND this with other capabilities!</tp:docstring>
</tp:flag>
<tp:flag suffix="CIPHER_WEP40" value="0x1">
<tp:docstring>The device supports the 40-bit WEP cypher.</tp:docstring>
</tp:flag>
<tp:flag suffix="CIPHER_WEP104" value="0x2">
<tp:docstring>The device supports the 104-bit WEP cypher.</tp:docstring>
</tp:flag>
<tp:flag suffix="CIPHER_TKIP" value="0x4">
<tp:docstring>The device supports the TKIP cypher.</tp:docstring>
</tp:flag>
<tp:flag suffix="CIPHER_CCMP" value="0x8">
<tp:docstring>The device supports the CCMP cypher.</tp:docstring>
</tp:flag>
<tp:flag suffix="WPA" value="0x10">
<tp:docstring>The device supports the WPA encryption/authentication protocol.</tp:docstring>
</tp:flag>
<tp:flag suffix="RSN" value="0x20">
<tp:docstring>The device supports the RSN encryption/authentication protocol.</tp:docstring>
</tp:flag>
</tp:flags>
</interface>
</node>
<?xml version="1.0" encoding="UTF-8" ?>
<node name="/">
<node name="/" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
<interface name="org.freedesktop.NetworkManager.Device.Wired">
<property name="HwAddress" type="s" access="read"/>
<property name="Speed" type="u" access="read"/>
<property name="HwAddress" type="s" access="read">
<tp:docstring>
Hardware address of the device.
</tp:docstring>
</property>
<property name="Speed" type="u" access="read">
<tp:docstring>
Design speed of the device.
</tp:docstring>
</property>
</interface>
</node>
<?xml version="1.0" encoding="UTF-8" ?>
<node name="/">
<node name="/" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
<interface name="org.freedesktop.NetworkManager.Device">
<method name="Deactivate">
<annotation name="org.freedesktop.DBus.GLib.CSymbol" value="impl_device_deactivate"/>
<tp:docstring>
Deactivate the device, removing its routing table entry and IP address
</tp:docstring>
</method>
<property name="Udi" type="s" access="read"/>
<property name="Interface" type="s" access="read"/>
<property name="Driver" type="s" access="read"/>
<property name="Capabilities" type="u" access="read"/>
<property name="Ip4Address" type="i" access="read"/>
<property name="State" type="u" access="read"/>
<property name="Ip4Config" type="o" access="read"/>
<property name="Carrier" type="b" access="read"/>
<property name="Udi" type="s" access="read">
<tp:docstring>
HAL UDI for the device.
</tp:docstring>
</property>
<property name="Interface" type="s" access="read">
<tp:docstring>
The network interface offered by the device.
</tp:docstring>
</property>
<property name="Driver" type="s" access="read">
<tp:docstring>
The driver handling the device.
</tp:docstring>
</property>
<property name="Capabilities" type="u" access="read" tp:type="NM_DEVICE_CAP">
<tp:docstring>
Flags describing the capabilities of the device.
</tp:docstring>
</property>
<property name="Ip4Address" type="i" access="read">
<tp:docstring>
The IPv4 address bound to the device. FIXME: what about devices with >1 IP address?
</tp:docstring>
</property>
<property name="State" type="u" access="read" tp:type="NM_DEVICE_STATE">
<tp:docstring>
The current state of the device.
</tp:docstring>
</property>
<property name="Ip4Config" type="o" access="read">
<tp:docstring>
Object path of the Ip4Config object describing the configuration of the device.
</tp:docstring>
</property>
<property name="Carrier" type="b" access="read">
<tp:docstring>
Indicates whether the physical carrier is found (e.g. the device is plugged in or associated to a network).
</tp:docstring>
</property>
<!-- Ugh, but I see no other way of getting the type on the caller
based on dbus object path only -->
<property name="DeviceType" type="u" access="read"/>
based on dbus object path only -->
<property name="DeviceType" type="u" access="read">
<tp:docstring>
</tp:docstring>
</property>
<signal name="StateChanged">
<arg name="state" type="u"/>
<arg name="state" type="u" tp:type="NM_DEVICE_STATE">
<tp:docstring>
The new state of the device.
</tp:docstring>
</arg>
</signal>
<signal name="CarrierChanged">
<arg name="carrier_on" type="b"/>
<arg name="carrier_on" type="b">
<tp:docstring>
Boolean indicating whether the carrier is now on or off.
</tp:docstring>
</arg>
</signal>
<tp:enum name="NM_DEVICE_STATE" type="u">
<tp:enumvalue suffix="UNKNOWN" value="0">
<tp:docstring>
The device is in an unknown state.
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="DOWN" value="1">
<tp:docstring>
The device is down.
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="DISCONNECTED" value="2">
<tp:docstring>
The device is not connected.
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="PREPARE" value="3">
<tp:docstring>
The device is preparing to connect.
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="CONFIG" value="4">
<tp:docstring>
The device is being configured.
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="NEED_AUTH" value="5">
<tp:docstring>
The device is awaiting authorization credentials.
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="IP_CONFIG" value="6">
<tp:docstring>
The IP address of the device is being configured.
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="ACTIVATED" value="7">
<tp:docstring>
The device is active.
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="FAILED" value="8">
<tp:docstring>
The device is in a failure state following an attempt to activate it.
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="CANCELLED" value="9">
<tp:docstring>
The previous activation attempt on this device was cancelled.
</tp:docstring>
</tp:enumvalue>
</tp:enum>
<tp:flags name="NM_DEVICE_CAP" value-prefix="NM_DEVICE_CAP" type="u">
<tp:flag suffix="NONE" value="0x0">
<tp:docstring>Null capability.</tp:docstring>
</tp:flag>
<tp:flag suffix="NM_SUPPORTED" value="0x1">
<tp:docstring>The device is supported by NetworkManager.</tp:docstring>
</tp:flag>
<tp:flag suffix="CARRIER_DETECT" value="0x2">
<tp:docstring>The device supports carrier detection.</tp:docstring>
</tp:flag>
</tp:flags>
</interface>
</node>
<?xml version="1.0" encoding="UTF-8" ?>
<node name="/">
<node name="/" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
<interface name="org.freedesktop.NetworkManagerSettings.Connection">
<interface name="org.freedesktop.NetworkManagerSettings.Connection">
<tp:docstring>
Represents a single network connection configuration.
</tp:docstring>
<method name="GetID">
<tp:docstring>
Obtain the ID of this connection.
</tp:docstring>
<annotation name="org.freedesktop.DBus.GLib.CSymbol" value="impl_exported_connection_get_id"/>
<arg name="id" type="s" direction="out">
<tp:docstring>
The ID of this connection.
</tp:docstring>
</arg>
</method>
<method name="GetID">
<annotation name="org.freedesktop.DBus.GLib.CSymbol" value="impl_exported_connection_get_id"/>
<arg name="id" type="s" direction="out"/>
</method>
<method name="GetSettings">
<tp:docstring>