blob: 15d1dadc056b83b6471ac831a63a3982d01bff80 [file] [log] [blame]
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
[service].Error.PermissionDenied
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
void MoveBefore(object service)
Reorder a Service object to be before the
Service object service.
This method does not work and should not be used.
Possible Errors: [service].Error.InvalidArguments
[service].Error.NotSupported
[service].Error.InvalidService
void MoveAfter(object service)
Reorder a Service object to be after the
Service object service.
This method does not work and should not be used.
Possible Errors: [service].Error.InvalidArguments
[service].Error.NotSupported
[service].Error.InvalidService
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.
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.
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.
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 StickyHostRoute [readonly]
Indicates the IP address of a host route which
is installed for this interface. This is
typically used for cellular connections to
route usage server requests.
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 flimflam.
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.