X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=doc%2Fsession-api.txt;h=8bfcf6b05335abb21c2a219ed05e041674f24d8e;hb=c647a4b6f1132684c9d8b8ad71ec38d81147b278;hp=e20449b7352de598dd9fe6d54e60e56fc10a4671;hpb=09c48519ad3ff07acd01ba9c037271c368989000;p=platform%2Fupstream%2Fconnman.git diff --git a/doc/session-api.txt b/doc/session-api.txt old mode 100644 new mode 100755 index e20449b..8bfcf6b --- a/doc/session-api.txt +++ b/doc/session-api.txt @@ -51,9 +51,9 @@ Methods void Destroy() Depending on the bearer settings the current service is used or a new service will be connected. - This method returns when the connection has been - established and it is online. Additionally an update - notification with the IP settings is sent. + This method returns immediately after it has been + called. The application is informed through the update + notification about the state of the session. It is also not guaranteed that a session stays online after this method call. It can be taken offline at any @@ -68,9 +68,9 @@ Methods void Destroy() This method indicates that the current session does not need a connection anymore. - In most cases this method returns right away without - any delays. However in some cases it might take a few - seconds before a connection can be terminated. + This method returns immediately. The application is + informed through the update notification about the + state of the session. void Change(string name, variant value) @@ -84,56 +84,25 @@ Methods void Destroy() to be sent. Some changes might cause the session to be moved to offline state. -Settings string Bearer [readonly] +Settings string State [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 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 indicates if the connection is online or - offline. + 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. - 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 + 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 3G etc. - - boolean Priority [readwrite] - - This allows a session to mark itself as priority or - not. In general application are not allowed to make - themselves more important than others. - - The priority handling is done internally by usage - and first come, first serve order. By default this - settings is of course false. - - Internally there can be different priorities for - different application, but these are defined by a - configuration file and not via this interface. - - 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. - - 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. - - 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. + is done to avoid congestion on bearers like cellular + etc. string Name [readonly] @@ -141,131 +110,109 @@ Settings string Bearer [readonly] It should only be used for displaying it in the UI and not for getting hold on session object. - array{string} AllowedBearers [readwrite] - - A list of bearers that can be used for this session. - In general this list should be empty to indicate that - any bearer is acceptable. - - dict IPv4 [readonly] - - Current IPv4 configuration. This settings is only - valid when online is true as well. Otherwise an - empty dictionary is reported. - - dict IPv6 [readonly] - - Current IPv6 configuration. This setting is only - valid when online is true as well. Otherwise an - empty dictionary is reported. - - boolean AvoidHandover [readwrite] + string Bearer [readonly] - 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. - - It is a bad idea to always enable this settings and - actually it will be reset after a while to avoid - congestion. + This indicates the current bearer that is used + for this session. Or an empty string if no bearer + if available. - 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. + string Interface [readonly] - Never the less application needs to be aware that - handovers can happen at any time even if this is - set to true. + Interface name used by the service object to connect. + This name can be used for SO_BINDTODEVICE in the + application. - boolean StayConnected [readwrite] + dict IPv4 [readonly] - This disables the idle timeout for this session. There - is no guarantee and this should be used with care. + Current IPv4 configuration. - If the system is not online yet this value is ignored. + dict IPv6 [readonly] - uint32 PeriodicConnect [readwrite] + Current IPv6 configuration. - 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. + array{string} AllowedBearers [readwrite] - A value of 0 disable this feature. + A list of bearers that can be used for this session. + In general this list should be empty to indicate that + any bearer is acceptable. - 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. + The order of the entries in AllowedBearers matters. + The services are sorted in the order of the bearer + entries in this list. - An example application would be an email client that - wants to check for new emails every 10 minutes. + Also "*" matches any bearer. This is useful to prefer + certain bearers such as 'wifi' with a fallback to any + other available bearer. - 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. + 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. - 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. + When a session is created and the provided settings + dictionary does not contain AllowedBearers, a default + session with "*" will be created. - uint32 IdleTimeout [readwrite] + string ConnectionType [readwrite] - If the system is idle for given period then it should - go offline. + 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'. - 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. + '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. - boolean EmergencyCall [readwrite] + '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. - Boolean representing the emergency mode of the - modem. The Emergency is true if an emergency call or - related operation is currently active. + 'any' means either 'local' or 'internet'. - 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. + Invalid values will be ignored and removed. An + empty ConnectionType is an invalid configuration. - string RoamingPolicy [readwrite] + When a session is created and the provided settings + dictionary does not contain ConnectionType, a default + session with 'any' will be created. - The allowed roaming behavior. + (This setting will be removed when the unique process + identification problem is solved.) - Valid policies are "national", "international", - "default", "always" and "forbidden". + string AllowedInterface [readwrite] [experimental] - "national" allows roaming within a country. - "international" allows roaming in a country and - between countries. + 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. - "default" is used to tell the Session to use - the global roaming setting. + Only one interface may be specified. - "always" will overwrite the default "forbidden" - value which is useful for emergency application. - This value will be protected by additional PolicyKit - rule. + If a specified network interface is not available + (e.g. because AllowedBearers filters it out), the + session will not go online. - Default value is "forbidden". + boolean SourceIPRule [readwrite] [experimental] - string Interface [readonly] + If set to true the session will create source IP + address rule in the firewall, which redirects traffic + to that session's routing table. - 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.