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 immediately after it has been
  55                         called. The application is informed through the update
  56                         notification about the state of the session.
  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                         This method returns immediately. The application is
  72                         informed through the update notification about the
  73                         state of the session.
  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 State [readonly]
  88
  89                         This indicates if the connection is disconnected,
  90                         connected or online. It is updated according to the
  91                         selected ConnectionType. The session will not be
  92                         in a useful shape (i.e.: providing a network connection
  93                         to the owner) until its State gets updated to connected
  94                         and/or online.
  95
  96                         This maps to the useful port of the  service state.
  97                         And it is only valid for the selected bearer
  98                         configuration. Otherwise it will be reported as
  99                         disconnected even if connected services are present.
 100
 101                         In addition the State settings notification might
 102                         not happen right away. Notifications of this state
 103                         can be delayed based on the speed of the bearer. It
 104                         is done to avoid congestion on bearers like cellular
 105                         etc.
 106
 107                 string Name [readonly]
 108
 109                         The Service name to which the system is connected.
 110                         It should only be used for displaying it in the UI
 111                         and not for getting hold on session object.
 112
 113                 string  Bearer [readonly]
 114
 115                         This indicates the current bearer that is used
 116                         for this session. Or an empty string if no bearer
 117                         if available.
 118
 119                 string  Interface [readonly]
 120
 121                         Interface name used by the service object to connect.
 122                         This name can be used for SO_BINDTODEVICE in the
 123                         application.
 124
 125                 dict IPv4 [readonly]
 126
 127                         Current IPv4 configuration.
 128
 129                 dict IPv6 [readonly]
 130
 131                         Current IPv6 configuration.
 132
 133                 array{string} AllowedBearers [readwrite]
 134
 135                         A list of bearers that can be used for this session.
 136                         In general this list should be empty to indicate that
 137                         any bearer is acceptable.
 138
 139                         The order of the entries in AllowedBearers matters.
 140                         The services are sorted in the order of the bearer
 141                         entries in this list.
 142
 143                         Also "*" matches any bearer. This is useful to prefer
 144                         certain bearers such as 'wifi' with a fallback to any
 145                         other available bearer.
 146
 147                         Invalid bearer names will be ignored and removed
 148                         from the list. And empty AllowedBearers will
 149                         not match to any bearer, therefore the session
 150                         will never go online.
 151
 152                         When a session is created and the provided settings
 153                         dictionary does not contain AllowedBearers, a default
 154                         session with "*" will be created.
 155
 156                 string ConnectionType [readwrite]
 157
 158                         This is used to indicate which connection is requested
 159                         from the session. The state of the session will be
 160                         updated accordingly. Values can be 'local',
 161                         'internet' or 'any'.
 162
 163                         'local' means the session requests to be connected,
 164                         but does not require specifically to be online.
 165                         Therefore State property will be set to 'connected' if
 166                         underlying service gets ready and/or online.
 167
 168                         'online' means the session requests to be connected,
 169                         and online. State property will never get 'connected'
 170                         but instead will switch to 'online' if underlying
 171                         service gets online.
 172
 173                         'any' means either 'local' or 'internet'.
 174
 175                         Invalid values will be ignored and removed. An
 176                         empty ConnectionType is an invalid configuration.
 177
 178                         When a session is created and the provided settings
 179                         dictionary does not contain ConnectionType, a default
 180                         session with 'any' will be created.
 181
 182                         (This setting will be removed when the unique process
 183                         identification problem is solved.)
 184
 185                 string AllowedInterface [readwrite] [experimental]
 186
 187                         This field is used to bind a session to a specific
 188                         network interface. If this field is empty, the first
 189                         interface from a list of available ones will be used.
 190                         Also "*" string matches any interface.
 191
 192                         Only one interface may be specified.
 193
 194                         If a specified network interface is not available
 195                         (e.g. because AllowedBearers filters it out), the
 196                         session will not go online.
 197
 198                 boolean SourceIPRule [readwrite] [experimental]
 199
 200                         If set to true the session will create source IP
 201                         address rule in the firewall, which redirects traffic
 202                         to that session's routing table.
 203
 204                         Each session maintains a dedicated routing table, with
 205                         a default route. When the source IP rule is enabled,
 206                         an application can select which session/interface to
 207                         send traffic on, using bind-before-connect mechanism.
 208
 209                 string ContextIdentifier [readwrite] [experimental]
 210
 211                         The application can provide an identifier for a
 212                         session. If an application runs several session
 213                         at the same time, the additional information
 214                         can be used by ConnMan to assign different
 215                         bearers according the identifier. For example
 216                         a web browser creates per tab a session. For
 217                         each session a different should bearer be
 218                         assigned.