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 when the connection has been
55 established and it is online. Additionally an update
56 notification with the IP settings is sent.
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 In most cases this method returns right away without
72 any delays. However in some cases it might take a few
73 seconds before a connection can be terminated.
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 boolean Online [readonly]
95 This indicates if the connection is online or
98 This maps to the online service state. And it is
99 only valid for the selected bearer configuration.
100 Otherwise it will be reported as offline even if
101 the global state would be online.
103 In addition the Online settings notification might
104 not happen right away. Notifications of online state
105 can be delayed based on the speed of the bearer. It
106 is done to avoid congestion on bearers like 3G etc.
108 boolean Priority [readwrite]
110 This allows a session to mark itself as priority or
111 not. In general application are not allowed to make
112 themselves more important than others.
114 The priority handling is done internally by usage
115 and first come, first serve order. By default this
116 settings is of course false.
118 Internally there can be different priorities for
119 different application, but these are defined by a
120 configuration file and not via this interface.
122 An application that calls the method to connect
123 a session is preferred over other sessions. This
124 priority value is more for application that want to
125 push themselves up in the asychronization notification
126 queue once a bearer becomes online.
128 This actual priority order also depends on the
129 allowed bearers and other factors. This is setting
130 is just a little indicator of one application being
131 notified before another one.
133 For example a streaming session should set the
134 priority value. As soon as realtime data is involved
135 then this should be set. An email client should not
138 string Name [readonly]
140 The Service name to which the system is connected.
141 It should only be used for displaying it in the UI
142 and not for getting hold on session object.
144 array{string} AllowedBearers [readwrite]
146 A list of bearers that can be used for this session.
147 In general this list should be empty to indicate that
148 any bearer is acceptable.
150 The order of the entries in AllowedBearers matters.
151 The services are sorted in the order of the bearer
152 entries in this list.
154 Also "*" matches any bearer. This is usefull to prefer
155 certain bearers such as Wifi with a fallback to any
156 other available bearer.
160 Current IPv4 configuration. This settings is only
161 valid when online is true as well. Otherwise an
162 empty dictionary is reported.
166 Current IPv6 configuration. This setting is only
167 valid when online is true as well. Otherwise an
168 empty dictionary is reported.
170 boolean AvoidHandover [readwrite]
172 By default this setting is false. It can be used
173 to indicate that a handover is currently not a good
174 idea. However no connection is guaranteed. So a
175 handover can happen anyway. This is just an indication
176 that the application would like to avoid it right now.
178 It is a bad idea to always enable this settings and
179 actually it will be reset after a while to avoid
182 Main use case it is for application that are currently
183 doing a specific tasks that it prefers to finish
184 before allowing handovers again. An example would
187 Never the less application needs to be aware that
188 handovers can happen at any time even if this is
191 boolean StayConnected [readwrite]
193 This disables the idle timeout for this session. There
194 is no guarantee and this should be used with care.
196 If the system is not online yet this value is ignored.
198 uint32 PeriodicConnect [readwrite]
200 Indicate that a periodic connection attempt every
201 n minutes should be made. The minutes value is a
202 suggestion when to connection. There is no guarantee
203 that it will be made or will succeed.
205 A value of 0 disable this feature.
207 This feature is interesting for applications that
208 wanna check status on a regular interval. And instead
209 of the application waking up and trying to connect,
210 this can be centralized nicely and multiple wakeups
211 avoided in case no connection is available.
213 An example application would be an email client that
214 wants to check for new emails every 10 minutes.
216 On purpose the smallest setting is 1 minute here since
217 waking up more often and trying to set up a connection
218 seems rather pointless use case.
220 If an interval step has passed this can be nicely
221 rescheduled when any connection matching the bearer
222 settings becomes available becomes available. Using
223 this feature it is also easy to avoid congestion.
225 uint32 IdleTimeout [readwrite]
227 If the system is idle for given period then it should
230 If the timeout is 0, this feature is disabled. If
231 different values are provided by several session object
232 the longest interval is taken as timeout value.
234 boolean EmergencyCall [readwrite]
236 Boolean representing the emergency mode of the
237 modem. The Emergency is true if an emergency call or
238 related operation is currently active.
240 Only one application is supposed to write this setting
241 and therefore it will be protected by additional
242 PolicyKit rule so that only the emergency application
245 string RoamingPolicy [readwrite]
247 The allowed roaming behavior.
249 Valid policies are "national", "international",
250 "default", "always" and "forbidden".
252 "national" allows roaming within a country.
253 "international" allows roaming in a country and
256 "default" is used to tell the Session to use
257 the global roaming setting.
259 "always" will overwrite the default "forbidden"
260 value which is useful for emergency application.
261 This value will be protected by additional PolicyKit
264 Default value is "forbidden".
266 string Interface [readonly]
268 Interface name used by the service object to connect.
269 This name can be used for SO_BINDTODEVICE in the
272 uint32 SessionMarker [readonly]
274 The unique session marker can be used to mark all
275 traffic from the application with the SO_MARK
276 socket option. In combination of the EmergencyCall
277 this allows ConnMan to setup the firewall rules
278 that only traffic from the emergency application