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
|
Service unique name
Interface net.connman.Notification
Object path freely definable
Methods void Release()
This method gets called when the service daemon
unregisters the session. A counter can use it to do
cleanup tasks. There is no need to unregister the
session, because when this method gets called it has
already been unregistered.
void Update(dict settings)
Sends an update of changed settings. Only settings
that are changed will be included.
Initially on every session creation this method is
called once to inform about the current settings.
Service net.connman
Interface net.connman.Session
Object path variable
Methods void Destroy()
Close the current session. This is similar to
DestroySession method on the manager interface. It
is just provided for convenience depending on how
the application wants to track the session.
void Connect()
If not connected, then attempt to connect this
session.
The usage of this method depends a little bit on
the model of the application. Some application
should not try to call Connect on any session at
all. They should just monitor if it becomes online
or gets back offline.
Others might require an active connection right now.
So for example email notification should only check
for new emails when a connection is available. However
if the user presses the button for get email or wants
to send an email it should request to get online with
this method.
Depending on the bearer settings the current service
is used or a new service will be connected.
This method returns immediately after it has been
called. The application is informed through the update
notification about the state of the session.
It is also not guaranteed that a session stays online
after this method call. It can be taken offline at any
time. This might happen because of idle timeouts or
other reasons.
It is safe to call this method multiple times. The
actual usage will be sorted out for the application.
void Disconnect()
This method indicates that the current session does
not need a connection anymore.
This method returns immediately. The application is
informed through the update notification about the
state of the session.
void Change(string name, variant value)
Change the value of certain settings. Not all
settings can be changed. Normally this should not
be needed or an extra session should be created.
However in some cases it makes sense to change
a value and trigger different behavior.
A change of a setting will cause an update notification
to be sent. Some changes might cause the session to
be moved to offline state.
Settings string Bearer [readonly]
This indicates the current bearer that is used
for this session. Or an empty string if no bearer
if available.
string ConnectionType [readwrite]
This is used to indicate which connection is requested
from the session. The state of the session will be
updated accordingly. Values can be nothing, 'local' or
'internet'.
'local' means the session requests to be connected,
but does not require specifically to be online.
Therefore State property will be set to 'connected' if
underlying service gets ready and/or online.
'online' means the session requests to be connected,
and online. State property will never get 'connected'
but instead will switch to 'online' if underlying
service gets online.
No value means the session requests any kind of
connection and the state will be updated on all steps,
'connected' and 'online'. This is the default value.
boolean State [readonly]
This indicates if the connection is disconnected,
connected or online. It is updated according to the
selected ConnectionType. The session will not be
in a useful shape (i.e.: providing a network connection
to the owner) until its State gets updated to connected
and/or online.
This maps to the useful port of the service state.
And it is only valid for the selected bearer
configuration. Otherwise it will be reported as
disconnected even if connected services are present.
In addition the State settings notification might
not happen right away. Notifications of this state
can be delayed based on the speed of the bearer. It
is done to avoid congestion on bearers like cellular
etc.
boolean Priority [readwrite]
This allows a session to mark itself as priority or
not. In general application are not allowed to make
themselves more important than others.
The priority handling is done internally by usage
and first come, first serve order. By default this
settings is of course false.
Internally there can be different priorities for
different application, but these are defined by a
configuration file and not via this interface.
An application that calls the method to connect
a session is preferred over other sessions. This
priority value is more for application that want to
push themselves up in the asychronization notification
queue once a bearer becomes online.
This actual priority order also depends on the
allowed bearers and other factors. This is setting
is just a little indicator of one application being
notified before another one.
For example a streaming session should set the
priority value. As soon as realtime data is involved
then this should be set. An email client should not
set this value.
string Name [readonly]
The Service name to which the system is connected.
It should only be used for displaying it in the UI
and not for getting hold on session object.
array{string} AllowedBearers [readwrite]
A list of bearers that can be used for this session.
In general this list should be empty to indicate that
any bearer is acceptable.
The order of the entries in AllowedBearers matters.
The services are sorted in the order of the bearer
entries in this list.
Also "*" matches any bearer. This is usefull to prefer
certain bearers such as Wifi with a fallback to any
other available bearer.
dict IPv4 [readonly]
Current IPv4 configuration.
dict IPv6 [readonly]
Current IPv6 configuration.
boolean AvoidHandover [readwrite]
By default this setting is false. It can be used
to indicate that a handover is currently not a good
idea. However no connection is guaranteed. So a
handover can happen anyway. This is just an indication
that the application would like to avoid it right now.
It is a bad idea to always enable this settings and
actually it will be reset after a while to avoid
congestion.
Main use case it is for application that are currently
doing a specific tasks that it prefers to finish
before allowing handovers again. An example would
be synchronization.
Never the less application needs to be aware that
handovers can happen at any time even if this is
set to true.
boolean StayConnected [readwrite]
This disables the idle timeout for this session. There
is no guarantee and this should be used with care.
If the system is not online yet this value is ignored.
uint32 PeriodicConnect [readwrite]
Indicate that a periodic connection attempt every
n minutes should be made. The minutes value is a
suggestion when to connection. There is no guarantee
that it will be made or will succeed.
A value of 0 disable this feature.
This feature is interesting for applications that
wanna check status on a regular interval. And instead
of the application waking up and trying to connect,
this can be centralized nicely and multiple wakeups
avoided in case no connection is available.
An example application would be an email client that
wants to check for new emails every 10 minutes.
On purpose the smallest setting is 1 minute here since
waking up more often and trying to set up a connection
seems rather pointless use case.
If an interval step has passed this can be nicely
rescheduled when any connection matching the bearer
settings becomes available becomes available. Using
this feature it is also easy to avoid congestion.
uint32 IdleTimeout [readwrite]
If the system is idle for given period then it should
go offline.
If the timeout is 0, this feature is disabled. If
different values are provided by several session object
the longest interval is taken as timeout value.
boolean EmergencyCall [readwrite]
Boolean representing the emergency mode of the
modem. The Emergency is true if an emergency call or
related operation is currently active.
If the emergency application sets this setting to true
all other session will be informed about the emergency
situation with setting it also to true. Only the
emergency application can set back to false.
As long the EmergencyCall is true no new session can
be created.
Only one application is supposed to write this setting
and therefore it will be protected by additional
PolicyKit rule so that only the emergency application
can write.
The emergency application is expected to call Connect()
after setting this setting true. If the emergency
situation is over the application should call
Disconnect() and also set the EmergencyCall to false
afterward.
Note only services matching the AllowedBearers rule
will be considered.
string RoamingPolicy [readwrite]
The allowed roaming behavior.
Valid policies are "national", "international",
"default", "always" and "forbidden".
"national" allows roaming within a country.
"international" allows roaming in a country and
between countries.
"default" is used to tell the Session to use
the global roaming setting.
"always" will overwrite the default "forbidden"
value which is useful for emergency application.
This value will be protected by additional PolicyKit
rule.
Default value is "forbidden".
string Interface [readonly]
Interface name used by the service object to connect.
This name can be used for SO_BINDTODEVICE in the
application.
uint32 SessionMarker [readonly]
The unique session marker can be used to mark all
traffic from the application with the SO_MARK
socket option. In combination of the EmergencyCall
this allows ConnMan to setup the firewall rules
that only traffic from the emergency application
are transmitted.
|
