bdef9f328808e9f2d00a2c00ae80e45885c2eb54
[platform/upstream/connman.git] / doc / vpn-agent-api.txt
1 Agent hierarchy
2 ===============
3
4 Service         unique name
5 Interface       net.connman.vpn.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.vpn.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 password or username.
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 "Username" and of
38                         course "Password".
39
40                         The dictionary arguments contains field names with
41                         their input parameters.
42
43                         Possible Errors: net.connman.vpn.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 Username
51
52                         Username for authentication. This field will be
53                         requested when connecting to L2TP and PPTP.
54
55                 string Password
56
57                         Password for authentication.
58
59                 boolean SaveCredentials
60
61                         Tells if the user wants the user credentials
62                         be saved by connman-vpnd.
63
64                 string Host
65
66                         End point of this VPN link i.e., the VPN gateway
67                         we are trying to connect to.
68
69                 string Name
70
71                         Name of the VPN connection we are trying to connect to.
72
73                 string OpenConnect.Cookie
74
75                         Return the OpenConnect cookie value that is used to
76                         authenticate the user and is specific to this user.
77
78 Arguments       string Type
79
80                         Contains the type of a field. For example "password",
81                         "response", "boolean" or plain "string".
82
83                 string Requirement
84
85                         Contains the requirement option. Valid values are
86                         "mandatory", "optional", "alternate" or
87                         "informational".
88
89                         The "alternate" value specifies that this field can be
90                         returned as an alternative to another one.
91
92                         All "mandatory" fields must be returned, while the
93                         "optional" can be returned if available.
94
95                         Nothing needs to be returned for "informational", as it
96                         is here only to provide an information so a value is
97                         attached to it.
98
99                 array{string} Alternates
100
101                         Contains the list of alternate field names this
102                         field can be represented by.
103
104                 string Value
105
106                         Contains data as a string, relatively to an
107                         "informational" argument.
108
109 Examples        Requesting a username and password for L2TP network
110
111                         RequestInput("/vpn1",
112                                 { "Username" : { "Type"        : "string",
113                                                  "Requirement" : "mandatory"
114                                                 } }
115                                 { "Password" : { "Type"        : "password",
116                                                  "Requirement" : "mandatory"
117                                                 } }
118                                 { "SaveCredentials" : { "Type" : "boolean",
119                                                 "Requirement" : "optional"
120                                                 }
121                                 }
122                         ==> { "Username" : "foo", "Password" : "secret123",
123                                 "SaveCredentials" : true }
124
125                 Requesting a OpenConnect cookie
126
127                         RequestInput("/vpn2",
128                                 { "OpenConnect.Cookie" : { "Type" : "string",
129                                                  "Requirement" : "mandatory"
130                                                         } }
131                                 { "Host" : { "Type" : "string",
132                                          "Requirement" : "informational"
133                                                         } }
134                                 { "Name" : { "Type" : "string",
135                                          "Requirement" : "informational"
136                                                         } }
137                         ==> { "OpenConnect.Cookie" : "0123456@adfsf@asasdf" }