doc/agent-api.txt

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

Service		unique name
Interface	org.moblin.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: [service].Error.Retry

		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. Alternative an error indicating that
			the request got cannceled can be returned.

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

			The dictionary arguments contains field names with
			their input parameters.

			Possible Errors: [service].Error.Canceled

		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 Passphrase

			The passphrase for a network. For example a WEP
			key or a PSK passphrase.

Arguments	string Type

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

		string Requirement

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

			The "alternate" specifies that this field can be
			return 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.

		array{string} Alternates

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

Examples	Requesting a passphrase for WPA2 network

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

		Requesting name for hidden network

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