doc: Make session methods as experimental for now
[platform/upstream/connman.git] / doc / manager-api.txt
index 13ca366..02fd89d 100644 (file)
@@ -1,8 +1,8 @@
 Manager hierarchy
 =================
 
-Service                org.moblin.connman
-Interface      org.moblin.connman.Manager
+Service                net.connman
+Interface      net.connman.Manager
 Object path    /
 
 Methods                dict GetProperties()
@@ -20,28 +20,56 @@ Methods             dict GetProperties()
                        will be emitted.
 
                        Possible Errors: [service].Error.InvalidArguments
-                                        [service].Error.DoesNotExist
+                                        [service].Error.InvalidProperty
 
-               object AddProfile(string name)
+               void RequestScan(string type)
 
-                       Add a new profile with the specified name.
+                       Request to trigger a scan for the specified
+                       technology. The empty string "" triggers scanning
+                       on all technologies.
 
-                       It is possible to create two profiles with the same
-                       name. The identification is done via the object path
-                       and not the name of the profile.
+                       Possible Errors: [service].Error.InvalidArguments
+
+               void EnableTechnology(string type)
+
+                       Enable specified type of technologies.
 
                        Possible Errors: [service].Error.InvalidArguments
 
-               void RemoveProfile(object path)
+               void DisableTechnology(string type)
 
-                       Remove profile with specified object path.
+                       Disable specified type of technologies.
 
-                       It is not possible to remove the current active
-                       profile. To remove the active profile a different
-                       one must be selected via ActiveProfile property
-                       first.
+                       Possible Errors: [service].Error.InvalidArguments
 
-                       At minimum one profile must be available all the time.
+               array{object,dict} GetServices()
+
+                       Returns a sorted list of tuples with service
+                       object path and dictionary of service properties.
+
+                       This list will not contain sensitive information
+                       like passphrases etc.
+
+                       Possible Errors: [service].Error.InvalidArguments
+
+               object ConnectProvider(dict provider)
+
+                       Connect to a VPN specified by the given provider
+                       properties.
+
+                       When successful this method will return the object
+                       path of the VPN service object.
+
+                       This method can also be used to connect to an
+                       already existing VPN.
+
+                       This method call will only return in case of an
+                       error or when the service is fully connected. So
+                       setting a longer D-Bus timeout might be a really
+                       good idea.
+
+                       When 'SessionMode' property is enabled, this method
+                       call is disallowed.
 
                        Possible Errors: [service].Error.InvalidArguments
 
@@ -57,6 +85,75 @@ Methods              dict GetProperties()
 
                        Possible Errors: [service].Error.InvalidArguments
 
+               void RegisterCounter(object path, uint32 accuracy, uint32 period)  [experimental]
+
+                       Register a new counter for user notifications.
+
+                       The accuracy is specified in kilo-bytes and defines
+                       a threshold for counter updates. Together with the
+                       period value it defines how often user space needs
+                       to be updated. The period value is in seconds.
+
+                       This interface is not meant for time tracking. If
+                       the time needs to be tracked down to the second, it
+                       is better to have a real timer running inside the
+                       application than using this interface.
+
+                       Also getting notified for every kilo-byte is a bad
+                       choice (even if the interface supports it). Something
+                       like 10 kilo-byte units or better 1 mega-byte seems
+                       to be a lot more reasonable and better for the user.
+
+                       Possible Errors: [service].Error.InvalidArguments
+
+               void UnregisterCounter(object path)  [experimental]
+
+                       Unregister an existing counter.
+
+                       Possible Errors: [service].Error.InvalidArguments
+
+               object CreateSession(dict settings, object notifier)  [experimental]
+
+                       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.
+
+                       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.
+
+                       Every application should at least create one session
+                       to inform about its requirements and it purpose.
+
+               void DestroySession(object session)  [experimental]
+
+                       Remove the previously created session.
+
+                       If an application exits unexpectatly the session
+                       will be automatically destroyed.
+
+               object path, dict, fd RequestPrivateNetwork(dict options)
+                                                               [experimental]
+
+                       Request a new Private Network, which includes the
+                       creation of a tun/tap interface, and IP
+                       configuration, NAT and IP forwarding on that
+                       interface.
+                       An object path, a dictionnary and a file descriptor
+                       with IP settings are returned.
+
+                       Possible Errors: [service].Error.InvalidArguments
+                                        [service].Error.NotSupported
+
+               void ReleasePrivateNetwork(object path) [experimental]
+
+                       Releases a private network.
+
+                       Possible Errors: [service].Error.InvalidArguments
+
 Signals                PropertyChanged(string name, variant value)
 
                        This signal indicates a changed value of the given
@@ -72,17 +169,25 @@ Properties string State [readonly]
                        the value "connected". This can only be seen if
                        previously no connection was present.
 
-               string Policy [readwrite]
+               array{string} AvailableTechnologies [readonly]
+
+                       The list of available technologies. The strings
+                       are the same as the ones from the service types.
+
+               array{string} EnabledTechnologies [readonly]
+
+                       The list of enabled technologies. The strings
+                       are the same as the ones from the service types.
 
-                       The global connection policy of a system. This
-                       allows to configure how connections are established
-                       and also when they are taken down again.
+               array{string} ConnectedTechnologies [readonly]
 
-                       Possible values are "single", "multiple" and "ask".
+                       The list of connected technologies. The strings
+                       are the same as the ones from the service type.
 
-                       For the single policy, the priority setting of the
-                       device defines which becomes the default connection
-                       when multiple are available.
+               string DefaultTechnology [readonly]
+
+                       The current connected technology which holds the
+                       default route.
 
                boolean OfflineMode [readwrite]
 
@@ -97,17 +202,9 @@ Properties  string State [readonly]
                        the limited usage of WiFi or Bluetooth devices might
                        be allowed in some situations.
 
-               object ActiveProfile [readwrite]
-
-                       Object path of the current active profile.
-
-               array{object} Profiles [readonly]
+               array{object} Technologies [readonly]
 
-                       List of profile object paths.
-
-               array{object} Devices [readonly]
-
-                       List of device object paths.
+                       List of technology object paths.
 
                array{object} Services [readonly]
 
@@ -125,6 +222,11 @@ Properties string State [readonly]
                        applications only dealing with the current active
                        profile.
 
-               array{object} Connections [readonly]
+               boolean SessionMode [readwrite]  [experminental]
+
+                       This disables the auto connect feature. It should be
+                       enabled when the Session API is used. When SessionMode
+                       is enabled, 'ConnectService' and 'ConnectProvider'
+                       method calls are disallowed.
 
-                       List of active connection object paths.
+                       The default value is false.