wifi: Add wifi pointer NULL checks

[framework/connectivity/connman.git] / doc / service-api.txt

diff --git a/doc/service-api.txt b/doc/service-api.txt
index 0f22f39..7cc6fb4 100644 (file)
--- 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)


@@ -104,6 +107,12 @@ Methods            dict GetProperties()
 
                        Possible Errors: [service].Error.InvalidArguments
 
 
                        Possible Errors: [service].Error.InvalidArguments
 

+               void ResetCounters()  [experimental]
+
+                       Reset the counter statistics.
+
+                       Possible Errors: None
+

 Signals                PropertyChanged(string name, variant value)
 
                        This signal indicates a changed value of the given
 Signals                PropertyChanged(string name, variant value)
 
                        This signal indicates a changed value of the given


@@ -114,14 +123,19 @@ 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" and "online".
+
+                       The "ready" state signals a successfully
+                       connected device. "online" signals that an
+                       Internet connection is available and has been
+                       verified.

 
                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.
 


@@ -136,10 +150,11 @@ Properties        string State [readonly]
                        The service name (for example "Wireless" etc.)
 
                        This name can be used for directly displaying it in
                        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]
 


@@ -149,54 +164,21 @@ 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.
+                       Together with a missing Name property, this can
+                       be used to identify hidden WiFi networks.

 
 

-                       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".
-
-                       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" and
-                       also "ieee8021x". Alternate values for "psk"
-                       can also be "wpa" and "rsn".
+                       Possible values are "none", "wep", "psk", "ieee8021x"
+                       and also "wps".

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

-               string Passphrase [readwrite]
-
-                       If the service type is WiFi, then this property
-                       can be used to store a passphrase.
-
-                       No PropertyChanged signals will be send for this
-                       property. The PassphraseRequired property should
-                       be monitored instead.
-
-                       This property might also not always be included
-                       since it is protected by a different security policy.
-
-               boolean PassphraseRequired [readonly]
-
-                       If the service type is WiFi, then this property
-                       indicates if a passphrase is required.
-
-                       If a passphrase has been set already or if no
-                       passphrase is needed, then this property will
-                       be set to false.
-

                uint8 Strength [readonly]
 
                        Indicates the signal strength of the service. This
                uint8 Strength [readonly]
 
                        Indicates the signal strength of the service. This


@@ -226,54 +208,85 @@ Properties        string State [readonly]
                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]
+               boolean Roaming [readonly]

 
 

-                       If the service is Cellular, then this property
-                       indicates that some extra setup steps are required.
+                       This property indicates if this service is roaming.

 
 

-                       In most cases it is required to fill in the APN
-                       details.
+                       In the case of Cellular services this normally
+                       indicates connections to a foreign provider when
+                       traveling abroad.

 
 

-               string APN [readwrite]
+               array{string} Nameservers [readonly]

 
 

-                       If the service is Cellular, then this property
-                       contains the APN details.
+                       The list of currently active nameservers for this
+                       service. If the server is not in READY or ONLINE
+                       state than this list will be empty.

 
 

-                       The APN is network provider specific and even
-                       sometimes data plan specific. Possible examples
-                       are "isp.cingular" or "internet.t-mobile".
+                       Global nameservers are automatically added to this
+                       list. The array represents a sorted list of the
+                       current nameservers. The first one has the highest
+                       priority and is used by default.

 
 

-               string MCC [readonly]
+                       When using DHCP this array represents the nameservers
+                       provided by the network. In case of manual settings,
+                       the ones from Nameservers.Configuration are used.

 
 

-                       If the service is Cellular, then this property
-                       contains the Mobile Country Code.
+               array{string} Nameservers.Configuration [readwrite]

 
 

-               string MNC [readonly]
+                       The list of manually configured domain name
+                       servers. Some cellular networks don't provide
+                       correct name servers and this allows for an
+                       override.

 
 

-                       If the service is Cellular, then this property
-                       contains the Mobile Network Code.
+                       This array is sorted by priority and the first
+                       entry in the list represents the nameserver with
+                       the highest priority.

 
 

-               boolean Roaming [readonly]
+                       When using manual configuration and no global
+                       nameservers are configured, then it is useful
+                       to configure this setting.

 
 

-                       This property indicates if this service is roaming.
+                       Changes to the domain name servers can be done
+                       at any time. It will not cause a disconnect of
+                       the service. However there might be small window
+                       where name resolution might fail.

 
 

-                       In the case of Cellular services this normally
-                       indicates connections to a foreign provider when
-                       traveling abroad.
+               array{string} Timeservers [readonly]

 
 

-               array{string} Nameservers [readwrite]
+                       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.

 
 

-                       The list of manually configured domain name
-                       servers. Some 3G networks don't provide correct
-                       name servers and this allows for an override.
+               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 [readwrite]
+                       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]

 
                        The list of manually configured search domains.
 
 
                        The list of manually configured search domains.
 


@@ -284,6 +297,10 @@ Properties string State [readonly]
                                Possible values are "dhcp", "manual"
                                and "off".
 
                                Possible values are "dhcp", "manual"
                                and "off".
 

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

                        string Address [readonly]
 
                                The current configured IPv4 address.
                        string Address [readonly]
 
                                The current configured IPv4 address.


@@ -302,27 +319,136 @@ Properties       string State [readonly]
                        the actual system configuration while this allows
                        user configuration.
 
                        the actual system configuration while this allows
                        user configuration.
 

-               dict Proxy [readonly]
+                       Changing these settings will cause a state change
+                       of the service. The service will become unavailable
+                       until the new configuration has been successfully
+                       installed.
+
+               dict IPv6 [readonly]

 
                        string Method [readonly]
 
 
                        string Method [readonly]
 

-                               Possible values are "direct", "auto",
-                               "manual" and "auto-config".
+                               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.
+                               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]

 
 

-                               If the DHCP server provides an automatic
-                               configuration URL, then this value is set
-                               to "auto-config". The PAC file will be
-                               referenced by the URL value.
+                               The current configured IPv6 address.

 
 

-                               If no automatic configuration is available,
-                               then "direct" is set.
+                       uint8 PrefixLength [readonly]

 
 

-                               The values "auto" and "manual" are not yet
-                               supported.
+                               The prefix length of the IPv6 address.
+
+                       string Gateway [readonly]
+
+                               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
+                       the actual system configuration while this allows
+                       user configuration.
+
+                       Changing these settings will cause a state change
+                       of the service. The service will become unavailable
+                       until the new configuration has been successfully
+                       installed.
+
+               dict Proxy [readonly]
+
+                       string Method [readonly]
+
+                               Possible values are "direct", "auto" and
+                               "manual".
+
+                               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 "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]
 

-                               Automatic proxy configuration URL.
+                               Automatic proxy configuration URL. Used by
+                               "auto" method.
+
+                       array{string} Servers [readonly]
+
+                               Used when "manual" method is set.
+
+                               List of proxy URIs. The URI without a protocol
+                               will be interpreted as the generic proxy URI.
+                               All others will target a specific protocol and
+                               only once.
+
+                               Example for generic proxy server entry would
+                               be like this: "server.example.com:911".
+
+                       array{string} Excludes [readonly]
+
+                               Used when "manual" method is set.
+
+                               List of hosts which can be accessed directly.
+
+               dict Proxy.Configuration [readwrite]
+
+                       Same values as Proxy property. The Proxy represents
+                       the actual system configuration while this allows
+                       user configuration.
+
+                       If "auto" method is set with an empty URL, then
+                       DHCP/WPAD auto-discover will be tried. Otherwise the
+                       specified URL will be used.
+
+               dict Provider [readonly]
+
+                       string Host [readonly]
+
+                               VPN host IP.
+
+                       string Domain [readonly]
+
+                               VPN Domain.
+
+                       string Name [readonly]
+
+                               VPN provider Name.
+
+                       string Type [readonly]
+
+                               VPN provider type.

 
                dict Ethernet [readonly]
 
 
                dict Ethernet [readonly]
 


@@ -330,6 +456,10 @@ Properties string State [readonly]
 
                                Possible values are "auto" and "manual".
 
 
                                Possible values are "auto" and "manual".
 

+                       string Interface [readonly]
+
+                               Interface name (for example eth0).
+

                        string Address [readonly]
 
                                Ethernet device address (MAC address).
                        string Address [readonly]
 
                                Ethernet device address (MAC address).