doc/session-api.txt

   1 Service         unique name
   2 Interface       net.connman.Notification
   3 Object path     freely definable
   4
   5 Methods         void Release()
   6
   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.
  12
  13                 void Update(dict settings)
  14
  15                         Sends an update of changed settings. Only settings
  16                         that are changed will be included.
  17
  18                         Initially on every session creation this method is
  19                         called once to inform about the current settings.
  20
  21
  22 Service         net.connman
  23 Interface       net.connman.Session
  24 Object path     variable
  25
  26 Methods         void Destroy()
  27
  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.
  32
  33                 void Connect()
  34
  35                         If not connected, then attempt to connect this
  36                         session.
  37
  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
  42                         or gets back offline.
  43
  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
  49                         this method.
  50
  51                         Depending on the bearer settings the current service
  52                         is used or a new service will be connected.
  53
  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.
  57
  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
  61                         other reasons.
  62
  63                         It is safe to call this method multiple times. The
  64                         actual usage will be sorted out for the application.
  65
  66                 void Disconnect()
  67
  68                         This method indicates that the current session does
  69                         not need a connection anymore.
  70
  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.
  74
  75                 void Change(string name, variant value)
  76
  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.
  82
  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.
  86
  87 Settings        string  Bearer [readonly]
  88
  89                         This indicates the current bearer that is used
  90                         for this session. Or an empty string if no bearer
  91                         is available.
  92
  93                 boolean Online [readonly]
  94
  95                         This indicates if the connection is online or
  96                         offline.
  97
  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.
 102
 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.
 107
 108                 boolean Priority [readwrite]
 109
 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.
 113
 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.
 117
 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.
 121
 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.
 127
 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.
 132
 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
 136                         set this value.
 137
 138                 string Name [readonly]
 139
 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.
 143
 144                 array{string} AllowedBearers [readwrite]
 145
 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.
 149
 150                 dict IPv4 [readonly]
 151
 152                         Current IPv4 configuration. This settings is only
 153                         valid when online is true as well. Otherwise an
 154                         empty dictionary is reported.
 155
 156                 dict IPv6 [readonly]
 157
 158                         Current IPv6 configuration. This setting is only
 159                         valid when online is true as well. Otherwise an
 160                         empty dictionary is reported.
 161
 162                 boolean AvoidHandover [readwrite]
 163
 164                         By default this setting is false. It can be used
 165                         to indicate that a handover is currently not a good
 166                         idea. However no connection is guaranteed. So a
 167                         handover can happen anyway. This is just an indication
 168                         that the application would like to avoid it right now.
 169
 170                         It is a bad idea to always enable this settings and
 171                         actually it will be reset after a while to avoid
 172                         congestion.
 173
 174                         Main use case it is for application that are currently
 175                         doing a specific tasks that it prefers to finish
 176                         before allowing handovers again. An example would
 177                         be synchronization.
 178
 179                         Never the less application needs to be aware that
 180                         handovers can happen at any time even if this is
 181                         set to true.
 182
 183                 boolean StayConnected [readwrite]
 184
 185                         This disables the idle timeout for this session. There
 186                         is no guarantee and this should be used with care.
 187
 188                         If the system is not online yet this value is ignored.
 189
 190                 uint32  PeriodicConnect [readwrite]
 191
 192                         Indicate that a periodic connection attempt every
 193                         n minutes should be made. The minutes value is a
 194                         suggestion when to connection. There is no guarantee
 195                         that it will be made or will succeed.
 196
 197                         A value of 0 disable this feature.
 198
 199                         This feature is interesting for applications that
 200                         wanna check status on a regular interval. And instead
 201                         of the application waking up and trying to connect,
 202                         this can be centralized nicely and multiple wakeups
 203                         avoided in case no connection is available.
 204
 205                         An example application would be an email client that
 206                         wants to check for new emails every 10 minutes.
 207
 208                         On purpose the smallest setting is 1 minute here since
 209                         waking up more often and trying to set up a connection
 210                         seems rather pointless use case.
 211
 212                         If an interval step has passed this can be nicely
 213                         rescheduled when any connection matching the bearer
 214                         settings becomes available becomes available. Using
 215                         this feature it is also easy to avoid congestion.
 216
 217                 uint32  IdleTimeout [readwrite]
 218
 219                         If the system is idle for given period then it should
 220                         go offline.
 221
 222                         If the timeout is 0, this feature is disabled. If
 223                         different values are provided by several session object
 224                         the longest interval is taken as timeout value.
 225
 226                 boolean EmergencyCall [readwrite]
 227
 228                         Boolean representing the emergency mode of the
 229                         modem. The Emergency is true if an emergency call or
 230                         related operation is currently active.
 231
 232                         Only one application is supposed to write this setting
 233                         and therefore it will be protected by additional
 234                         PolicyKit rule so that only the emergency application
 235                         can write.
 236
 237                 string  RoamingPolicy [readwrite]
 238
 239                         The allowed roaming behavior.
 240
 241                         Valid policies are "national", "international",
 242                         "default", "always" and "forbidden".
 243
 244                         "national" allows roaming within a country.
 245                         "international" allows roaming in a country and
 246                         between countries.
 247
 248                         "default" is used to tell the Session to use
 249                         the global roaming setting.
 250
 251                         "always" will overwrite the default "forbidden"
 252                         value which is useful for emergency application.
 253                         This value will be protected by additional PolicyKit
 254                         rule.
 255
 256                         Default value is "forbidden".
 257
 258                 string  Interface [readonly]
 259
 260                         Interface name used by the service object to connect.
 261                         This name can be used for SO_BINDTODEVICE in the
 262                         application.
 263
 264                 uint32  SessionMarker [readonly]
 265
 266                         The unique session marker can be used to mark all
 267                         traffic from the application with the SO_MARK
 268                         socket option. In combination of the EmergencyCall
 269                         this allows ConnMan to setup the firewall rules
 270                         that only traffic from the emergency application
 271                         are transmitted.