Documentation update: device-lowlevel-api and service-api

doc/service-api.txt

 Service hierarchy
 =================
 
 Service         org.chromium.flimflam
 Interface       org.chromium.flimflam.Service
 Object path     [variable prefix]/{service0,service1,...}
 
 Methods         dict GetProperties()
 
                         Returns properties for the service object. See
@@ skipping 40 matching lines @@
 
                         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.
+                        connection 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
@@ skipping 21 matching lines @@
                 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 ActivateCellularModem()
+                void ActivateCellularModem(string carrier)
 
-                        Activate a cellular modem.
+                        Activate a cellular modem on the provided carrier.
 
                         This method returns immediately.  The caller
                         can either poll the Cellular.ActivationState
                         property, or monitor the PropertyChanged
                         signal to know when and if the
                         ActivateCellularModem call succeeded.
 
                         The correct carrier specific modem firmware
                         must already be loaded before this method is
                         called.
 
                         If this method is called for a non-cellular
                         service or on a service associated with a
                         non-CDMA device, it will return a NotSupported
-                        error.  If the device is already activated
-                        nothing is returned, but if the device needs
-                        to be activated an InProgress error is
-                        returned.
+                        error.
+                        
+                        If the device is already activated nothing is returned.
+                        but if the device needs to be activated an InProgress
+                        error is returned.
 
+                        Expected Result: [service].Error.InProgress
                         Possible Errors: [service].Error.NotSupported
-                        Possible Errors: [service].Error.InProgress
-
 
 Signals         PropertyChanged(string name, variant value)
 
                         This signal indicates a changed value of the given
                         property.
 
 Properties      string State [readonly]
 
                         The state of the service.
 
                         Possible states are: "idle", "carrier", "association",
                         "configuration", "ready", "disconnect", "failure", and
                         "activation-failure".
 
                         "idle" means the service is not enabled or otherwise
                         operational.
 
                         "carrier" means the associated device is powered and
                         ready for Layer 2 operation; e.g. a wired Ethernet
                         device that is powered up and connected to a switch.
 
                         "configuration" means the service is setup for Layer
                         2 operation but not yet setup at Layer 3.
 
                         "association" and "disconnect" are intermediate states
                         associated with connection-based devices such as wifi
-                        and celluar.  These are exposed for UI applications to
+                        and cellular.  These are exposed for UI applications to
                         provide more fine-grained feedback.
 
                         "ready" means the device is fully setup and ready for
                         use; i.e. it is ready to transit data.
 
                         "failure" means an error occurred when attempting to
                         bring a service to the "ready" state.  The Error
                         property should be consulted for an explanation.
 
                         "activation-failure" means an error occurred while
@@ skipping 61 matching lines @@
 
                 string Passphrase [readwrite]
 
                         If the service type is "wifi", then this property
                         holds a passphrase used in setting up services of
                         type "wep", "wpa", and "rsn", or a private
                         key password used in setting up services of
                         type "802_1x".
 
                         This property is included in get requests only
-                        when the requestor has sufficient privileges.
+                        when the requester has sufficient privileges.
 
                         Note that no PropertyChanged signals are sent for
                         this property. The PassphraseRequired property
                         should be monitored instead.
 
                 string Identity [readwrite]
 
                         If the service type is "wifi", then this property
-                        holds a client identity string used in setting up services of
-                        type "802_1x".
+                        holds a client identity string used in setting up
+                        services of type "802_1x".
 
                         This property is included in get requests only
-                        when the requestor has sufficient privileges.
+                        when the requester has sufficient privileges.
 
                 string CertPath [readwrite]
 
                         If the service type is "wifi", then this
                         property holds information that selects a
                         client certificate and private key used in
                         setting up services of type "802_1x".
                         
                         If the value of the property begins with "/",
                         then the property is interpreted as a path in
@@ skipping 10 matching lines @@
                         (used for authentication via a PKCS#11
                         provider), ca_cert, client_cert, private_key,
                         private_key_passwd, and identity.
 
                         Note that the "SETTINGS:" mechanism can
                         replace the use of the Identity and Passphrase
                         parameters for 802.1x, and that the CertPath
                         parameter name is poorly chosen for this use.
 
                         This property is included in get requests only
-                        when the requestor has sufficient privileges.
+                        when the requester has sufficient privileges.
 
                 boolean PassphraseRequired [readonly]
 
                         If the service type is "wifi", then this property
                         indicates if a passphrase or key (for WEP) is required.
 
                         If a passphrase has been set already or if no
                         passphrase is needed, then this property will
                         be set to false.
 
@@ skipping 21 matching lines @@
                 boolean AutoConnect [readwrite]
 
                         If set to true, this service will auto-connect
                         when no other connection is available.  If multiple
                         services are marked for auto-connect then the highest
                         priority available service will be selected.
 
                         For favorite services it is possible to change
                         this value to prevent or permit automatic
                         connection attempts.
+                        
+                        For non favorite services, this always reads FALSE and
+                        is not writeable.
 
-                string Device [readonly]
+                object Device [readonly]
 
                         The object path of the device associated with this
                         service.  This value may be used to retrieve and
                         manipulate Layer 3 configuration state.
 
                 string Cellular.ActivationState [readonly]
 
                         If the service type is "cellular", then this
                         property is present and indicates if the
                         device has been activated on the cellular
@@ skipping 56 matching lines @@
                         gives the roaming status of the modem on the current
                         network. Possible values are "home", "roaming", and
                         "unknown".
 
                 boolean Cellular.RestrictedPool [readonly]
                         If the service type is "cellular", then this property
                         indicates whether the mobile data connection is within
                         a "walled garden", in which only a restricted set of
                         IP addresses can be reached. A value of "true" indicates
                         that the connection is in a restricted IP pool.
+
+                string Cellular.OlpUrl [readonly]
+
+                        If the service type is "cellular", then this property
+                        gives the URL of an online payment portal (OLP) at
+                        which a user can sign up for, or modify, a mobile data
+                        plan.
+
+                string Passphrase [readwrite]
+
+                        If the service type is "wifi", then this property
+                        gives the Passphrase.
+                        
+                        This property is only accessible if the caller has 
+                        'secret' security privileges. 
+
+                string Identity [readwrite]
+
+                        If the service type is "wifi", then this property
+                        gives the 802.1X identity.
+
+                        This property is only accessible if the caller has 
+                        'secret' security privileges. 
+
+                string CertPath [readwrite]
+
+                        If the service type is "wifi", then this property
+                        gives the 802.1X Certificate Path.
+                        
+                        This property is only accessible if the caller has 
+                        'secret' security privileges. 
+
+                string PassphraseRequired [readonly]
+
+                        If the service type is "wifi", then this property
+                        indicates that a Passphrase is required but not
+                        currently set.