dnsproxy: Only one copy of the relevant buffers will be made to a TCP request

[framework/connectivity/connman.git] / doc / agent-api.txt

diff --git a/doc/agent-api.txt b/doc/agent-api.txt
index 98499a3..8201ac1 100644 (file)
--- a/doc/agent-api.txt
+++ b/doc/agent-api.txt
@@ -23,6 +23,17 @@ Methods              void Release()
 
                        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
@@ -40,7 +51,12 @@ 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
 
                void Cancel()
 
@@ -61,10 +77,24 @@ 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 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
 
@@ -75,10 +105,22 @@ Fields             string Name
                        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", "ssid", "wpspin" or plain "string".
+                       Contains the type of a field. For example "psk", "wep"
+                       "informational", "passphrase", "response", "ssid",
+                       "wpspin" or plain "string". "informational" has no
+                       "Requirement" but a "Value".
 
                string Requirement
 
@@ -97,15 +139,32 @@ Arguments  string Type
                        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"  : "informational",
+                                                 "Value" : "secret123"
+                                               }
+                               }
+
                Requesting name for hidden network
 
                        RequestInput("/service2",
@@ -113,9 +172,9 @@ 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" }
 
@@ -127,8 +186,47 @@ Examples   Requesting a passphrase for WPA2 network
                                                   "Alternates"  : [ "WPS" ]
                                                 },
                                  "WPS"        : { "Type"        : "wpspin",
-                                                  "Requirement" : "alternate"
+                                                  "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" }