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 Passphrase
  65
  66                         The passphrase for a network. For example a WEP
  67                         key or a PSK passphrase.
  68
  69                 string WPS
  70
  71                         This field requests the use of WPS to get associated.
  72                         This is an alternate choice against Passphrase when
  73                         requested service supports WPS. The reply can contain
  74                         either empty pin, if user wants to use push-button
  75                         method, or a pin code if user wants to use the pin
  76                         method.
  77
  78 Arguments       string Type
  79
  80                         Contains the type of a field. For example "psk",
  81                         "wep", "ssid", "wpspin" or plain "string".
  82
  83                 string Requirement
  84
  85                         Contains the requirement option. Valid values are
  86                         "mandatory", "optional" or "alternate".
  87
  88                         The "alternate" value specifies that this field can be
  89                         returned as an alternative to another one. An example
  90                         would be the network name or SSID.
  91
  92                         All "mandatory" fields must be returned, while the
  93                         "optional" can be returned if available.
  94
  95                 array{string} Alternates
  96
  97                         Contains the list of alternate field names this
  98                         field can be represented by.
  99
 100 Examples        Requesting a passphrase for WPA2 network
 101
 102                         RequestInput("/service1",
 103                                 { "Passphrase" : { "Type" : "psk",
 104                                                    "Requirement" : "mandatory"
 105                                                  }
 106                                 }
 107                         ==> { "Passphrase" : "secret123" }
 108
 109                 Requesting name for hidden network
 110
 111                         RequestInput("/service2",
 112                                 { "Name" : { "Type"        : "string",
 113                                              "Requirement" : "mandatory",
 114                                              "Alternates"  : [ "SSID" ]
 115                                            },
 116                                   "SSID" : { "Type" : "ssid",
 117                                              "Requirement" : "alternate"
 118                                            }
 119                                 }
 120                         ==> { "Name" : "My hidden network" }
 121
 122                 Requesting a passphrase for a WPA2 network with WPS alternative:
 123
 124                         RequestInput("/service3",
 125                                 { "Passphrase" : { "Type"        : "psk",
 126                                                    "Requirement" : "mandatory",
 127                                                    "Alternates"  : [ "WPS" ]
 128                                                  },
 129                                   "WPS"        : { "Type"        : "wpspin",
 130                                                    "Requirement" : "alternate"
 131                                                  }
 132                                 }
 133
 134                         ==> { "WPS" : "123456" }