Add additional information to the API overview
[connman] / doc / manager-api.txt
index 0c4de41..13ca366 100644 (file)
 Manager hierarchy
-*****************
+=================
 
-Service name   org.freedesktop.connman
-Interface name org.freedesktop.connman.Manager
+Service                org.moblin.connman
+Interface      org.moblin.connman.Manager
 Object path    /
 
-Methods                array{object} ListInterfaces()
-               string GetState()
+Methods                dict GetProperties()
+
+                       Returns all global system properties. See the
+                       properties section for available properties.
+
+                       Possible Errors: [service].Error.InvalidArguments
+
+               void SetProperty(string name, variant value)
+
+                       Changes the value of the specified property. Only
+                       properties that are listed as read-write are
+                       changeable. On success a PropertyChanged signal
+                       will be emitted.
+
+                       Possible Errors: [service].Error.InvalidArguments
+                                        [service].Error.DoesNotExist
+
+               object AddProfile(string name)
+
+                       Add a new profile with the specified name.
+
+                       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 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 RegisterAgent(object path)
+
+                       Register new agent for handling user requests.
+
+                       Possible Errors: [service].Error.InvalidArguments
+
                void UnregisterAgent(object path)
 
-Signals                InterfaceAdded(object)
-               InterfaceRemoved(object)
-               StateChanged(string state)
-
-
-Method: ListInferfaces
-======================
-This method lists all available interfaces. The return value is an array of
-object paths. Every attached network interface (eth0, wlan0 etc.) of the
-system is presented by an object path with additional interfaces on it. The
-main interface is org.freedesktop.connman.Interface.
-
-Method: GetState
-================
-This method gets the overall master state of the Internet connection. Possible
-return values are "offline" and "online". If at least one interface is
-connected it will return "online".
-
-Method: RegisterAgent
-=====================
-This method allows the user interace to register an agent. There can be only
-one agent registered at a time. The parameter of the method is the object
-path the agent has been registered for the callback method. The agent has
-to implement org.freedesktop.connman.Agent interface on this object path.
-
-Method: UnregisterAgent
-=======================
-This method unregisters a previously registered agent. In case the agent
-application exits the core will automatically unregister the agent. However
-for a clean agent application it is important to call the unregister method.
-
-Signal: InterfaceAdded
-======================
-This signal is emitted every time a new interface has been found by the
-core and successfully activated. The signal is also emitted on startup
-or at anytime at runtime in case of hotplug devices.
-
-Signal: InterfaceRemoved
-========================
-This signal is emitted every time an interface has been removed. This can
-happen at any time in case of hotplug devices. When the system shuts down,
-this signal is also emitted.
-
-Signal: StateChanged
-====================
-This signal is emitted every time the master state changes. Possible values
-are "offline" and "online" and reflect the state of the Internet connection.
+                       Unregister an existing agent.
+
+                       Possible Errors: [service].Error.InvalidArguments
+
+Signals                PropertyChanged(string name, variant value)
+
+                       This signal indicates a changed value of the given
+                       property.
+
+Properties     string State [readonly]
+
+                       The global connection state of a system. Possible
+                       values are "online" if at least one connection exists
+                       and "offline" if no device is connected.
+
+                       In certain situations the state might change to
+                       the value "connected". This can only be seen if
+                       previously no connection was present.
+
+               string Policy [readwrite]
+
+                       The global connection policy of a system. This
+                       allows to configure how connections are established
+                       and also when they are taken down again.
+
+                       Possible values are "single", "multiple" and "ask".
+
+                       For the single policy, the priority setting of the
+                       device defines which becomes the default connection
+                       when multiple are available.
+
+               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.
+
+               object ActiveProfile [readwrite]
+
+                       Object path of the current active profile.
+
+               array{object} Profiles [readonly]
+
+                       List of profile object paths.
+
+               array{object} Devices [readonly]
+
+                       List of device object paths.
+
+               array{object} Services [readonly]
+
+                       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 list represents the available services for the
+                       current selected profile. If the profile gets changed
+                       then this list will be updated.
+
+                       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.
+
+               array{object} Connections [readonly]
+
+                       List of active connection object paths.