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