diff options
authorMarcel Holtmann <>2011-03-31 10:02:24 +0200
committerSamuel Ortiz <>2011-03-31 12:28:47 +0200
commit2d1d20c887192944ce6da3cc5e5b8c23ed3860db (patch)
parentcdb087d5765682578a1fbf0067ef9950ff79f46b (diff)
session: Update documentation
2 files changed, 251 insertions, 16 deletions
diff --git a/doc/manager-api.txt b/doc/manager-api.txt
index 332f6cda..c92c2957 100644
--- a/doc/manager-api.txt
+++ b/doc/manager-api.txt
@@ -174,28 +174,29 @@ Methods dict GetProperties()
Possible Errors: [service].Error.InvalidArguments
- object RequestSession(string bearer)
+ object CreateSession(dict settings, object notifier)
- Request a networking session.
+ Create a new session for the application. Every
+ application can create multiple session with
+ different settings. The settings are described
+ as part of the session interface.
- If the bearer is an empty string the best available
- service will be picked.
+ The notifier allows asynchronous notification about
+ session specific changes. These changes can be
+ for online/offline state or IP address changes or
+ similar things the application is required to
+ handle.
- When successful this method will return the object
- path of the corresponding service.
- Possible Errors: [service].Error.InvalidArguments
+ Every application should at least create one session
+ to inform about its requirements and it purpose.
- void ReleaseSession()
- Release a networking session.
- Possible Errors: [service].Error.InvalidArguments
+ void DestroySession(object session)
-Signals PropertyChanged(string name, variant value)
+ Remove the previously created session. The notifier
+ will be informed via its release method.
- This signal indicates a changed value of the given
- property.
+ If an application exits unexpectatly the session
+ will be automatically destroyed.
StateChanged(string state)
diff --git a/doc/session-api.txt b/doc/session-api.txt
new file mode 100644
index 00000000..0e2a3643
--- /dev/null
+++ b/doc/session-api.txt
@@ -0,0 +1,234 @@
+Service unique name
+Interface net.connman.Notification
+Object path freely definable
+Methods void Release()
+ This method gets called when the service daemon
+ unregisters the session. A counter can use it to do
+ cleanup tasks. There is no need to unregister the
+ session, because when this method gets called it has
+ already been unregistered.
+ void Update(dict settings)
+ Sends an update of changed settings. Only settings
+ that are changed will be included.
+ Initially on every session creation this method is
+ called once to inform about the current settings.
+Service net.connman
+Interface net.connman.Session
+Object path variable
+Methods void Destroy()
+ Close the current session. This is similar to
+ DestroySession method on the manager interface. It
+ is just provided for convenience depending on how
+ the application wants to track the session.
+ void Connect()
+ If not connected, then attempt to connect this
+ session.
+ The usage of this method depends a little bit on
+ the model of the application. Some application
+ should not try to call Connect on any session at
+ all. They should just monitor if it becomes online
+ or gets back offline.
+ Others might require an active connection right now.
+ So for example email notification should only check
+ for new emails when a connection is available. However
+ if the user presses the button for get email or wants
+ to send an email it should request to get online with
+ this method.
+ 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.
+ It is also not guaranteed that a session stays online
+ after this method call. It can be taken offline at any
+ time. This might happen because of idle timeouts or
+ other reasons.
+ It is safe to call this method multiple times. The
+ actual usage will be sorted out for the application.
+ void Disconnect()
+ 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.
+ void Change(string name, variant value)
+ Change the value of certain settings. Not all
+ settings can be changed. Normally this should not
+ be needed or an extra session should be created.
+ However in some cases it makes sense to change
+ a value and trigger different behavior.
+ A change of a setting will cause an update notification
+ 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
+ can be delayed based on the speed of the bearer. It
+ is done to avoid congestion on bearers like 3G etc.
+ boolean Realtime [readwrite]
+ This indicates if the application uses realtime traffic.
+ For example a streaming session should set the
+ realtime value. As soon as realtime data is involved
+ then this should be set. An email client should not
+ set this value.
+ 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.
+ 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]
+ 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.
+ 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.
+ Never the less application needs to be aware that
+ handovers can happen at any time even if this is
+ set to true.
+ boolean StayConnected [readwrite]
+ This disables the idle timeout for this session. There
+ is no guarantee and this should be used with care.
+ If the system is not online yet this value is ignored.
+ uint32 PeriodicConnect [readwrite]
+ 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.
+ A value of 0 disable this feature.
+ 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.
+ 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.
+ 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.
+ boolean RoamingAllowed [readwrite]
+ By default this value is true. The application can
+ disabling roaming on a global level.
+ string Interface [readonly]
+ Interface name used by the service object to connect.
+ This name can be used for SO_BINDTODEVICE in the
+ application.
+ uint32 SessionMarker [readonly]
+ 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.