doc: Describe VPN agent API

diff --git a/doc/vpn-agent-api.txt b/doc/vpn-agent-api.txt
new file mode 100644 (file)
index 0000000..bdef9f3
--- /dev/null
+++ b/doc/vpn-agent-api.txt
@@ -0,0 +1,137 @@
+Agent hierarchy
+===============
+
+Service                unique name
+Interface      net.connman.vpn.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.
+
+               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: net.connman.vpn.Agent.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 password or username.
+
+                       The return value should be a dictionary where the
+                       keys are the field names and the values are the
+                       actual fields. Alternatively an error indicating that
+                       the request got canceled can be returned.
+
+                       Most common return field names are "Username" and of
+                       course "Password".
+
+                       The dictionary arguments contains field names with
+                       their input parameters.
+
+                       Possible Errors: net.connman.vpn.Agent.Error.Canceled
+
+               void Cancel()
+
+                       This method gets called to indicate that the agent
+                       request failed before a reply was returned.
+
+Fields         string Username
+
+                       Username for authentication. This field will be
+                       requested when connecting to L2TP and PPTP.
+
+               string Password
+
+                       Password for authentication.
+
+               boolean SaveCredentials
+
+                       Tells if the user wants the user credentials
+                       be saved by connman-vpnd.
+
+               string Host
+
+                       End point of this VPN link i.e., the VPN gateway
+                       we are trying to connect to.
+
+               string Name
+
+                       Name of the VPN connection we are trying to connect to.
+
+               string OpenConnect.Cookie
+
+                       Return the OpenConnect cookie value that is used to
+                       authenticate the user and is specific to this user.
+
+Arguments      string Type
+
+                       Contains the type of a field. For example "password",
+                       "response", "boolean" or plain "string".
+
+               string Requirement
+
+                       Contains the requirement option. Valid values are
+                       "mandatory", "optional", "alternate" or
+                       "informational".
+
+                       The "alternate" value specifies that this field can be
+                       returned as an alternative to another one.
+
+                       All "mandatory" fields must be returned, while the
+                       "optional" can be returned if available.
+
+                       Nothing needs to be returned for "informational", as it
+                       is here only to provide an information so a value is
+                       attached to it.
+
+               array{string} Alternates
+
+                       Contains the list of alternate field names this
+                       field can be represented by.
+
+               string Value
+
+                       Contains data as a string, relatively to an
+                       "informational" argument.
+
+Examples       Requesting a username and password for L2TP network
+
+                       RequestInput("/vpn1",
+                               { "Username" : { "Type"        : "string",
+                                                "Requirement" : "mandatory"
+                                               } }
+                               { "Password" : { "Type"        : "password",
+                                                "Requirement" : "mandatory"
+                                               } }
+                               { "SaveCredentials" : { "Type" : "boolean",
+                                               "Requirement" : "optional"
+                                               }
+                               }
+                       ==> { "Username" : "foo", "Password" : "secret123",
+                               "SaveCredentials" : true }
+
+               Requesting a OpenConnect cookie
+
+                       RequestInput("/vpn2",
+                               { "OpenConnect.Cookie" : { "Type" : "string",
+                                                "Requirement" : "mandatory"
+                                                       } }
+                               { "Host" : { "Type" : "string",
+                                        "Requirement" : "informational"
+                                                       } }
+                               { "Name" : { "Type" : "string",
+                                        "Requirement" : "informational"
+                                                       } }
+                       ==> { "OpenConnect.Cookie" : "0123456@adfsf@asasdf" }