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 ReportPeerError(object peer, string error)
  27
  28                         This method gets called when an error has to be
  29                         reported to the user about a peer connection.
  30
  31                         A special return value can be used to trigger a
  32                         retry of the failed transaction.
  33
  34                         Possible Errors: net.connman.Agent.Error.Retry
  35
  36                 void RequestBrowser(object service, string url)
  37
  38                         This method gets called when it is required
  39                         to ask the user to open a website to procceed
  40                         with login handling.
  41
  42                         This can happen if connected to a hotspot portal
  43                         page without WISPr support.
  44
  45                         Possible Errors: net.connman.Agent.Error.Canceled
  46
  47                 dict RequestInput(object service, dict fields)
  48
  49                         This method gets called when trying to connect to
  50                         a service and some extra input is required. For
  51                         example a passphrase or the name of a hidden network.
  52
  53                         The return value should be a dictionary where the
  54                         keys are the field names and the values are the
  55                         actual fields. Alternatively an error indicating that
  56                         the request got canceled can be returned.
  57                         OperationAborted will be return on a successfull
  58                         cancel request.
  59
  60                         Most common return field names are "Name" and of
  61                         course "Passphrase".
  62
  63                         The dictionary arguments contains field names with
  64                         their input parameters.
  65
  66                         In case of WISPr credentials requests and if the user
  67                         prefers to login through the browser by himself, agent
  68                         will have to return a LaunchBrowser error (see below).
  69
  70                         Possible Errors: net.connman.Agent.Error.Canceled
  71                                          net.connman.Agent.Error.LaunchBrowser
  72
  73                 dict RequestPeerAuthorization(object peer, dict fields) [experimental]
  74
  75                         This method gets called when trying to connect to a
  76                         peer or when an incoming peer connection is requested,
  77                         for which some extra input is required. In this case,
  78                         it will only deal with WPS input as well as accepting
  79                         or rejecting an incoming connection.
  80
  81                         The return value should be a dictionary where the
  82                         keys are the field names and the values are the
  83                         actual fields. Alternatively an error indicating that
  84                         the request got canceled or rejected can be returned.
  85
  86                         The dictionary arguments contains field names with
  87                         their input parameters.
  88
  89                         Possible Errors: net.connman.Agent.Error.Canceled
  90                                          net.connman.Agent.Error.Rejected
  91
  92                 void Cancel()
  93
  94                         This method gets called to indicate that the agent
  95                         request failed before a reply was returned.
  96
  97 Fields          string Name
  98
  99                         The name of a network. This field will be requested
 100                         when trying to connect to a hidden network.
 101
 102                 array{byte} SSID
 103
 104                         This field is an alternative to "Name" for WiFi
 105                         networks and can be used to return the exact binary
 106                         representation of a network name.
 107
 108                         Normally returning the "Name" field is the better
 109                         option here.
 110
 111                 string Identity
 112
 113                         Identity (username) for EAP authentication methods.
 114
 115                 string Passphrase
 116
 117                         The passphrase for authentication. For example a WEP
 118                         key, a PSK passphrase or a passphrase for EAP
 119                         authentication methods.
 120
 121                 string PreviousPassphrase
 122
 123                         The previous passphrase successfully saved, i.e.
 124                         which led to a successfull connection. This field is
 125                         provided as an informational argument when connecting
 126                         with it does not work anymore, for instance when it
 127                         has been changed on the AP. Such argument appears when
 128                         a RequestInput is raised after a retry. In case of WPS
 129                         association through PIN method: when retrying, the
 130                         previous wpspin will be provided.
 131
 132                 string WPS
 133
 134                         This field requests the use of WPS to get associated.
 135                         This is an alternate choice against Passphrase when
 136                         requested service supports WPS. The reply can contain
 137                         either empty pin, if user wants to use push-button
 138                         method, or a pin code if user wants to use the pin
 139                         method.
 140
 141                         In case of a RequestPeerAuthorization, this field will
 142                         be set as mandatory.
 143
 144                 string Username
 145
 146                         Username for WISPr authentication. This field will be
 147                         requested when connecting to a WISPr-enabled hotspot.
 148
 149                 string Password
 150
 151                         Password for WISPr authentication. This field will be
 152                         requested when connecting to a WISPr-enabled hotspot.
 153
 154 Arguments       string Type
 155
 156                         Contains the type of a field. For example "psk", "wep"
 157                         "passphrase", "response", "ssid", "wpspin" or plain
 158                         "string".
 159
 160                 string Requirement
 161
 162                         Contains the requirement option. Valid values are
 163                         "mandatory", "optional", "alternate" or
 164                         "informational".
 165
 166                         The "alternate" value specifies that this field can be
 167                         returned as an alternative to another one. An example
 168                         would be the network name or SSID.
 169
 170                         All "mandatory" fields must be returned, while the
 171                         "optional" ones can be returned if available.
 172
 173                         Nothing needs to be returned for "informational", as it
 174                         is here only to provide an information. A value is
 175                         attached to it.
 176
 177                 array{string} Alternates
 178
 179                         Contains the list of alternate field names this
 180                         field can be represented by.
 181
 182                 string Value
 183
 184                         Contains data as a string, relatively to an
 185                         "informational" argument.
 186
 187 Examples        Requesting a passphrase for WPA2 network
 188
 189                         RequestInput("/service1",
 190                                 { "Passphrase" : { "Type"        : "psk",
 191                                                    "Requirement" : "mandatory"
 192                                                  }
 193                                 }
 194                         ==> { "Passphrase" : "secret123" }
 195
 196                 Requesting a passphrase after an error on the previous one:
 197
 198                         RequestInput("/service1",
 199                                 { "Passphrase" : { "Type"        : "psk",
 200                                                    "Requirement" : "mandatory"
 201                                                  },
 202                                   "PreviousPassphrase" :
 203                                         { "Type"       : "psk",
 204                                           "Requirement : "informational",
 205                                           "Value"      : "secret123"
 206                                         }
 207                                 }
 208
 209                 Requesting name for hidden network
 210
 211                         RequestInput("/service2",
 212                                 { "Name" : { "Type"        : "string",
 213                                              "Requirement" : "mandatory",
 214                                              "Alternates"  : [ "SSID" ]
 215                                            },
 216                                   "SSID" : { "Type"        : "ssid",
 217                                              "Requirement" : "alternate"
 218                                            }
 219                                 }
 220                         ==> { "Name" : "My hidden network" }
 221
 222                 Requesting a passphrase for a WPA2 network with WPS alternative:
 223
 224                         RequestInput("/service3",
 225                                 { "Passphrase" : { "Type"        : "psk",
 226                                                    "Requirement" : "mandatory",
 227                                                    "Alternates"  : [ "WPS" ]
 228                                                  },
 229                                   "WPS"        : { "Type"        : "wpspin",
 230                                                    "Requirement" : "alternate"
 231                                                  }
 232                                 }
 233
 234                         ==> { "WPS" : "123456" }
 235
 236                 Requesting a passphrase for a WPA2 network with WPS alternative
 237                 after an error on the previous one:
 238
 239                         RequestInput("/service3",
 240                                 { "Passphrase" : { "Type"        : "psk",
 241                                                    "Requirement" : "mandatory",
 242                                                    "Alternates"  : [ "WPS" ]
 243                                                  },
 244                                 "WPS"          : { "Type"        : "wpspin",
 245                                                    "Requirement" : "alternate"
 246                                                  }
 247                                 "PreviousPassphrase" :
 248                                                 { "Type"       : "wpspin",
 249                                                 "Requirement : "informational",
 250                                                 "Value"      : "123456"
 251                                                 }
 252
 253                 Requesting passphrase for a WPA-Enterprise network:
 254
 255                         RequestInput("/service4",
 256                                 { "Identity"   : { "Type"        : "string",
 257                                                    "Requirement" : "mandatory"
 258                                                  },
 259                                   "Passphrase" : { "Type"        : "passphrase",
 260                                                    "Requirement" : "mandatory"
 261                                                  }
 262                                 }
 263
 264                         ==> { "Identity" : "alice", "Passphrase": "secret123" }
 265
 266                 Requesting challenge response for a WPA-Enterprise network:
 267
 268                         RequestInput("/service4",
 269                                 { "Identity"   : { "Type"        : "string",
 270                                                    "Requirement" : "mandatory"
 271                                                  },
 272                                   "Passphrase" : { "Type"        : "response",
 273                                                    "Requirement" : "mandatory"
 274                                                  }
 275                                 }
 276
 277                         ==> { "Identity" : "bob", "Passphrase": "secret123" }
 278
 279                 Requesting username and password for a WISPr-enabled hotspot:
 280
 281                         RequestInput("/service5",
 282                                 { "Username"   : { "Type"        : "string",
 283                                                    "Requirement" : "mandatory"
 284                                                  },
 285                                   "Password"   : { "Type"        : "passphrase",
 286                                                    "Requirement" : "mandatory"
 287                                                  }
 288                                 }
 289
 290                         ==> { "Username" : "foo", "Password": "secret" }
 291
 292                 Requesting a answer about an inconming peer connection:
 293
 294                         RequestPeerAuthorization("/peer3", {})
 295
 296                         ==> { }
 297
 298                 Requesting the WPS details when connecting to a peer:
 299
 300                         RequestPeerAuthorization("/peer4",
 301                                 { "WPS":
 302                                         { "Type"        : "wpspin",
 303                                           "Requirement" : "mandatory"
 304                                         }
 305                                 }
 306
 307                         ==> { "WPS" : "" }