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" : "" }