X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=doc%2Fagent-api.txt;h=91371af42b621722bb24f2bf3de44e46f77bd181;hb=57156cc5738cfbf60e1b0ddf444ad6eec5964a0d;hp=f39c9664243a5e13f485a89a9c8b8a5110457c8a;hpb=00052435b7d3ea4139684c7f3b39911fdff5ac91;p=framework%2Fconnectivity%2Fconnman.git diff --git a/doc/agent-api.txt b/doc/agent-api.txt index f39c966..91371af 100644 --- a/doc/agent-api.txt +++ b/doc/agent-api.txt @@ -2,7 +2,7 @@ Agent hierarchy =============== Service unique name -Interface org.moblin.connman.Agent +Interface net.connman.Agent Object path freely definable Methods void Release() @@ -12,3 +12,226 @@ Methods void Release() 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 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 + + 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. + + 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. + + 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 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" }