connman/doc/agent-api.txt

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

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

Methods		void Release()

			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 ReportError(object service, string error)

			This method gets called when an error has to be
			reported to the user.

			A special return value can be used to trigger a
			retry of the failed transaction.

			Possible Errors: net.connman.Agent.Error.Retry

		void ReportPeerError(object peer, string error)

			This method gets called when an error has to be
			reported to the user about a peer connection.

			A special return value can be used to trigger a
			retry of the failed transaction.

			Possible Errors: net.connman.Agent.Error.Retry

		void RequestBrowser(object service, string url)

			This method gets called when it is required
			to ask the user to open a website to procceed
			with login handling.

			This can happen if connected to a hotspot portal
			page without WISPr support.

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

		dict RequestInput(object service, dict fields)

			This method gets called when trying to connect to
			a service and some extra input is required. For
			example a passphrase or the name of a hidden network.

			The return value should be a dictionary where the
			keys are the field names and the values are the
			actual fields. Alternatively an error indicating that
			the request got canceled can be returned.

			Most common return field names are "Name" and of
			course "Passphrase".

			The dictionary arguments contains field names with
			their input parameters.

			In case of WISPr credentials requests and if the user
			prefers to login through the browser by himself, agent
			will have to return a LaunchBrowser error (see below).

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

		dict RequestPeerAuthorization(object peer, dict fields) [experimental]

			This method gets called when trying to connect to a
			peer or when an incoming peer connection is requested,
			for which some extra input is required. In this case,
			it will only deal with WPS input as well as accepting
			or rejecting an incoming connection.

			The return value should be a dictionary where the
			keys are the field names and the values are the
			actual fields. Alternatively an error indicating that
			the request got canceled or rejected can be returned.

			The dictionary arguments contains field names with
			their input parameters.

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

		void Cancel()

			This method gets called to indicate that the agent
			request failed before a reply was returned.

Fields		string Name

			The name of a network. This field will be requested
			when trying to connect to a hidden network.

		array{byte} SSID

			This field is an alternative to "Name" for WiFi
			networks and can be used to return the exact binary
			representation of a network name.

			Normally returning the "Name" field is the better
			option here.

		string Identity

			Identity (username) for EAP authentication methods.

		string Passphrase

			The passphrase for authentication. For example a WEP
			key, a PSK passphrase or a passphrase for EAP
			authentication methods.

		string PreviousPassphrase

			The previous passphrase successfully saved, i.e.
			which lead to a successfull connection. This field is
			provided as an informational argument when connecting
			with it does not work anymore, for instance when it
			has been changed on the AP. Such argument appears when
			a RequestInput is raised after a retry. In case of WPS
			association through PIN method: when retrying, the
			previous wpspin will be provided.

		string WPS

			This field requests the use of WPS to get associated.
			This is an alternate choice against Passphrase when
			requested service supports WPS. The reply can contain
			either empty pin, if user wants to use push-button
			method, or a pin code if user wants to use the pin
			method.

			In case of a RequestPeerAuthorization, this field will
			be set as mandatory.

		string Username

			Username for WISPr authentication. This field will be
			requested when connecting to a WISPr-enabled hotspot.

		string Password

			Password for WISPr authentication. This field will be
			requested when connecting to a WISPr-enabled hotspot.

Arguments	string Type

			Contains the type of a field. For example "psk", "wep"
			"passphrase", "response", "ssid", "wpspin" or plain
			"string".

		string Requirement

			Contains the requirement option. Valid values are
			"mandatory", "optional", "alternate" or
			"informational".

			The "alternate" value specifies that this field can be
			returned as an alternative to another one. An example
			would be the network name or SSID.

			All "mandatory" fields must be returned, while the
			"optional" can be returned if available.

			Nothing needs to be returned for "informational", as it
			is here only to provide an information so a value is
			attached to it.

		array{string} Alternates

			Contains the list of alternate field names this
			field can be represented by.

		string Value

			Contains data as a string, relatively to an
			"informational" argument.

Examples	Requesting a passphrase for WPA2 network

			RequestInput("/service1",
				{ "Passphrase" : { "Type"        : "psk",
						   "Requirement" : "mandatory"
						 }
				}
			==> { "Passphrase" : "secret123" }

		Requesting a passphrase after an error on the previous one:

			RequestInput("/service1",
				{ "Passphrase" : { "Type"        : "psk",
						   "Requirement" : "mandatory"
						 },
				  "PreviousPassphrase" :
					{ "Type"       : "psk",
					  "Requirement : "informational",
					  "Value"      : "secret123"
					}
				}

		Requesting name for hidden network

			RequestInput("/service2",
				{ "Name" : { "Type"        : "string",
					     "Requirement" : "mandatory",
					     "Alternates"  : [ "SSID" ]
					   },
				  "SSID" : { "Type"        : "ssid",
					     "Requirement" : "alternate"
					   }
				}
			==> { "Name" : "My hidden network" }

		Requesting a passphrase for a WPA2 network with WPS alternative:

			RequestInput("/service3",
				{ "Passphrase" : { "Type"        : "psk",
						   "Requirement" : "mandatory",
						   "Alternates"  : [ "WPS" ]
						 },
				  "WPS"        : { "Type"        : "wpspin",
						   "Requirement" : "alternate"
						 }
				}

			==> { "WPS" : "123456" }

		Requesting a passphrase for a WPA2 network with WPS alternative
		after an error on the previous one:

			RequestInput("/service3",
				{ "Passphrase" : { "Type"        : "psk",
						   "Requirement" : "mandatory",
						   "Alternates"  : [ "WPS" ]
					         },
				"WPS"          : { "Type"        : "wpspin",
						   "Requirement" : "alternate"
						 }
				"PreviousPassphrase" :
						{ "Type"       : "wpspin",
					  	"Requirement : "informational",
					  	"Value"      : "123456"
						}

		Requesting passphrase for a WPA-Enterprise network:

			RequestInput("/service4",
				{ "Identity"   : { "Type"        : "string",
						   "Requirement" : "mandatory"
						 },
				  "Passphrase" : { "Type"        : "passphrase",
						   "Requirement" : "mandatory"
						 }
				}

			==> { "Identity" : "alice", "Passphrase": "secret123" }

		Requesting challenge response for a WPA-Enterprise network:

			RequestInput("/service4",
				{ "Identity"   : { "Type"        : "string",
						   "Requirement" : "mandatory"
						 },
				  "Passphrase" : { "Type"        : "response",
						   "Requirement" : "mandatory"
						 }
				}

			==> { "Identity" : "bob", "Passphrase": "secret123" }

		Requesting username and password for a WISPr-enabled hotspot:

			RequestInput("/service5",
				{ "Username"   : { "Type"        : "string",
						   "Requirement" : "mandatory"
						 },
				  "Password"   : { "Type"        : "passphrase",
						   "Requirement" : "mandatory"
						 }
				}

			==> { "Username" : "foo", "Password": "secret" }

		Requesting a answer about an inconming peer connection:

			RequestPeerAuthorization("/peer3", {})

			==> { }

		Requesting the WPS details when connecting to a peer:

			RequestPeerAuthorization("/peer4",
				{ "WPS":
					{ "Type"        : "wpspin",
					  "Requirement" : "mandatory"
					}
				}

			==> { "WPS" : "" }