iwd/doc/agent-api.txt

Agent Manager hierarchy
=======================

Service		net.connman.iwd
Interface	net.connman.iwd.AgentManager
Object path	/net/connman/iwd

Methods		void RegisterAgent(object path)

			Register new agent for handling user secrets requests.
			The agent object's methods on the net.connman.iwd.Agent
			interface will be called when IWD needs to request
			credentials for a connection to a network in station
			mode.

			Possible Errors: [service].InvalidArguments
					 [service].Failed
					 [service].AlreadyExists

		void UnregisterAgent(object path)

			Unregister an existing agent.

			Possible Errors: [service].InvalidArguments
					 [service].Failed
					 [service].NotFound

		void RegisterNetworkConfigurationAgent(object path)

			Register the agent for handling IPv4 and IPv6
			configuration setting.  This method and its
			corresponding unregister method are only supported
			if network configuration is enabled: see
			EnableNetworkConfiguration in iwd.config(5) and
			NetworkConfigurationEnabled in
			net.connman.iwd.Daemon.GetInfo in daemon-api.txt.

			During a station-mode, AP-mode or P2P connection, IWD
			will obtain the IP configuration values for a network
			interface, either automatically from a remote server
			(DHCP or otherwise), generate it or read it from a
			settings file.  If no network configuration agent is
			present, IWD immediately writes (commits) those
			values to the corresponding interface, the routing
			table and communicates them to the resolver.  If such
			agent is registered, IWD requests the agent to do
			this last step.

			Connection success is not signalled until the agent
			method has returned.  The agent may also be invoked
			during the connection lifetime whenever the IP
			configuration changes and after a roam.  The agent
			object must have the NetworkConfigurationAgent
			interface.

			Possible Errors: [service].InvalidArguments
					 [service].Failed
					 [service].AlreadyExists
					 [service].NotSupported

		void UnregisterNetworkConfigurationAgent(object path)

			Unregister an existing network configuration agent.

			Possible Errors: [service].InvalidArguments
					 [service].Failed
					 [service].NotFound
					 [service].NotAvailable


Agent hierarchy
===============

Service		unique name
Interface	net.connman.iwd.Agent
Object path	freely definable

Methods		void Release() [noreply]

			This method gets called when the service daemon
			unregisters the agent. An agent can use it to do
			cleanup tasks. There is no need to unregister the
			agent, because when this method gets called it has
			already been unregistered.

		string RequestPassphrase(object network)

			This method gets called when trying to connect to
			a network and passphrase is required.

			Possible Errors: net.connman.iwd.Agent.Error.Canceled

		string RequestPrivateKeyPassphrase(object network)

			This method gets called when connecting to
			a network that requires authentication using a
			locally-stored encrypted private key file, to
			obtain that private key's encryption passphrase.

			Possible Errors: net.connman.iwd.Agent.Error.Canceled

		(string, string) RequestUserNameAndPassword(object network)

			This method gets called when connecting to
			a network that requires authentication using a
			user name and password.

			Possible Errors: net.connman.iwd.Agent.Error.Canceled

		string RequestUserPassword(object network, string user)

			This method gets called when connecting to
			a network that requires authentication with a
			user password.  The user name is optionally passed
			in the parameter.

			Possible Errors: net.connman.iwd.Agent.Error.Canceled

		void Cancel(string reason) [noreply]

			This method gets called to indicate that the agent
			request failed before a reply was returned.  The
			argument will indicate why the request is being
			cancelled and may be "out-of-range", "user-canceled",
			"timed-out" or "shutdown".

Examples	Requesting a passphrase for WPA2 network

			RequestPassphrase("/net/connman/iwd/0/3/54657374_psk")
			==> "secret123"


NetworkConfigurationAgent hierarchy [experimental]
===================================

Service		unique name
Interface	net.connman.iwd.NetworkConfigurationAgent
Object path	freely definable

Methods		void Release() [noreply]

			This method gets called when the service daemon
			unregisters the agent. An agent can use it to do
			cleanup tasks. There is no need to unregister the
			agent, because when this method gets called it has
			already been unregistered.

		void ConfigureIPv4(object device, dict config)

			This method gets called during connection setup
			and later while the connection is operational
			whenever a new set of IPv4 configuration values is to
			be written to a network interface.  The connection is
			aborted if the method call returns an error or times
			out.

			In case of a station-mode connection, the 'device'
			parameter points at an object with a
			net.connman.iwd.Device interface whose Name property
			contains the name of network interface.  In case of a
			P2P connection, the object will have
			a net.connman.iwd.p2p.Peer interface whose
			ConnectectedInterface property contains the name of
			the target network interface.

			The 'config' dictionary (a{sv}) maps string keys to
			values of types defined per key.  Each call receives
			the full set of values which supersede those from
			previous calls.

			The following key/value pairs are defined, but more
			may be added in future versions.

			string Method - Indicates whether the local address
			was set statically (value "static") or obtained
			automatically such as through DHCP (value "auto").
			Even when addresses were obtained from the remote
			end some configuration bits, such as DNS addresses,
			may have been overridden locally.

			array(dict) Addresses - Local IP addresses.  Each
			address is described by a set of key/value properties
			as documented further down.

			array(dict) Routes - Routes for on-link and off-link
			prefixes/subnets and default routers.  Each route is
			described by a set of key/value properties as
			documented further down.

			array(string) DomainNameServers [optional] - Holds
			the list of DNS server addresses configured if any
			exist.

			array(string) DomainNames [optional] - Holds the
			network's local domain names if any exist.

			string MDNS [optional] - One of "true", "false" and
			"resolve".  Controls whether Multicast DNS support is
			to be enabled on the link.  When set to "resolve",
			only resolution is enabled, but not host or service
			registration and announcement (see systemd.network(5).)

			The following properties are defined for local
			addresses, but more may be added in the future:

			string Address - Holds the IP address string.

			byte PrefixLength [optional] - Prefix length
			associated with the address's subnet (IPv4 only).

			string Broadcast [optional] - Broadcast address
			associated with the address's subnet (IPv4 only).

			uint32 ValidLifetime [optional] - Remaining validity
			and ownership time for this address assignment/lease,
			in seconds at the time of the method call.
			If absent the address doesn't expire.

			uint32 PreferredLifetime [optional] - Number of
			seconds left at the time of the method call for this
			address to be preferred over other addresses.

			The following properties are defined for routes,
			but more may be added in the future:

			string, byte Destination [optional] - Holds the
			route's destination IP prefix string and the prefix
			length in bits.  Absent for default routes.

			string Router [optional] - Holds the router's IP
			address.  Absent for on-link routes.

			string PreferredSource [optional] - Route source IP
			address.

			uint32 Lifetime [optional] - Remaining route validity
			time in seconds at the time of the method call.
			If absent the route doesn't expire.

			uint32 Priority - Relative route priority.

			byte Preference [optional] - ICMPv6 route preference:
			0 for medium, 1 for high and 3 for low.

			uint32 MTU [optional] - Router MTU.

			Possible Errors: net.connman.iwd.Agent.Error.Canceled
					 net.connman.iwd.Agent.Error.Failed

		void ConfigureIPv6(object device, dict config)

			Same as ConfigureIPv4 above but for IPv6.

		void CancelIPv4(object device, string reason) [noreply]

			This method gets called to indicate that the network
			configuration was aborted before a reply was received
			for an ongoing ConfigureIPv4 or ConfigureIPv6 call.
			The last argument will indicate why the request is being
			cancelled and may be one of: "aborted", "superseded",
			"timed-out".

		void CancelIPv6(object device, string reason) [noreply]

			Same as CancelIPv4 above but for IPv6.