Update counter API documentation

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

diff --git a/doc/service-api.txt b/doc/service-api.txt
index 3ae9faf..a3e3c10 100644 (file)
--- a/doc/service-api.txt
+++ b/doc/service-api.txt
@@ -12,18 +12,399 @@ Methods            dict GetProperties()
 
                        Possible Errors: [service].Error.InvalidArguments
 
 
                        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.InvalidProperty
+
+               void ClearProperty(string name)
+
+                       Clears the value of the specified property.
+
+                       Possible Errors: [service].Error.InvalidArguments
+                                        [service].Error.InvalidProperty
+
+               void Connect()
+
+                       Connect this service. It will attempt to connect
+                       WiFi, WiMAX or Bluetooth services.
+
+                       For Ethernet devices this method can only be used
+                       if it has previously been disconnected. Otherwise
+                       the plugging of a cable will trigger connecting
+                       automatically. If no cable is plugged in this method
+                       will fail.
+
+                       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.
+
+                       Possible Errors: [service].Error.InvalidArguments
+
+               void Disconnect()
+
+                       Disconnect this service. If the service is not
+                       connected an error message will be generated.
+
+                       On Ethernet devices this will disconnect the IP
+                       details from the service. It will not magically
+                       unplug the cable. When no cable is plugged in this
+                       method will fail.
+
+                       This method can also be used to abort a previous
+                       connectiong attempt via the Connect method.
+
+                       Possible Errors: [service].Error.InvalidArguments
+
+               void Remove()
+
+                       A successfully connected service with Favorite=true
+                       can be removed this way. If it is connected, it will
+                       be automatically disconnected first.
+
+                       If the service requires a passphrase it will be
+                       cleared and forgotten when removing.
+
+                       This is similar to setting the Favorite property
+                       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.
+
+                       Calling this method on Ethernet devices will cause
+                       an error message. It is not possible to remove these
+                       kind of devices.
+
+                       Possible Errors: [service].Error.InvalidArguments
+
+               void MoveBefore(object service)
+
+                       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)
+
+                       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 ResetCounters()
+
+                       Reset the counter statistics.
+
+                       Possible Errors: None
+

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

-Properties     string Name [readonly]
+Properties     string State [readonly]
+
+                       The service state information.
+
+                       Valid states are "idle", "failure", "association",
+                       "configuration" and "ready".
+
+                       Also "login" and "online" states are used. The
+                       state "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
+                       the detailed information are represented in this
+                       property to help the user interface to present the
+                       user with alternate options.
+
+                       This property is only valid when the service is in
+                       the "failure" state. Otherwise it might be empty or
+                       not present at all.
+
+                       Current defined error code is "dhcp-failed".
+
+               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 service name (for example "Wireless" etc.)
 
                        This name can be used for directly displaying it in
                        the application. It has pure informational purpose.
 

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

                string Type [readonly]
 
                string Type [readonly]
 

-                       The device type (for example "ethernet", "wifi" etc.)
+                       The service type (for example "ethernet", "wifi" etc.)
+
+                       This information should only be used to determine
+                       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".
+
+                       This property might be only present for WiFi and
+                       Cellular services.
+
+               string Security [readonly]
+
+                       If the service type is WiFi, then this property is
+                       present and contains the security method or key
+                       management setting.
+
+                       Possible values are "none", "wep", "psk" and
+                       also "ieee8021x". Alternate values for "psk"
+                       can also be "wpa" and "rsn".
+
+                       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
+                       is a normalized value between 0 and 100.
+
+                       This property will not be present for Ethernet
+                       devices.
+
+               boolean Favorite [readonly]
+
+                       Will be true if a cable is plugged in or the user
+                       selected and successfully connected to this service.
+
+                       This value is automatically changed and to revert
+                       it back to false the Remove() method needs to be
+                       used.
+
+               boolean Immutable [readonly]
+
+                       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.
+
+               boolean AutoConnect [readwrite]
+
+                       If set to true, this service will auto-connect
+                       when not other connection is available.
+
+                       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.
+
+                       In the case of Cellular services this normally
+                       indicates connections to a foreign provider when
+                       traveling abroad.
+
+               array{string} Nameservers [readonly]
+
+                       The list of currently active nameservers for this
+                       service. If the server is not in READY, LOGIN or
+                       ONLINE state than this list will be empty.
+
+                       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.
+
+                       When using DHCP this array represents the nameservers
+                       provided by the network. In case of manual settings,
+                       the ones from Nameservers.Configuration are used.
+
+               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.
+
+                       This array is sorted by priority and the first
+                       entry in the list represents the nameserver with
+                       the highest priority.
+
+                       When using manual configuration and no global
+                       nameservers are configured, then it is useful
+                       to configure this setting.
+
+                       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.
+
+               array{string} Domains [readonly]
+
+                       The list of currently used search domains.
+
+               array{string} Domains.Configuration [readwrite]
+
+                       The list of manually configured search domains.
+
+               dict IPv4 [readonly]
+
+                       string Method [readonly]
+
+                               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 Netmask [readonly]
+
+                               The current configured IPv4 netmask.
+
+                       string Gateway [readonly]
+
+                               The current configured IPv4 gateway.
+
+               dict IPv4.Configuration [readwrite]
+
+                       Same values as IPv4 property. The IPv4 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",
+                               "manual" and "auto-config".
+
+                               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.
+
+                               If no automatic configuration is available,
+                               then "direct" is set.
+
+                               The values "auto" and "manual" are not yet
+                               supported.
+
+                       string URL [readonly]
+
+                               Automatic proxy configuration URL.
+
+               dict Ethernet [readonly]
+
+                       string Method [readonly]
+
+                               Possible values are "auto" and "manual".
+
+                       string Interface [readonly]
+
+                               Interface name (for example eth0).
+
+                       string Address [readonly]
+
+                               Ethernet device address (MAC address).
+
+                       uint16 MTU [readonly]
+
+                               The Ethernet MTU (default is 1500).
+
+                       uint16 Speed [readonly]
+
+                               Selected speed of the line.
+
+                               This information might not always be
+                               available.
+
+                       string Duplex [readonly]
+
+                               Selected duplex settings of the line.
+
+                               Possible values are "half" and "full".
+
+                               This information might not always be
+                               available.