dnsproxy: Do not print too many info messages

[framework/connectivity/connman.git] / doc / session-overview.txt

diff --git a/doc/session-overview.txt b/doc/session-overview.txt
index f07eca2..82e3f89 100644 (file)
--- a/doc/session-overview.txt
+++ b/doc/session-overview.txt
@@ -12,7 +12,7 @@ following rules:
  - AllowedBearers (filter and sort)
  - RoamingPolicy (filter and sort)
 
-A stable sorting algorithms maintains the relative order.
+A stable sorting algorithm maintains the relative order.
 
 If a service is removed or added all sessions are updated according
 the above rules.
@@ -31,7 +31,7 @@ Connect algorithm:
                        | Yes  +------+-------+  No
                        +------+StayConnected?+------ Do nothing
                        |      +--------------+
-                       |
+Session.Change() ------+
                        |
                 +------+-------+
           +-----+EmergencyCall?+-----+
@@ -60,7 +60,7 @@ Disconnect algorithm:
   Session.Disconnect()
   IdleTimeout
        |
-       |
+       +--- Session.Change()
        |
 +-----------------+    Yes
 |service not used +-------------+
@@ -69,3 +69,73 @@ Disconnect algorithm:
        |No                      |
        |                        |
     Service.Disconnect()   Do nothing
+
+
+Session States and Transitions
+==============================
+
+There are three main strategies for state changes.
+
+ - Free Ride
+ - Connect
+ - Disconnect
+
+The initial state for all new sessions is Free Ride.
+
+The Free Ride state means that a session will go online if a matching
+service goes online without calling Service.Connect() itself. The idea
+behind this is that a session doesn't request a connection for itself
+instead waits until another session actively requires to go online.
+This is comparable to piggy-backing.
+
+When a session is in the Connect state ConnMan tries to find a
+matching service (see Connect algorithm) and then decides either to
+connect the service or delay the request. ConnMan is allowed to
+connect to the service or to delay it, e.g. group PeriodicConnects
+together. The session will leave the Connect state when the service
+goes offline unless StayConnected is True. It will enter the Free Ride
+mode again.
+
+When the application calls Disconnect() the session enters the
+Disconnect state and stays there until the application calls Connect()
+again.
+
+
+                 State Change to offline & StayConnected = True
+                              +------+
+                              |      v
++-----------+                +---------+ -- Disconnect() --> +------------+
+| Free Ride |-- Connect() -->| Connect |                     | Disconnect |
++-----------+                +---------+  <-- Connect() ---  +------------+
+      |  ^                         |                               ^
+      |  +------------------------ +                               |
+      |   State Change to offline & StayConnected = False          |
+      |                                                            |
+      |                                                            |
+      +----------------------- Disconnect() -----------------------+
+
+Note: this documents the current behavior it is likely to change in near
+future.
+
+
+Additional Information on Settings
+==================================
+
+PeriodicConnect and IdleTimeout
+-------------------------------
+
+If an application wants to go online periodically (e.g. checking for
+new mails) then the application should use PeriodicConnect instead of
+calling Session.Connect() periodically. There is no need for the
+application to maintain timers. ConnMan is also able to try to combine
+several PeriodicConnect calls into one. Applications should not rely on a
+very precise periodic connect. Apart from merging periodic connect
+timeouts there is also the problem that no service might be available
+at that point and ConnMan will defer the connect call.
+
+The IdleTimeout tells ConnMan when a link is idle for given period it
+is okay to disonnect.
+
+PeriodicConnect and IdleTimeout should only consired as hints. ConnMan
+will try to meet them but there is no garantee for doing so. For
+example global settings have precedence over session settings.