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 Arguments       string Type
  84
  85                         Contains the type of a field. For example "psk", "wep"
  86                         "passphrase", "response", "ssid", "wpspin" or plain
  87                         "string".
  88
  89                 string Requirement
  90
  91                         Contains the requirement option. Valid values are
  92                         "mandatory", "optional" or "alternate".
  93
  94                         The "alternate" value specifies that this field can be
  95                         returned as an alternative to another one. An example
  96                         would be the network name or SSID.
  97
  98                         All "mandatory" fields must be returned, while the
  99                         "optional" can be returned if available.
 100
 101                 array{string} Alternates
 102
 103                         Contains the list of alternate field names this
 104                         field can be represented by.
 105
 106 Examples        Requesting a passphrase for WPA2 network
 107
 108                         RequestInput("/service1",
 109                                 { "Passphrase" : { "Type" : "psk",
 110                                                    "Requirement" : "mandatory"
 111                                                  }
 112                                 }
 113                         ==> { "Passphrase" : "secret123" }
 114
 115                 Requesting name for hidden network
 116
 117                         RequestInput("/service2",
 118                                 { "Name" : { "Type"        : "string",
 119                                              "Requirement" : "mandatory",
 120                                              "Alternates"  : [ "SSID" ]
 121                                            },
 122                                   "SSID" : { "Type" : "ssid",
 123                                              "Requirement" : "alternate"
 124                                            }
 125                                 }
 126                         ==> { "Name" : "My hidden network" }
 127
 128                 Requesting a passphrase for a WPA2 network with WPS alternative:
 129
 130                         RequestInput("/service3",
 131                                 { "Passphrase" : { "Type"        : "psk",
 132                                                    "Requirement" : "mandatory",
 133                                                    "Alternates"  : [ "WPS" ]
 134                                                  },
 135                                   "WPS"        : { "Type"        : "wpspin",
 136                                                    "Requirement" : "alternate"
 137                                                  }
 138                                 }
 139
 140                         ==> { "WPS" : "123456" }
 141
 142                 Requesting passphrase for a WPA-Enterprise network:
 143
 144                         RequestInput("/service4",
 145                                 { "Identity"   : { "Type"        : "string",
 146                                                    "Requirement" : "mandatory"
 147                                                  },
 148                                   "Passphrase" : { "Type" : "passphrase",
 149                                                    "Requirement" : "mandatory"
 150                                                  }
 151                                 }
 152
 153                         ==> { "Identity" : "alice", "Passphrase": "secret123" }
 154
 155                 Requesting challenge response for a WPA-Enterprise network:
 156
 157                         RequestInput("/service4",
 158                                 { "Identity"   : { "Type"        : "string",
 159                                                    "Requirement" : "mandatory"
 160                                                  },
 161                                   "Passphrase" : { "Type" : "response",
 162                                                    "Requirement" : "mandatory"
 163                                                  }
 164                                 }
 165
 166                         ==> { "Identity" : "bob", "Passphrase": "secret123" }