Depending on the bearer settings the current service
is used or a new service will be connected.
- This method returns when the connection has been
- established and it is online. Additionally an update
- notification with the IP settings is sent.
+ 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
This method indicates that the current session does
not need a connection anymore.
- In most cases this method returns right away without
- any delays. However in some cases it might take a few
- seconds before a connection can be terminated.
+ This method returns immediately. The application is
+ informed through the update notification about the
+ state of the session.
void Change(string name, variant value)
to be sent. Some changes might cause the session to
be moved to offline state.
-Settings string Bearer [readonly]
+Settings string State [readonly]
- This indicates the current bearer that is used
- for this session. Or an empty string if no bearer
- is available.
-
- boolean Online [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 indicates if the connection is online or
- offline.
+ 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.
- This maps to the online service state. And it is
- only valid for the selected bearer configuration.
- Otherwise it will be reported as offline even if
- the global state would be online.
-
- In addition the Online settings notification might
- not happen right away. Notifications of online state
+ 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 3G 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.
+ is done to avoid congestion on bearers like cellular
+ etc.
string Name [readonly]
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.
-
- dict IPv4 [readonly]
-
- Current IPv4 configuration. This settings is only
- valid when online is true as well. Otherwise an
- empty dictionary is reported.
-
- dict IPv6 [readonly]
-
- Current IPv6 configuration. This setting is only
- valid when online is true as well. Otherwise an
- empty dictionary is reported.
-
- boolean AvoidHandover [readwrite]
+ string Bearer [readonly]
- 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.
+ This indicates the current bearer that is used
+ for this session. Or an empty string if no bearer
+ if available.
- 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.
+ string Interface [readonly]
- Never the less application needs to be aware that
- handovers can happen at any time even if this is
- set to true.
+ Interface name used by the service object to connect.
+ This name can be used for SO_BINDTODEVICE in the
+ application.
- boolean StayConnected [readwrite]
+ dict IPv4 [readonly]
- This disables the idle timeout for this session. There
- is no guarantee and this should be used with care.
+ Current IPv4 configuration.
- If the system is not online yet this value is ignored.
+ dict IPv6 [readonly]
- uint32 PeriodicConnect [readwrite]
+ Current IPv6 configuration.
- 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.
+ array{string} AllowedBearers [readwrite]
- A value of 0 disable this feature.
+ 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.
- 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.
+ The order of the entries in AllowedBearers matters.
+ The services are sorted in the order of the bearer
+ entries in this list.
- An example application would be an email client that
- wants to check for new emails every 10 minutes.
+ Also "*" matches any bearer. This is useful to prefer
+ certain bearers such as 'wifi' with a fallback to any
+ other available bearer.
- 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.
+ Invalid bearer names will be ignored and removed
+ from the list. And empty AllowedBearers will
+ not match to any bearer, therefore the session
+ will never go online.
- 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.
+ When a session is created and the provided settings
+ dictionary does not contain AllowedBearers, a default
+ session with "*" will be created.
- uint32 IdleTimeout [readwrite]
+ string ConnectionType [readwrite]
- If the system is idle for given period then it should
- go offline.
+ This is used to indicate which connection is requested
+ from the session. The state of the session will be
+ updated accordingly. Values can be 'local',
+ 'internet' or 'any'.
- 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.
+ '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.
- boolean EmergencyCall [readwrite]
+ '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.
- Boolean representing the emergency mode of the
- modem. The Emergency is true if an emergency call or
- related operation is currently active.
+ 'any' means either 'local' or 'internet'.
- 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.
+ Invalid values will be ignored and removed. An
+ empty ConnectionType is an invalid configuration.
- string RoamingPolicy [readwrite]
+ When a session is created and the provided settings
+ dictionary does not contain ConnectionType, a default
+ session with 'any' will be created.
- The allowed roaming behavior.
+ (This setting will be removed when the unique process
+ identification problem is solved.)
- Valid policies are "national", "international",
- "default", "always" and "forbidden".
+ string AllowedInterface [readwrite] [experimental]
- "national" allows roaming within a country.
- "international" allows roaming in a country and
- between countries.
+ This field is used to bind a session to a specific
+ network interface. If this field is empty, the first
+ interface from a list of available ones will be used.
+ Also "*" string matches any interface.
- "default" is used to tell the Session to use
- the global roaming setting.
+ Only one interface may be specified.
- "always" will overwrite the default "forbidden"
- value which is useful for emergency application.
- This value will be protected by additional PolicyKit
- rule.
+ If a specified network interface is not available
+ (e.g. because AllowedBearers filters it out), the
+ session will not go online.
- Default value is "forbidden".
+ boolean SourceIPRule [readwrite] [experimental]
- string Interface [readonly]
+ If set to true the session will create source IP
+ address rule in the firewall, which redirects traffic
+ to that session's routing table.
- Interface name used by the service object to connect.
- This name can be used for SO_BINDTODEVICE in the
- application.
+ Each session maintains a dedicated routing table, with
+ a default route. When the source IP rule is enabled,
+ an application can select which session/interface to
+ send traffic on, using bind-before-connect mechanism.
- uint32 SessionMarker [readonly]
+ string ContextIdentifier [readwrite] [experimental]
- 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.
+ The application can provide an identifier for a
+ session. If an application runs several session
+ at the same time, the additional information
+ can be used by ConnMan to assign different
+ bearers according the identifier. For example
+ a web browser creates per tab a session. For
+ each session a different should bearer be
+ assigned.
projects / platform / upstream / connman.git / blobdiff