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
===================================

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, string interface, dict config)

			This method gets called during a connection setup
			when 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.  The 'config' dictionary (a{sv}) maps
			string keys to values of types defined per key.

			The following key/value pairs are used, 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 the address was obtained from the remote
			end some configuration bits, such as DNS addresses,
			may have been overridden locally.

			string Address - Local IP address string.

			byte PrefixLength - Holds the prefix-length of the
			local subnet.  For IPv4 this maps to the netmask.

			string Gateway [optional] - Local subnet's gateway
			address if one exists.

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

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

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

		void ConfigureIPv6(object device, string interface, dict config)

			Same as ConfigureIPv4 above but for IPv6.

		void Cancel(object device, string interface,
						string reason) [noreply]

			This method gets called to indicate that the connection
			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".