Add more details and examples for agent API

[platform/upstream/connman.git] / doc / agent-api.txt

diff --git a/doc/agent-api.txt b/doc/agent-api.txt
index 27bd321..1aa06b6 100644 (file)
--- a/doc/agent-api.txt
+++ b/doc/agent-api.txt
@@ -1,17 +1,111 @@
 Agent hierarchy
-***************
+===============
 
-Service name   [unique name]
-Interface name org.freedesktop.connman.Agent
-Object path    [random object]
+Service                unique name
+Interface      org.moblin.connman.Agent
+Object path    freely definable
 
 Methods                void Release()
 
+                       This method gets called when the service daemon
+                       unregisters the agent. An agent can use it to do
+                       cleanup tasks. There is no need to unregister the
+                       agent, because when this method gets called it has
+                       already been unregistered.
 
-Method: Release
-===============
-This method will be called when the core releases the agent. This normally
-happens when the core shuts down.
+               void ReportError(object service, string error)
+
+                       This method gets called when an error has to be
+                       reported to the user.
+
+                       A special return value can be used to trigger a
+                       retry of the failed transaction.
+
+                       Possible Errors: [service].Error.Retry
+
+               dict RequestInput(object service, dict fields)
+
+                       This method gets called when trying to connect to
+                       a service and some extra input is required. For
+                       example a passphrase or the name of a hidden network.
+
+                       The return value should be a dictionary where the
+                       keys are the field names and the values are the
+                       actual fields. Alternative an error indicating that
+                       the request got cannceled can be returned.
+
+                       Most common return field names are "Name" and of
+                       course "Passphrase".
+
+                       The dictionary arguments contains field names with
+                       their input parameters.
+
+                       Possible Errors: [service].Error.Canceled
+
+               void Cancel()
+
+                       This method gets called to indicate that the agent
+                       request failed before a reply was returned.
+
+Fields         string Name
+
+                       The name of a network. This field will be requested
+                       when trying to connect to a hidden network.
+
+               array{byte} SSID
+
+                       This field is an alternative to "Name" for WiFi
+                       networks and can be used to return the exact binary
+                       representation of a network name.
+
+                       Normally returning the "Name" field is the better
+                       option here.
+
+               string Passphrase
+
+                       The passphrase for a network. For example a WEP
+                       key or a PSK passphrase.
+
+Arguments      string Type
+
+                       Contains the type of a field. For example "psk",
+                       "wep", "ssid" or plain "string".
+
+               string Requirement
+
+                       Contains the requirement option. Valid values are
+                       "mandatory", "optional" or "alternate".
+
+                       The "alternate" specifies that this field can be
+                       return as an alternative to another one. An example
+                       would be the network name or SSID.
+
+                       All "mandatory" fields must be returned, while the
+                       "optional" can be returned if available.
+
+               array{string} Alternates
+
+                       Contains the list of alternate field names this
+                       field can be represented by.
+
+Examples       Requesting a passphrase for WPA2 network
+
+                       RequestInput("/service1",
+                               { "Passphrase" : { "Type" : "psk",
+                                                  "Requirement" : "mandatory"
+                                                }
+                               }
+                       ==> { "Passphrase" : "secret123" }
+
+               Requesting name for hidden network
 
-To get notified when the core exits, an agent should also watch out for the
-NameOwnerChanged from org.freedesktop.connman service.
+                       RequestInput("/service2",
+                               { "Name" : { "Type"        : "string",
+                                            "Requirement" : "mandatory",
+                                            "Alternates"  : [ "SSID" ]
+                                          },
+                                 "SSID" : { "Type" : "ssid",
+                                            "Requirement" : "alternate"
+                                          }
+                               }
+                       ==> { "Name" : "My hidden network" }