Svace Fix: memory leak

[platform/upstream/connman.git] / doc / manager-api.txt

diff --git a/doc/manager-api.txt b/doc/manager-api.txt
old mode 100644 (file)
new mode 100755 (executable)
index f07e185..bfb07bd
--- a/doc/manager-api.txt
+++ b/doc/manager-api.txt
@@ -22,50 +22,10 @@ Methods             dict GetProperties()
                        Possible Errors: [service].Error.InvalidArguments
                                         [service].Error.InvalidProperty
 
                        Possible Errors: [service].Error.InvalidArguments
                                         [service].Error.InvalidProperty
 

-               string GetState()
+               array{object,dict} GetTechnologies()

 
 

-                       Return global connection state of a system. The
-                       same value is return via the State property.
-
-                       Possible Errors: [service].Error.InvalidArguments
-
-               object CreateProfile(string name)
-
-                       Create and add new profile with the specified
-                       identifier name.
-
-                       Possible Errors: [service].Error.InvalidArguments
-
-               void RemoveProfile(object path)
-
-                       Remove profile with specified object path.
-
-                       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.
-
-                       At minimum one profile must be available all the time.
-
-                       Possible Errors: [service].Error.InvalidArguments
-
-               void RequestScan(string type)
-
-                       Request to trigger a scan for the specified
-                       technology. The empty string "" triggers scanning
-                       on all technologies.
-
-                       Possible Errors: [service].Error.InvalidArguments
-
-               void EnableTechnology(string type)
-
-                       Enable specified type of technologies.
-
-                       Possible Errors: [service].Error.InvalidArguments
-
-               void DisableTechnology(string type)
-
-                       Disable specified type of technologies.
+                       Returns a list of tuples with technology object
+                       path and dictionary of technology properties.

 
                        Possible Errors: [service].Error.InvalidArguments
 
 
                        Possible Errors: [service].Error.InvalidArguments
 


@@ -79,45 +39,19 @@ Methods             dict GetProperties()
 
                        Possible Errors: [service].Error.InvalidArguments
 
 
                        Possible Errors: [service].Error.InvalidArguments
 

-               object LookupService(string pattern)
-
-                       Lookup a service matching the specific pattern.
+               array{object,dict} GetPeers() [experimental]

 
 

-                       Examples are interface names like "eth0", "wlan0"
-                       etc. or service names like "hotspot" etc.
-
-                       In case of multiple services match the the pattern
-                       an error is returned.
+                       Returns a sorted list of tuples with peer object path
+                       and dictionary of peer properties

 
                        Possible Errors: [service].Error.InvalidArguments
 
                        Possible Errors: [service].Error.InvalidArguments

-                                        [service].Error.NotUnique
-                                        [service].Error.NotFound
-
-               object ConnectService(dict network)
-
-                       Connect to a network specified by the given
-                       properties.
-
-                       For connecting to a hidden WiFi network for example
-                       it is required that Type = "wifi" and the SSID
-                       properties are provided.
-
-                       When successful this method will return object
-                       path of the service object.

 
 

-                       This method can also be used to connect to an
-                       already existing service. It works exactly the
-                       same as executing the Connect method from the
-                       service interface.
-
-                       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.
+               array{string} GetTetheringClients() [experimental]

 
 

-                       Possible Errors: [service].Error.InvalidArguments
+                       Returns a sorted list of MAC addresses of clients
+                       connected to tethered technologies.

 
 

-               object ConnectProvider(dict provider)
+               object ConnectProvider(dict provider)   [deprecated]

 
                        Connect to a VPN specified by the given provider
                        properties.
 
                        Connect to a VPN specified by the given provider
                        properties.


@@ -133,8 +67,19 @@ Methods             dict GetProperties()
                        setting a longer D-Bus timeout might be a really
                        good idea.
 
                        setting a longer D-Bus timeout might be a really
                        good idea.
 

+                       When 'SessionMode' property is enabled, this method
+                       call is disallowed.
+
+                       This API is deprecated and should not be used.
+                       The VPN configuration API is provided by ConnMan
+                       VPN daemon and user should use that one instead.
+

                        Possible Errors: [service].Error.InvalidArguments
 
                        Possible Errors: [service].Error.InvalidArguments
 

+               void RemoveProvider(object path)        [deprecated]
+
+                       Remove a VPN specified by the object path.
+

                void RegisterAgent(object path)
 
                        Register new agent for handling user requests.
                void RegisterAgent(object path)
 
                        Register new agent for handling user requests.


@@ -147,7 +92,7 @@ Methods              dict GetProperties()
 
                        Possible Errors: [service].Error.InvalidArguments
 
 
                        Possible Errors: [service].Error.InvalidArguments
 

-               void RegisterCounter(object path, uint32 accuracy, uint32 period)
+               void RegisterCounter(object path, uint32 accuracy, uint32 period)  [experimental]

 
                        Register a new counter for user notifications.
 
 
                        Register a new counter for user notifications.
 


@@ -168,13 +113,13 @@ Methods           dict GetProperties()
 
                        Possible Errors: [service].Error.InvalidArguments
 
 
                        Possible Errors: [service].Error.InvalidArguments
 

-               void UnregisterCounter(object path)
+               void UnregisterCounter(object path)  [experimental]

 
                        Unregister an existing counter.
 
                        Possible Errors: [service].Error.InvalidArguments
 
 
                        Unregister an existing counter.
 
                        Possible Errors: [service].Error.InvalidArguments
 

-               object CreateSession(dict settings, object notifier)
+               object CreateSession(dict settings, object notifier)  [experimental]

 
                        Create a new session for the application. Every
                        application can create multiple session with
 
                        Create a new session for the application. Every
                        application can create multiple session with


@@ -190,97 +135,187 @@ Methods          dict GetProperties()
                        Every application should at least create one session
                        to inform about its requirements and it purpose.
 
                        Every application should at least create one session
                        to inform about its requirements and it purpose.
 

-               void DestroySession(object session)
+               void DestroySession(object session)  [experimental]

 
 

-                       Remove the previously created session. The notifier
-                       will be informed via its release method.
+                       Remove the previously created session.

 
                        If an application exits unexpectatly the session
                        will be automatically destroyed.
 
 
                        If an application exits unexpectatly the session
                        will be automatically destroyed.
 

-               StateChanged(string state)
+               object path, dict, fd RequestPrivateNetwork(dict options)
+                                                               [experimental]

 
 

-                       This signal is similar to the PropertyChanged signal
-                       for the State property.
+                       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.

 
 

-                       It exists for application state only care about the
-                       current state and so can avoid to be woken up when
-                       other details changes.
+                       Possible Errors: [service].Error.InvalidArguments
+                                        [service].Error.NotSupported

 
 

-Properties     string State [readonly]
+               void ReleasePrivateNetwork(object path) [experimental]

 
 

-                       The global connection state of a system. Possible
-                       values are "online" if at least one connection exists
-                       and "offline" if no device is connected.
+                       Releases a private network.

 
 

-                       In certain situations the state might change to
-                       the value "connected". This can only be seen if
-                       previously no connection was present.
+                       Possible Errors: [service].Error.InvalidArguments

 
 

-               array{string} AvailableTechnologies [readonly]
+               void RegisterPeerService(dict specification, boolean master)
+                          [experimental]

 
 

-                       The list of available technologies. The strings
-                       are the same as the ones from the service types.
+                       Registers a local P2P Peer service

 
 

-               array{string} EnabledTechnologies [readonly]
+                       Even if p2p techonology is not available, it will be
+                       possible to register peer services, since a p2p
+                       enabled WiFi device might appear at anytime. The
+                       registered peer services will automatically be enabled
+                       for the p2p WiFi device; the application does not need
+                       to do any re-registration.

 
 

-                       The list of enabled technologies. The strings
-                       are the same as the ones from the service types.
+                       A Peer service belongs to the process that registers
+                       it, thus if that process dies, its Peer services will
+                       be destroyed as well.

 
 

-               array{string} ConnectedTechnologies [readonly]
+                       The specification dict follows the format described
+                       in the Peer API document.

 
 

-                       The list of connected technologies. The strings
-                       are the same as the ones from the service type.
+                       ConnMan will be able to determine in most cases
+                       whether to be the P2P Group Owner or not. If the
+                       service for some reason must belong to a group that
+                       this device manages, the "master" property can be
+                       set. Do not enable the "master" property unless it
+                       is absolutely sure that this is needed for the
+                       provided peer service.

 
 

-               string DefaultTechnology [readonly]
+                       Possible Errors: [service].Error.InvalidArguments
+                                        [service].Error.AlreadyExists
+                                        [service].Error.NotSupported

 
 

-                       The current connected technology which holds the
-                       default route.
+               void UnregisterPeerService(dict specification) [experimental]

 
 

-               boolean OfflineMode [readwrite]
+                       Unregisters an existing local P2P Peer service

 
 

-                       The offline mode indicates the global setting for
-                       switching all radios on or off. Changing offline mode
-                       to true results in powering down all devices. When
-                       leaving offline mode the individual policy of each
-                       device decides to switch the radio back on or not.
+                       Possible Errors: [service].Error.InvalidArguments
+                                        [service].Error.NotRegistered

 
 

-                       During offline mode, it is still possible to switch
-                       certain technologies manually back on. For example
-                       the limited usage of WiFi or Bluetooth devices might
-                       be allowed in some situations.
+Signals                TechnologyAdded(object path, dict properties)
+
+                       Signal that is sent when a new technology is added.
+
+                       It contains the object path of the technology and
+                       also its properties.
+
+               TechnologyRemoved(object path)
+
+                       Signal that is sent when a technology has been removed.
+
+                       The object path is no longer accessible after this
+                       signal and only emitted for reference.
+
+               ServicesChanged(array{object, dict}, array{object})
+
+                       This signal indicates a change in the services.
+                       List of all services currently registered is passed
+                       via the first array. And a list of services that have
+                       been removed via the second array.
+
+                       The list of all services is sorted. The dictionary
+                       with the properties might be empty in case none of
+                       the properties have changed. Or only contains the
+                       properties that have changed.
+
+                       For newly added services the whole set of properties
+                       will be present.
+
+                       The list of removed services can be empty.
+
+                       This signal will only be triggered when the sort
+                       order of the service list or the number of services
+                       changes. It will not be emitted if only a property
+                       of the service object changes. For that it is
+                       required to watch the PropertyChanged signal of
+                       the service object.

 
 

-               object ActiveProfile [readwrite]
+               PeersChanged(array{object, dict}, array{object}) [experimental]

 
 

-                       Object path of the current active profile.
+                       This signal indicates a change in the peers. List of
+                       all peers currently registered is passed via the first
+                       array. And a list of peers that have been removed via
+                       the second array.

 
 

-               array{object} Profiles [readonly]
+                       The list of all peers is sorted. The dictionary
+                       with the properties might be empty in case none of the
+                       properties have changed. Or only contains the
+                       properties that have changed.

 
 

-                       List of profile object paths.
+                       For newly added peers the whole set of properties will
+                       be present.

 
 

-               array{object} Technologies [readonly]
+                       The list of removed peers can be empty.

 
 

-                       List of technology object paths.
+                       This signal will only be triggered when the sort order
+                       of the peer list or the number of peers changes. It
+                       will not be emitted if only a property of the peer
+                       object changes. For that it is required to watch the
+                       PropertyChanged signal of the peer object.

 
 

-               array{object} Services [readonly]
+               TetheringClientsChanged(array{string}, array{string}) [experimental]

 
 

-                       List of service object paths. The list is sorted
-                       internally to have the service with the default
-                       route always first and then the favorite services
-                       followed by scan results.
+                       This signal indicates a change in the tethering clients.
+                       List of all tethering clients currently registered connman is
+                       passed via the first array. And a list of tethering clients that
+                       have been removed via the second array.

 
 

-                       This list represents the available services for the
-                       current selected profile. If the profile gets changed
-                       then this list will be updated.
+               PropertyChanged(string name, variant value)

 
 

-                       The same list is available via the profile object
-                       itself. It is just provided here for convenience of
-                       applications only dealing with the current active
-                       profile.
+                       This signal indicates a changed value of the given
+                       property.
+
+Properties     string State [readonly]
+
+                       The global connection state of a system. Possible
+                       values are "offline", "idle", "ready" and "online".
+
+                       If the device is in offline mode, the value "offline"
+                       indicates this special global state. It can also be
+                       retrieved via the OfflineMode property, but is kept
+                       here for consistency and to differentiate from "idle".
+
+                       However when OfflineMode property is true, the State
+                       property can still be "idle", "ready" or "online"
+                       since it is possible by the end user to re-enable
+                       individual technologies like WiFi and Bluetooth while
+                       in offline mode.
+
+                       The states "idle", "ready" and "online" match to
+                       states from the services. If no service is in
+                       either "ready" or "online" state it will indicate
+                       the "idle" state.
+
+                       If at least one service is in "ready" state and no
+                       service is in "online" state, then it will indicate
+                       the "ready" state.
+
+                       When at least one service is in "online" state,
+                       this property will indicate "online" as well.
+
+               boolean OfflineMode [readwrite]
+
+                       The offline mode indicates the global setting for
+                       switching all radios on or off. Changing offline mode
+                       to true results in powering down all devices. When
+                       leaving offline mode the individual policy of each
+                       device decides to switch the radio back on or not.
+
+                       During offline mode, it is still possible to switch
+                       certain technologies manually back on. For example
+                       the limited usage of WiFi or Bluetooth devices might
+                       be allowed in some situations.

 
 

-               boolean SessionMode [readwrite]
+               boolean SessionMode [readwrite]  [experminental][deprecated]

 
 

-                       This disables the auto connect feature. It should be
-                       enabled when the Session API is used.
+                       This property exists only for compatibility reasons
+                       and does not affect ConnMan in any way.

 
                        The default value is false.
 
                        The default value is false.