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: [service].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. Alternative an error indicating that
  35                         the request got cannceled 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: [service].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 Passphrase
  65
  66                         The passphrase for a network. For example a WEP
  67                         key or a PSK passphrase.
  68
  69 Arguments       string Type
  70
  71                         Contains the type of a field. For example "psk",
  72                         "wep", "ssid" or plain "string".
  73
  74                 string Requirement
  75
  76                         Contains the requirement option. Valid values are
  77                         "mandatory", "optional" or "alternate".
  78
  79                         The "alternate" specifies that this field can be
  80                         return as an alternative to another one. An example
  81                         would be the network name or SSID.
  82
  83                         All "mandatory" fields must be returned, while the
  84                         "optional" can be returned if available.
  85
  86                 array{string} Alternates
  87
  88                         Contains the list of alternate field names this
  89                         field can be represented by.
  90
  91 Examples        Requesting a passphrase for WPA2 network
  92
  93                         RequestInput("/service1",
  94                                 { "Passphrase" : { "Type" : "psk",
  95                                                    "Requirement" : "mandatory"
  96                                                  }
  97                                 }
  98                         ==> { "Passphrase" : "secret123" }
  99
 100                 Requesting name for hidden network
 101
 102                         RequestInput("/service2",
 103                                 { "Name" : { "Type"        : "string",
 104                                              "Requirement" : "mandatory",
 105                                              "Alternates"  : [ "SSID" ]
 106                                            },
 107                                   "SSID" : { "Type" : "ssid",
 108                                              "Requirement" : "alternate"
 109                                            }
 110                                 }
 111                         ==> { "Name" : "My hidden network" }