doc/session-overview.txt

   1 Session API
   2 ***********
   3
   4
   5 Connection management algorithm basics
   6 ======================================
   7
   8 When a session is created, a sorted list of services is added to the
   9 session. The services are filtered and stable sorted according
  10 following rules:
  11
  12  - AllowedBearers (filter and sort)
  13  - RoamingPolicy (filter and sort)
  14
  15 A stable sorting algorithm maintains the relative order.
  16
  17 If a service is removed or added all sessions are updated according
  18 the above rules.
  19
  20 There are three triggers which lead to evaluate the connect
  21 algorithm:
  22
  23  - Session.Connect()
  24  - PeriodicConnect
  25  - Offline
  26
  27 Connect algorithm:
  28
  29               Session.Connect()     Offline
  30               PeriodicConnect        |
  31                        | Yes  +------+-------+  No
  32                        +------+StayConnected?+------ Do nothing
  33                        |      +--------------+
  34 Session.Change() ------+
  35                        |
  36                 +------+-------+
  37           +-----+EmergencyCall?+-----+
  38        Yes|     +--------------+     |No
  39           |                          |
  40         Connect to            +--------------+
  41         first available   +---+AvoidHandover?+---+
  42         Service           |   +--------------+   |
  43                        Yes|                      |No
  44                  +----------------+              |
  45              +---+In service_list +---+          |
  46           Yes|   |and online?     |   |No        |
  47              |   +----------------+   |          |
  48              |                        |          |
  49          Take that one                Take first in
  50                                       the service list
  51
  52 There are two triggers which lead to evaluate the disconnect
  53 algorithm
  54
  55  - Session.Disconnect()
  56  - IdleTimeout
  57
  58 Disconnect algorithm:
  59
  60   Session.Disconnect()
  61   IdleTimeout
  62        |
  63        +--- Session.Change()
  64        |
  65 +-----------------+    Yes
  66 |service not used +-------------+
  67 |by other session?|             |
  68 +------.----------+             |
  69        |No                      |
  70        |                        |
  71     Service.Disconnect()   Do nothing
  72
  73
  74 Session States and Transitions
  75 ==============================
  76
  77 There are three main strategies for state changes.
  78
  79  - Free Ride
  80  - Connect
  81  - Disconnect
  82
  83 The initial state for all new sessions is Free Ride.
  84
  85 The Free Ride state means that a session will go online if a matching
  86 service goes online without calling Service.Connect() itself. The idea
  87 behind this is that a session doesn't request a connection for itself
  88 instead waits until another session actively requires to go online.
  89 This is comparable to piggy-backing.
  90
  91 When a session is in the Connect state ConnMan tries to find a
  92 matching service (see Connect algorithm) and then decides either to
  93 connect the service or delay the request. ConnMan is allowed to
  94 connect to the service or to delay it, e.g. group PeriodicConnects
  95 together. The session will leave the Connect state when the service
  96 goes offline unless StayConnected is True. It will enter the Free Ride
  97 mode again.
  98
  99 When the application calls Disconnect() the session enters the
 100 Disconnect state and stays there until the application calls Connect()
 101 again.
 102
 103
 104                  State Change to offline & StayConnected = True
 105                               +------+
 106                               |      v
 107 +-----------+                +---------+ -- Disconnect() --> +------------+
 108 | Free Ride |-- Connect() -->| Connect |                     | Disconnect |
 109 +-----------+                +---------+  <-- Connect() ---  +------------+
 110       |  ^                         |                               ^
 111       |  +------------------------ +                               |
 112       |   State Change to offline & StayConnected = False          |
 113       |                                                            |
 114       |                                                            |
 115       +----------------------- Disconnect() -----------------------+
 116
 117 Note: this documents the current behavior it is likely to change in near
 118 future.
 119
 120
 121 Additional Information on Settings
 122 ==================================
 123
 124 PeriodicConnect and IdleTimeout
 125 -------------------------------
 126
 127 If an application wants to go online periodically (e.g. checking for
 128 new mails) then the application should use PeriodicConnect instead of
 129 calling Session.Connect() periodically. There is no need for the
 130 application to maintain timers. ConnMan is also able to try to combine
 131 several PeriodicConnect calls into one. Applications should not rely on a
 132 very precise periodic connect. Apart from merging periodic connect
 133 timeouts there is also the problem that no service might be available
 134 at that point and ConnMan will defer the connect call.
 135
 136 The IdleTimeout tells ConnMan when a link is idle for given period it
 137 is okay to disonnect.
 138
 139 PeriodicConnect and IdleTimeout should only consired as hints. ConnMan
 140 will try to meet them but there is no garantee for doing so. For
 141 example global settings have precedence over session settings.