X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=doc%2Fsession-api.txt;h=8bfcf6b05335abb21c2a219ed05e041674f24d8e;hb=dd3cccc5e67548dcc2dd6c6254ed6c97859085d5;hp=0bc93fcedec35ea4771f234a049d9e1b6fbf84a1;hpb=30f0643ab578e240dac727f650d3672c1188e609;p=platform%2Fupstream%2Fconnman.git diff --git a/doc/session-api.txt b/doc/session-api.txt index 0bc93fc..8bfcf6b 100644 --- a/doc/session-api.txt +++ b/doc/session-api.txt @@ -84,63 +84,51 @@ Methods void Destroy() to be sent. Some changes might cause the session to be moved to offline state. -Settings string Bearer [readonly] - - This indicates the current bearer that is used - for this session. Or an empty string if no bearer - is available. - - boolean Online [readonly] - - This indicates if the connection is online or - offline. - - This maps to the online service state. And it is - only valid for the selected bearer configuration. - Otherwise it will be reported as offline even if - the global state would be online. - - In addition the Online settings notification might - not happen right away. Notifications of online state +Settings string State [readonly] + + This indicates if the connection is disconnected, + connected or online. It is updated according to the + selected ConnectionType. The session will not be + in a useful shape (i.e.: providing a network connection + to the owner) until its State gets updated to connected + and/or online. + + This maps to the useful port of the service state. + And it is only valid for the selected bearer + configuration. Otherwise it will be reported as + disconnected even if connected services are present. + + In addition the State settings notification might + not happen right away. Notifications of this state can be delayed based on the speed of the bearer. It is done to avoid congestion on bearers like cellular etc. - boolean Priority [readwrite] + string Name [readonly] + + The Service name to which the system is connected. + It should only be used for displaying it in the UI + and not for getting hold on session object. - This allows a session to mark itself as priority or - not. In general application are not allowed to make - themselves more important than others. + string Bearer [readonly] - The priority handling is done internally by usage - and first come, first serve order. By default this - settings is of course false. + This indicates the current bearer that is used + for this session. Or an empty string if no bearer + if available. - Internally there can be different priorities for - different application, but these are defined by a - configuration file and not via this interface. + string Interface [readonly] - An application that calls the method to connect - a session is preferred over other sessions. This - priority value is more for application that want to - push themselves up in the asychronization notification - queue once a bearer becomes online. + Interface name used by the service object to connect. + This name can be used for SO_BINDTODEVICE in the + application. - This actual priority order also depends on the - allowed bearers and other factors. This is setting - is just a little indicator of one application being - notified before another one. + dict IPv4 [readonly] - For example a streaming session should set the - priority value. As soon as realtime data is involved - then this should be set. An email client should not - set this value. + Current IPv4 configuration. - string Name [readonly] + dict IPv6 [readonly] - The Service name to which the system is connected. - It should only be used for displaying it in the UI - and not for getting hold on session object. + Current IPv6 configuration. array{string} AllowedBearers [readwrite] @@ -152,146 +140,79 @@ Settings string Bearer [readonly] The services are sorted in the order of the bearer entries in this list. - Also "*" matches any bearer. This is usefull to prefer - certain bearers such as Wifi with a fallback to any + Also "*" matches any bearer. This is useful to prefer + certain bearers such as 'wifi' with a fallback to any other available bearer. - dict IPv4 [readonly] + Invalid bearer names will be ignored and removed + from the list. And empty AllowedBearers will + not match to any bearer, therefore the session + will never go online. - Current IPv4 configuration. This settings is only - valid when online is true as well. Otherwise an - empty dictionary is reported. + When a session is created and the provided settings + dictionary does not contain AllowedBearers, a default + session with "*" will be created. - dict IPv6 [readonly] + string ConnectionType [readwrite] - Current IPv6 configuration. This setting is only - valid when online is true as well. Otherwise an - empty dictionary is reported. + This is used to indicate which connection is requested + from the session. The state of the session will be + updated accordingly. Values can be 'local', + 'internet' or 'any'. - boolean AvoidHandover [readwrite] + 'local' means the session requests to be connected, + but does not require specifically to be online. + Therefore State property will be set to 'connected' if + underlying service gets ready and/or online. - By default this setting is false. It can be used - to indicate that a handover is currently not a good - idea. However no connection is guaranteed. So a - handover can happen anyway. This is just an indication - that the application would like to avoid it right now. + 'online' means the session requests to be connected, + and online. State property will never get 'connected' + but instead will switch to 'online' if underlying + service gets online. - It is a bad idea to always enable this settings and - actually it will be reset after a while to avoid - congestion. + 'any' means either 'local' or 'internet'. - Main use case it is for application that are currently - doing a specific tasks that it prefers to finish - before allowing handovers again. An example would - be synchronization. + Invalid values will be ignored and removed. An + empty ConnectionType is an invalid configuration. - Never the less application needs to be aware that - handovers can happen at any time even if this is - set to true. + When a session is created and the provided settings + dictionary does not contain ConnectionType, a default + session with 'any' will be created. - boolean StayConnected [readwrite] + (This setting will be removed when the unique process + identification problem is solved.) - This disables the idle timeout for this session. There - is no guarantee and this should be used with care. + string AllowedInterface [readwrite] [experimental] - If the system is not online yet this value is ignored. + This field is used to bind a session to a specific + network interface. If this field is empty, the first + interface from a list of available ones will be used. + Also "*" string matches any interface. - uint32 PeriodicConnect [readwrite] + Only one interface may be specified. - Indicate that a periodic connection attempt every - n minutes should be made. The minutes value is a - suggestion when to connection. There is no guarantee - that it will be made or will succeed. + If a specified network interface is not available + (e.g. because AllowedBearers filters it out), the + session will not go online. - A value of 0 disable this feature. + boolean SourceIPRule [readwrite] [experimental] - This feature is interesting for applications that - wanna check status on a regular interval. And instead - of the application waking up and trying to connect, - this can be centralized nicely and multiple wakeups - avoided in case no connection is available. + If set to true the session will create source IP + address rule in the firewall, which redirects traffic + to that session's routing table. - An example application would be an email client that - wants to check for new emails every 10 minutes. - - On purpose the smallest setting is 1 minute here since - waking up more often and trying to set up a connection - seems rather pointless use case. - - If an interval step has passed this can be nicely - rescheduled when any connection matching the bearer - settings becomes available becomes available. Using - this feature it is also easy to avoid congestion. - - uint32 IdleTimeout [readwrite] - - If the system is idle for given period then it should - go offline. - - If the timeout is 0, this feature is disabled. If - different values are provided by several session object - the longest interval is taken as timeout value. - - boolean EmergencyCall [readwrite] - - Boolean representing the emergency mode of the - modem. The Emergency is true if an emergency call or - related operation is currently active. - - If the emergency application sets this setting to true - all other session will be informed about the emergency - situation with setting it also to true. Only the - emergency application can set back to false. - - As long the EmergencyCall is true no new session can - be created. - - Only one application is supposed to write this setting - and therefore it will be protected by additional - PolicyKit rule so that only the emergency application - can write. - - The emergency application is expected to call Connect() - after setting this setting true. If the emergency - situation is over the application should call - Disconnect() and also set the EmergencyCall to false - afterward. - - Note only services matching the AllowedBearers rule - will be considered. - - string RoamingPolicy [readwrite] - - The allowed roaming behavior. - - Valid policies are "national", "international", - "default", "always" and "forbidden". - - "national" allows roaming within a country. - "international" allows roaming in a country and - between countries. - - "default" is used to tell the Session to use - the global roaming setting. - - "always" will overwrite the default "forbidden" - value which is useful for emergency application. - This value will be protected by additional PolicyKit - rule. - - Default value is "forbidden". - - string Interface [readonly] - - Interface name used by the service object to connect. - This name can be used for SO_BINDTODEVICE in the - application. + Each session maintains a dedicated routing table, with + a default route. When the source IP rule is enabled, + an application can select which session/interface to + send traffic on, using bind-before-connect mechanism. - uint32 SessionMarker [readonly] + string ContextIdentifier [readwrite] [experimental] - The unique session marker can be used to mark all - traffic from the application with the SO_MARK - socket option. In combination of the EmergencyCall - this allows ConnMan to setup the firewall rules - that only traffic from the emergency application - are transmitted. + The application can provide an identifier for a + session. If an application runs several session + at the same time, the additional information + can be used by ConnMan to assign different + bearers according the identifier. For example + a web browser creates per tab a session. For + each session a different should bearer be + assigned.