From f88dd66e6d8afd952e286b9aa5f48c4f70141fed Mon Sep 17 00:00:00 2001 From: Lubomir Rintel Date: Sat, 26 Mar 2016 10:16:28 +0100 Subject: [PATCH 1/6] introspection: build docbook when generating the code --- .gitignore | 1 + introspection/Makefile.am | 43 ++++++++++++++++++++++++++++++++++++++- 2 files changed, 43 insertions(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index 0cd4e28d6e..7a880bba25 100644 --- a/.gitignore +++ b/.gitignore @@ -142,6 +142,7 @@ test-*.trs /introspection/all.xml /introspection/nmdbus-*.c /introspection/nmdbus-*.h +/introspection/nmdbus-*.xml /libgsystem/ diff --git a/introspection/Makefile.am b/introspection/Makefile.am index 735921d373..4d2e129834 100644 --- a/introspection/Makefile.am +++ b/introspection/Makefile.am @@ -78,21 +78,62 @@ nodist_libnmdbus_la_SOURCES = \ nmdbus-vpn-plugin.c \ nmdbus-vpn-plugin.h +DBUS_INTERFACE_DOCS = \ + nmdbus-access-point-org.freedesktop.NetworkManager.AccessPoint.xml \ + nmdbus-active-connection-org.freedesktop.NetworkManager.Connection.Active.xml \ + nmdbus-device-team-org.freedesktop.NetworkManager.Device.Team.xml \ + nmdbus-dhcp6-config-org.freedesktop.NetworkManager.DHCP6Config.xml \ + nmdbus-device-wifi-org.freedesktop.NetworkManager.Device.Wireless.xml \ + nmdbus-manager-org.freedesktop.NetworkManager.xml \ + nmdbus-vpn-connection-org.freedesktop.NetworkManager.VPN.Connection.xml \ + nmdbus-secret-agent-org.freedesktop.NetworkManager.SecretAgent.xml \ + nmdbus-device-org.freedesktop.NetworkManager.Device.xml \ + nmdbus-vpn-plugin-org.freedesktop.NetworkManager.VPN.Plugin.xml \ + nmdbus-device-bt-org.freedesktop.NetworkManager.Device.Bluetooth.xml \ + nmdbus-device-vxlan-org.freedesktop.NetworkManager.Device.Vxlan.xml \ + nmdbus-settings-connection-org.freedesktop.NetworkManager.Settings.Connection.xml \ + nmdbus-device-bond-org.freedesktop.NetworkManager.Device.Bond.xml \ + nmdbus-device-macvlan-org.freedesktop.NetworkManager.Device.Macvlan.xml \ + nmdbus-ppp-manager-org.freedesktop.NetworkManager.PPP.xml \ + nmdbus-device-vlan-org.freedesktop.NetworkManager.Device.Vlan.xml \ + nmdbus-device-adsl-org.freedesktop.NetworkManager.Device.Adsl.xml \ + nmdbus-agent-manager-org.freedesktop.NetworkManager.AgentManager.xml \ + nmdbus-device-wimax-org.freedesktop.NetworkManager.Device.WiMax.xml \ + nmdbus-device-ip-tunnel-org.freedesktop.NetworkManager.Device.IPTunnel.xml \ + nmdbus-device-tun-org.freedesktop.NetworkManager.Device.Tun.xml \ + nmdbus-device-bridge-org.freedesktop.NetworkManager.Device.Bridge.xml \ + nmdbus-device-olpc-mesh-org.freedesktop.NetworkManager.Device.OlpcMesh.xml \ + nmdbus-dhcp4-config-org.freedesktop.NetworkManager.DHCP4Config.xml \ + nmdbus-device-generic-org.freedesktop.NetworkManager.Device.Generic.xml \ + nmdbus-device-infiniband-org.freedesktop.NetworkManager.Device.Infiniband.xml \ + nmdbus-device-modem-org.freedesktop.NetworkManager.Device.Modem.xml \ + nmdbus-ip6-config-org.freedesktop.NetworkManager.IP6Config.xml \ + nmdbus-device-veth-org.freedesktop.NetworkManager.Device.Veth.xml \ + nmdbus-settings-org.freedesktop.NetworkManager.Settings.xml \ + nmdbus-device-ethernet-org.freedesktop.NetworkManager.Device.Wired.xml \ + nmdbus-ip4-config-org.freedesktop.NetworkManager.IP4Config.xml + define _make_nmdbus_rule $(1): $(patsubst nmdbus-%.c,nm-%.xml,$(1)) $$(AM_V_GEN) gdbus-codegen \ --generate-c-code $$(basename $$@) \ + --generate-docbook $$(basename $$@) \ --c-namespace NMDBus \ --interface-prefix org.freedesktop.NetworkManager \ $$< +$(filter $(basename $(1))-org.freedesktop.NetworkManager.%,$(DBUS_INTERFACE_DOCS)): $(1) + @true + $(basename $(1)).h: $(1) @true endef $(foreach f,$(filter %.c,$(nodist_libnmdbus_la_SOURCES)),$(eval $(call _make_nmdbus_rule,$f))) -CLEANFILES = $(nodist_libnmdbus_la_SOURCES) +BUILT_SOURCES = $(nodist_libnmdbus_la_SOURCES) $(DBUS_INTERFACE_DOCS) + +CLEANFILES = $(BUILT_SOURCES) EXTRA_DIST = \ all.xml.in \ From 618373a14fd6993bd4317bed01dc48506f6f7d98 Mon Sep 17 00:00:00 2001 From: Lubomir Rintel Date: Thu, 24 Mar 2016 14:36:14 +0100 Subject: [PATCH 2/6] dbus: use the annotations for documentation gdbus only understands those (and gtk docstrings, which we should eventually use) when generating the documentation. --- callouts/nm-dispatcher.xml | 54 +- introspection/errors.xml | 12 +- introspection/generic-types.xml | 26 +- introspection/nm-access-point.xml | 60 +- introspection/nm-active-connection.xml | 90 +-- introspection/nm-agent-manager.xml | 26 +- introspection/nm-device-adsl.xml | 8 +- introspection/nm-device-bond.xml | 16 +- introspection/nm-device-bridge.xml | 16 +- introspection/nm-device-bt.xml | 26 +- introspection/nm-device-ethernet.xml | 24 +- introspection/nm-device-generic.xml | 12 +- introspection/nm-device-infiniband.xml | 12 +- introspection/nm-device-ip-tunnel.xml | 48 +- introspection/nm-device-macvlan.xml | 22 +- introspection/nm-device-modem.xml | 34 +- introspection/nm-device-olpc-mesh.xml | 20 +- introspection/nm-device-team.xml | 16 +- introspection/nm-device-tun.xml | 40 +- introspection/nm-device-veth.xml | 8 +- introspection/nm-device-vlan.xml | 20 +- introspection/nm-device-vxlan.xml | 72 +-- introspection/nm-device-wifi.xml | 112 ++-- introspection/nm-device-wimax.xml | 64 +- introspection/nm-device.xml | 556 +++++++++--------- introspection/nm-dhcp4-config.xml | 10 +- introspection/nm-dhcp6-config.xml | 10 +- introspection/nm-ip4-config.xml | 42 +- introspection/nm-ip6-config.xml | 42 +- introspection/nm-manager.xml | 354 +++++------ introspection/nm-secret-agent.xml | 122 ++-- introspection/nm-settings-connection.xml | 70 +-- introspection/nm-settings.xml | 118 ++-- introspection/nm-vpn-connection.xml | 104 ++-- introspection/nm-vpn-plugin.xml | 184 +++--- introspection/nm-wimax-nsp.xml | 22 +- introspection/vpn-errors.xml | 38 +- src/settings/plugins/ifcfg-rh/nm-ifcfg-rh.xml | 20 +- 38 files changed, 1265 insertions(+), 1265 deletions(-) diff --git a/callouts/nm-dispatcher.xml b/callouts/nm-dispatcher.xml index b2c4a21aec..e2e89a89ad 100644 --- a/callouts/nm-dispatcher.xml +++ b/callouts/nm-dispatcher.xml @@ -5,87 +5,87 @@ - + - + - + - + - + - + - + - + - + - VPN interface name. + - + - + - + - + diff --git a/introspection/errors.xml b/introspection/errors.xml index f2db86679f..34a0a7b96f 100644 --- a/introspection/errors.xml +++ b/introspection/errors.xml @@ -4,21 +4,21 @@ Copyright (C) 2008 Novell, Inc. - + - + - + diff --git a/introspection/generic-types.xml b/introspection/generic-types.xml index 681b6662b7..2fb680af92 100644 --- a/introspection/generic-types.xml +++ b/introspection/generic-types.xml @@ -1,50 +1,50 @@ - 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. + - + - Mode is unknown. + - + - + - + diff --git a/introspection/nm-access-point.xml b/introspection/nm-access-point.xml index 16eae04476..603be7132e 100644 --- a/introspection/nm-access-point.xml +++ b/introspection/nm-access-point.xml @@ -3,99 +3,99 @@ - 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, in MHz. + - The hardware address (BSSID) of the access point. + - Describes the operating mode of the access point. + - The maximum bitrate this access point is capable of, in kilobits/second (Kb/s). + - The current signal quality of the access point, in percent. + - + - + - + - Null capability - says nothing about the access point. + - Access point supports privacy measures. + - + - 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 cipher. + - Access point supports a group 104-bit WEP cipher. + - Access point supports a group TKIP cipher. + - Access point supports a group CCMP cipher. + - Access point supports PSK key management. + - Access point supports 802.1x key management. + diff --git a/introspection/nm-active-connection.xml b/introspection/nm-active-connection.xml index 203437b7cc..59bf78f4d0 100644 --- a/introspection/nm-active-connection.xml +++ b/introspection/nm-active-connection.xml @@ -3,12 +3,12 @@ - + + " /> - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + diff --git a/introspection/nm-agent-manager.xml b/introspection/nm-agent-manager.xml index 4b53675cfd..52460eeeec 100644 --- a/introspection/nm-agent-manager.xml +++ b/introspection/nm-agent-manager.xml @@ -4,45 +4,45 @@ - + - + + " /> - + - + - + - + diff --git a/introspection/nm-device-adsl.xml b/introspection/nm-device-adsl.xml index ec50d11044..68859d3bea 100644 --- a/introspection/nm-device-adsl.xml +++ b/introspection/nm-device-adsl.xml @@ -5,16 +5,16 @@ - + - + diff --git a/introspection/nm-device-bond.xml b/introspection/nm-device-bond.xml index a804ca0b68..9bc21225a3 100644 --- a/introspection/nm-device-bond.xml +++ b/introspection/nm-device-bond.xml @@ -4,29 +4,29 @@ - + - + - + - + diff --git a/introspection/nm-device-bridge.xml b/introspection/nm-device-bridge.xml index f3b25602f0..6cf99a10c2 100644 --- a/introspection/nm-device-bridge.xml +++ b/introspection/nm-device-bridge.xml @@ -4,29 +4,29 @@ - + - + - + - + diff --git a/introspection/nm-device-bt.xml b/introspection/nm-device-bt.xml index cc4a9b544a..3b487158e8 100644 --- a/introspection/nm-device-bt.xml +++ b/introspection/nm-device-bt.xml @@ -4,43 +4,43 @@ - + - + - + - + - + - The device has no recognized capabilities. + - The device supports Bluetooth Dial-Up Networking. + - The device supports Bluetooth Personal Area Networking. + diff --git a/introspection/nm-device-ethernet.xml b/introspection/nm-device-ethernet.xml index 86d68a35ab..87b7f755d6 100644 --- a/introspection/nm-device-ethernet.xml +++ b/introspection/nm-device-ethernet.xml @@ -5,40 +5,40 @@ - + - + - + - + - + - + diff --git a/introspection/nm-device-generic.xml b/introspection/nm-device-generic.xml index 79d1989968..2f8fc7eead 100644 --- a/introspection/nm-device-generic.xml +++ b/introspection/nm-device-generic.xml @@ -4,22 +4,22 @@ - + - + - + diff --git a/introspection/nm-device-infiniband.xml b/introspection/nm-device-infiniband.xml index 097714c69f..169c2c66cc 100644 --- a/introspection/nm-device-infiniband.xml +++ b/introspection/nm-device-infiniband.xml @@ -4,22 +4,22 @@ - + - + - + diff --git a/introspection/nm-device-ip-tunnel.xml b/introspection/nm-device-ip-tunnel.xml index fcb42ce275..3ca04ee66c 100644 --- a/introspection/nm-device-ip-tunnel.xml +++ b/introspection/nm-device-ip-tunnel.xml @@ -4,81 +4,81 @@ - + - + - + - + - + - + - + - + - + - + - + - + diff --git a/introspection/nm-device-macvlan.xml b/introspection/nm-device-macvlan.xml index c4dcb4e602..d5d66068df 100644 --- a/introspection/nm-device-macvlan.xml +++ b/introspection/nm-device-macvlan.xml @@ -4,34 +4,34 @@ - + - - The macvlan mode, one of "private", "vepa", "bridge", or "passthru". - + - + - + - + diff --git a/introspection/nm-device-modem.xml b/introspection/nm-device-modem.xml index 0ca101fd74..67742c463d 100644 --- a/introspection/nm-device-modem.xml +++ b/introspection/nm-device-modem.xml @@ -5,58 +5,58 @@ - + - + - + - + - Modem has no capabilties. + - + - + - + - + diff --git a/introspection/nm-device-olpc-mesh.xml b/introspection/nm-device-olpc-mesh.xml index c30ecfc602..a92e73709a 100644 --- a/introspection/nm-device-olpc-mesh.xml +++ b/introspection/nm-device-olpc-mesh.xml @@ -3,32 +3,32 @@ - + - + - + - + - + diff --git a/introspection/nm-device-team.xml b/introspection/nm-device-team.xml index baf39fa860..982b767018 100644 --- a/introspection/nm-device-team.xml +++ b/introspection/nm-device-team.xml @@ -4,29 +4,29 @@ - + - + - + - + diff --git a/introspection/nm-device-tun.xml b/introspection/nm-device-tun.xml index 2b3ae2f521..0f74cf8c41 100644 --- a/introspection/nm-device-tun.xml +++ b/introspection/nm-device-tun.xml @@ -4,56 +4,56 @@ - + - + - - The tunnel mode, either "tun" or "tap". - + - - The tunnel's "TUN_NO_PI" flag; true if no protocol info is + - - The tunnel's "TUN_VNET_HDR" flag; true if the tunnel packets + - - The tunnel's "TUN_TAP_MQ" flag; true if callers can connect to + - + - + diff --git a/introspection/nm-device-veth.xml b/introspection/nm-device-veth.xml index e06d0ceb7d..a3cff6da08 100644 --- a/introspection/nm-device-veth.xml +++ b/introspection/nm-device-veth.xml @@ -4,16 +4,16 @@ - + - + diff --git a/introspection/nm-device-vlan.xml b/introspection/nm-device-vlan.xml index 992340e009..bac220e899 100644 --- a/introspection/nm-device-vlan.xml +++ b/introspection/nm-device-vlan.xml @@ -4,34 +4,34 @@ - + - + - + - + - + diff --git a/introspection/nm-device-vxlan.xml b/introspection/nm-device-vxlan.xml index 97c517fb7e..de23020d5b 100644 --- a/introspection/nm-device-vxlan.xml +++ b/introspection/nm-device-vxlan.xml @@ -4,123 +4,123 @@ - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + diff --git a/introspection/nm-device-wifi.xml b/introspection/nm-device-wifi.xml index 27f3eb9066..2ece0ef0ae 100644 --- a/introspection/nm-device-wifi.xml +++ b/introspection/nm-device-wifi.xml @@ -6,164 +6,164 @@ - + - + - + - + - + + Currently 'ssids' option with value of "aay" type is supported. + " /> - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - Null capability - syntactic sugar for no capabilities supported. Do not AND this with other capabilities! + - The device supports the 40-bit WEP cipher. + - The device supports the 104-bit WEP cipher. + - The device supports the TKIP cipher. + - The device supports the CCMP cipher. + - The device supports the WPA encryption/authentication protocol. + - The device supports the RSN encryption/authentication protocol. + - The device supports Access Point mode. + - The device supports Ad-Hoc mode. + - + - + - + diff --git a/introspection/nm-device-wimax.xml b/introspection/nm-device-wimax.xml index 3bad624530..e790e4fc62 100644 --- a/introspection/nm-device-wimax.xml +++ b/introspection/nm-device-wimax.xml @@ -4,105 +4,105 @@ - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + diff --git a/introspection/nm-device.xml b/introspection/nm-device.xml index f1033c73f2..321cace13b 100644 --- a/introspection/nm-device.xml +++ b/introspection/nm-device.xml @@ -3,7 +3,7 @@ - + - + - + - + - + - + - + - + - + - + - - Object path of an ActiveConnection object that "owns" this device during + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - Unused + - Unused + - + - + - + - + - + - + - + - + - + - + - + - Null capability. + - The device is supported by NetworkManager. + - The device supports carrier detection. + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + diff --git a/introspection/nm-dhcp4-config.xml b/introspection/nm-dhcp4-config.xml index 379c50f9b0..bca34fc53f 100644 --- a/introspection/nm-dhcp4-config.xml +++ b/introspection/nm-dhcp4-config.xml @@ -3,18 +3,18 @@ - + - Configuration options returned by a DHCP server, if any. + - + diff --git a/introspection/nm-dhcp6-config.xml b/introspection/nm-dhcp6-config.xml index df75660a70..84e13b77b1 100644 --- a/introspection/nm-dhcp6-config.xml +++ b/introspection/nm-dhcp6-config.xml @@ -3,18 +3,18 @@ - + - Configuration options returned by a DHCP server, if any. + - + diff --git a/introspection/nm-ip4-config.xml b/introspection/nm-ip4-config.xml index 5a9e8ea1c3..111e1acf78 100644 --- a/introspection/nm-ip4-config.xml +++ b/introspection/nm-ip4-config.xml @@ -3,26 +3,26 @@ - + - + + " /> - The gateway in use. + - + - - Array of IP route data objects. All routes will include "dest" - (an IP address string) and "prefix" (a uint). Some routes may - include "next-hop" (an IP address string), "metric" (a uint), + - The nameservers in use. + - A list of domains this address belongs to. + - A list of dns searches. + - + - The Windows Internet Name Service servers associated with the connection. Each address is in network byte order. + - + diff --git a/introspection/nm-ip6-config.xml b/introspection/nm-ip6-config.xml index 1a107bf29f..0cca33c4f9 100644 --- a/introspection/nm-ip6-config.xml +++ b/introspection/nm-ip6-config.xml @@ -3,63 +3,63 @@ - + - + + " /> - The gateway in use. + - + - - Array of IP route data objects. All routes will include "dest" - (an IP address string) and "prefix" (a uint). Some routes may - include "next-hop" (an IP address string), "metric" (a uint), + - The nameservers in use. + - A list of domains this address belongs to. + - A list of dns searches. + - + - + diff --git a/introspection/nm-manager.xml b/introspection/nm-manager.xml index dd6fc4bdd1..8203020b39 100644 --- a/introspection/nm-manager.xml +++ b/introspection/nm-manager.xml @@ -5,213 +5,213 @@ - + - + - + - + - + - + - + - + - - The connection to activate. If "/" is given, a valid device path must + - + - + + "base" connection (to which the VPN connections lifetime will be tied), + or pass "/" and NM will automatically use the current default device. + " /> - + - + - + - + - + + " /> - + - + - + - + - + - + - + - + - + - + + " /> - + - + - + + " /> - - A combination of logging domains separated by commas (','), or "NONE" + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - - The object path of the "primary" active connection being used + - - The connection type of the "primary" active connection being + - + - + - + - + - + - + - + - + - + + third-level dictionary with the keys "servers" and + "options". "servers" is a string array of DNS servers, + "options" is a string array of domain-specific options. + " /> - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + diff --git a/introspection/nm-secret-agent.xml b/introspection/nm-secret-agent.xml index 337d0a7fa8..ec7ede0912 100644 --- a/introspection/nm-secret-agent.xml +++ b/introspection/nm-secret-agent.xml @@ -3,20 +3,20 @@ - + + " /> - + - + - + - + - + + "x-vpn-message:". + " /> - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - No special capabilities. + - + diff --git a/introspection/nm-settings-connection.xml b/introspection/nm-settings-connection.xml index 2d919619fd..fc62046c80 100644 --- a/introspection/nm-settings-connection.xml +++ b/introspection/nm-settings-connection.xml @@ -3,27 +3,27 @@ - + - + - + - + - + - + - + - + - + - + - + - + - - Saves a "dirty" connection (that had previously been + - + - + - + - + diff --git a/introspection/nm-settings.xml b/introspection/nm-settings.xml index b6ab8260ea..6289202511 100644 --- a/introspection/nm-settings.xml +++ b/introspection/nm-settings.xml @@ -2,58 +2,58 @@ - + - + - + - + - + - + - + - + - + - + - + - + - + + " /> - + - + - + - + + "monitor-connection-files=false" in NetworkManager.conf. + " /> - + - + - + - + - + - + - + - + - + - + - + diff --git a/introspection/nm-vpn-connection.xml b/introspection/nm-vpn-connection.xml index 03bbbe980f..6a4fb37db4 100644 --- a/introspection/nm-vpn-connection.xml +++ b/introspection/nm-vpn-connection.xml @@ -4,143 +4,143 @@ - + - + - The VPN-specific state of the connection. + - The banner string of the VPN connection. + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + diff --git a/introspection/nm-vpn-plugin.xml b/introspection/nm-vpn-plugin.xml index adb6a08526..ee8c69f8bf 100644 --- a/introspection/nm-vpn-plugin.xml +++ b/introspection/nm-vpn-plugin.xml @@ -4,20 +4,20 @@ - + - + - + @@ -30,22 +30,22 @@ - + - + - + @@ -59,19 +59,19 @@ - + - + - + @@ -79,9 +79,9 @@ - + @@ -90,105 +90,105 @@ - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + @@ -199,113 +199,113 @@ - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + diff --git a/introspection/nm-wimax-nsp.xml b/introspection/nm-wimax-nsp.xml index 55ac4abcf2..6174ad6738 100644 --- a/introspection/nm-wimax-nsp.xml +++ b/introspection/nm-wimax-nsp.xml @@ -4,38 +4,38 @@ - The name of the NSP. + - The current signal quality of the NSP, in percent. + - The network type of the NSP. + - + - + - Unknown network. + - Home network. + - Partner network. + - Roaming partner network. + diff --git a/introspection/vpn-errors.xml b/introspection/vpn-errors.xml index 7b92d07366..c1e02aacb2 100644 --- a/introspection/vpn-errors.xml +++ b/introspection/vpn-errors.xml @@ -2,59 +2,59 @@ - General failure without further details. + - + - + - + - + - + - + - + - + - + diff --git a/src/settings/plugins/ifcfg-rh/nm-ifcfg-rh.xml b/src/settings/plugins/ifcfg-rh/nm-ifcfg-rh.xml index 1f308dd48a..c2a6cb34ea 100644 --- a/src/settings/plugins/ifcfg-rh/nm-ifcfg-rh.xml +++ b/src/settings/plugins/ifcfg-rh/nm-ifcfg-rh.xml @@ -2,28 +2,28 @@ - + - + - + - + - + From 3a2803b42c1547337d25767baa1028b047893589 Mon Sep 17 00:00:00 2001 From: Lubomir Rintel Date: Sat, 26 Mar 2016 10:17:34 +0100 Subject: [PATCH 3/6] docs: replace spec.html with docbook D-Bus API reference May use a lot of improvement (actually documenting the names and objects that use the interfaces in question), but at least this looks a lot better on developer.gnome.org. --- .gitignore | 1 - docs/api/Makefile.am | 51 +- docs/api/network-manager-docs.xml | 46 +- examples/python/dbus/create-bond.py | 2 +- tools/Makefile.am | 1 - tools/doc-generator.xsl | 691 ---------------------------- 6 files changed, 80 insertions(+), 712 deletions(-) delete mode 100644 tools/doc-generator.xsl diff --git a/.gitignore b/.gitignore index 7a880bba25..89911274c7 100644 --- a/.gitignore +++ b/.gitignore @@ -70,7 +70,6 @@ test-*.trs /docs/api/version.xml /docs/api/settings-spec.html /docs/api/settings-spec.xml -/docs/api/spec.html /docs/api/*.stamp /docs/api/html/ /docs/api/tmpl/ diff --git a/docs/api/Makefile.am b/docs/api/Makefile.am index 1b50d02b65..d369dd545f 100644 --- a/docs/api/Makefile.am +++ b/docs/api/Makefile.am @@ -8,10 +8,9 @@ OTHER_FILES= \ $(top_srcdir)/introspection/generic-types.xml \ $(top_srcdir)/introspection/errors.xml \ $(top_srcdir)/introspection/vpn-errors.xml \ - $(top_srcdir)/tools/doc-generator.xsl \ $(top_srcdir)/introspection/generic-types.xml -GENERATED_FILES = spec.html +GENERATED_FILES = if SETTING_DOCS_AVAILABLE @@ -23,15 +22,6 @@ $(DOC_MAIN_SGML_FILE): settings-spec.xml GENERATED_FILES += settings-spec.xml -endif - -if ENABLE_GTK_DOC - -spec.html: $(XMLS) $(OTHER_FILES) html-build.stamp - $(XSLTPROC) --path "$(top_builddir)/introspection:$(top_srcdir)/introspection" $(top_srcdir)/tools/doc-generator.xsl $(top_builddir)/introspection/all.xml > spec.html - mkdir -p $(builddir)/html/ - cp spec.html $(builddir)/html/ - all: $(GENERATED_FILES) endif @@ -62,6 +52,41 @@ content_files = \ ../../COPYING \ $(NULL) +expand_content_files = \ + $(top_builddir)/introspection/nmdbus-access-point-org.freedesktop.NetworkManager.AccessPoint.xml \ + $(top_builddir)/introspection/nmdbus-active-connection-org.freedesktop.NetworkManager.Connection.Active.xml \ + $(top_builddir)/introspection/nmdbus-device-team-org.freedesktop.NetworkManager.Device.Team.xml \ + $(top_builddir)/introspection/nmdbus-dhcp6-config-org.freedesktop.NetworkManager.DHCP6Config.xml \ + $(top_builddir)/introspection/nmdbus-device-wifi-org.freedesktop.NetworkManager.Device.Wireless.xml \ + $(top_builddir)/introspection/nmdbus-manager-org.freedesktop.NetworkManager.xml \ + $(top_builddir)/introspection/nmdbus-vpn-connection-org.freedesktop.NetworkManager.VPN.Connection.xml \ + $(top_builddir)/introspection/nmdbus-secret-agent-org.freedesktop.NetworkManager.SecretAgent.xml \ + $(top_builddir)/introspection/nmdbus-device-org.freedesktop.NetworkManager.Device.xml \ + $(top_builddir)/introspection/nmdbus-vpn-plugin-org.freedesktop.NetworkManager.VPN.Plugin.xml \ + $(top_builddir)/introspection/nmdbus-device-bt-org.freedesktop.NetworkManager.Device.Bluetooth.xml \ + $(top_builddir)/introspection/nmdbus-device-vxlan-org.freedesktop.NetworkManager.Device.Vxlan.xml \ + $(top_builddir)/introspection/nmdbus-settings-connection-org.freedesktop.NetworkManager.Settings.Connection.xml \ + $(top_builddir)/introspection/nmdbus-device-bond-org.freedesktop.NetworkManager.Device.Bond.xml \ + $(top_builddir)/introspection/nmdbus-device-macvlan-org.freedesktop.NetworkManager.Device.Macvlan.xml \ + $(top_builddir)/introspection/nmdbus-ppp-manager-org.freedesktop.NetworkManager.PPP.xml \ + $(top_builddir)/introspection/nmdbus-device-vlan-org.freedesktop.NetworkManager.Device.Vlan.xml \ + $(top_builddir)/introspection/nmdbus-device-adsl-org.freedesktop.NetworkManager.Device.Adsl.xml \ + $(top_builddir)/introspection/nmdbus-agent-manager-org.freedesktop.NetworkManager.AgentManager.xml \ + $(top_builddir)/introspection/nmdbus-device-wimax-org.freedesktop.NetworkManager.Device.WiMax.xml \ + $(top_builddir)/introspection/nmdbus-device-ip-tunnel-org.freedesktop.NetworkManager.Device.IPTunnel.xml \ + $(top_builddir)/introspection/nmdbus-device-tun-org.freedesktop.NetworkManager.Device.Tun.xml \ + $(top_builddir)/introspection/nmdbus-device-bridge-org.freedesktop.NetworkManager.Device.Bridge.xml \ + $(top_builddir)/introspection/nmdbus-device-olpc-mesh-org.freedesktop.NetworkManager.Device.OlpcMesh.xml \ + $(top_builddir)/introspection/nmdbus-dhcp4-config-org.freedesktop.NetworkManager.DHCP4Config.xml \ + $(top_builddir)/introspection/nmdbus-device-generic-org.freedesktop.NetworkManager.Device.Generic.xml \ + $(top_builddir)/introspection/nmdbus-device-infiniband-org.freedesktop.NetworkManager.Device.Infiniband.xml \ + $(top_builddir)/introspection/nmdbus-device-modem-org.freedesktop.NetworkManager.Device.Modem.xml \ + $(top_builddir)/introspection/nmdbus-ip6-config-org.freedesktop.NetworkManager.IP6Config.xml \ + $(top_builddir)/introspection/nmdbus-device-veth-org.freedesktop.NetworkManager.Device.Veth.xml \ + $(top_builddir)/introspection/nmdbus-settings-org.freedesktop.NetworkManager.Settings.xml \ + $(top_builddir)/introspection/nmdbus-device-ethernet-org.freedesktop.NetworkManager.Device.Wired.xml \ + $(top_builddir)/introspection/nmdbus-ip4-config-org.freedesktop.NetworkManager.IP4Config.xml + include $(top_srcdir)/gtk-doc.make #################################### @@ -74,7 +99,3 @@ CLEANFILES += html/* tmpl/* xml/* \ if BUILD_SETTING_DOCS CLEANFILES += settings-spec.xml endif - -if ENABLE_GTK_DOC -CLEANFILES += spec.html -endif diff --git a/docs/api/network-manager-docs.xml b/docs/api/network-manager-docs.xml index e8c99460d8..9b491c7ef4 100644 --- a/docs/api/network-manager-docs.xml +++ b/docs/api/network-manager-docs.xml @@ -5,11 +5,12 @@ ]> - NetworkManager D-Bus Reference Manual + NetworkManager D-Bus API Reference Manual Version &version; 2012 + 2016 The NetworkManager Authors @@ -36,13 +37,52 @@ - + D-Bus API Reference + This part documents the D-Bus interface used to access the NetworkManager daemon. - + +
+ Interfaces + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
diff --git a/examples/python/dbus/create-bond.py b/examples/python/dbus/create-bond.py index 41ffabe8e1..f36426ca41 100755 --- a/examples/python/dbus/create-bond.py +++ b/examples/python/dbus/create-bond.py @@ -21,7 +21,7 @@ # This example configures a Bond from ethernet devices and activates it # # NetworkManager D-Bus API: -# https://developer.gnome.org/NetworkManager/1.0/spec.html +# https://developer.gnome.org/NetworkManager/stable/spec.html # import dbus, sys, uuid diff --git a/tools/Makefile.am b/tools/Makefile.am index 27d6bcc417..91ada71a0e 100644 --- a/tools/Makefile.am +++ b/tools/Makefile.am @@ -1,7 +1,6 @@ EXTRA_DIST = \ check-exports.sh \ debug-helper.py \ - doc-generator.xsl \ run-test-valgrind.sh \ run-test-dbus-session.sh \ test-networkmanager-service.py \ diff --git a/tools/doc-generator.xsl b/tools/doc-generator.xsl deleted file mode 100644 index bcc88e8376..0000000000 --- a/tools/doc-generator.xsl +++ /dev/null @@ -1,691 +0,0 @@ - - - - - - - - - - - - - - - - -

Errors:

- - - - -

Generic types:

- - - - - -

Simple types:

- - - - -

Enumerated types:

- - - - -

Sets of flags:

- - - - -

Structure types:

- - - - -

Mapping types:

- - - - -

Types defined elsewhere:

-
- - - - -

- - - - -
- -
- - -
- -
- - - - - - -

- - -

- This interface is - and is likely to cause havoc to your API/ABI if bindings are generated. - Don't include it in libraries that care about compatibility. -

- - - -

Implementations of this interface must also implement:

-
    - -
    • -     -
- - - - - - -

Methods:

- - - -

Interface has no methods.

- - - - - -

Signals:

- - - -

Interface has no signals.

- - - - - -

Properties:

-
- -
- - -

Interface has no properties.

- - - - - - - - -

- - - -

- -
- - - - - - - - - - - -
=
- - -
- - -
(Undocumented)
- - - -
- - - -

- - - -

- -
- - - - - - - - - - - -
=
- - -
- - -
(Undocumented)
- - - -
- - - -
- - - - - - - () - -
-
- -
- - - -
-

- - - - a{ - - - : - - → - - } -

-
- -
-
-

Members

-
- -
-
-
- - - - - - - - - - -
-

- - - - -

-
- -
-
- - - -
-
- - - - -
-
Defined by:
-
- - - - - ( - - , - ) - - - - - a{ - - → - } - - - -
-

- - - - ( - - - : - - , - - ) -

-
- -
- - -

In bindings that need a separate name, arrays of - should be called - .

- - -

Arrays of don't generally - make sense.

- - -
-

Members

-
- -
-
-
- - - -
-

- - - ( - - : - , - - ) → - - - - - , - - - nothing - -

-
- -
- - -
-

Parameters

-
- -
-
- - - -
-

Returns

-
- -
-
- - - -
-

Possible errors

-
- -
-
- - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ERR: Unable to find type ' - - ' - - - - () - - - - -
- - - - -
-
- - - - - - (undocumented) - - -
- - - -
- - - - -
-
- -
- - - -
- - - - - - -
-
- -
- - - -
- -
-
- - - - - - - (generic description) - - - (Undocumented.) - - -
- - - -
-

- - - ( - - : - , - - )

-
- -
- - -
-

Parameters

-
- -
-
- -
- - - - - - - - - <xsl:value-of select="tp:title"/> - <xsl:if test="tp:version"> - <xsl:text> version </xsl:text> - <xsl:value-of select="tp:version"/> - </xsl:if> - - - - -

- -

- -

Version

- - - - - -

Interfaces

-
    - -
    • -     -
- - - - - -

Index

-

Index of interfaces

-
    - -
    • -     -
-

Index of types

-
    - - -
  • - - - - - - -
    • -     -
- - - - - - - From 8f8c15fb3a8e12f51f188899919b99f276dc5ef6 Mon Sep 17 00:00:00 2001 From: Lubomir Rintel Date: Thu, 24 Mar 2016 13:10:45 +0100 Subject: [PATCH 4/6] docs: remove some outdated documentation The migration guide and the old D-Bus API are not needed anymore. --- docs/NetworkManager DBUS API.txt | 195 ------------ docs/api/Makefile.am | 1 - docs/api/migrating-to-09.xml | 478 ------------------------------ docs/api/network-manager-docs.xml | 2 - 4 files changed, 676 deletions(-) delete mode 100644 docs/NetworkManager DBUS API.txt delete mode 100644 docs/api/migrating-to-09.xml diff --git a/docs/NetworkManager DBUS API.txt b/docs/NetworkManager DBUS API.txt deleted file mode 100644 index 0a12c2674e..0000000000 --- a/docs/NetworkManager DBUS API.txt +++ /dev/null @@ -1,195 +0,0 @@ -********* 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 - - diff --git a/docs/api/Makefile.am b/docs/api/Makefile.am index d369dd545f..b9d6cfaa28 100644 --- a/docs/api/Makefile.am +++ b/docs/api/Makefile.am @@ -48,7 +48,6 @@ MKHTML_OPTIONS=--path="$(abs_srcdir)" # Non-autogenerated SGML files to be included in $(DOC_MAIN_SGML_FILE) content_files = \ version.xml \ - migrating-to-09.xml \ ../../COPYING \ $(NULL) diff --git a/docs/api/migrating-to-09.xml b/docs/api/migrating-to-09.xml deleted file mode 100644 index f282d64626..0000000000 --- a/docs/api/migrating-to-09.xml +++ /dev/null @@ -1,478 +0,0 @@ - - -]> - - Migrating from NetworkManager 0.8 to NetworkManager 0.9 - - - NetworkManager 0.9 is a new major version of NetworkManager that breaks - both API and ABI compared to previous versions. These changes are - intended to make communication with NetworkManager much simpler, especially - for network control and configuration programs. Thankfully, most changes - are not difficult to implement, and the advantages of the simpler - architecture of NetworkManager 0.9 greatly outweight the effort of - updating client programs. - - -
- Architecture and D-Bus API Changes in 0.9 - - - This section details the architectural and D-Bus API changes in - NetworkManager 0.9. - - -
- Elimination of the User Settings Service - - Previously there were two "settings services", or D-Bus services that - provided and saved network configuration information. NetworkManager - owned the "system" settings service, and one user-level applet owned the - "user" settings service. Now, the "user" settings service has been - eliminated, so clients only have to track one D-Bus service to read and - update network configuration. The functionality of the old user settings - service has been replaced with a "permissions" key on each connection - object to preserve the ability to restrict which users can use the - connection, and with a "secret agent" D-Bus API for user-session-level - secure storage of network secrets and passwords. - - - Elimination of the user settings service provides the following advantages - for clients of NetworkManager: - - Simpler discovery of network configuration and change tracking - Simpler storage of user-level network secrets by control applets - Correct operation of fast-user switching and multi-seat configurations - More granular network connection permissions for system administrators - Connections are now system-wide by default (unless restricted by the user or system administrator) - Easier deployment of user-specific connections (ie, VPNs) - - - - With this change, D-Bus methods that previously took a "service name" - argument (like - org.freedesktop.NetworkManager.ActivateConnection) and - objects with service name properties (like ActiveConnection objects) no - longer have those arguments or properties. - - - Action: if you develop a network control - applet that talks to NetworkManager and used to provide a user settings - service, you can eliminate that code and rely on NetworkManager for all - storage of network configuration. Your applet should now implement the - Secret Agent D-Bus API (see below) to store user-specific secrets, and - add legacy user-specific configuration to NetworkManager when run. More - information about both these changes follows. - -
- -
- User Secret Agents - - Even with the elimination of the user settings service, in some cases it - is still desirable to store secrets in the user's session and not in - system-wide storage (and thus available to all users). To allow this - functionality the concept of agents has been introduced. Using the new - - org.freedesktop.NetworkManager.AgentManager - D-Bus interface provided by NetworkManager, user applications can register - themselves as "secret agents", ie programs capable of saving and providing - secrets to NetworkManager. The agent should export the - - org.freedesktop.NetworkManager.SecretAgent - D-Bus interface, but should NOT claim a bus name on the system or session - bus. Instead, NetworkManager talks to the agent directly over the D-Bus - connection which the agent used to register itself. - - - Each agent must send a unique identifier to NetworkManager when it - registers. This identifier must follow certain rules (see the NM D-Bus - API documentation for more details) but looks essentially the same as - a D-Bus service name. Only one agent using a given identifier may be - registered at the same time. The agent is automatically unregistered - if it disconnects from D-Bus or exits. - - - When NetworkManager requires secrets during the attempt to connect to a - network, and no secrets are available from the internal settings service, - NetworkManager queries each registered agent for secrets. Agents that - are in "active" user sessions (as determined by ConsoleKit) are preferred - over inactive ones. Only agents belonging to users who have permission - to view and modify the connection are queried. For more information on - connection permissions, see below. - - When secrets are requested, the agent is also sent a set of flags that - modify the behavior of the request. By default, the agent should never - attempt to query the user for secrets, but should simply return any - available saved secrets. Other flags allow the agent to explicitly - request new secrets from the user. - - Action: the parts of a previous user - settings service that handled secrets may be easily repurposed as the bulk - of the implementation of a secret agent. The agent is sent all available - connection settings, and from those should be able to retrieve or save - any saved user secrets, or to request new secrets from the user. - -
- -
- Settings Service Interface Changes - - With the elimination of the user settings service, the old - org.freedesktop.NetworkManagerUserSettings and - org.freedesktop.NetworkManagerSystemSettings D-Bus - service names are no longer used. Instead NetworkManager provides the - settings service using its own D-Bus service name, - org.freedesktop.NetworkManager. The object path of - the settings service has also changed to - /org/freedesktop/NetworkManager/Settings. - - - Additionally, the D-Bus interface of the settings service has changed - to - org.freedesktop.NetworkManager.Settings from - the old interface name of - org.freedesktop.NetworkManagerSettings, and the old - org.freedesktop.NetworkManagerSettings.System - interface has been merged into the new - - org.freedesktop.NetworkManager.Settings interface - as the split no longer made sense. This includes the - SaveHostname method and the Hostname - and CanModify properties. - - - Action: change the service name and - object path that your application uses to request system network settings - to org.freedesktop.NetworkManager and - /org/freedesktop/NetworkManager/Settings respectively, - and update the D-Bus interface that codes uses to talk to the settings - service to - org.freedesktop.NetworkManager.Settings. - Listen for hostname changes using the new interface name as well. - -
- -
- Connection Object Interface Changes - - Consistent with the interface changes to the Settings object, the - Connection object's D-Bus interface has changed to - - org.freedesktop.NetworkManager.Settings.Connection - from the previous - org.freedesktop.NetworkManagerSettings.Connection. - - - Additionally, the - org.freedesktop.NetworkManager.Settings.Connection.Updated - signal of the Connection object no longer includes the updated settings - data argument, as that might allow users who are not authorized to - view the connection details to do so. Instead, when a client receives the - Updated signal, it should requery the Connection's settings with the - org.freedesktop.NetworkManager.Settings.Connection.GetSettings - method. If the client receives an error as a result of this method call, - it should assume the connection has been deleted. - - - Action: where code manipulates - Connection objects, update the D-Bus interface that code uses to be - org.freedesktop.NetworkManager.Settings.Connection. - Additionally, code that listens for the - org.freedesktop.NetworkManager.Settings.Connection.Updated - signal should no longer expect the new settings data as an argument, but - instead should request the new settings data using the - org.freedesktop.NetworkManager.Settings.Connection.GetSettings - method. - -
- -
- Permissions Methods Consolidation - - Previously there were two D-Bus method calls to retrieve the list of - operations that a user client could perform, and two signals notifying - callers that they should recheck permissions. Those two calls were: - - - org.freedesktop.NetworkManagerSettings.System.GetPermissions - which returned a bitfield of operations the caller was allowed to - perform related to modify system network settings and the machine - hostname - - - org.freedesktop.NetworkManager.GetPermissions which - returned a dictionary mapping permission names to result strings like - "yes", "auth", or "no", relating to network control permissions like - the ability to enable or disable WiFi. - - - These two calls have been consolidated into an enhanced - org.freedesktop.NetworkManager.GetPermissions call that - uses the same arguments, but includes all permissions, including those which - the settings service used to handle. - - - With this change, the bitfield items from - org.freedesktop.NetworkManagerSettings.System.GetPermissions - are now string-based permissions. The mapping is as follows: - - - - Old bitfield valueNew permission name - - - - 0x1 (connection-modify) - - org.freedesktop.NetworkManager.settings.modify.system - or org.freedesktop.NetworkManager.settings.modify.system - depending on the permissions of the connection. - - - - 0x2 (wifi-share-protected) - - org.freedesktop.NetworkManager.wifi.share.protected - - - - 0x4 (wifi-share-open) - - org.freedesktop.NetworkManager.wifi.share.open - - - - 0x8 (hostname-modify) - - org.freedesktop.NetworkManager.settings.modify.hostname - - - - -
- - - Action: modify handling of existing - code that checks permissions to recognize the new permissions names for - old system settings permissions, and remove code that used to call - org.freedesktop.NetworkManagerSettings.System.GetPermissions. - -
- -
- AddConnection Returns Object Path of New Connection - - The - org.freedesktop.NetworkManager.Settings.AddConnection - method call now returns the object path of the newly added - connection. Previously, if code wanted to manipulate a connection - post-addition, it had to wait for the new connection to be announced via - the NewConnection signal by matching connection UUIDs. Now the object - path is returned and this workaround is no longer required. - - - Action: update code that adds new - connections to handle the object path returned from AddConnection, and - remove workarounds for finding the new connection via signals. - -
- -
- Support for WiMAX Devices - - NetworkManager now supports Intel WiMAX mobile broadband devices. A - corresponding device type (NM_DEVICE_TYPE_WIMAX) and - a new - org.freedesktop.NetworkManager.Device.WiMax - D-Bus interface have been added. Furthermore, to support connection to - different WiMAX Network Service Providers (NSPs) the - - org.freedesktop.NetworkManager.Device.WiMax.Nsp - interface has been added to access information about each available - WiMAX network. - - - Action: update code that handles - devices and/or displays status to users to recognize the new device type, - and to display available WiMAX NSPs similar to how WiFi Access Points - are displayed. Also update code that creates new connections to allow - creation of new WiMAX connections. - -
- -
- New Device States - - A few new device states - have been added, and all device states have been renumbered for flexibility. - The new devices states IP_CHECK, SECONDARIES, and DEACTIVATING. - - - Action: where code checks device state - or shows UI indication of the device's state, make sure the new device - states are processed correctly, and that code in switch()-type statements - is updated to handle the new states. - -
- -
- New Active Connection State - - Along with the new device states, an - additional - ActiveConnection state has been added: DEACTIVATING. This state - is entered when the connection is being torn down and deactivated. - - - Action: where code checks active - connection states or shows UI indication of active connection states, make - sure the DEACTIVATING state is processed correctly, and that code in - switch()-type statements is updated to handle it. - -
- -
- Consolidated Modem Devices - - Many new mobile broadband devices support multiple access families, like - Qualcomm Gobi cards (CDMA/EVDO and GSM/UMTS), or multi-mode EVDO/LTE - or UMTS/LTE modems like the Pantech UML290. The previous hard split - between CDMA/EVDO and GSM/UMTS device classes was not flexible enough to - deal with these new multi-mode devices. Thus the previously separate - CDMA and GSM device classes have been combined into a single Modem - device class, which exposes both hardware "ModemCapabilities" and - runtime "CurrentCapabilities" which represent generic access technology - families like CDMA/EVDO, GSM/UMTS, and LTE which the device supports. - ModemCapabilities indicate all the access technology families which the - modem is capable of supporting, while CurrentCapabilities indicate the - immediate access technology families the device supports without reloading - the firmware and thus restarting the device. - - - Along with this change, the - org.freedesktop.NetworkManager.Device.Serial - interface has been removed as it's functionality will be incorporated - into the - - org.freedesktop.NetworkManager.Device.Modem - interface in the future. - - - Action: combine code that checks for - the old CDMA and GSM device types, and instead handle the new Modem device - type. Where behavior must change based on the capabilities of the device, - check the CurrentCapabilities device property to determine whether to - treat the device as CDMA, GSM, or LTE for purposes of configuration and - status. - -
- -
- Secret Property Flags - - In the Connection object's configuration properties, each setting's secret - properties (like WiFi passphrases, or public key passwords, etc) now has - an associated "flags" property that changes how NetworkManager treats the - secret. The "flags" property is a bitfield of one or more of the - following values: - - - - Flag ValueMeaning - - - - 0x00 (none) - - NetworkManager is responsible for providing and storing this - secret (default) - - - - 0x01 (agent-owned) - - A user secret agent is responsible for providing and storing - this secret; when it is required agents will be asked to - retrieve it - - - - 0x02 (not saved) - - The secret is not saved, and should be requested each time it - is required. Used for OTP/token configurations where the - secret changes periodically, or if the user simply wants to - manually enter the secret each time. - - - - 0x04 (not required) - - In situations where it cannot be automatically determined that - the secret is required (some VPNs and PPP providers dont require - all possible secrets) this flag indicates that the specific - secret is not required. - - - - -
- - - Action: user interface code which - handles entry of connection secrets should be updated to read and set - secret flags. For example, code that creates new VPN connections may want - to set the "agent-owned" flag to ensure that the user's VPN password is - not available to all users. EAP-TLS and VPN interface code might add a - checkbox that toggles the "not saved" bit to indicate that the - password/PIN code should be requested from a hardware token each time it - is required. - -
- -
- Deprecated Methods Removed - - A few methods and signals of the org.freedesktop.NetworkManager - interface deprecated in version 0.7 have been removed. All the - replacement methods and signals have existed since version 0.7 and so are - not new to this version of NetworkManager, but some older programs may - be using removed items. The following table lists the removed items and - their replacements: - - - - Removed ItemReplacement - - - - StateChange signal - - Use the StateChanged signal, which has the - same arguments. - - - - sleep() and wake() methods - - Use the Sleep() method instead, which takes - a boolean argument indicating whether NetworkManager should - go to sleep or wake up. - - - - -
- - - Action: update code to use these - replacement methods and properties where it used old deprecated ones - -
- -
- - diff --git a/docs/api/network-manager-docs.xml b/docs/api/network-manager-docs.xml index 9b491c7ef4..2035bb5b02 100644 --- a/docs/api/network-manager-docs.xml +++ b/docs/api/network-manager-docs.xml @@ -142,8 +142,6 @@ - - Index From 5ce4c9fd84df9c0d8c31f20b8d6771019360c2ef Mon Sep 17 00:00:00 2001 From: Lubomir Rintel Date: Thu, 24 Mar 2016 13:30:52 +0100 Subject: [PATCH 5/6] docs: add manual pages to docbook documentation This way they will make it to developer.gnome.org. --- docs/api/Makefile.am | 8 +++++++- docs/api/network-manager-docs.xml | 11 +++++++++++ 2 files changed, 18 insertions(+), 1 deletion(-) diff --git a/docs/api/Makefile.am b/docs/api/Makefile.am index b9d6cfaa28..666bad0048 100644 --- a/docs/api/Makefile.am +++ b/docs/api/Makefile.am @@ -84,7 +84,13 @@ expand_content_files = \ $(top_builddir)/introspection/nmdbus-device-veth-org.freedesktop.NetworkManager.Device.Veth.xml \ $(top_builddir)/introspection/nmdbus-settings-org.freedesktop.NetworkManager.Settings.xml \ $(top_builddir)/introspection/nmdbus-device-ethernet-org.freedesktop.NetworkManager.Device.Wired.xml \ - $(top_builddir)/introspection/nmdbus-ip4-config-org.freedesktop.NetworkManager.IP4Config.xml + $(top_builddir)/introspection/nmdbus-ip4-config-org.freedesktop.NetworkManager.IP4Config.xml \ + $(top_builddir)/man/NetworkManager.xml \ + $(top_builddir)/man/NetworkManager.conf.xml \ + $(top_builddir)/man/nmcli-examples.xml \ + $(top_builddir)/man/nm-settings.xml \ + $(top_builddir)/man/nm-settings-keyfile.xml \ + $(top_builddir)/man/nm-settings-ifcfg-rh.xml include $(top_srcdir)/gtk-doc.make diff --git a/docs/api/network-manager-docs.xml b/docs/api/network-manager-docs.xml index 2035bb5b02..48f592653c 100644 --- a/docs/api/network-manager-docs.xml +++ b/docs/api/network-manager-docs.xml @@ -142,6 +142,17 @@ + + UNIX Manual Pages + + + + + + + + + Index From f67bf52046c249117040c530c837b5da2c027437 Mon Sep 17 00:00:00 2001 From: Beniamino Galvani Date: Sat, 26 Mar 2016 10:19:25 +0100 Subject: [PATCH 6/6] man: use replace with It makes more sense and actually looks good in rendered HTML. [lkundrak@v3.sk: wrote the commit message] --- man/nmcli-examples.xml | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/man/nmcli-examples.xml b/man/nmcli-examples.xml index 4f5f22f60f..0ce7dc72c6 100644 --- a/man/nmcli-examples.xml +++ b/man/nmcli-examples.xml @@ -143,9 +143,9 @@ org.freedesktop.NetworkManager.settings.modify.hostname auth by a system administrator and are not meant to be changed by users. The usual place for the polkit configuration is /usr/share/polkit-1/actions/org.freedesktop.NetworkManager.policy. pkaction command can display description for polkit actions. - - pkaction --action-id org.freedesktop.NetworkManager.network-control --verbose - + +pkaction --action-id org.freedesktop.NetworkManager.network-control --verbose + More information about polkit can be found at http://www.freedesktop.org/wiki/Software/polkit. @@ -176,11 +176,11 @@ $ nmcli g log level INFO domains DEFAULT Adding a bonding master and two slave connection profiles - + $ nmcli con add type bond ifname mybond0 mode active-backup $ nmcli con add type ethernet ifname eth1 master mybond0 $ nmcli con add type ethernet ifname eth2 master mybond0 - + This example demonstrates adding a bond master connection and two slaves. The @@ -192,11 +192,11 @@ $ nmcli con add type ethernet ifname eth2 master mybond0 Adding a team master and two slave connection profiles - + $ nmcli con add type team con-name Team1 ifname Team1 config team1-master-json.conf $ nmcli con add type ethernet con-name Team1-slave1 ifname em1 master Team1 $ nmcli con add type ethernet con-name Team1-slave2 ifname em2 master Team1 - + This example demonstrates adding a team master connection profile and two slaves. It is @@ -210,22 +210,22 @@ $ nmcli con add type ethernet con-name Team1-slave2 ifname em2 master Team1 em2. The slaves don't specify config and thus teamd will use its default configuration. You will activate the whole setup by activating both slaves: - + $ nmcli con up Team1-slave1 $ nmcli con up Team1-slave2 - + By default, the created profiles are marked for auto-activation. But if another connection has been activated on the device, the new profile won't activate automatically and you need to activate it manually. Adding a bridge and two slave profiles - + $ nmcli con add type bridge con-name TowerBridge ifname TowerBridge $ nmcli con add type ethernet con-name br-slave-1 ifname ens3 master TowerBridge $ nmcli con add type ethernet con-name br-slave-2 ifname ens4 master TowerBridge $ nmcli con modify TowerBridge bridge.stp no - + This example demonstrates adding a bridge master connection and two slaves. The @@ -239,7 +239,7 @@ $ nmcli con modify TowerBridge bridge.stp no Adding an ethernet connection profile with manual IP configuration - + $ nmcli con add con-name my-con-em1 ifname em1 type ethernet ip4 192.168.100.100/24 gw4 192.168.100.1 ip4 1.2.3.4 ip6 abbe::cafe $ nmcli con mod my-con-em1 ipv4.dns "8.8.8.8 8.8.4.4" @@ -247,7 +247,7 @@ $ nmcli con mod my-con-em1 +ipv4.dns 1.2.3.4 $ nmcli con mod my-con-em1 ipv6.dns "2001:4860:4860::8888 2001:4860:4860::8844" $ nmcli -p con show my-con-em1 - + The first command adds an Ethernet connection profile named my-con-em1 @@ -263,11 +263,11 @@ $ nmcli -p con show my-con-em1 Escaping colon characters in tabular mode - + $ nmcli -t -f general -e yes -m tab dev show eth0 - + GENERAL:eth0:ethernet:Intel Corporation:82567LM Gigabit Network Connection:e1000e:2.1.4-k:1.8-3:00\:22\:68\:15\:29\:21:1500:100 (connected):0 (No reason given):/sys/devices/pci0000\:00/0000\:00\:19.0/net/eth0:eth0:yes:yes:no:ethernet-13:89cbcbc6-dc85-456c-9c8b-bd828fee3917:/org/freedesktop/NetworkManager/ActiveConnection/9 @@ -316,11 +316,11 @@ fi Example sessions of interactive connection editor Adding an ethernet connection profile in interactive editor (a) - + $ nmcli connection edit type ethernet - + ===| nmcli interactive connection editor |===