X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=doc%2Fagent-api.txt;h=b2becd2a5af7be8dd2a8c6574c010528dbb1f847;hb=c647a4b6f1132684c9d8b8ad71ec38d81147b278;hp=d215b9beb29edc374b98238939f00b38b071a8ec;hpb=03041f1a3a8712d5f957bf4a6b1398d1b496f5d4;p=platform%2Fupstream%2Fconnman.git diff --git a/doc/agent-api.txt b/doc/agent-api.txt old mode 100644 new mode 100755 index d215b9b..b2becd2 --- a/doc/agent-api.txt +++ b/doc/agent-api.txt @@ -23,6 +23,27 @@ Methods void Release() 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 proceed + 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 @@ -31,8 +52,10 @@ Methods void Release() 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. + actual fields. Alternatively an error indicating that + the request got canceled can be returned. + OperationAborted will be return on a successful + cancel request. Most common return field names are "Name" and of course "Passphrase". @@ -40,7 +63,31 @@ Methods void Release() 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() @@ -61,42 +108,104 @@ Fields string Name Normally returning the "Name" field is the better option here. + string Identity + + Identity (username) for EAP authentication methods. + string Passphrase - The passphrase for a network. For example a WEP - key or a PSK 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 led to a successful 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", "ssid" or plain "string". + 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" or "alternate". + "mandatory", "optional", "alternate" or + "informational". - The "alternate" specifies that this field can be - return as an alternative to another one. An example + 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. + "optional" ones can be returned if available. + + Nothing needs to be returned for "informational", as it + is here only to provide an information. 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", + { "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", @@ -104,8 +213,95 @@ Examples Requesting a passphrase for WPA2 network "Requirement" : "mandatory", "Alternates" : [ "SSID" ] }, - "SSID" : { "Type" : "ssid", - "Requirement" : "alternate" - } + "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" : "" }