1Device hierarchy 2================ 3 4Service org.chromium.flimflam 5Interface org.chromium.flimflam.Device 6Object path [variable prefix]/{device0,device1,...} 7 8Methods dict GetProperties() 9 10 Returns properties for the device object. See 11 the properties section for available properties. 12 13 void SetProperty(string name, variant value) 14 15 Changes the value of the specified property. Only 16 properties that are listed as read-write are 17 changeable. On success a PropertyChanged signal 18 will be emitted. 19 20 Possible Errors: [service].Error.InvalidArguments 21 [service].Error.InvalidProperty 22 23 void ClearProperty(string name) 24 25 Reset the specified parameter to its "factory" 26 value and remove any previously set value from 27 the profile. Only properties that are listed as 28 read-write are changeable. 29 30 void Enable() 31 32 Enable the device. 33 34 Possible Errors: [service].Error.PermissionDenied 35 36 void Disable() 37 38 Disable the device. 39 40 void ProposeScan() --DEPRECATED-- 41 42 Start a scan operation if possible. 43 44 For WiFi devices this triggers a search for 45 available WiFi networks. When results are 46 available, the Device.Networks property is 47 updated and a PropertyChanged signal is issued. 48 49 For cellular devices, this triggers a search for 50 available cellular networks, which may take up to a 51 minute to complete. When the results are available, 52 the property Cellular.FoundNetworks (see below) is 53 set with the results. 54 55 Possible Errors: [service].Error.InvalidArguments 56 57 object path AddIPConfig(string method) --DEPRECATED-- 58 59 This function only remains so it does not trigger 60 an error in the caller, and returns the path "/", 61 and never returns an error. In flimflam it used to 62 provide the ability to create IPConfig objects 63 to the device to provide IPv4 or IPv6 setup state. 64 65 void RequirePin(string pin, boolean require) 66 67 (Cellular only) Enable or disable PIN protection for 68 a cellular modem's SIM card. If 'require' is true, 69 then a PIN will need to be supplied (by calling 70 EnterPin) before the modem is usable. If 'require' 71 is false, a PIN will not be required. 72 73 Possible Errors: [service].Error.InvalidArguments 74 [service].Error.NotSupported 75 [service].Error.PinError 76 77 In the case of PinError, the error message gives 78 more detail: [interface].PinRequired 79 [interface].PinBlocked 80 [interface].IncorrectPin 81 82 void EnterPin(string pin) 83 84 (Cellular only) Provide a PIN to unlock a SIM card. 85 86 Possible Errors: [service].Error.InvalidArguments 87 [service].Error.NotSupported 88 [service].Error.PinError 89 90 In the case of PinError, the error message gives 91 more detail: [interface].PinRequired 92 [interface].PinBlocked 93 [interface].IncorrectPin 94 95 void UnblockPin(string puk, string pin) 96 97 (Cellular only) Provide a PUK code to unblock a PIN. 98 When an incorrect PIN has been entered too many times 99 (three is generally the number of tries allowed), the 100 PIN becomes "blocked", and the SIM card can only be 101 unlocked by providing a PUK code provided by the 102 carrier. At the same time, a new PIN must be specified. 103 104 Possible Errors: [service].Error.InvalidArguments 105 [service].Error.NotSupported 106 [service].Error.PinError 107 108 In the case of PinError, the error message gives 109 more detail: [interface].PinRequired 110 [interface].PinBlocked 111 [interface].IncorrectPin 112 113 void ChangePin(string old_pin, string new_pin) 114 115 (Cellular only) Change the PIN used to unlock a SIM 116 card. The existing PIN must be provided along with 117 the new PIN. 118 119 Possible Errors: [service].Error.InvalidArguments 120 [service].Error.NotSupported 121 [service].Error.PinError 122 123 In the case of PinError, the error message gives 124 more detail: [interface].PinRequired 125 [interface].PinBlocked 126 [interface].IncorrectPin 127 128 void Register(string network_id) 129 130 (Cellular only) Initiate registration on the network 131 specified by network_id, which is in the form MCCMNC. 132 If the network ID is the empty string, then switch 133 back to automatic registration mode before initiating 134 registration. 135 136 If registration succeeds, the network_id is remembered, 137 and is saved in the profile, so that the same network 138 will be tried again if the modem is disabled and then 139 re-enabled, or if the system is restarted or resumed. 140 141 If registration fails, the network_id is not 142 remembered, and is not saved in the profile. If it was 143 already in the profile, it is deleted. In addtion, one 144 more attempt is made to register, after switching back 145 to automatic registration mode. 146 147 void SetCarrier(string carrier) 148 149 (Cellular only) Set the modem carrier firmware. For 150 example, switch between CDMA (Verizon Wireless/Sprint) 151 and Generic UMTS. The Cellular.SupportedCarriers 152 property lists all supported carriers. 153 154 Possible Errors: [service].Error.Failure 155 [service].Error.NotSupported 156 157 void Reset() 158 159 Reset the device. The implementation is device- 160 dependent. In some cases, the device and its associated 161 service(s) may be destroyed after the physical device 162 is reset. In such case, a new device is expected to be 163 created after the physical device reappears on the 164 system. Currently, device reset is only supported by 165 cellular devices managed by ModemManager. 166 167 Possible Errors: [service].Error.Failure 168 [service].Error.NotSupported 169 170 void ResetByteCounters() 171 172 Reset the device's persisted counters of transmitted 173 174 string PerformTDLSOperation(string operation, 175 string peer) [readwrite] 176 177 (WiFi only) Perform a TDLS operation on a peer 178 station. The |peer| argument should be a mac 179 address specified in traditional colon-separated 180 hexidecimal notation, e.g., "aa:bb:cc:dd:ee:ff", 181 or an IPv4 address on the same subnet of this 182 device, e.g., "192.168.1.1". The |operation| 183 parameter should be one of the following: 184 185 "Discover" : Perform TDLS discovery with |peer|. 186 "Setup" : Setup TDLS peering with |peer|. 187 "Status" : Return TDLS status for |peer|. 188 "Teardown" : Tear down TDLS peering with |peer|. 189 190 The method returns without an error if the operation 191 is initiated successfully with the supplicant, but 192 before it is clear whether the operation actually 193 succeeded. 194 195 All methods except "Status" return an empty string. 196 For "Status", the returned string can be one of: 197 198 "Connected" : The TDLS link is active. 199 "Disabled" : TDLS is disabled on this device. 200 "Disconnected" : The TDLS link has been 201 disconnected. 202 "Nonexistent" : No information is known 203 about this TDLS peer. 204 "Unknown" : The TDLS link is in an unknown 205 state. 206 207 Possible Errors: 208 [service].Error.InProgress 209 An IP-to-MAC address lookup is being 210 performed. The caller should retry 211 this operation. 212 [service].Error.InvalidArguments 213 The |operation| is unknown or the 214 |peer| address is misformatted or 215 does not belong to the local subnet. 216 [service].Error.OperationFailed 217 The TDLS or ARP operation failed. 218 219Signals PropertyChanged(string name, variant value) 220 221 This signal indicates a changed value of the given 222 property. 223 224Properties string Address [readonly] 225 226 The low-level (physical) address of the device. 227 228 string BgscanMethod [readwrite] 229 230 (WiFi only) A string identifying the background scan 231 algorithm. 232 Possible values: 233 "simple" [default] 234 "learn" 235 236 A change to this property takes affect on the next 237 association. 238 239 uint16 BgscanShortInterval [readwrite] 240 241 (WiFi only) Time in seconds between background scans 242 when actively searching for better APs (e.g., when 243 roaming). 244 245 A change to this property takes affect on the next 246 association. 247 248 int32 BgscanSignalThreshold [readwrite] 249 250 (WiFi only) Receive signal strength threshold (in dBm), 251 for the currently connected network, below which 252 roaming is triggered. 253 254 A change to this property takes affect on the next 255 association. 256 257 boolean Cellular.AllowRoaming [readwrite] 258 259 (Celluar only) Whether cellular data connections 260 are allowed when the device is roaming (i.e, 261 not registered on the home network). When this 262 property is false, data connections are not 263 allowed while roaming (regardless of the AutoConnect 264 setting of associated services). 265 266 If a connection was established while on the home 267 network, and the device begins roaming, the data 268 connection is terminated. 269 270 If the property is true, and a data connection was 271 established while roaming, and then the property is 272 set to false, the connection is terminated. 273 274 If the Cellular.ProviderRequiresRoaming property 275 is true, that setting will override this property's 276 setting. 277 278 By default Cellular.AllowRoaming is false. 279 280 string Cellular.Carrier [readonly] 281 282 (Cellular only) The name of the carrier for 283 which the device is configured. 284 285 dict Cellular.HomeProvider [readonly] [GSM only] 286 287 (Cellular only) Description of the operator that 288 issued the SIM card currently installed in the modem. 289 The dictionary may contain the following string-valued 290 properties: 291 292 "name" The operator name 293 "country" The two-letter country code. 294 "network_id" The MCC (Mobile Country Code) 295 and MNC (Mobile Network Code) of the 296 operator on whose network the device is 297 registered. The value of the property is 298 the simple concatenation of the MCC and 299 the MNC, with no separator. The first 300 three digits are always the MCC, and 301 the following two or three digits are the 302 MNC. 303 304 string Cellular.MEID [readonly] 305 306 (Cellular only) For CDMA modems, the Mobile 307 Equipment Identifer of the modem. 308 309 string Cellular.IMEI [readonly] 310 311 (Cellular only) The International Mobile Equipment 312 Identity of the modem. 313 314 string Cellular.ICCID [readonly] 315 316 (Cellular only) For GSM / LTE modems, the Integrated 317 Circuit Card Identifer of the SIM card installed in 318 the device. Blank otherwise. 319 320 string Cellular.IMSI [readonly] 321 322 (Cellular only) For GSM modems, the International 323 Mobile Subscriber Identity of the SIM card 324 installed in the device. 325 326 string Cellular.ESN [readonly] 327 328 (Cellular only) The Electronic Serial Number of 329 the modem. 330 331 string Cellular.MDN [readonly] 332 333 (Cellular only) The Mobile Directory Number 334 (i.e., phone number) of the device. 335 336 string Cellular.MIN [readonly] 337 338 (Cellular only) The Mobile Identification Number 339 of the device. The MIN is often the same as 340 the MDN, but may change if a user changes to a 341 different service provider. 342 343 string Cellular.ModelID [readonly] 344 345 (Cellular only) The hardware model of the modem. The 346 contents of this property are unspecified, and are 347 useful primarily as a diagnostic aid. 348 349 string Cellular.Manufacturer [readonly] 350 351 (Cellular only) The manufacturer of the modem. The 352 contents of this property are unspecified, 353 and are useful primarily as a diagnostic aid. 354 355 string Cellular.FirmwareRevision [readonly] 356 357 (Cellular only) The revision of firmware that is 358 loaded in the modem. The contents of this property 359 are unspecified, and are useful primarily as a 360 diagnostic aid. 361 362 string Cellular.HardwareRevision [readonly] 363 364 (Cellular only) The hardware revision of 365 the modem. The contents of this property are 366 unspecified, and are useful primarily as a 367 diagnostic aid. 368 369 int16 Cellular.PRLVersion [readonly] 370 371 (Cellular only) The revision of the Preferred 372 Roaming List that is loaded in the modem. 373 Cellular.PRLVersion is primarily useful as a 374 diagnostic aid. 375 376 boolean Cellular.ProviderRequiresRoaming [readonly] 377 378 (Celluar only) Indicates that the cellular 379 provider (determined based on IMSI and SPN) 380 requires roaming. This is important to 381 certain MVNOs which have no home network and 382 wish to provide network services without 383 regard to the Cellular.AllowRoaming setting. 384 385 dict Cellular.SIMLockStatus [readonly] 386 387 (Cellular only) For GSM modems, a dictionary 388 containing two properties describing the state 389 of the SIM card lock. The two properties are: 390 391 string LockType 392 393 If this string is empty, the SIM card is not 394 PIN-locked. Otherwise, it specifies the type 395 of lock in effect: "sim-pin" or "sim-puk". 396 397 uint32 RetriesLeft 398 399 If LockType is empty or is "sim-pin", then 400 this property gives the number of attempts 401 remaining to supply a correct PIN before the 402 PIN becomes blocked, at which point a PUK 403 provided by the carrier would be necessary 404 to unlock the SIM (and the LockType changes to 405 "sim-puk"). 406 407 If LockType is "sim-puk", then this property 408 gives the number of attempts remaining to supply 409 a correct PUK before the SIM card becomes 410 permanently locked, at which point the SIM 411 card must be replaced. This state is indicated 412 when LockType is "sim-puk" and RetriesLeft is 413 zero. 414 415 boolean LockEnabled 416 417 Indicates whether SIM locking is enabled, 418 i.e., whether, when the device is powered 419 on, a PIN or PUK will need to be entered to 420 unlock the SIM. This differs from the 421 LockType property, which indicates whether 422 the device is currently waiting for a PIN 423 to be entered. The SIM can currently be 424 unlocked (LockType is ""), but at the same 425 time locking can be enabled (LockEnabled is 426 True). 427 428 boolean Cellular.SIMPresent [readonly] 429 430 (Cellular only) For GSM or LTE modems, indicates 431 whether a SIM card is present or not. 432 433 array{string} Cellular.SupportedCarriers [readonly] 434 435 (Cellular only) A list of supported carriers. Each 436 carrier can be used as an argument to the SetCarrier 437 method. 438 439 array{dict} Cellular.FoundNetworks [readonly] [GSM only] 440 441 (Cellular only) The result of the most recent 442 scan operation. The property is an array 443 of dictionaries, with each (string, string) entry 444 from the following properties: 445 446 "status" The availability of the network. Values 447 are "unknown", "available", "current", 448 and "forbidden". 449 "network_id" The network id in the form MCC/MNC 450 (without the '/') 451 "short_name" Short-format name of the network operator 452 "long_name" Long-format name of the network operator 453 "technology" Access technology used by the network, e.g. 454 "GSM", "UMTS", "EDGE", "HSPA", etc. 455 456 array{dict} Cellular.APNList [readonly] [GSM only] 457 458 (Cellular only) The list of APNs associated with 459 the home provider (ref. Cellular.HomeProvider property) 460 The property is an array of dictionaries, with each 461 (string, string) entry from the following properties: 462 463 "apn" The APN, to be used when making 464 connections. 465 "username" The username to be passed along with the 466 APN when making connections. This property 467 is present only if a username is required. 468 "password" The password to be passed along with the 469 APN when making connections. This property 470 is present only if a password is required. 471 "name" Optional description of the APN, not localized. 472 "localized_name" 473 Optional description of the APN, localized. 474 "language" 475 If the "localized_name" property is present, this 476 gives the two-letter language code for the locale 477 of the localized name. If "localized_name" exists, 478 then this property will always exist as well. 479 480 bool EapAuthenticatorDetected [readonly] 481 482 (Ethernet only) Indicates whether an EAP (802.1X) 483 authenticator has been detected on this link. 484 This may mean that EAP credentials are necessary 485 to gain full access to this network. 486 487 bool EapAuthenticationCompleted [readonly] 488 489 (Ethernet only) Indicates whether an EAP (802.1X) 490 authentication is currently valid on this interface. 491 492 bool Ethernet.LinkUp [readonly] 493 494 (Ethernet only) Indicates whether the underlying 495 device has detected the presence of a physical link. 496 497 bool Ethernet.PPPoE 498 499 (Ethernet only) Configures an Ethernet device to be 500 the carrier for a PPPoE connection. Changing this 501 property can tear down the Ethernet/PPPoE service 502 associated with the Ethernet device. 503 504 string Interface [readonly] 505 506 The device interface (for example "eth0" etc.) 507 508 This value is for pure informational purposes. It 509 is not guaranteed that it is always present. 510 511 object SelectedService [readonly] 512 513 Object path of the currently selected service path. 514 The selected service of a device is the service for 515 which it is currently receiving link events. WiFi 516 is slightly different in that it sets the link event 517 immediately after requesting a connection so that 518 failures to connect are correctly attributed. 519 520 The device guarantees that if it is connected, the 521 connected service will appear in SelectedService. 522 However, SelectedService could be just "/", indicating 523 no selected service. The SelectedService is also 524 not guaranteed to be online (e.g. it could be in the 525 process of being connected, or an error state). 526 527 array{object} IPConfigs [readonly] 528 529 List of IPConfig objects paths. Every object path 530 represents a Layer 3 configuration record for 531 the device. In shill, for a connected device, 532 the IPv4 configuration is represented in the 533 first object path in this array. This object is also 534 referenced in the the "IPConfig" property of the 535 connected Service. If the kernel has assigned a 536 globally scoped IPv6 address to this interface, it 537 is reported as an additional object path in this 538 array. 539 540 Whenever either the IPv4 or IPv6 state changes 541 in a way that modifies the contents of either of 542 these IPConfigs, a PropertyChanged signal will be 543 emitted for the Device's IPConfig property. 544 545 int32 LinkMonitorResponseTime [readonly] 546 547 Latest running average of the link monitor response 548 for this device in milliseconds, if the link monitor 549 is active. 550 551 dict LinkStatistics [readonly] 552 553 (WiFi only) A dictionary providing current link 554 statitistics. This can include the following 555 properties, depending on whether the system is 556 connected and the capabilities of the specific 557 WiFi device. 558 559 int8 AverageReceiveSignalDbm 560 561 Reports the running average of signal 562 strength to the connected AP. 563 564 uint32 InactiveTimeMilliseconds 565 566 Reports the time in milliseconds since 567 the last activity by the station. 568 569 int8 LastReceiveSignalDbm 570 571 Reports the signal strength of the last 572 received packet. 573 574 uint32 PacketReceiveSuccesses 575 576 Reports the number of successfully received 577 packets. 578 579 uint32 PacketTransmitFailures 580 581 Reports the number of failed packet 582 transmission attempts. 583 584 uint32 PacketTrasmitSuccesses 585 586 Reports the number of successful packet 587 transmission attempts. 588 589 string TransmitBitrate 590 591 Reports the transmit bitrate of the last 592 successful outbound packet in a textual format 593 which includes additional 802.11n transmit 594 parameters. 595 596 uint32 TransmitRetries 597 598 Reports the number of times the system has had 599 to retry an outgoing packet. 600 601 602 string Name [readonly] 603 604 The device name (for example "Wireless" etc.) 605 606 This name can be used for directly displaying it in 607 the application. It has pure informational purpose 608 and there is not guarantee that it is present. 609 610 boolean Powered [readonly] 611 612 Indicates whether the device is on or off. 613 614 This value does not influence the value of the 615 Policy property. 616 617 The value of this property can be changed by other 618 parts of the system (including the kernel). An 619 example would be modifications via the "ifconfig" 620 command line utility. 621 622 uint64 ReceiveByteCount [readonly] 623 624 The number of bytes received on this interface. 625 This value is persisted and accumulated across 626 connection manager restarts. Shill retrieves 627 these counters from all interfaces every 60 seconds 628 so this value returned might be slightly old. 629 630 uint16 RoamThreshold [readwrite] 631 632 (Defined in WiFi) 633 634 The roam threshold is the AP signal-to-noise value (in 635 dB) below which wpa_supplicant will attempt to roam to 636 a new AP. This property applies to all WiFi services 637 except those that have their per-service RoamThreshold 638 set. Changes to this property will take effect immediately 639 if the current service does not have its RoamThreshold 640 property set. Otherwise, it will take effect the next time 641 we connect to a WiFi service that does not have its 642 RoamThreshold property set. 643 644 uint16 ScanInterval [readwrite] 645 646 (Defined in WiFi and Cellular) 647 648 The scan interval is the time in seconds between 649 automated scan attempts. Setting this value to 650 0 will disable the periodic scanning. 651 652 The default value is 180 and so every 3 minutes 653 a scan procedure will be triggered. 654 655 This property is not available with all types 656 of devices. Some may not support background 657 scanning at all. 658 659 boolean Scanning [readonly] 660 661 (Defined in Cellular, WiFi and WiMAX) 662 663 Indicates that a device is currently performing a 664 network scan. 665 666 uint64 TransmitByteCount [readonly] 667 668 The number of bytes transmitted on this interface. 669 This value is persisted and accumulated across 670 connection manager restarts. Shill retrieves 671 these counters from all interfaces every 60 seconds 672 so this value returned might be slightly old. 673 674 string Type [readonly] 675 676 The device type (for example "ethernet", "wifi" etc.) 677 678 string WakeOnWiFiFeaturesEnabled [readwrite] 679 680 (Defined in WiFi) 681 682 The wake on WiFi features that are currently enabled. 683 The value of this property is "packet" if only wake on 684 packet is enabled, "ssid" if only wake on ssid is enabled, 685 "packet_and_ssid" if both wake on packet and wake on ssid 686 are enabled, and "none" if all wake on WiFi features are 687 disabled. 688 689 Possible errors: [service].Error.NotSupported (wake on WiFi not supported) 690 [service].Error.InvalidArguments (invalid wake on WiFi feature) 691 692 uint32 WakeToScanPeriodSeconds [readwrite] 693 694 (Defined in WiFi) 695 696 The length of time (in seconds) between each instance where the system 697 is woken from suspend to scan for networks in dark resume. Changes to this 698 property will take effect at the next system suspend. 699 700 uint32 NetDetectScanPeriodSeconds [readwrite] 701 702 (Defined in WiFi) 703 704 The length of time (in seconds) between each instance where the wireless 705 NIC performs Net Detect scans while the system is suspended. Changes to 706 this property will take effect at the next system suspend. 707 708 boolean ForceWakeToScanTimer [readwrite] 709 710 (Defined in WiFi) 711 712 If true, forces shill to start an RTC timer that wakes the system 713 periodically to scan for networks if the system is going into suspend 714 while disconnected. This will likely be used for testing only. Otherwise, 715 if this property is false, shill will only start this timer if it has more 716 SSIDs to whitelist than the NIC supports for net detect. Changes to this 717 property will take effect at the next system suspend. 718 719 void AddWakeOnPacketConnection(string endpoint) 720 721 (WiFi only) Program a wake-on-packet rule into the NIC to wake 722 the system from suspend upon receiving packets from the source IP 723 address in the string argument. The format of the argument is: 724 725 <source_ip> 726 727 where <source_ip> is the source IP address of the TCP 728 connection. IPV4 and IPV6 addresses are specified with 729 the standard conventions for IPV4 and IPV6 addresses. 730 The following are a few non-exhaustive examples: 731 732 IPV4: 1.2.3.4, 192.142.3.10 733 IPV6: a::bc:f:5:6d:7:8, abd::20 734 735 The request is valid until removed. However, on shill 736 restart, any wake-on-packet rules are cleared. 737 738 Possible errors: [service].Error.InvalidArguments (argument parsing error) 739 [service].Error.NotFound (there is no such connection) 740 [service].Error.NotSupported (wake-on-packet not supported) 741 742 void RemoveWakeOnPacketConnection(string endpoint) 743 744 (WiFi only) Removes a wake-on-packet rule previously programmed into the 745 NIC to wake the system from suspend upon receiving packets from the 746 source IP address in the string argument. The argument format is the 747 same as that of AddWakeOnPacketConnection. 748 749 Possible errors: [service].Error.InvalidArgument (argument parsing error) 750 [service].Error.NotFound (no such request is active) 751 [service].Error.NotSupported (wake-on-packet not supported) 752 753 void RemoveAllWakeOnPacketConnections() 754 755 (WiFi only) Removes all wake-on-packet rules programmed into the NIC. 756 This is useful to ensure the NIC is in a known state. 757 758 Possible errors: 759 [service].Error.NotSupported (wake-on-packet not supported) 760