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  Bearer [readonly]
  88
  89                         This indicates the current bearer that is used
  90                         for this session. Or an empty string if no bearer
  91                         if available.
  92
  93                 string ConnectionType [readwrite]
  94
  95                         This is used to indicate which connection is requested
  96                         from the session. The state of the session will be
  97                         updated accordingly. Values can be nothing, 'local' or
  98                         'internet'.
  99                         'local' means the session requests to be connected,
 100                         but does not require specifically to be online.
 101                         Therefore State property will be set to 'connected' if
 102                         underlying service gets ready and/or online.
 103                         'online' means the session requests to be connected,
 104                         and online. State property will never get 'connected'
 105                         but instead will switch to 'online' if underlying
 106                         service gets online.
 107                         No value means the session requests any kind of
 108                         connection and the state will be updated on all steps,
 109                         'connected' and 'online'. This is the default value.
 110
 111                         (This setting will be removed when the unique process
 112                         identifaction problem is solved.)
 113
 114                 boolean State [readonly]
 115
 116                         This indicates if the connection is disconnected,
 117                         connected or online. It is updated according to the
 118                         selected ConnectionType. The session will not be
 119                         in a useful shape (i.e.: providing a network connection
 120                         to the owner) until its State gets updated to connected
 121                         and/or online.
 122
 123                         This maps to the useful port of the  service state.
 124                         And it is only valid for the selected bearer
 125                         configuration. Otherwise it will be reported as
 126                         disconnected even if connected services are present.
 127
 128                         In addition the State settings notification might
 129                         not happen right away. Notifications of this state
 130                         can be delayed based on the speed of the bearer. It
 131                         is done to avoid congestion on bearers like cellular
 132                         etc.
 133
 134                 string Name [readonly]
 135
 136                         The Service name to which the system is connected.
 137                         It should only be used for displaying it in the UI
 138                         and not for getting hold on session object.
 139
 140                 array{string} AllowedBearers [readwrite]
 141
 142                         A list of bearers that can be used for this session.
 143                         In general this list should be empty to indicate that
 144                         any bearer is acceptable.
 145
 146                         The order of the entries in AllowedBearers matters.
 147                         The services are sorted in the order of the bearer
 148                         entries in this list.
 149
 150                         Also "*" matches any bearer. This is usefull to prefer
 151                         certain bearers such as Wifi with a fallback to any
 152                         other available bearer.
 153
 154                 dict IPv4 [readonly]
 155
 156                         Current IPv4 configuration.
 157
 158                 dict IPv6 [readonly]
 159
 160                         Current IPv6 configuration.
 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                 boolean EmergencyCall [readwrite]
 191
 192                         Boolean representing the emergency mode of the
 193                         modem. The Emergency is true if an emergency call or
 194                         related operation is currently active.
 195
 196                         If the emergency application sets this setting to true
 197                         all other session will be informed about the emergency
 198                         situation with setting it also to true. Only the
 199                         emergency application can set back to false.
 200
 201                         As long the EmergencyCall is true no new session can
 202                         be created.
 203
 204                         Only one application is supposed to write this setting
 205                         and therefore it will be protected by additional
 206                         PolicyKit rule so that only the emergency application
 207                         can write.
 208
 209                         The emergency application is expected to call Connect()
 210                         after setting this setting true. If the emergency
 211                         situation is over the application should call
 212                         Disconnect() and also set the EmergencyCall to false
 213                         afterward.
 214
 215                         Note only services matching the AllowedBearers rule
 216                         will be considered.
 217
 218                 string  RoamingPolicy [readwrite]
 219
 220                         The allowed roaming behavior.
 221
 222                         Valid policies are "national", "international",
 223                         "default", "always" and "forbidden".
 224
 225                         "national" allows roaming within a country.
 226                         "international" allows roaming in a country and
 227                         between countries.
 228
 229                         "default" is used to tell the Session to use
 230                         the global roaming setting.
 231
 232                         "always" will overwrite the default "forbidden"
 233                         value which is useful for emergency application.
 234                         This value will be protected by additional PolicyKit
 235                         rule.
 236
 237                         Default value is "forbidden".
 238
 239                 string  Interface [readonly]
 240
 241                         Interface name used by the service object to connect.
 242                         This name can be used for SO_BINDTODEVICE in the
 243                         application.