doc/service-api.txt

Service hierarchy
=================

Service		org.chromium.flimflam
Interface	org.chromium.flimflam.Service
Object path	[variable prefix]/{service0,service1,...}

Methods		dict GetProperties()

			Return the properties for the service object. See
			the Properties section for available properties.

		void SetProperty(string name, variant value)

			Change 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
					 [service].Error.InvalidService
					 [service].Error.InvalidPassphrase

		void ClearProperty(string name)

			Clear 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 Connect()

			Initiate a connection for the specified service.

			For Ethernet devices this method can only be used
			if it has previously been disconnected. Otherwise
			the plugging of a cable automatically triggers
			a connection.  If no cable is plugged in this
			method will fail.

			If the requested service is already connected
			then this request is ignored and AlreadyConnected
			is returned.

			If the requested service is in the process of
			connecting then this request is ignored and
			InProgress is returned.

			If another service of the same type is connected or
			connecting then it is terminated before this request
			is handled.

			Possible Errors: [service].Error.AlreadyConnected
					 [service].Error.InProgress
					 [service].Error.OperationAborted
					 [service].Error.InvalidService

		void Disconnect()

			Disconnect a service. If the service is not
			connected or in the process of connecting an
			error message will be generated.

			For Ethernet devices this will remove all
			Layer 3 state and mark the associated network
			interface down.  If no cable is plugged in this
			request will fail.

			This method can also be used to abort a previous
			connection attempt via the Connect method.

			Possible Errors: [service].Error.InvalidArguments

		void Remove()

			Disconnect and remove all recorded state of a
			service.  The service must have previously had
			a success connection so that the Favorite property
			is marked "true".

			This method is not permitted for Ethernet devices;
			it will generate a NotSupported error response.

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

			[Silently ignored in shill so far]

		void MoveBefore(object service)

			Silently ignored in shill.  Do not use.

		void MoveAfter(object service)

			Silently ignored in shill.  Do not use.

		void ActivateCellularModem(string carrier)

			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.

			Expected Result: [service].Error.InProgress
			Possible Errors: [service].Error.NotSupported

Signals		PropertyChanged(string name, variant value)

			This signal indicates a changed value of the given
			property.


Properties	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, setting
			AutoConnect to TRUE causes favorite to be set to TRUE.

		string Cellular.ActivationState [readonly]

			(Cellular only) The activate state of the device
			on the cellular network.  Possible values for
			activate_state are:
			   "not-activated"
			   "activating"
			   "partially-activated"
			   "activated"

			A CDMA device can be activated by calling the
			Activate method.

			This property is relevant only for services
			associated with a CDMA cellular device.

		dict Cellular.ServingOperator [readonly] [GSM only]
			(Cellular only) Description of the operator on whose
			network the modem is currently registered, if any.
			The dictionary may contain the following string-valued
			properties:

			"name"       The operator name
			"country"    The two-letter country code.
			"network_id" The MCC (Mobile Country Code)
				     and MNC (Mobile Network Code) of the
				     operator on whose network the device is
				     registered. The value of the property is
				     the simple concatenation of the MCC and
				     the MNC, with no separator. The first
				     three digits are always the MCC, and
				     the following two or three digits are the
				     MNC.

		string Cellular.NetworkTechnology [readonly]

			(Cellular only) If the modem is registered on a
			network, then this property gives the data bearer
			technology currently in use.  The following
			table lists the values this property may have,
			along with a rough indication of the "generation"
			to which the technology is considered to belong.

			Value          Generation
			-----------------------------
			"1xRTT" (CDMA) 2.5G
			"EVDO" (CDMA)  3G to 3.5G
			"GPRS"         2.5G
			"EDGE"         2.75G
			"UMTS"         3G
			"HSPA"         3.5G
			"HSPA+"        3.75G
			"LTE"          3.9G
			"LTE Advanced" 4G

		string Cellular.RoamingState [readonly]

			(Cellular only) The roaming status of the modem on
			the current network. Possible values are "home",
			"roaming", and "unknown".

		string Cellular.Olp [readonly]

			(Cellular only) A dictionary describing the
			online payment portal (OLP) at which a user
			can sign up for, or modify, a mobile data
			plan.  The value of this property is a
			string -> string dictionary, which includes
			the following keys:

			"url"      The URL for the portal
			"method"   The HTTP method to use, "GET" or "POST"
			"postdata" If the method is POST then this key is
				   present and contains the postdata
				   to send.

		dict Cellular.APN [readwrite] [GSM only]

			(Cellular only) The APN to be used with a GSM
			carrier for making data connections. The value of
			this property is a string -> string dictionary,
			which must include at least the following key:

			"apn"  The APN to use for making connections

			There are three optional properties. The first is

			"network_id" The network ID (MCC/MNC pair) of the
			             network for which the APN should be used.
				     If not specified, then the network ID of
				     the currently registered network is used.

			The other two optional properties are "username"
			and "password", which, if specified, will be supplied
			to the connect operation on the modem along with the
			APN.

			When the APN is set using this method, it overrides
			any APN that may be associated with the specified
			network ID in the APN database. The APN setting is
			persistent across reboots.

			A user-specified APN may be cleared by clearing this
			property.

			The algorithm for connecting to GSM networks is as
			follows, stopping when a connection is succesfully
			established:
			1. Try the last APN that resulted in a successful
			   connection.
			2. Try the APN that was set from the Cellular.APN
			   property (if any).
			3. Try the list of APNs for the current provider one
			   at a time. The list comes from the mobile broadband
			   provider information database.
			4. As a last resort, try connecting without specifying
			   an APN.

			If all these steps fail, then the connect attempt fails.
			Whenever this property is set to establish a new APN to
			use, the remembered last-good-APN is cleared. The
			remembered last-good-APN is persistent across reboots.

		dict Cellular.LastGoodAPN [readonly] [GSM only]

			(Cellular only) The APN information used in the
			last successful connection attempt.  If the last
			attempt was unsuccesful, this property is unset.
			The format of this property is the same as for
			the Cellular.APN property.

		string CheckPortal [readwrite]

			Control captive portal checking.  Possible values
			are "true", "false", and "auto" (default).
			When set to "auto" captive portal checking is
			controlled by Manager.CheckPortalList (which
			is a per-technology mask/list of which services
			should do captive portal checking).

		boolean Connectable [readonly]

			Indicates whether a service is prepared for use
			as an argument to the Connect method.  A service
			will not be marked Connectable if, for example,
			it is missing necessary security credentials.
			Clients may use this property to not disable
			services or to mark them in some way to indicate
			they are present but not usable.

		object Device [readonly]

			The object path of the associated device.
			This value may be used to retrieve and manipulate
			Layer 3 configuration state.

		string EAP.Identity [readwrite]

			The client identity string used in setting up
			services of type "802_1x".

			This property is included in get requests only
			when the requester has sufficient privileges.

		string EAP.EAP [readwrite]

			The EAP methods that will be accepted when setting
			up services of type "802_1x".

			This property is included in get requests only
			when the requester has sufficient privileges.

		string EAP.InnerEAP [readwrite]

			The authentication methods that will be on the
			inside of a PEAP or EAP-TTLS tunnel.

			This property is included in get requests only
			when the requester has sufficient privileges.

		string EAP.AnonymousIdentity [readwrite]

			The client identity string that will be used
			for the outer EAP authentication for tunneled
			methods such as PEAP and EAP-TTLS.

			This property is included in get requests only
			when the requester has sufficient privileges.

		string EAP.ClientCert [readwrite]

			The pathname to a file containing the client
			certificate for setting up services of type
			"802_1x".  The certificate file must be in
			PEM format.

			This property is included in get requests only
			when the requester has sufficient privileges.

		string EAP.CertID [readwrite]

			The PKCS#11 identifier of the client certificate
			to use when setting up services of type "802_1x".

			This property is included in get requests only
			when the requester has sufficient privileges.

		string EAP.PrivateKey [readwrite]

			The pathname of a file containing the private
			key for setting up services of type "802_1x".
			The private key file must be in PEM format.

			This property is included in get requests only
			when the requester has sufficient privileges.

		string EAP.PrivateKeyPassword [readwrite]

			The password to decrypt a private key given
			in EAP.PrivateKey.

			This property is included in get requests only
			when the requester has sufficient privileges.

		string EAP.KeyID [readwrite]

			The PKCS#11 identifier of the private key to
			use when setting up services of type "802_1x".

			This property is included in get requests only
			when the requester has sufficient privileges.

		string EAP.CACert [readwrite]

			The pathname of a file containing the Certificate
			Authority's certificate for validating server
			certificates during the 802.1x authentication
			process.

			This property is included in get requests only
			when the requester has sufficient privileges.

		string EAP.CACertID [readwrite]

			The PKCS#11 ID of the EAP.CACert file for
			validating server certificate recieved during
			the 802.1x authentication process.

			This property is included in get requests only
			when the requester has sufficient privileges.

		boolean EAP.UseSystemCAs [readwrite]

			Control whether EAP operations are
			configured to use the system's installed set
			of certificate authorities when validating
			server certificates. Note that if UseSystemCAs
			is false and no CA is specified with EAP.CACert
			or EAP.CaCertID - that is, no CAs are configured
			at all - server certificates will not have their
			signatures checked. Defaults to true.

			This property is included in get requests only
			when the requester has sufficient privileges.

		string EAP.PIN [readwrite]

			The PIN used to authenticate to the PKCS#11 device
			to retrieve a client certificate, private key,
			or certificate authority certificate.

			This property is included in get requests only
			when the requester has sufficient privileges.
		
		string EAP.Password [readwrite]

			The password to use in 802.1x authentication.

			This property is included in get requests only
			when the requester has sufficient privileges.
		
		string EAP.KeyMgmt [readwrite]

			(WiFi only) The key management algorithm to be
			used in 802.1x authentication.	If this property
			is not set then "WPA-EAP" is used for the key
			management algorithm.

			This property is included in get requests only
			when the requester has sufficient privileges.

		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" or "activation-failure" states. Otherwise
			it might be empty or not present at all.

			Current defined error code is "dhcp-failed".

		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.

		string GUID [readwrite]

			The Globally Unique IDentifier for the service.
			This value may be set by a client and is
			intended for cross-referencing Service objects
			to externally-maintained data.

		object IPConfig [readonly]

			The object path of the associated IP configuration.
			This value only exists when the service is connected,
			and is used used to retrieve Layer 3 configuration
			state.

		boolean IsActive [readonly]

			Will be true if this service has a default route;
			i.e.  network traffic is being sent through it.

		string Mode [readonly]

			If the service type is "wifi", then this property is
			present and contains the mode of the network. The
			possible values are "managed" or "adhoc".

			This property is present only for WiFi services.

		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.

			For Ethernet devices and hidden WiFi networks it is
			not guaranteed that this property is present. For
			visible WiFi networks, this may contain the SSID.

			See also the WiFi.HexSSID property.

		string Passphrase [readwrite]

			If the service type is "wifi", then this property
			holds a passphrase used in setting up services of
			type "wep", "wpa", "rsn", "psk", or a private
			key password used in setting up services of
			type "802_1x".

			For "wep" services, this must contain the WEP
			key and, optionally, a key index.  Only 40-bit
			and 104-bit WEP keys are supported.  The WEP
			key can be formatted either as an ASCII string
			(5 or 13 characters), or as ASCII hex digits
			(10 or 26). When using ASCII hex digits, the
			key may optionally be preceded by "0x" or "0X".
			To specify an optional WEP key index, prepend
			the key with "0:", "1:", "2:" or "3:".  If no
			index is specified, 0 is used.

			By default this property is not included in get
			requests.  It may be present if a non-default
			security policy is configured and the client has
			"read secret" privileges.

			Note that no PropertyChanged signals are sent for
			this property. The PassphraseRequired property
			should be monitored instead.

		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.

			UI clients may monitor this property for a
			PropertyChanged signals to prompt for a required
			passphrase or key.

                        [We will be supporting this soon for VPN]

		int32 Priority [readwrite]

			An optional value used to calculate the priority order
			of this service.  Priorities are between 1 to 100.
			Services with priorities are sorted ahead of services
			without.  Services with the same priority are ordered
			by other means such as service type and signal
			strength.

			By default services are not assigned a priority;
			clients must set one if they desire.  To remove an
			existing priority use the ClearProperty method.

		object Profile [readwrite]

			The object path of the associated Profile object.
			This may not be present if the Service object
			has not been written to a profile yet.

		string ProxyConfig [readwrite]

			An externalized json dictionary describing the proxy
                        configuration that can be stored on the service, and
                        modified by a user.
			Flimflam does not use this information for anything,
			but it is left available to the caller, and stored
			persistently.
			This property may be set by any client and will be
                        adopted by chrome during run-time.  If syntax of the
                        value is wrong, chrome will ignore this property during
                        runtime.
                        The value of this property is a string -> string
                        dictionary that includes the following keys. The final
                        string is a comma separated list of key-value pairs
                        enclosed by "{" and "}"; syntax of a key-value pair is:
                        <key>":"<value>. Example:
                        {"mode":"fixed-servers","server":"http=foopy:80"}

			"mode"
                            type of proxy that can be one of:
                            "direct" --
                              direct connection to network, other preferences
                              are ignored
                            "auto_detect" --
                              try to retrieve a PAC script from
                              http://wpad/wpad.dat or fall back to direct
                              connection
                            "pac_script" --
                              try to retrieve PAC script specified for "pac_url"
                              (see below) or fall back to direct connection
                            "fixed_servers" --
                              manual configuration of one or more servers
                              to be used as proxy

			"pac_url"
                            URL for proxy .pac file (meaningful only if mode=
                            pac_script); scheme of URL must be specified

			"pac_mandatory"
                            indciate if a valid PAC script is mandatory
                            (meaningful only if mode=pac_script);
                            value is either true or false (without quotes), e.g.
                            "pac_mandatory":true;
                            if true, network traffic does not fall back to
                            direct connections in case the PAC script is not
                            available

			"server"
                            proxy server for manual configuration (meaningful
                            only if mode=fixed-servers); syntax is
                            [<proxy-scheme>"://"]<proxy-host>[":"<proxy-port>];
                            if the proxy to use depends on the scheme of the
                            URL, specify a semicolon separated list of :
                            <url-scheme>"="<proxy-uri>
                            for example:
                            - "http=foopy:80;ftp=foopy2" --
                              use HTTP proxy "foopy:80" for http:// URLs, and
                              HTTP proxy "foopy2:80" for ftp:// URLS
                            - "foopy:80" -- use HTTP proxy "foopy:80" for all
                              URLs
                            - "socks4://foopy" --
                              use SOCKS v4 proxy "foopy:80" for all URLs

			"bypass_list"
                            proxy bypass rules for manual configuration
                            (meaningful only if mode=fixed-servers); format
                            can be any one of the following:
                            1) [<url_scheme>"://"]<hostname_pattern>[":"<port>]
                               Match all hostnames that match the pattern
                               hostname_pattern which can be a substring of the
                               hostname with asterisks.
                               Examples: "foobar.com", "*foobar.com",
                               "*.foobar.com", "*foobar.com:99",
                               "https://x.*.y.com:99"
                            2) "."<hostname_suffix_pattern>[":"<port>]
                               Match a particular domain suffix.
                               Examples: ".google.com", ".com",
                               "http://.google.com"
                            3) [<scheme>"://"]<ip_literal>[":"<port>]
                               Match URLs that are IP address literals.
                               Conceptually this is the similar to (1), but with
                               special cases to handle IP literal
                               canonicalization. For example matching on
                               "[0:0:0::1]" would be the same as matching on
                               "[::1]" since the IPv6 canonicalization is done
                               internally.
                               Examples: "127.0.1", "[0:0::1]", "[::1]",
                               "http://[::1]:99"
                            4) <ip_literal>"/"<prefix_length_in_bits>
                               Match any URL that is to an IP literal that falls
                               in the given range. IP range is specified using
                               CIDR notation.
                               Examples: "192.168.1.1/16", "fefe:13::abc/33".
                            5)  "<local>"
                                Match local addresses; this is a literal string.
                                "<local>" matches one of: "127.0.0.1", "::1",
                                "localhost".

		dict Provider [readonly]

			(VPN only) Provider data.  A provider is a service
			that piggy-backs on top of a transport service.
			This is presently used by VPN services.

			string Domain [readonly]
				VPN domain name.
			string Host [readonly]
				VPN host IP address.
			string Name [readonly]
				VPN provider name.
			string Type [readonly]
				VPN provider type (e.g. openvpn).

		boolean SaveCredentials [readwrite]

			This property indicates if security credentials
			should be reused and/or written to stable storage.
			Setting this property to FALSE ensures nothing is
			recorded and the client must supply credentials
			for each Connect request.

			The following credentials are not recorded when
			this property is set to FALSE:
			
			Passphrase
			EAP.Identity
			EAP.AnonymousIdentity
			EAP.ClientCert
			EAP.CertID
			EAP.PrivateKey
			EAP.PrivateKeyPassword
			EAP.KeyID
			EAP.PIN
			EAP.Password

			Note that no PropertyChanged signals are sent for
			this property.

		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" (no privacy),
			"wep" (fixed key WEP), "wpa" (WPA-PSK), "rsn"
			(IEEE 802.11i-PSK), "psk" (either "wpa" or "rsn"),
			and "802_1x" (IEEE 802.11i with 802.1x authentication).

			This property is only present for WiFi services.

		string State [readonly]

			The state of the service; one of:

			"idle"		The service is not enabled or otherwise
					operational.

			"carrier"	The associated device is powered on and
					ready for Layer 2 operation; e.g. a
					wired Ethernet device that is powered
					up and connected to a switch.

			"association"	Intermediate states associated with
			"disconnect"	connection-based devices such as WiFi
					and Cellular.  These are exposed for
					UI applications to provide more
					fine-grained status.

			"configuration"	Layer 2 is setup but Layer 3 setup
					has yet to completed.

			"ready"		Layer 3 setup is complete; ready to
					transit and receive data.

			"portal"	Layer 3 setup is complete but
					connectivity to the Internet may be
					limited or unavailable.

			"online"	Layer 3 setup is complete and an
					Internet connection has been checked
					to support HTTP access to the
					Manager.PortalURL site.

			"failure"	An error occurred while trying to
					reach the "ready" state. Consult the
					Error propery for details.

			"activation-failure"
					An error occurred while trying to
					activate a cellular modem. Consult the
					Error property for details.

		string StaticIP.Address [readwrite]
		string StaticIP.Gateway [readwrite]
		int32 StaticIP.Mtu [readwrite]
		string StaticIP.NameServers [readwrite]
		string StaticIP.PeerAddress [readwrite]
		int32 StaticIP.Prefixlen [readwrite]

			The properties above can be set on a service to
			selectively override individual parameters received
			over DHCP or whatever default IP aquisition technique
			is used by the service.  The "StaticIP.NameServers"
			property should be a comma-separated list of IP
			addresses.

			Additionally, in services that use DHCP, if the
			"StaticIP.Address" and "StaticIP.Prefixlen"
			parameters are both set on a service, the service
			will be configured as soon as a link is established,
			in order to allow full static IP configuration.  A
			DHCP client will be launched in parallel, which, if
			successful, will provide values for any parameters
			that were not set statically.

			The IPConfig associated with the service (object
			path supplied in the "IPConfig" property above)
			will display the result of the merged network
			parameters.

		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.

		string Type [readonly]

			The service type; one of:
			  "ethernet"    (802.3 wired Ethernet),
			  "wifi"        (IEEE 802.11),
			  "wimax"       (IEEE 802.16),
			  "bluetooth"   (Bluetooth PAN),
			  "cellular"    (3G Cellular), or
			  "vpn"         (Virtual Private Network).

			This information should only be used to determine
			advanced properties or showing the correct icon
			to the user.

		string UIData [readwrite]

			This is additional data available about this service
			for use by the user interface.  This value is opaque
			and not used by shill.

		string WiFi.AuthMode [readonly]

			(WiFi only) If the service state is
			"configuration" or "ready", then this property
			will be present and contains the negotiated
			authentication method.

			There are too many possible values to enumerate here.
			The complete set depends on the capabilities of the
			associated WiFi supplicant.

		string WiFi.BSSID [readonly]

			(WiFi only) The BSSID of the associated AP.
			One can monitor this property for PropertyChanged
			signals to identify when roaming changes the
			current AP.

		boolean WiFi.HiddenSSID [readonly]

			(WiFi only) If true, the associated WiFi network
			does not broadcast it's SSID in beacon frames.

		uint16 WiFi.Frequency [readonly]

			(WiFi only) The operating frequency in MHz of
			the network.

		string WiFi.PhyMode [readonly]

			(WiFi only) If the service state is
			"configuration" or "ready", then this property
			will be present and contains the negotiated
			operating mode for the channel.  Possible values
			include "802.11a", "802.11b", "802.11g",
			"802.11n".  This value is for informational
			purposes only.

		string WiFi.HexSSID [readonly]

			(WiFi only) If the service's SSID contains
			unprintable characters then this property is
			present and holds a hex-encoded copy of the SSID.

			See also the Name property. (Note that there is
			no SSID property.)

		string WiFi.SSID [readonly]
			(WiFi only) The service's SSID. Must have a non-zero
			length less than or equal to 32.