X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=doc%2Fsession-api.txt;h=8bfcf6b05335abb21c2a219ed05e041674f24d8e;hb=f2a9f93bbb2df62e3b3246ea253f8aaae29234d2;hp=252a9047de12a49b0c04eb38cb5094171931d20f;hpb=9844cb3d499b654e6d337dab29673513680b6bb5;p=platform%2Fupstream%2Fconnman.git diff --git a/doc/session-api.txt b/doc/session-api.txt old mode 100644 new mode 100755 index 252a904..8bfcf6b --- a/doc/session-api.txt +++ b/doc/session-api.txt @@ -84,34 +84,7 @@ 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 - if available. - - string ConnectionType [readwrite] - - This is used to indicate which connection is requested - from the session. The state of the session will be - updated accordingly. Values can be nothing, 'local' or - 'internet'. - '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. - '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. - No value means the session requests any kind of - connection and the state will be updated on all steps, - 'connected' and 'online'. This is the default value. - - (This setting will be removed when the unique process - identifaction problem is solved.) - - boolean State [readonly] +Settings string State [readonly] This indicates if the connection is disconnected, connected or online. It is updated according to the @@ -137,19 +110,17 @@ 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] + string Bearer [readonly] - 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 indicates the current bearer that is used + for this session. Or an empty string if no bearer + if available. - The order of the entries in AllowedBearers matters. - The services are sorted in the order of the bearer - entries in this list. + string Interface [readonly] - Also "*" matches any bearer. This is usefull to prefer - certain bearers such as Wifi with a fallback to any - other available bearer. + Interface name used by the service object to connect. + This name can be used for SO_BINDTODEVICE in the + application. dict IPv4 [readonly] @@ -159,85 +130,89 @@ Settings string Bearer [readonly] Current IPv6 configuration. - boolean AvoidHandover [readwrite] - - 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. + array{string} AllowedBearers [readwrite] - It is a bad idea to always enable this settings and - actually it will be reset after a while to avoid - congestion. + 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. - 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. + The order of the entries in AllowedBearers matters. + The services are sorted in the order of the bearer + entries in this list. - Never the less application needs to be aware that - handovers can happen at any time even if this is - set to true. + Also "*" matches any bearer. This is useful to prefer + certain bearers such as 'wifi' with a fallback to any + other available bearer. - boolean StayConnected [readwrite] + 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. - This disables the idle timeout for this session. There - is no guarantee and this should be used with care. + When a session is created and the provided settings + dictionary does not contain AllowedBearers, a default + session with "*" will be created. - If the system is not online yet this value is ignored. + string ConnectionType [readwrite] - boolean EmergencyCall [readwrite] + 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 representing the emergency mode of the - modem. The Emergency is true if an emergency call or - related operation is currently active. + '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. - 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. + '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. - As long the EmergencyCall is true no new session can - be created. + '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. - 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. + When a session is created and the provided settings + dictionary does not contain ConnectionType, a default + session with 'any' will be created. - Note only services matching the AllowedBearers rule - will be considered. + (This setting will be removed when the unique process + identification problem is solved.) - string RoamingPolicy [readwrite] + string AllowedInterface [readwrite] [experimental] - The allowed roaming behavior. + 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. - Valid policies are "national", "international", - "default", "always" and "forbidden". + Only one interface may be specified. - "national" allows roaming within a country. - "international" allows roaming in a country and - between countries. + If a specified network interface is not available + (e.g. because AllowedBearers filters it out), the + session will not go online. - "default" is used to tell the Session to use - the global roaming setting. + boolean SourceIPRule [readwrite] [experimental] - "always" will overwrite the default "forbidden" - value which is useful for emergency application. - This value will be protected by additional PolicyKit - rule. + If set to true the session will create source IP + address rule in the firewall, which redirects traffic + to that session's routing table. - Default value is "forbidden". + 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. - string Interface [readonly] + string ContextIdentifier [readwrite] [experimental] - Interface name used by the service object to connect. - This name can be used for SO_BINDTODEVICE in the - application. + 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.