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                         Possible Errors: net.connman.Agent.Error.Canceled
  55
  56                 void Cancel()
  57
  58                         This method gets called to indicate that the agent
  59                         request failed before a reply was returned.
  60
  61 Fields          string Name
  62
  63                         The name of a network. This field will be requested
  64                         when trying to connect to a hidden network.
  65
  66                 array{byte} SSID
  67
  68                         This field is an alternative to "Name" for WiFi
  69                         networks and can be used to return the exact binary
  70                         representation of a network name.
  71
  72                         Normally returning the "Name" field is the better
  73                         option here.
  74
  75                 string Identity
  76
  77                         Identity (username) for EAP authentication methods.
  78
  79                 string Passphrase
  80
  81                         The passphrase for authentication. For example a WEP
  82                         key, a PSK passphrase or a passphrase for EAP
  83                         authentication methods.
  84
  85                 string WPS
  86
  87                         This field requests the use of WPS to get associated.
  88                         This is an alternate choice against Passphrase when
  89                         requested service supports WPS. The reply can contain
  90                         either empty pin, if user wants to use push-button
  91                         method, or a pin code if user wants to use the pin
  92                         method.
  93
  94                 string Username
  95
  96                         Username for WISPr authentication. This field will be
  97                         requested when connecting to a WISPr-enabled hotspot.
  98
  99                 string Password
 100
 101                         Password for WISPr authentication. This field will be
 102                         requested when connecting to a WISPr-enabled hotspot.
 103
 104 Arguments       string Type
 105
 106                         Contains the type of a field. For example "psk", "wep"
 107                         "passphrase", "response", "ssid", "wpspin" or plain
 108                         "string".
 109
 110                 string Requirement
 111
 112                         Contains the requirement option. Valid values are
 113                         "mandatory", "optional" or "alternate".
 114
 115                         The "alternate" value specifies that this field can be
 116                         returned as an alternative to another one. An example
 117                         would be the network name or SSID.
 118
 119                         All "mandatory" fields must be returned, while the
 120                         "optional" can be returned if available.
 121
 122                 array{string} Alternates
 123
 124                         Contains the list of alternate field names this
 125                         field can be represented by.
 126
 127 Examples        Requesting a passphrase for WPA2 network
 128
 129                         RequestInput("/service1",
 130                                 { "Passphrase" : { "Type" : "psk",
 131                                                    "Requirement" : "mandatory"
 132                                                  }
 133                                 }
 134                         ==> { "Passphrase" : "secret123" }
 135
 136                 Requesting name for hidden network
 137
 138                         RequestInput("/service2",
 139                                 { "Name" : { "Type"        : "string",
 140                                              "Requirement" : "mandatory",
 141                                              "Alternates"  : [ "SSID" ]
 142                                            },
 143                                   "SSID" : { "Type" : "ssid",
 144                                              "Requirement" : "alternate"
 145                                            }
 146                                 }
 147                         ==> { "Name" : "My hidden network" }
 148
 149                 Requesting a passphrase for a WPA2 network with WPS alternative:
 150
 151                         RequestInput("/service3",
 152                                 { "Passphrase" : { "Type"        : "psk",
 153                                                    "Requirement" : "mandatory",
 154                                                    "Alternates"  : [ "WPS" ]
 155                                                  },
 156                                   "WPS"        : { "Type"        : "wpspin",
 157                                                    "Requirement" : "alternate"
 158                                                  }
 159                                 }
 160
 161                         ==> { "WPS" : "123456" }
 162
 163                 Requesting passphrase for a WPA-Enterprise network:
 164
 165                         RequestInput("/service4",
 166                                 { "Identity"   : { "Type"        : "string",
 167                                                    "Requirement" : "mandatory"
 168                                                  },
 169                                   "Passphrase" : { "Type" : "passphrase",
 170                                                    "Requirement" : "mandatory"
 171                                                  }
 172                                 }
 173
 174                         ==> { "Identity" : "alice", "Passphrase": "secret123" }
 175
 176                 Requesting challenge response for a WPA-Enterprise network:
 177
 178                         RequestInput("/service4",
 179                                 { "Identity"   : { "Type"        : "string",
 180                                                    "Requirement" : "mandatory"
 181                                                  },
 182                                   "Passphrase" : { "Type" : "response",
 183                                                    "Requirement" : "mandatory"
 184                                                  }
 185                                 }
 186
 187                         ==> { "Identity" : "bob", "Passphrase": "secret123" }
 188
 189                 Requesting username and password for a WISPr-enabled hotspot:
 190
 191                         RequestInput("/service5",
 192                                 { "Username"   : { "Type"        : "string",
 193                                                    "Requirement" : "mandatory"
 194                                                  },
 195                                   "Password"   : { "Type"        : "passphrase",
 196                                                    "Requirement" : "mandatory"
 197                                                  }
 198                                 }
 199
 200                         ==> { "Username" : "foo", "Password": "secret" }