Imported Upstream connman version 1.38

[platform/upstream/connman.git] / doc / session-api.txt

diff --git a/doc/session-api.txt b/doc/session-api.txt
old mode 100644 (file)
new mode 100755 (executable)
index 9305e34..8bfcf6b
--- a/doc/session-api.txt
+++ b/doc/session-api.txt
@@ -51,9 +51,9 @@ Methods               void Destroy()
                        Depending on the bearer settings the current service
                        is used or a new service will be connected.
 
                        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
 
                        It is also not guaranteed that a session stays online
                        after this method call. It can be taken offline at any


@@ -68,9 +68,9 @@ Methods               void Destroy()
                        This method indicates that the current session does
                        not need a connection anymore.
 
                        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)
 
 
                void Change(string name, variant value)
 


@@ -84,62 +84,51 @@ Methods             void Destroy()
                        to be sent. Some changes might cause the session to
                        be moved to offline state.
 
                        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
                        can be delayed based on the speed of the bearer. It

-                       is done to avoid congestion on bearers like 3G etc.
+                       is done to avoid congestion on bearers like cellular
+                       etc.

 
 

-               boolean Priority [readwrite]
+               string Name [readonly]

 
 

-                       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 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.
+
+               string  Bearer [readonly]

 
 

-                       The priority handling is done internally by usage
-                       and first come, first serve order. By default this
-                       settings is of course false.
+                       This indicates the current bearer that is used
+                       for this session. Or an empty string if no bearer
+                       if available.

 
 

-                       Internally there can be different priorities for
-                       different application, but these are defined by a
-                       configuration file and not via this interface.
+               string  Interface [readonly]

 
 

-                       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.
+                       Interface name used by the service object to connect.
+                       This name can be used for SO_BINDTODEVICE in the
+                       application.

 
 

-                       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.
+               dict IPv4 [readonly]

 
 

-                       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.
+                       Current IPv4 configuration.

 
 

-               string Name [readonly]
+               dict IPv6 [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.
+                       Current IPv6 configuration.

 
                array{string} AllowedBearers [readwrite]
 
 
                array{string} AllowedBearers [readwrite]
 


@@ -151,129 +140,79 @@ Settings string  Bearer [readonly]
                        The services are sorted in the order of the bearer
                        entries in this list.
 
                        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
+                       Also "*" matches any bearer. This is useful to prefer
+                       certain bearers such as 'wifi' with a fallback to any

                        other available bearer.
 
                        other available bearer.
 

-               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]
-
-                       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.
+                       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 the system is not online yet this value is ignored.
+                       When a session is created and the provided settings
+                       dictionary does not contain AllowedBearers, a default
+                       session with "*" will be created.

 
 

-               uint32  PeriodicConnect [readwrite]
+               string ConnectionType [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.
+                       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'.

 
 

-                       A value of 0 disable this feature.
+                       '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.

 
 

-                       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.
+                       '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.

 
 

-                       An example application would be an email client that
-                       wants to check for new emails every 10 minutes.
+                       'any' means either 'local' or 'internet'.

 
 

-                       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 values will be ignored and removed. An
+                       empty ConnectionType is an invalid configuration.

 
 

-                       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 ConnectionType, a default
+                       session with 'any' will be created.

 
 

-               uint32  IdleTimeout [readwrite]
+                       (This setting will be removed when the unique process
+                       identification problem is solved.)

 
 

-                       If the system is idle for given period then it should
-                       go offline.
+               string AllowedInterface [readwrite] [experimental]

 
 

-                       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.
+                       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.

 
 

-               boolean EmergencyCall [readwrite]
+                       Only one interface may be specified.

 
 

-                       Boolean representing the emergency mode of the
-                       modem. The Emergency is true if an emergency call or
-                       related operation is currently active.
+                       If a specified network interface is not available
+                       (e.g. because AllowedBearers filters it out), the
+                       session will not go online.

 
 

-                       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.
+               boolean SourceIPRule [readwrite] [experimental]

 
 

-               string  RoamingPolicy [readwrite]
+                       If set to true the session will create source IP
+                       address rule in the firewall, which redirects traffic
+                       to that session's routing table.

 
 

-                       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.
+                       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.