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