doc/agent-api.txt

   1 Agent hierarchy
   2 ===============
   3
   4 Service         unique name
   5 Interface       net.connman.Agent
   6 Object path     freely definable
   7
   8 Methods         void Release()
   9
  10                         This method gets called when the service daemon
  11                         unregisters the agent. An agent can use it to do
  12                         cleanup tasks. There is no need to unregister the
  13                         agent, because when this method gets called it has
  14                         already been unregistered.
  15
  16                 void ReportError(object service, string error)
  17
  18                         This method gets called when an error has to be
  19                         reported to the user.
  20
  21                         A special return value can be used to trigger a
  22                         retry of the failed transaction.
  23
  24                         Possible Errors: net.connman.Agent.Error.Retry
  25
  26                 void RequestBrowser(object service, string url)
  27
  28                         This method gets called when it is required
  29                         to ask the user to open a website to procceed
  30                         with login handling.
  31
  32                         This can happen if connected to a hotspot portal
  33                         page without WISPr support.
  34
  35                         Possible Errors: net.connman.Agent.Error.Canceled
  36
  37                 dict RequestInput(object service, dict fields)
  38
  39                         This method gets called when trying to connect to
  40                         a service and some extra input is required. For
  41                         example a passphrase or the name of a hidden network.
  42
  43                         The return value should be a dictionary where the
  44                         keys are the field names and the values are the
  45                         actual fields. Alternatively an error indicating that
  46                         the request got canceled can be returned.
  47
  48                         Most common return field names are "Name" and of
  49                         course "Passphrase".
  50
  51                         The dictionary arguments contains field names with
  52                         their input parameters.
  53
  54                         In case of WISPr credentials requests and if the user
  55                         prefers to login through the browser by himself, agent
  56                         will have to return a LaunchBrowser error (see below).
  57
  58                         Possible Errors: net.connman.Agent.Error.Canceled
  59                                          net.connman.Agent.Error.LaunchBrowser
  60
  61                 void Cancel()
  62
  63                         This method gets called to indicate that the agent
  64                         request failed before a reply was returned.
  65
  66 Fields          string Name
  67
  68                         The name of a network. This field will be requested
  69                         when trying to connect to a hidden network.
  70
  71                 array{byte} SSID
  72
  73                         This field is an alternative to "Name" for WiFi
  74                         networks and can be used to return the exact binary
  75                         representation of a network name.
  76
  77                         Normally returning the "Name" field is the better
  78                         option here.
  79
  80                 string Identity
  81
  82                         Identity (username) for EAP authentication methods.
  83
  84                 string Passphrase
  85
  86                         The passphrase for authentication. For example a WEP
  87                         key, a PSK passphrase or a passphrase for EAP
  88                         authentication methods.
  89
  90                 string PreviousPassphrase
  91
  92                         The previous passphrase successfully saved, i.e.
  93                         which lead to a successfull connection. This field is
  94                         provided as an informational argument when connecting
  95                         with it does not work anymore, for instance when it
  96                         has been changed on the AP. Such argument appears when
  97                         a RequestInput is raised after a retry. In case of WPS
  98                         association through PIN method: when retrying, the
  99                         previous wpspin will be provided.
 100
 101                 string WPS
 102
 103                         This field requests the use of WPS to get associated.
 104                         This is an alternate choice against Passphrase when
 105                         requested service supports WPS. The reply can contain
 106                         either empty pin, if user wants to use push-button
 107                         method, or a pin code if user wants to use the pin
 108                         method.
 109
 110                 string Username
 111
 112                         Username for WISPr authentication. This field will be
 113                         requested when connecting to a WISPr-enabled hotspot.
 114
 115                 string Password
 116
 117                         Password for WISPr authentication. This field will be
 118                         requested when connecting to a WISPr-enabled hotspot.
 119
 120 Arguments       string Type
 121
 122                         Contains the type of a field. For example "psk", "wep"
 123                         "passphrase", "response", "ssid", "wpspin" or plain
 124                         "string".
 125
 126                 string Requirement
 127
 128                         Contains the requirement option. Valid values are
 129                         "mandatory", "optional", "alternate" or
 130                         "informational".
 131
 132                         The "alternate" value specifies that this field can be
 133                         returned as an alternative to another one. An example
 134                         would be the network name or SSID.
 135
 136                         All "mandatory" fields must be returned, while the
 137                         "optional" can be returned if available.
 138
 139                         Nothing needs to be returned for "informational", as it
 140                         is here only to provide an information so a value is
 141                         attached to it.
 142
 143                 array{string} Alternates
 144
 145                         Contains the list of alternate field names this
 146                         field can be represented by.
 147
 148                 string Value
 149
 150                         Contains data as a string, relatively to an
 151                         "informational" argument.
 152
 153 Examples        Requesting a passphrase for WPA2 network
 154
 155                         RequestInput("/service1",
 156                                 { "Passphrase" : { "Type"        : "psk",
 157                                                    "Requirement" : "mandatory"
 158                                                  }
 159                                 }
 160                         ==> { "Passphrase" : "secret123" }
 161
 162                 Requesting a passphrase after an error on the previous one:
 163
 164                         RequestInput("/service1",
 165                                 { "Passphrase" : { "Type"        : "psk",
 166                                                    "Requirement" : "mandatory"
 167                                                  },
 168                                   "PreviousPassphrase" :
 169                                         { "Type"       : "psk",
 170                                           "Requirement : "informational",
 171                                           "Value"      : "secret123"
 172                                         }
 173                                 }
 174
 175                 Requesting name for hidden network
 176
 177                         RequestInput("/service2",
 178                                 { "Name" : { "Type"        : "string",
 179                                              "Requirement" : "mandatory",
 180                                              "Alternates"  : [ "SSID" ]
 181                                            },
 182                                   "SSID" : { "Type"        : "ssid",
 183                                              "Requirement" : "alternate"
 184                                            }
 185                                 }
 186                         ==> { "Name" : "My hidden network" }
 187
 188                 Requesting a passphrase for a WPA2 network with WPS alternative:
 189
 190                         RequestInput("/service3",
 191                                 { "Passphrase" : { "Type"        : "psk",
 192                                                    "Requirement" : "mandatory",
 193                                                    "Alternates"  : [ "WPS" ]
 194                                                  },
 195                                   "WPS"        : { "Type"        : "wpspin",
 196                                                    "Requirement" : "alternate"
 197                                                  }
 198                                 }
 199
 200                         ==> { "WPS" : "123456" }
 201
 202                 Requesting a passphrase for a WPA2 network with WPS alternative
 203                 after an error on the previous one:
 204
 205                         RequestInput("/service3",
 206                                 { "Passphrase" : { "Type"        : "psk",
 207                                                    "Requirement" : "mandatory",
 208                                                    "Alternates"  : [ "WPS" ]
 209                                                  },
 210                                 "WPS"          : { "Type"        : "wpspin",
 211                                                    "Requirement" : "alternate"
 212                                                  }
 213                                 "PreviousPassphrase" :
 214                                                 { "Type"       : "wpspin",
 215                                                 "Requirement : "informational",
 216                                                 "Value"      : "123456"
 217                                                 }
 218
 219                 Requesting passphrase for a WPA-Enterprise network:
 220
 221                         RequestInput("/service4",
 222                                 { "Identity"   : { "Type"        : "string",
 223                                                    "Requirement" : "mandatory"
 224                                                  },
 225                                   "Passphrase" : { "Type"        : "passphrase",
 226                                                    "Requirement" : "mandatory"
 227                                                  }
 228                                 }
 229
 230                         ==> { "Identity" : "alice", "Passphrase": "secret123" }
 231
 232                 Requesting challenge response for a WPA-Enterprise network:
 233
 234                         RequestInput("/service4",
 235                                 { "Identity"   : { "Type"        : "string",
 236                                                    "Requirement" : "mandatory"
 237                                                  },
 238                                   "Passphrase" : { "Type"        : "response",
 239                                                    "Requirement" : "mandatory"
 240                                                  }
 241                                 }
 242
 243                         ==> { "Identity" : "bob", "Passphrase": "secret123" }
 244
 245                 Requesting username and password for a WISPr-enabled hotspot:
 246
 247                         RequestInput("/service5",
 248                                 { "Username"   : { "Type"        : "string",
 249                                                    "Requirement" : "mandatory"
 250                                                  },
 251                                   "Password"   : { "Type"        : "passphrase",
 252                                                    "Requirement" : "mandatory"
 253                                                  }
 254                                 }
 255
 256                         ==> { "Username" : "foo", "Password": "secret" }