summaryrefslogtreecommitdiff
path: root/doc/service-api.txt
blob: c9dd7e2f4b77239f57e874d3f77acf0511b15be6 (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
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
Service hierarchy
=================

Service		net.connman
Interface	net.connman.Service
Object path	[variable prefix]/{service0,service1,...}

Methods		dict GetProperties()  [deprecated]

			Returns properties for the service object. See
			the properties section for available properties.

			Usage of this method is highly discouraged. Use
			the Manager.GetServices() method instead.

			Possible Errors: [service].Error.InvalidArguments

		void SetProperty(string name, variant value)

			Changes the value of the specified property. Only
			properties that are listed as read-write are
			changeable. On success a PropertyChanged signal
			will be emitted.

			Properties cannot be set for hidden WiFi service
			entries or provisioned services.

			Possible Errors: [service].Error.InvalidArguments
					 [service].Error.InvalidProperty

		void ClearProperty(string name)

			Clears the value of the specified property.

			Properties cannot be cleared for hidden WiFi service
			entries or provisioned services.

			Possible Errors: [service].Error.InvalidArguments
					 [service].Error.InvalidProperty

		void Connect()

			Connect this service. It will attempt to connect
			WiFi or Bluetooth services.

			For Ethernet devices this method can only be used
			if it has previously been disconnected. Otherwise
			the plugging of a cable will trigger connecting
			automatically. If no cable is plugged in this method
			will fail.

			This method call will only return in case of an
			error or when the service is fully connected. So
			setting a longer D-Bus timeout might be a really
			good idea.

			Calling Connect() on a hidden WiFi service entry will
			query the missing SSID via the Agent API causing a
			WiFi service with the given SSID to be scanned,
			created and connected.

			Possible Errors: [service].Error.InvalidArguments

		void Disconnect()

			Disconnect this service. If the service is not
			connected an error message will be generated.

			On Ethernet devices this will disconnect the IP
			details from the service. It will not magically
			unplug the cable. When no cable is plugged in this
			method will fail.

			This method can also be used to abort a previous
			connection attempt via the Connect method.

			Hidden WiFi service entries cannot be disconnected
			as they always stay in idle state.

			Possible Errors: [service].Error.InvalidArguments

		void Remove()

			A successfully connected service with Favorite=true
			can be removed this way. If it is connected, it will
			be automatically disconnected first.

			If the service requires a passphrase it will be
			cleared and forgotten when removing.

			This is similar to setting the Favorite property
			to false, but that is currently not supported.

			In the case a connection attempt failed and the
			service is in the State=failure, this method can
			also be used to reset the service.

			Calling this method on Ethernet devices, hidden WiFi
			services or provisioned services will cause an error
			message. It is not possible to remove these kind of
			services.

			Possible Errors: [service].Error.InvalidArguments

		void MoveBefore(object service)

			If a service has been used before, this allows a
			reorder of the favorite services.

			Possible Errors: [service].Error.InvalidArguments

		void MoveAfter(object service)

			If a service has been used before, this allows a
			reorder of the favorite services.

			Possible Errors: [service].Error.InvalidArguments

		void ResetCounters()  [experimental]

			Reset the counter statistics.

			Possible Errors: None

Signals		PropertyChanged(string name, variant value)

			This signal indicates a changed value of the given
			property.

Properties	string State [readonly]

			The service state information.

			Valid states are "idle", "failure", "association",
			"configuration", "ready", "disconnect" and "online".

			The "ready" state signals a successfully
			connected device. "online" signals that an
			Internet connection is available and has been
			verified.

			See doc/overview-api.txt for more information about
			state transitions.

		string Error [readonly]

			The service error status details.

			When error occur during connection or disconnection
			the detailed information is represented in this
			property to help the user interface to present the
			user with alternate options.

			This property is only valid when the service is in
			the "failure" state. Otherwise it might be empty or
			not present at all.

			Current defined error code is "dhcp-failed".

		string Name [readonly]

			The service name (for example "Wireless" etc.)

			This name can be used for directly displaying it in
			the application. It has pure informational purpose
			and no attempt should be made to translate it.

			For Ethernet devices and hidden WiFi networks this
			property is not present.

		string Type [readonly]

			The service type (for example "ethernet", "wifi" etc.)

			This information should only be used to determine
			advanced properties or showing the correct icon
			to the user.

			Together with a missing Name property, this can
			be used to identify hidden WiFi networks.

		array{string} Security [readonly]

			If the service type is WiFi, then this property is
			present and contains the list of security methods
			or key management settings.

			Possible values are "none", "wep", "psk", "ieee8021x"
			and also "wps".

			This property might be only present for WiFi
			services.

		uint8 Strength [readonly]

			Indicates the signal strength of the service. This
			is a normalized value between 0 and 100.

			This property will not be present for Ethernet
			devices.

		boolean Favorite [readonly]

			Will be true if a cable is plugged in or the user
			selected and successfully connected to this service.

			This value is automatically changed and to revert
			it back to false the Remove() method needs to be
			used.

		boolean Immutable [readonly]

			This value will be set to true if the service is
			configured externally via a configuration file.

			The only valid operation are Connect() and of
			course Disconnect(). The Remove() method will
			result in an error.

		boolean AutoConnect [readwrite]

			If set to true, this service will auto-connect
			when no other connection is available.

			The service won't auto-connect while roaming.

			For favorite services it is possible to change
			this value to prevent or permit automatic
			connection attempts.

		boolean Roaming [readonly]

			This property indicates if this service is roaming.

			In the case of Cellular services this normally
			indicates connections to a foreign provider when
			traveling abroad.

		array{string} Nameservers [readonly]

			The list of currently active nameservers for this
			service. If the server is not in READY or ONLINE
			state than this list will be empty.

			Global nameservers are automatically added to this
			list. The array represents a sorted list of the
			current nameservers. The first one has the highest
			priority and is used by default.

			When using DHCP this array represents the nameservers
			provided by the network. In case of manual settings,
			the ones from Nameservers.Configuration are used.

		array{string} Nameservers.Configuration [readwrite]

			The list of manually configured domain name
			servers. Some cellular networks don't provide
			correct name servers and this allows for an
			override.

			This array is sorted by priority and the first
			entry in the list represents the nameserver with
			the highest priority.

			When using manual configuration and no global
			nameservers are configured, then it is useful
			to configure this setting.

			Changes to the domain name servers can be done
			at any time. It will not cause a disconnect of
			the service. However there might be small window
			where name resolution might fail.

		array{string} Timeservers [readonly]

			The list of currently active timeservers for this
			service. If the server is not in READY or ONLINE
			state than this list will be empty.

		array{string} Timeservers.Configuration [readwrite]

			The list of manually configured time servers.

			The first entry in the list represents the
			timeserver with the highest priority.

			When using manual configuration this setting
			is useful to override all the other timeserver
			settings. This is service specific, hence only
			the values for the default service are used.

			Changes to this property will result in restart
			of NTP query.

		array{string} Domains [readonly]

			The list of currently used search domains taken
			from Domains.Configurations if set, otherwise a
			domain name if provided by DHCP or VPNs.

		array{string} Domains.Configuration [readwrite]

			The list of manually configured search domains.

		dict IPv4 [readonly]

			string Method [readonly]

				Possible values are "dhcp", "manual"
				and "off".

				The value "fixed" indicates an IP address
				that can not be modified. For example
				cellular networks return fixed information.

			string Address [readonly]

				The current configured IPv4 address.

			string Netmask [readonly]

				The current configured IPv4 netmask.

			string Gateway [readonly]

				The current configured IPv4 gateway.

		dict IPv4.Configuration [readwrite]

			Same values as IPv4 property. The IPv4 represents
			the actual system configuration while this allows
			user configuration.

			Changing these settings will cause a state change
			of the service. The service will become unavailable
			until the new configuration has been successfully
			installed.

		dict IPv6 [readonly]

			string Method [readonly]

				Possible values are "auto", "manual", "6to4"
				and "off".

				The value "fixed" indicates an IP address
				that can not be modified. For example
				cellular networks return fixed information.
				The value "6to4" is returned if 6to4 tunnel
				is created by connman. The tunnel can only be
				created if method was set to "auto" by the
				user. User cannot set the method to "6to4".

			string Address [readonly]

				The current configured IPv6 address.

			uint8 PrefixLength [readonly]

				The prefix length of the IPv6 address.

			string Gateway [readonly]

				The current configured IPv6 gateway.

			string Privacy [readonly]

				Enable or disable IPv6 privacy extension
				that is described in RFC 4941. The value
				has only meaning if Method is set to "auto".

				Value "disabled" means that privacy extension
				is disabled and normal autoconf addresses are
				used.

				Value "enabled" means that privacy extension is
				enabled and system prefers to use public
				addresses over temporary addresses.

				Value "prefered" means that privacy extension is
				enabled and system prefers temporary addresses
				over public addresses.

				Default value is "disabled".

		dict IPv6.Configuration [readwrite]

			Same values as IPv6 property. The IPv6 represents
			the actual system configuration while this allows
			user configuration.

			Changing these settings will cause a state change
			of the service. The service will become unavailable
			until the new configuration has been successfully
			installed.

		dict Proxy [readonly]

			string Method [readonly]

				Possible values are "direct", "auto" and
				"manual".

				In case of "auto" method, the URL file can be
				provided unless you want to let DHCP/WPAD
				auto-discover to be tried. In such case if DHCP
				and WPAD auto-discover methods fails then
				method will be "direct".

				In case of "direct" no additional information
				are provided. For the "manual" method the
				Servers have to be set, Excludes is optional.

			string URL [readonly]

				Automatic proxy configuration URL. Used by
				"auto" method.

			array{string} Servers [readonly]

				Used when "manual" method is set.

				List of proxy URIs. The URI without a protocol
				will be interpreted as the generic proxy URI.
				All others will target a specific protocol and
				only once.

				Example for generic proxy server entry would
				be like this: "server.example.com:911".

			array{string} Excludes [readonly]

				Used when "manual" method is set.

				List of hosts which can be accessed directly.

		dict Proxy.Configuration [readwrite]

			Same values as Proxy property. The Proxy represents
			the actual system configuration while this allows
			user configuration.

			If "auto" method is set with an empty URL, then
			DHCP/WPAD auto-discover will be tried. Otherwise the
			specified URL will be used.

		dict Provider [readonly]

			string Host [readonly]

				VPN host IP.

			string Domain [readonly]

				VPN Domain.

			string Name [readonly]

				VPN provider Name.

			string Type [readonly]

				VPN provider type.

		dict Ethernet [readonly]

			string Method [readonly]

				Possible values are "auto" and "manual".

			string Interface [readonly]

				Interface name (for example eth0).

			string Address [readonly]

				Ethernet device address (MAC address).

			uint16 MTU [readonly]

				The Ethernet MTU (default is 1500).

			uint16 Speed [readonly] [deprecated]

				Selected speed of the line.

				This information is not available.

			string Duplex [readonly] [deprecated]

				Selected duplex settings of the line.
				Possible values are "half" and "full".

				This information is not available.