summaryrefslogtreecommitdiff
path: root/doc/agent-api.txt
blob: 7ba3d5635463a2684b5af7643859a0cf8e8bdd7e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
Agent hierarchy
===============

Service		unique name
Interface	net.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.

		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.Agent.Error.Retry

		void RequestBrowser(object service, string url)

			This method gets called when it is required
			to ask the user to open a website to procceed
			with login handling.

			This can happen if connected to a hotspot portal
			page without WISPr support.

			Possible Errors: net.connman.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 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. Alternatively an error indicating that
			the request got canceled 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: net.connman.Agent.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 Identity

			Identity (username) for EAP authentication methods.

		string Passphrase

			The passphrase for authentication. For example a WEP
			key, a PSK passphrase or a passphrase for EAP
			authentication methods.

		string WPS

			This field requests the use of WPS to get associated.
			This is an alternate choice against Passphrase when
			requested service supports WPS. The reply can contain
			either empty pin, if user wants to use push-button
			method, or a pin code if user wants to use the pin
			method.

		string Username

			Username for WISPr authentication. This field will be
			requested when connecting to a WISPr-enabled hotspot.

		string Password

			Password for WISPr authentication. This field will be
			requested when connecting to a WISPr-enabled hotspot.

Arguments	string Type

			Contains the type of a field. For example "psk", "wep"
			"passphrase", "response", "ssid", "wpspin" or plain
			"string".

		string Requirement

			Contains the requirement option. Valid values are
			"mandatory", "optional" or "alternate".

			The "alternate" value specifies that this field can be
			returned 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

			RequestInput("/service2",
				{ "Name" : { "Type"        : "string",
					     "Requirement" : "mandatory",
					     "Alternates"  : [ "SSID" ]
					   },
				  "SSID" : { "Type" : "ssid",
				             "Requirement" : "alternate"
				           }
				}
			==> { "Name" : "My hidden network" }

		Requesting a passphrase for a WPA2 network with WPS alternative:

			RequestInput("/service3",
				{ "Passphrase" : { "Type"        : "psk",
						   "Requirement" : "mandatory",
						   "Alternates"  : [ "WPS" ]
						 },
				  "WPS"        : { "Type"        : "wpspin",
				                   "Requirement" : "alternate"
						 }
				}

			==> { "WPS" : "123456" }

		Requesting passphrase for a WPA-Enterprise network:

			RequestInput("/service4",
				{ "Identity"   : { "Type"        : "string",
						   "Requirement" : "mandatory"
						 },
				  "Passphrase" : { "Type" : "passphrase",
						   "Requirement" : "mandatory"
						 }
				}

			==> { "Identity" : "alice", "Passphrase": "secret123" }

		Requesting challenge response for a WPA-Enterprise network:

			RequestInput("/service4",
				{ "Identity"   : { "Type"        : "string",
						   "Requirement" : "mandatory"
						 },
				  "Passphrase" : { "Type" : "response",
						   "Requirement" : "mandatory"
						 }
				}

			==> { "Identity" : "bob", "Passphrase": "secret123" }

		Requesting username and password for a WISPr-enabled hotspot:

			RequestInput("/service5",
                                { "Username"   : { "Type"        : "string",
                                                   "Requirement" : "mandatory"
                                                 },
                                  "Password"   : { "Type"        : "passphrase",
                                                   "Requirement" : "mandatory"
                                                 }
                                }

                        ==> { "Username" : "foo", "Password": "secret" }