2 Interface net.connman.Notification
3 Object path freely definable
7 This method gets called when the service daemon
8 unregisters the session. A counter can use it to do
9 cleanup tasks. There is no need to unregister the
10 session, because when this method gets called it has
11 already been unregistered.
13 void Update(dict settings)
15 Sends an update of changed settings. Only settings
16 that are changed will be included.
18 Initially on every session creation this method is
19 called once to inform about the current settings.
23 Interface net.connman.Session
26 Methods void Destroy()
28 Close the current session. This is similar to
29 DestroySession method on the manager interface. It
30 is just provided for convenience depending on how
31 the application wants to track the session.
35 If not connected, then attempt to connect this
38 The usage of this method depends a little bit on
39 the model of the application. Some application
40 should not try to call Connect on any session at
41 all. They should just monitor if it becomes online
44 Others might require an active connection right now.
45 So for example email notification should only check
46 for new emails when a connection is available. However
47 if the user presses the button for get email or wants
48 to send an email it should request to get online with
51 Depending on the bearer settings the current service
52 is used or a new service will be connected.
54 This method returns immediately after it has been
55 called. The application is informed through the update
56 notification about the state of the session.
58 It is also not guaranteed that a session stays online
59 after this method call. It can be taken offline at any
60 time. This might happen because of idle timeouts or
63 It is safe to call this method multiple times. The
64 actual usage will be sorted out for the application.
68 This method indicates that the current session does
69 not need a connection anymore.
71 This method returns immediately. The application is
72 informed through the update notification about the
75 void Change(string name, variant value)
77 Change the value of certain settings. Not all
78 settings can be changed. Normally this should not
79 be needed or an extra session should be created.
80 However in some cases it makes sense to change
81 a value and trigger different behavior.
83 A change of a setting will cause an update notification
84 to be sent. Some changes might cause the session to
85 be moved to offline state.
87 Settings string Bearer [readonly]
89 This indicates the current bearer that is used
90 for this session. Or an empty string if no bearer
93 string ConnectionType [readwrite]
95 This is used to indicate which connection is requested
96 from the session. The state of the session will be
97 updated accordingly. Values can be nothing, 'local' or
99 'local' means the session requests to be connected,
100 but does not require specifically to be online.
101 Therefore State property will be set to 'connected' if
102 underlying service gets ready and/or online.
103 'online' means the session requests to be connected,
104 and online. State property will never get 'connected'
105 but instead will switch to 'online' if underlying
107 No value means the session requests any kind of
108 connection and the state will be updated on all steps,
109 'connected' and 'online'. This is the default value.
111 boolean State [readonly]
113 This indicates if the connection is disconnected,
114 connected or online. It is updated according to the
115 selected ConnectionType. The session will not be
116 in a useful shape (i.e.: providing a network connection
117 to the owner) until its State gets updated to connected
120 This maps to the useful port of the service state.
121 And it is only valid for the selected bearer
122 configuration. Otherwise it will be reported as
123 disconnected even if connected services are present.
125 In addition the State settings notification might
126 not happen right away. Notifications of this state
127 can be delayed based on the speed of the bearer. It
128 is done to avoid congestion on bearers like cellular
131 boolean Priority [readwrite]
133 This allows a session to mark itself as priority or
134 not. In general application are not allowed to make
135 themselves more important than others.
137 The priority handling is done internally by usage
138 and first come, first serve order. By default this
139 settings is of course false.
141 Internally there can be different priorities for
142 different application, but these are defined by a
143 configuration file and not via this interface.
145 An application that calls the method to connect
146 a session is preferred over other sessions. This
147 priority value is more for application that want to
148 push themselves up in the asychronization notification
149 queue once a bearer becomes online.
151 This actual priority order also depends on the
152 allowed bearers and other factors. This is setting
153 is just a little indicator of one application being
154 notified before another one.
156 For example a streaming session should set the
157 priority value. As soon as realtime data is involved
158 then this should be set. An email client should not
161 string Name [readonly]
163 The Service name to which the system is connected.
164 It should only be used for displaying it in the UI
165 and not for getting hold on session object.
167 array{string} AllowedBearers [readwrite]
169 A list of bearers that can be used for this session.
170 In general this list should be empty to indicate that
171 any bearer is acceptable.
173 The order of the entries in AllowedBearers matters.
174 The services are sorted in the order of the bearer
175 entries in this list.
177 Also "*" matches any bearer. This is usefull to prefer
178 certain bearers such as Wifi with a fallback to any
179 other available bearer.
183 Current IPv4 configuration.
187 Current IPv6 configuration.
189 boolean AvoidHandover [readwrite]
191 By default this setting is false. It can be used
192 to indicate that a handover is currently not a good
193 idea. However no connection is guaranteed. So a
194 handover can happen anyway. This is just an indication
195 that the application would like to avoid it right now.
197 It is a bad idea to always enable this settings and
198 actually it will be reset after a while to avoid
201 Main use case it is for application that are currently
202 doing a specific tasks that it prefers to finish
203 before allowing handovers again. An example would
206 Never the less application needs to be aware that
207 handovers can happen at any time even if this is
210 boolean StayConnected [readwrite]
212 This disables the idle timeout for this session. There
213 is no guarantee and this should be used with care.
215 If the system is not online yet this value is ignored.
217 uint32 PeriodicConnect [readwrite]
219 Indicate that a periodic connection attempt every
220 n minutes should be made. The minutes value is a
221 suggestion when to connection. There is no guarantee
222 that it will be made or will succeed.
224 A value of 0 disable this feature.
226 This feature is interesting for applications that
227 wanna check status on a regular interval. And instead
228 of the application waking up and trying to connect,
229 this can be centralized nicely and multiple wakeups
230 avoided in case no connection is available.
232 An example application would be an email client that
233 wants to check for new emails every 10 minutes.
235 On purpose the smallest setting is 1 minute here since
236 waking up more often and trying to set up a connection
237 seems rather pointless use case.
239 If an interval step has passed this can be nicely
240 rescheduled when any connection matching the bearer
241 settings becomes available becomes available. Using
242 this feature it is also easy to avoid congestion.
244 uint32 IdleTimeout [readwrite]
246 If the system is idle for given period then it should
249 If the timeout is 0, this feature is disabled. If
250 different values are provided by several session object
251 the longest interval is taken as timeout value.
253 boolean EmergencyCall [readwrite]
255 Boolean representing the emergency mode of the
256 modem. The Emergency is true if an emergency call or
257 related operation is currently active.
259 If the emergency application sets this setting to true
260 all other session will be informed about the emergency
261 situation with setting it also to true. Only the
262 emergency application can set back to false.
264 As long the EmergencyCall is true no new session can
267 Only one application is supposed to write this setting
268 and therefore it will be protected by additional
269 PolicyKit rule so that only the emergency application
272 The emergency application is expected to call Connect()
273 after setting this setting true. If the emergency
274 situation is over the application should call
275 Disconnect() and also set the EmergencyCall to false
278 Note only services matching the AllowedBearers rule
281 string RoamingPolicy [readwrite]
283 The allowed roaming behavior.
285 Valid policies are "national", "international",
286 "default", "always" and "forbidden".
288 "national" allows roaming within a country.
289 "international" allows roaming in a country and
292 "default" is used to tell the Session to use
293 the global roaming setting.
295 "always" will overwrite the default "forbidden"
296 value which is useful for emergency application.
297 This value will be protected by additional PolicyKit
300 Default value is "forbidden".
302 string Interface [readonly]
304 Interface name used by the service object to connect.
305 This name can be used for SO_BINDTODEVICE in the
308 uint32 SessionMarker [readonly]
310 The unique session marker can be used to mark all
311 traffic from the application with the SO_MARK
312 socket option. In combination of the EmergencyCall
313 this allows ConnMan to setup the firewall rules
314 that only traffic from the emergency application