Imported Upstream connman version 1.38

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

diff --git a/doc/service-api.txt b/doc/service-api.txt
old mode 100644 (file)
new mode 100755 (executable)
index 8599041..f8dbb96
--- a/doc/service-api.txt
+++ b/doc/service-api.txt
@@ -1,15 +1,18 @@
 Service hierarchy
 =================
 
 Service hierarchy
 =================
 

-Service                org.moblin.connman
-Interface      org.moblin.connman.Service
+Service                net.connman
+Interface      net.connman.Service

 Object path    [variable prefix]/{service0,service1,...}
 
 Object path    [variable prefix]/{service0,service1,...}
 

-Methods                dict GetProperties()
+Methods                dict GetProperties()  [deprecated]

 
                        Returns properties for the service object. See
                        the properties section for available properties.
 
 
                        Returns properties for the service object. See
                        the properties section for available properties.
 

+                       Usage of this method is highly discouraged. Use
+                       the Manager.GetServices() method instead.
+

                        Possible Errors: [service].Error.InvalidArguments
 
                void SetProperty(string name, variant value)
                        Possible Errors: [service].Error.InvalidArguments
 
                void SetProperty(string name, variant value)


@@ -19,20 +22,25 @@ Methods             dict GetProperties()
                        changeable. On success a PropertyChanged signal
                        will be emitted.
 
                        changeable. On success a PropertyChanged signal
                        will be emitted.
 

+                       Properties cannot be set for hidden WiFi service
+                       entries or provisioned services.
+

                        Possible Errors: [service].Error.InvalidArguments
                                         [service].Error.InvalidProperty
 
                void ClearProperty(string name)
 
                        Possible Errors: [service].Error.InvalidArguments
                                         [service].Error.InvalidProperty
 
                void ClearProperty(string name)
 

-                       Clears the value of the specified property.
+                       Clears the value of the specified property. Only
+                       the readonly Error property can be cleared using
+                       this method call. When cleared the service is reset
+                       to the idle state.

 
 

-                       Possible Errors: [service].Error.InvalidArguments
-                                        [service].Error.InvalidProperty
+                       Possible Errors: [service].Error.InvalidProperty

 
                void Connect()
 
                        Connect this service. It will attempt to connect
 
                void Connect()
 
                        Connect this service. It will attempt to connect

-                       WiFi, WiMAX or Bluetooth services.
+                       WiFi or Bluetooth services.

 
                        For Ethernet devices this method can only be used
                        if it has previously been disconnected. Otherwise
 
                        For Ethernet devices this method can only be used
                        if it has previously been disconnected. Otherwise


@@ -45,6 +53,11 @@ 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.
 

+                       Calling Connect() on a hidden WiFi service entry will
+                       query the missing SSID via the Agent API causing a
+                       WiFi service with the given SSID to be scanned,
+                       created and connected.
+

                        Possible Errors: [service].Error.InvalidArguments
 
                void Disconnect()
                        Possible Errors: [service].Error.InvalidArguments
 
                void Disconnect()


@@ -58,7 +71,10 @@ Methods              dict GetProperties()
                        method will fail.
 
                        This method can also be used to abort a previous
                        method will fail.
 
                        This method can also be used to abort a previous

-                       connectiong attempt via the Connect method.
+                       connection attempt via the Connect method.
+
+                       Hidden WiFi service entries cannot be disconnected
+                       as they always stay in idle state.

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


@@ -75,12 +91,14 @@ Methods             dict GetProperties()
                        to false, but that is currently not supported.
 
                        In the case a connection attempt failed and the
                        to false, but that is currently not supported.
 
                        In the case a connection attempt failed and the

-                       service is in the State=failure, this method can
-                       also be used to reset the service.
+                       service is in the state "failure", "idle" or
+                       "disconnect", this method can also be used
+                       to reset the service.

 
 

-                       Calling this method on Ethernet devices will cause
-                       an error message. It is not possible to remove these
-                       kind of devices.
+                       Calling this method on Ethernet devices, hidden WiFi
+                       services or provisioned services will cause an error
+                       message. It is not possible to remove these kind of
+                       services.

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


@@ -89,9 +107,6 @@ Methods              dict GetProperties()
                        If a service has been used before, this allows a
                        reorder of the favorite services.
 
                        If a service has been used before, this allows a
                        reorder of the favorite services.
 

-                       The target service object must be part of this
-                       profile. Moving between profiles is not supported.
-

                        Possible Errors: [service].Error.InvalidArguments
 
                void MoveAfter(object service)
                        Possible Errors: [service].Error.InvalidArguments
 
                void MoveAfter(object service)


@@ -99,12 +114,9 @@ Methods             dict GetProperties()
                        If a service has been used before, this allows a
                        reorder of the favorite services.
 
                        If a service has been used before, this allows a
                        reorder of the favorite services.
 

-                       The target service object must be part of this
-                       profile. Moving between profiles is not supported.
-

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

-               void ResetCounters()
+               void ResetCounters()  [experimental]

 
                        Reset the counter statistics.
 
 
                        Reset the counter statistics.
 


@@ -120,18 +132,22 @@ Properties        string State [readonly]
                        The service state information.
 
                        Valid states are "idle", "failure", "association",
                        The service state information.
 
                        Valid states are "idle", "failure", "association",

-                       "configuration" and "ready".
+                       "configuration", "ready", "disconnect" and "online".
+
+                       The "ready" state signals a successfully
+                       connected device. "online" signals that an
+                       Internet connection is available and has been
+                       verified.

 
 

-                       Also "login" and "online" states are used. The
-                       state "online" signals that an Internet connection
-                       is available and has been verified.
+                       See doc/overview-api.txt for more information about
+                       state transitions.

 
                string Error [readonly]
 
                        The service error status details.
 
                        When error occur during connection or disconnection
 
                string Error [readonly]
 
                        The service error status details.
 
                        When error occur during connection or disconnection

-                       the detailed information are represented in this
+                       the detailed information is represented in this

                        property to help the user interface to present the
                        user with alternate options.
 
                        property to help the user interface to present the
                        user with alternate options.
 


@@ -139,17 +155,20 @@ Properties        string State [readonly]
                        the "failure" state. Otherwise it might be empty or
                        not present at all.
 
                        the "failure" state. Otherwise it might be empty or
                        not present at all.
 

-                       Current defined error code is "dhcp-failed".
+                       Currently defined error codes are: "out-of-range",
+                       "pin-missing", "dhcp-failed", "connect-failed",
+                       "login-failed", "auth-failed" and "invalid-key".

 
                string Name [readonly]
 
                        The service name (for example "Wireless" etc.)
 
                        This name can be used for directly displaying it in
 
                string Name [readonly]
 
                        The service name (for example "Wireless" etc.)
 
                        This name can be used for directly displaying it in

-                       the application. It has pure informational purpose.
+                       the application. It has pure informational purpose
+                       and no attempt should be made to translate it.

 
 

-                       For Ethernet devices and hidden WiFi networks it is
-                       not guaranteed that this property is present.
+                       For Ethernet devices and hidden WiFi networks this
+                       property is not present.

 
                string Type [readonly]
 
 
                string Type [readonly]
 


@@ -159,59 +178,53 @@ Properties        string State [readonly]
                        advanced properties or showing the correct icon
                        to the user.
 
                        advanced properties or showing the correct icon
                        to the user.
 

-               string Mode [readonly]
-
-                       If the service type is WiFi or Cellular, then this
-                       property is present and contains the mode of the
-                       network.
-
-                       For WiFi services the possible values are "managed"
-                       and "adhoc". For Cellular services it describes the
-                       network technology. Possible values are "gprs", "edge"
-                       and "umts".
+                       Together with a missing Name property, this can
+                       be used to identify hidden WiFi networks.

 
 

-                       This property might be only present for WiFi and
-                       Cellular services.
-
-               string Security [readonly]
+               array{string} Security [readonly]

 
                        If the service type is WiFi, then this property is
 
                        If the service type is WiFi, then this property is

-                       present and contains the security method or key
-                       management setting.
+                       present and contains the list of security methods
+                       or key management settings.
+
+                       Possible values are "none", "wep", "psk", "ieee8021x",
+                       and also "wps" and "wps_advertising".

 
 

-                       Possible values are "none", "wep", "psk" and
-                       also "ieee8021x". Alternate values for "psk"
-                       can also be "wpa" and "rsn".
+                       Value "wps" means that the service supports WPS. A
+                       service advertising itself as WPS registrar contains
+                       the additional value "wps_advertising" for as long as
+                       it is advertising. That is, while "wps_advertising" is
+                       listed, WPS is active and it should be possible to
+                       connect to the corresponding service via WPS.

 
                        This property might be only present for WiFi
                        services.
 
 
                        This property might be only present for WiFi
                        services.
 

-               boolean LoginRequired [readonly]
+               string BSSID [readonly]

 
 

-                       This property indicates that an additional login
-                       step is needed before the connection establishment
-                       can proceed.
+                       If the service type is WiFi, then this property
+                       indicates the BSSID of the service.

 
 

-               string Passphrase [readwrite]
+               uint32 MaxRate [readonly]

 
                        If the service type is WiFi, then this property
 
                        If the service type is WiFi, then this property

-                       can be used to store a passphrase.
+                       indicates the Maximum speed(bps) of the service.

 
 

-                       No PropertyChanged signals will be send for this
-                       property. The PassphraseRequired property should
-                       be monitored instead.
+               uint16 Frequency [readonly]

 
 

-                       This property might also not always be included
-                       since it is protected by a different security policy.
+                       If the service type is WiFi, then this property
+                       indicates the frequency band(MHz) of the service.

 
 

-               boolean PassphraseRequired [readonly]
+               string EncryptionMode [readonly]

 
                        If the service type is WiFi, then this property
 
                        If the service type is WiFi, then this property

-                       indicates if a passphrase is required.
+                       indicates the key encryption mode.

 
 

-                       If a passphrase has been set already or if no
-                       passphrase is needed, then this property will
-                       be set to false.
+                       Possible values are "none", "wep", "tkip", "aes"
+                       and "mixed".
+
+                       This property might be only present for WiFi
+                       services.

 
                uint8 Strength [readonly]
 
 
                uint8 Strength [readonly]
 


@@ -235,46 +248,21 @@ Properties        string State [readonly]
                        This value will be set to true if the service is
                        configured externally via a configuration file.
 
                        This value will be set to true if the service is
                        configured externally via a configuration file.
 

-                       The only valid operation are Connect() and of
-                       course Disconnect(). The Remove() method will
-                       result in an error.
+                       The only valid operations are Connect(), Disconnect()
+                       and changing the AutoConnect property. The Remove()
+                       method will result in an error.

 
                boolean AutoConnect [readwrite]
 
                        If set to true, this service will auto-connect
 
                boolean AutoConnect [readwrite]
 
                        If set to true, this service will auto-connect

-                       when not other connection is available.
+                       when no other connection is available.
+
+                       The service won't auto-connect while roaming.

 
                        For favorite services it is possible to change
                        this value to prevent or permit automatic
                        connection attempts.
 
 
                        For favorite services it is possible to change
                        this value to prevent or permit automatic
                        connection attempts.
 

-               boolean SetupRequired [readonly]
-
-                       If the service is Cellular, then this property
-                       indicates that some extra setup steps are required.
-
-                       In most cases it is required to fill in the APN
-                       details.
-
-               string APN [readwrite]
-
-                       If the service is Cellular, then this property
-                       contains the APN details.
-
-                       The APN is network provider specific and even
-                       sometimes data plan specific. Possible examples
-                       are "isp.cingular" or "internet.t-mobile".
-
-               string MCC [readonly]
-
-                       If the service is Cellular, then this property
-                       contains the Mobile Country Code.
-
-               string MNC [readonly]
-
-                       If the service is Cellular, then this property
-                       contains the Mobile Network Code.
-

                boolean Roaming [readonly]
 
                        This property indicates if this service is roaming.
                boolean Roaming [readonly]
 
                        This property indicates if this service is roaming.


@@ -301,8 +289,9 @@ Properties  string State [readonly]
                array{string} Nameservers.Configuration [readwrite]
 
                        The list of manually configured domain name
                array{string} Nameservers.Configuration [readwrite]
 
                        The list of manually configured domain name

-                       servers. Some 3G networks don't provide correct
-                       name servers and this allows for an override.
+                       servers. Some cellular networks don't provide
+                       correct name servers and this allows for an
+                       override.

 
                        This array is sorted by priority and the first
                        entry in the list represents the nameserver with
 
                        This array is sorted by priority and the first
                        entry in the list represents the nameserver with


@@ -317,9 +306,32 @@ Properties string State [readonly]
                        the service. However there might be small window
                        where name resolution might fail.
 
                        the service. However there might be small window
                        where name resolution might fail.
 

+               array{string} Timeservers [readonly]
+
+                       The list of currently active timeservers for this
+                       service. If the server is not in READY or ONLINE
+                       state than this list will be empty.
+
+               array{string} Timeservers.Configuration [readwrite]
+
+                       The list of manually configured time servers.
+
+                       The first entry in the list represents the
+                       timeserver with the highest priority.
+
+                       When using manual configuration this setting
+                       is useful to override all the other timeserver
+                       settings. This is service specific, hence only
+                       the values for the default service are used.
+
+                       Changes to this property will result in restart
+                       of NTP query.
+

                array{string} Domains [readonly]
 
                array{string} Domains [readonly]
 

-                       The list of currently used search domains.
+                       The list of currently used search domains taken
+                       from Domains.Configurations if set, otherwise a
+                       domain name if provided by DHCP or VPNs.

 
                array{string} Domains.Configuration [readwrite]
 
 
                array{string} Domains.Configuration [readwrite]
 


@@ -329,9 +341,15 @@ Properties string State [readonly]
 
                        string Method [readonly]
 
 
                        string Method [readonly]
 

-                               Possible values are "dhcp", "manual"
+                               Possible values are "dhcp", "manual", "auto"

                                and "off".
 
                                and "off".
 

+                               It could be "auto" in case address was got
+                               through IPv4LL after DHCP failed. In this
+                               case also IPv4.Configuration will become
+                               "auto" to allow user to ask for a DHCP
+                               address at any time.
+

                                The value "fixed" indicates an IP address
                                that can not be modified. For example
                                cellular networks return fixed information.
                                The value "fixed" indicates an IP address
                                that can not be modified. For example
                                cellular networks return fixed information.


@@ -363,14 +381,16 @@ Properties        string State [readonly]
 
                        string Method [readonly]
 
 
                        string Method [readonly]
 

-                               Possible values are "dhcp", "manual"
+                               Possible values are "auto", "manual", "6to4"

                                and "off".
 
                                The value "fixed" indicates an IP address
                                that can not be modified. For example
                                cellular networks return fixed information.
                                and "off".
 
                                The value "fixed" indicates an IP address
                                that can not be modified. For example
                                cellular networks return fixed information.

-
-                               "dhcp" is not supported currently.
+                               The value "6to4" is returned if 6to4 tunnel
+                               is created by connman. The tunnel can only be
+                               created if method was set to "auto" by the
+                               user. User cannot set the method to "6to4".

 
                        string Address [readonly]
 
 
                        string Address [readonly]
 


@@ -384,6 +404,26 @@ Properties string State [readonly]
 
                                The current configured IPv6 gateway.
 
 
                                The current configured IPv6 gateway.
 

+                       string Privacy [readonly]
+
+                               Enable or disable IPv6 privacy extension
+                               that is described in RFC 4941. The value
+                               has only meaning if Method is set to "auto".
+
+                               Value "disabled" means that privacy extension
+                               is disabled and normal autoconf addresses are
+                               used.
+
+                               Value "enabled" means that privacy extension is
+                               enabled and system prefers to use public
+                               addresses over temporary addresses.
+
+                               Value "prefered" means that privacy extension is
+                               enabled and system prefers temporary addresses
+                               over public addresses.
+
+                               Default value is "disabled".
+

                dict IPv6.Configuration [readwrite]
 
                        Same values as IPv6 property. The IPv6 represents
                dict IPv6.Configuration [readwrite]
 
                        Same values as IPv6 property. The IPv6 represents


@@ -402,18 +442,15 @@ Properties        string State [readonly]
                                Possible values are "direct", "auto" and
                                "manual".
 
                                Possible values are "direct", "auto" and
                                "manual".
 

-                               If the DHCP server, or WPAD protocol, provides
-                               an automatic configuration URL, then this value
-                               is set to "auto" in case "auto" is configured"
-                               referenced by the URL value. If "auto" is
-                               configured and DHCP and WPAD auto-discover
-                               methods fails then method will be "direct".
+                               In case of "auto" method, the URL file can be
+                               provided unless you want to let DHCP/WPAD
+                               auto-discover to be tried. In such case if DHCP
+                               and WPAD auto-discover methods fails then
+                               method will be "direct".

 
 

-                               In case of "auto" method, the URL file has
-                               to be provided. In case of "direct" no
-                               additional information are provided. For
-                               the "manual" method the Servers have to
-                               be set.
+                               In case of "direct" no additional information
+                               are provided. For the "manual" method the
+                               Servers have to be set, Excludes is optional.

 
                        string URL [readonly]
 
 
                        string URL [readonly]
 


@@ -445,26 +482,26 @@ Properties        string State [readonly]
                        user configuration.
 
                        If "auto" method is set with an empty URL, then
                        user configuration.
 
                        If "auto" method is set with an empty URL, then

-                       WPAD protocol will be ran. Otherwise the specified
-                       URL will be used.
+                       DHCP/WPAD auto-discover will be tried. Otherwise the
+                       specified URL will be used.

 
                dict Provider [readonly]
 
                        string Host [readonly]
 
 
                dict Provider [readonly]
 
                        string Host [readonly]
 

-                              VPN host IP.
+                               VPN host IP.

 
                        string Domain [readonly]
 
 
                        string Domain [readonly]
 

-                              VPN Domain.
+                               VPN Domain.

 
                        string Name [readonly]
 
 
                        string Name [readonly]
 

-                              VPN provider Name.
+                               VPN provider Name.

 
                        string Type [readonly]
 
 
                        string Type [readonly]
 

-                              VPN provider type.
+                               VPN provider type.

 
                dict Ethernet [readonly]
 
 
                dict Ethernet [readonly]
 


@@ -484,18 +521,60 @@ Properties        string State [readonly]
 
                                The Ethernet MTU (default is 1500).
 
 
                                The Ethernet MTU (default is 1500).
 

-                       uint16 Speed [readonly]
+                       uint16 Speed [readonly] [deprecated]

 
                                Selected speed of the line.
 
 
                                Selected speed of the line.
 

-                               This information might not always be
-                               available.
+                               This information is not available.

 
 

-                       string Duplex [readonly]
+                       string Duplex [readonly] [deprecated]

 
                                Selected duplex settings of the line.
 
                                Selected duplex settings of the line.

-

                                Possible values are "half" and "full".
 
                                Possible values are "half" and "full".
 

-                               This information might not always be
-                               available.
+                               This information is not available.
+
+               bool mDNS [readonly]
+
+                       Whether or not mDNS support is enabled. Note
+                       that mDNS requires a DNS backend which
+                       supports it. Currently the only DNS backend
+                       which supports mDNS is systemd-resolved.
+
+               bool mDNS.Configuration [readwrite]
+
+                       Same values as mDNS property. The mDNS
+                       represents the actual system configuration
+                       while this allows user configuration.
+
+               dict LastAddressConflict [readonly]
+
+                       This property contains information about the previously detected
+                       address conflict. If there has been no address conflict then
+                       IPv4 Address is "0.0.0.0", Ethernet Address is "00:00:00:00:00:00",
+                       Timestamp is zero and Resolved is true.
+
+                       dict IPv4 [readonly]
+
+                               string Address [readonly]
+
+                               The IPv4 address which had a conflict.
+
+                       dict Ethernet [readonly]
+
+                               string Address [readonly]
+
+                               The ethernet device address (MAC address) of the conflicting
+                               host.
+
+                       int64 Timestamp [readonly]
+
+                               A timestamp when the conflict was detected in microseconds
+                               since January 1, 1970 UTC.
+
+                       bool Resolved [readonly]
+
+                               Set to false when an address conflict occurs.
+                               If a previous conflict could be resolved by probing another
+                               IPv4 address (which is not an IPv4LL) then this boolean is set
+                               to true.