doc/ipconfig-api.txt

IP Configuration Handling
*************************


IP basics
=========

Layer 3 configuration state is managed on a per-device basis.  Each device
may have one or more configuration records associated with it.  These
records are represented by IPConfig elements that are registered in the
element hierarchy as children of the device element.  IPConfig elements
are ordered and state changes are effected by processing each element
according to this ordering.  This is used, for example, to define the
order in which DNS queries are proxy'd to DNS servers.

Layer 3 configuration state is also integrated with information exported
by the Linux kernel via the RTNL interface.  RTNL messages are used to track
system state changes made by other processes and these events are used to
provide a consistent system-wide view.


IPConfig hierarchy
==================

Service		org.chromium.flimflam
Interface	org.chromium.flimflam.IPConfig
Object path	[variable prefix]/{ipconfig0,ipconfig1,...}

Methods		dict GetProperties()

			Return properties for the IPConfig object. See
			the properties section for available properties.

			Possible Errors: [service].Error.PermissionDenied

		void SetProperty(string name, variant value)

			Change the value of the specified property. Only
			properties that are listed as read-write are
			changeable. On success a PropertyChanged signal
			will be emitted.

			Possible Errors: [service].Error.PermissionDenied
					 [service].Error.InvalidArguments
					 [service].Error.NotSupported
					 [service].Error.InvalidProperty

		void ClearProperty(string name)

			Reset the specified parameter to its "factory"
			value and remove any previously set value from
			the profile. Only properties that are listed
			as read-write are changeable. On success a
			PropertyChanged signal will be emitted.

			Possible Errors: [service].Error.PermissionDenied
					 [service].Error.InvalidProperty

		void Remove()

			Remove the IPConfig object from the associated
			device.

			Possible Errors: [service].Error.PermissionDenied

		void MoveBefore(object ipconfig)

			Reorder an IPConfig object to be before the
			IPConfig object ipconfig.

			Possible Errors: [service].Error.InvalidArguments
					 [service].Error.InvalidIPConfig

		void MoveAfter(object ipconfig)

			Reorder an IPConfig object to be after the
			IPConfig object ipconfig.

			Possible Errors: [service].Error.InvalidArguments
					 [service].Error.InvalidIPConfig

Signals		PropertyChanged(string name, variant value)

			This signal indicates a changed value of the given
			property.

Properties	string Address [readwrite]

			The Layer 3 address expressed in the dotted-quad format
			for IPv4 and any allowed format for IPv6 (as specified
			for inet_pton(3)).

			For static address configuration methods this value
			may be read or written.  For methods that dynamically
			setup state this value is read-only and defined only
			when an associated service is in a "ready" state.

		string Broadcast [readwrite]

			The Layer 3 broadcast address specified as per Address.

		string DomainName [readwrite]

			The DNS domain name to use in building FQDN queries.

		string Gateway [readwrite]

			The Layer 3 address gateway address specified as
			per Address.  Only one gateway is supported for
			each IPConfig object, to setup multiple gateways
			multiple objects must be created and the first
			gateway is used as a "default route" to reach
			networks outside the local segment.

		string Method [readonly]

			The method by which Layer 3 state is managed.

			Possible methods are:
			   "ipv4"       (fixed IPv4 network state)
			   "ipv6"       (fixed IPv6 network state)
			   "dhcp"       (IPv4 state setup using DHCP)
			   "bootp"      (IPv4 state setup using BOOTP)
			   "zeroconf"   (IPV4 state setup using ZeroConf)
			   "dhcp6"      (IPv6 state setup using DHCP6)
			   "ppp"        (IPv4 state setup using PPP)

		int32 Mtu [readwrite]

			The maximum transmit unit (MTU) in bytes.

		array{string} NameServers [readwrite]

			The Layer 3 addresses of DNS domain name servers to
			use for DNS requests.

			When setting this property the set of addresses
			is supplied as a single string with multiple
			servers using a ,-delimeted list; e.g.

			    "192.168.1.1,10.0.0.3,192.168.3.6"

		string PeerAddress [readwrite]

			The Layer 3 address associated with the destination
			endpoint of a point-to-point link.  This value is
			specified as per Address.

		int32 Prefixlen [readwrite]

			The number of bits in a Layer 3 address that are
			part of the network address.  For IPv4 networks this
			corresponds to the length of the network mask; e.g.
			a netmask of 255.255.255.0 has a prefixlen of 24
			(note arbitrary CIDR masks are not supported.)

		array{string} SearchDomains [readwrite]

			The set of strings to use when doing DNS lookups of
			an unqualified domain name. This overrides the
			default lookup behaviour that uses the DomainName
			to lookup unqualified names.

			When setting this property the set of addresses
			is supplied as a single string with multiple
			servers using a ,-delimeted list; e.g.

			    "foo.com,bar.com,baz.com"