Paul Stewart | a4e618b | 2012-04-25 16:21:22 -0700 | [diff] [blame] | 1 | Device hierarchy |
| 2 | ================ |
| 3 | |
| 4 | Service org.chromium.flimflam |
| 5 | Interface org.chromium.flimflam.Device |
| 6 | Object path [variable prefix]/{device0,device1,...} |
| 7 | |
| 8 | Methods 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 | |
Jason Glasgow | 3711463 | 2012-05-04 09:45:14 -0400 | [diff] [blame] | 30 | void Enable() |
| 31 | |
| 32 | Enable the device. |
| 33 | |
| 34 | void Disable() |
| 35 | |
| 36 | Disable the device. |
| 37 | |
Paul Stewart | a4e618b | 2012-04-25 16:21:22 -0700 | [diff] [blame] | 38 | void ProposeScan() --DEPRECATED-- |
| 39 | |
| 40 | Start a scan operation if possible. |
| 41 | |
| 42 | For WiFi devices this triggers a search for |
| 43 | available WiFi networks. When results are |
| 44 | available, the Device.Networks property is |
| 45 | updated and a PropertyChanged signal is issued. |
| 46 | |
| 47 | For cellular devices, this triggers a search for |
| 48 | available cellular networks, which may take up to a |
| 49 | minute to complete. When the results are available, |
| 50 | the property Cellular.FoundNetworks (see below) is |
| 51 | set with the results. |
| 52 | |
| 53 | Possible Errors: [service].Error.InvalidArguments |
| 54 | |
| 55 | object path AddIPConfig(string method) --DEPRECATED-- |
| 56 | |
| 57 | This function only remains so it does not trigger |
| 58 | an error in the caller, and returns the path "/", |
| 59 | and never returns an error. In flimflam it used to |
| 60 | provide the ability to create IPConfig objects |
| 61 | to the device to provide IPv4 or IPv6 setup state. |
| 62 | |
| 63 | void RequirePin(string pin, boolean require) |
| 64 | |
| 65 | (Cellular only) Enable or disable PIN protection for |
| 66 | a cellular modem's SIM card. If 'require' is true, |
| 67 | then a PIN will need to be supplied (by calling |
| 68 | EnterPin) before the modem is usable. If 'require' |
| 69 | is false, a PIN will not be required. |
| 70 | |
| 71 | Possible Errors: [service].Error.InvalidArguments |
| 72 | [service].Error.NotSupported |
| 73 | [service].Error.PinError |
| 74 | |
| 75 | In the case of PinError, the error message gives |
| 76 | more detail: [interface].PinRequired |
| 77 | [interface].PinBlocked |
| 78 | [interface].IncorrectPin |
| 79 | |
| 80 | void EnterPin(string pin) |
| 81 | |
| 82 | (Cellular only) Provide a PIN to unlock a SIM card. |
| 83 | |
| 84 | Possible Errors: [service].Error.InvalidArguments |
| 85 | [service].Error.NotSupported |
| 86 | [service].Error.PinError |
| 87 | |
| 88 | In the case of PinError, the error message gives |
| 89 | more detail: [interface].PinRequired |
| 90 | [interface].PinBlocked |
| 91 | [interface].IncorrectPin |
| 92 | |
| 93 | void UnblockPin(string puk, string pin) |
| 94 | |
| 95 | (Cellular only) Provide a PUK code to unblock a PIN. |
| 96 | When an incorrect PIN has been entered too many times |
| 97 | (three is generally the number of tries allowed), the |
| 98 | PIN becomes "blocked", and the SIM card can only be |
| 99 | unlocked by providing a PUK code provided by the |
| 100 | carrier. At the same time, a new PIN must be specified. |
| 101 | |
| 102 | Possible Errors: [service].Error.InvalidArguments |
| 103 | [service].Error.NotSupported |
| 104 | [service].Error.PinError |
| 105 | |
| 106 | In the case of PinError, the error message gives |
| 107 | more detail: [interface].PinRequired |
| 108 | [interface].PinBlocked |
| 109 | [interface].IncorrectPin |
| 110 | |
| 111 | void ChangePin(string old_pin, string new_pin) |
| 112 | |
| 113 | (Cellular only) Change the PIN used to unlock a SIM |
| 114 | card. The existing PIN must be provided along with |
| 115 | the new PIN. |
| 116 | |
| 117 | Possible Errors: [service].Error.InvalidArguments |
| 118 | [service].Error.NotSupported |
| 119 | [service].Error.PinError |
| 120 | |
| 121 | In the case of PinError, the error message gives |
| 122 | more detail: [interface].PinRequired |
| 123 | [interface].PinBlocked |
| 124 | [interface].IncorrectPin |
| 125 | |
| 126 | void Register(string network_id) |
| 127 | |
| 128 | (Cellular only) Initiate registration on the network |
| 129 | specified by network_id, which is in the form MCCMNC. |
| 130 | If the network ID is the empty string, then switch |
| 131 | back to automatic registration mode before initiating |
| 132 | registration. |
| 133 | |
| 134 | If registration succeeds, the network_id is remembered, |
| 135 | and is saved in the profile, so that the same network |
| 136 | will be tried again if the modem is disabled and then |
| 137 | re-enabled, or if the system is restarted or resumed. |
| 138 | |
| 139 | If registration fails, the network_id is not |
| 140 | remembered, and is not saved in the profile. If it was |
| 141 | already in the profile, it is deleted. In addtion, one |
| 142 | more attempt is made to register, after switching back |
| 143 | to automatic registration mode. |
| 144 | |
Darin Petkov | c37a9c4 | 2012-09-06 15:28:22 +0200 | [diff] [blame] | 145 | void SetCarrier(string carrier) |
| 146 | |
| 147 | (Cellular only) Set the modem carrier firmware. For |
| 148 | example, switch between CDMA (Verizon Wireless/Sprint) |
Darin Petkov | 1abca3e | 2012-09-12 11:44:07 +0200 | [diff] [blame] | 149 | and Generic UMTS. The Cellular.SupportedCarriers |
| 150 | property lists all supported carriers. |
Darin Petkov | c37a9c4 | 2012-09-06 15:28:22 +0200 | [diff] [blame] | 151 | |
| 152 | Possible Errors: [service].Error.Failure |
| 153 | [service].Error.NotSupported |
| 154 | |
Paul Stewart | 6ff27f5 | 2012-07-11 06:51:41 -0700 | [diff] [blame] | 155 | void ResetByteCounters() |
| 156 | |
| 157 | Reset the device's persisted counters of transmitted |
| 158 | and received bytes. See RecieveByteCount and |
| 159 | TransmitByteCount properties below. |
| 160 | |
Paul Stewart | a4e618b | 2012-04-25 16:21:22 -0700 | [diff] [blame] | 161 | Signals PropertyChanged(string name, variant value) |
| 162 | |
| 163 | This signal indicates a changed value of the given |
| 164 | property. |
| 165 | |
| 166 | Properties string Address [readonly] |
| 167 | |
| 168 | The low-level (physical) address of the device. |
| 169 | |
| 170 | string BgscanMethod [readwrite] |
| 171 | |
| 172 | (WiFi only) A string identifying the background scan |
| 173 | algorithm. |
| 174 | Possible values: |
| 175 | "simple" [default] |
| 176 | "learn" |
| 177 | |
| 178 | A change to this property takes affect on the next |
| 179 | association. |
| 180 | |
| 181 | uint16 BgscanShortInterval [readwrite] |
| 182 | |
| 183 | (WiFi only) Time in seconds between background scans |
| 184 | when actively searching for better APs (e.g., when |
| 185 | roaming). |
| 186 | |
| 187 | A change to this property takes affect on the next |
| 188 | association. |
| 189 | |
| 190 | int32 BgscanSignalThreshold [readwrite] |
| 191 | |
| 192 | (WiFi only) Receive signal strength threshold (in dBm), |
| 193 | for the currently connected network, below which |
| 194 | roaming is triggered. |
| 195 | |
| 196 | A change to this property takes affect on the next |
| 197 | association. |
| 198 | |
| 199 | boolean Cellular.AllowRoaming [readwrite] |
| 200 | |
| 201 | (Celluar only) Whether cellular data connections |
| 202 | are allowed when the device is roaming (i.e, |
| 203 | not registered on the home network). When this |
| 204 | property is false, data connections are not |
| 205 | allowed while roaming (regardless of the AutoConnect |
| 206 | setting of associated services). |
| 207 | |
| 208 | If a connection was established while on the home |
| 209 | network, and the device begins roaming, the data |
| 210 | connection is terminated. |
| 211 | |
| 212 | If the property is true, and a data connection was |
| 213 | established while roaming, and then the property is |
| 214 | set to false, the connection is terminated. |
| 215 | |
| 216 | If the Cellular.ProviderRequiresRoaming property |
| 217 | is true, that setting will override this property's |
| 218 | setting. |
| 219 | |
| 220 | By default Cellular.AllowRoaming is false. |
| 221 | |
| 222 | string Cellular.Carrier [readonly] |
| 223 | |
| 224 | (Cellular only) The name of the carrier for |
| 225 | which the device is configured. |
| 226 | |
| 227 | dict Cellular.HomeProvider [readonly] [GSM only] |
| 228 | |
| 229 | (Cellular only) Description of the operator that |
| 230 | issued the SIM card currently installed in the modem. |
| 231 | The dictionary may contain the following string-valued |
| 232 | properties: |
| 233 | |
| 234 | "name" The operator name |
| 235 | "country" The two-letter country code. |
| 236 | "network_id" The MCC (Mobile Country Code) |
| 237 | and MNC (Mobile Network Code) of the |
| 238 | operator on whose network the device is |
| 239 | registered. The value of the property is |
| 240 | the simple concatenation of the MCC and |
| 241 | the MNC, with no separator. The first |
| 242 | three digits are always the MCC, and |
| 243 | the following two or three digits are the |
| 244 | MNC. |
| 245 | |
| 246 | string Cellular.MEID [readonly] |
| 247 | |
| 248 | (Cellular only) For CDMA modems, the Mobile |
| 249 | Equipment Identifer of the modem. |
| 250 | |
| 251 | string Cellular.IMEI [readonly] |
| 252 | |
| 253 | (Cellular only) The International Mobile Equipment |
| 254 | Identity of the modem. |
| 255 | |
Ben Chan | a5e2708 | 2012-07-31 14:30:28 -0700 | [diff] [blame] | 256 | string Cellular.ICCID [readonly] |
| 257 | |
| 258 | (Cellular only) For GSM / LTE modems, the Integrated |
| 259 | Circuit Card Identifer of the SIM card installed in |
| 260 | the device. |
| 261 | |
Paul Stewart | a4e618b | 2012-04-25 16:21:22 -0700 | [diff] [blame] | 262 | string Cellular.IMSI [readonly] |
| 263 | |
| 264 | (Cellular only) For GSM modems, the International |
| 265 | Mobile Subscriber Identity of the SIM card |
| 266 | installed in the device. |
| 267 | |
| 268 | string Cellular.ESN [readonly] |
| 269 | |
| 270 | (Cellular only) The Electronic Serial Number of |
| 271 | the modem. |
| 272 | |
| 273 | string Cellular.MDN [readonly] |
| 274 | |
| 275 | (Cellular only) The Mobile Directory Number |
| 276 | (i.e., phone number) of the device. |
| 277 | |
| 278 | string Cellular.MIN [readonly] |
| 279 | |
| 280 | (Cellular only) The Mobile Identification Number |
| 281 | of the device. The MIN is often the same as |
| 282 | the MDN, but may change if a user changes to a |
| 283 | different service provider. |
| 284 | |
| 285 | string Cellular.ModelID [readonly] |
| 286 | |
| 287 | (Cellular only) The hardware model of the modem. The |
| 288 | contents of this property are unspecified, and are |
| 289 | useful primarily as a diagnostic aid. |
| 290 | |
| 291 | string Cellular.Manufacturer [readonly] |
| 292 | |
| 293 | (Cellular only) The manufacturer of the modem. The |
| 294 | contents of this property are unspecified, |
| 295 | and are useful primarily as a diagnostic aid. |
| 296 | |
| 297 | string Cellular.FirmwareRevision [readonly] |
| 298 | |
| 299 | (Cellular only) The revision of firmware that is |
| 300 | loaded in the modem. The contents of this property |
| 301 | are unspecified, and are useful primarily as a |
| 302 | diagnostic aid. |
| 303 | |
| 304 | string Cellular.HardwareRevision [readonly] |
| 305 | |
| 306 | (Cellular only) The hardware revision of |
| 307 | the modem. The contents of this property are |
| 308 | unspecified, and are useful primarily as a |
| 309 | diagnostic aid. |
| 310 | |
| 311 | int16 Cellular.PRLVersion [readonly] |
| 312 | |
| 313 | (Cellular only) The revision of the Preferred |
| 314 | Roaming List that is loaded in the modem. |
| 315 | Cellular.PRLVersion is primarily useful as a |
| 316 | diagnostic aid. |
| 317 | |
| 318 | boolean Cellular.ProviderRequiresRoaming [readonly] |
| 319 | |
| 320 | (Celluar only) Indicates that the cellular |
| 321 | provider (determined based on IMSI and SPN) |
| 322 | requires roaming. This is important to |
| 323 | certain MVNOs which have no home network and |
| 324 | wish to provide network services without |
| 325 | regard to the Cellular.AllowRoaming setting. |
| 326 | |
| 327 | dict Cellular.SIMLockStatus [readonly] |
| 328 | |
| 329 | (Cellular only) For GSM modems, a dictionary |
| 330 | containing two properties describing the state |
| 331 | of the SIM card lock. The two properties are: |
| 332 | |
| 333 | string LockType |
| 334 | |
| 335 | If this string is empty, the SIM card is not |
| 336 | PIN-locked. Otherwise, it specifies the type |
| 337 | of lock in effect: "sim-pin" or "sim-puk". |
| 338 | |
| 339 | uint32 RetriesLeft |
| 340 | |
| 341 | If LockType is empty or is "sim-pin", then |
| 342 | this property gives the number of attempts |
| 343 | remaining to supply a correct PIN before the |
| 344 | PIN becomes blocked, at which point a PUK |
| 345 | provided by the carrier would be necessary |
| 346 | to unlock the SIM (and the LockType changes to |
| 347 | "sim-puk"). |
| 348 | |
| 349 | If LockType is "sim-puk", then this property |
| 350 | gives the number of attempts remaining to supply |
| 351 | a correct PUK before the SIM card becomes |
| 352 | permanently locked, at which point the SIM |
| 353 | card must be replaced. This state is indicated |
| 354 | when LockType is "sim-puk" and RetriesLeft is |
| 355 | zero. |
| 356 | |
| 357 | boolean LockEnabled |
| 358 | |
| 359 | Indicates whether SIM locking is enabled, |
| 360 | i.e., whether, when the device is powered |
| 361 | on, a PIN or PUK will need to be entered to |
| 362 | unlock the SIM. This differs from the |
| 363 | LockType property, which indicates whether |
| 364 | the device is currently waiting for a PIN |
| 365 | to be entered. The SIM can currently be |
| 366 | unlocked (LockType is ""), but at the same |
| 367 | time locking can be enabled (LockEnabled is |
| 368 | True). |
| 369 | |
Ben Chan | bd3aee8 | 2012-10-16 23:52:04 -0700 | [diff] [blame] | 370 | boolean Cellular.SIMPresent [readonly] |
| 371 | |
| 372 | (Cellular only) For GSM or LTE modems, indicates |
| 373 | whether a SIM card is present or not. |
| 374 | |
Darin Petkov | 1abca3e | 2012-09-12 11:44:07 +0200 | [diff] [blame] | 375 | array{string} Cellular.SupportedCarriers [readonly] |
| 376 | |
| 377 | (Cellular only) A list of supported carriers. Each |
| 378 | carrier can be used as an argument to the SetCarrier |
| 379 | method. |
| 380 | |
Paul Stewart | a4e618b | 2012-04-25 16:21:22 -0700 | [diff] [blame] | 381 | array{dict} Cellular.FoundNetworks [readonly] [GSM only] |
| 382 | |
| 383 | (Cellular only) The result of the most recent |
| 384 | scan operation. The property is an array |
| 385 | of dictionaries, with each (string, string) entry |
| 386 | from the following properties: |
| 387 | |
| 388 | "status" The availability of the network. Values |
| 389 | are "unknown", "available", "current", |
| 390 | and "forbidden". |
| 391 | "network_id" The network id in the form MCC/MNC |
| 392 | (without the '/') |
| 393 | "short_name" Short-format name of the network operator |
| 394 | "long_name" Long-format name of the network operator |
| 395 | "technology" Access technology used by the network, e.g. |
| 396 | "GSM", "UMTS", "EDGE", "HSPA", etc. |
| 397 | |
| 398 | array{dict} Cellular.APNList [readonly] [GSM only] |
| 399 | |
| 400 | (Cellular only) The list of APNs associated with |
| 401 | the home provider (ref. Cellular.HomeProvider property) |
| 402 | The property is an array of dictionaries, with each |
| 403 | (string, string) entry from the following properties: |
| 404 | |
| 405 | "apn" The APN, to be used when making |
| 406 | connections. |
| 407 | "username" The username to be passed along with the |
| 408 | APN when making connections. This property |
| 409 | is present only if a username is required. |
| 410 | "password" The password to be passed along with the |
| 411 | APN when making connections. This property |
| 412 | is present only if a password is required. |
| 413 | "name" Optional description of the APN, not localized. |
| 414 | "localized_name" |
| 415 | Optional description of the APN, localized. |
| 416 | "language" |
| 417 | If the "localized_name" property is present, this |
| 418 | gives the two-letter language code for the locale |
| 419 | of the localized name. If "localized_name" exists, |
| 420 | then this property will always exist as well. |
| 421 | |
| 422 | string Interface [readonly] |
| 423 | |
| 424 | The device interface (for example "eth0" etc.) |
| 425 | |
| 426 | This value is for pure informational purposes. It |
| 427 | is not guaranteed that it is always present. |
| 428 | |
| 429 | array{object} IPConfigs [readonly] --DEPRECATED-- |
| 430 | |
| 431 | List of IPConfig objects paths. Every object path |
| 432 | represents a Layer 3 configuration record for |
| 433 | the device. In shill, for a connected device, |
| 434 | this is always a single object path containing |
| 435 | the currently used IPConfig. In the future, use |
| 436 | the "IPConfig" property of the Service. |
| 437 | |
Paul Stewart | 036dba0 | 2012-08-07 12:34:41 -0700 | [diff] [blame] | 438 | int32 LinkMonitorResponseTime [readonly] |
| 439 | |
| 440 | Latest running average of the link monitor response |
Paul Stewart | 3c508e1 | 2012-08-09 11:40:06 -0700 | [diff] [blame] | 441 | for this device in milliseconds, if the link monitor |
| 442 | is active. |
Paul Stewart | 036dba0 | 2012-08-07 12:34:41 -0700 | [diff] [blame] | 443 | |
Paul Stewart | a4e618b | 2012-04-25 16:21:22 -0700 | [diff] [blame] | 444 | string Name [readonly] |
| 445 | |
| 446 | The device name (for example "Wireless" etc.) |
| 447 | |
| 448 | This name can be used for directly displaying it in |
| 449 | the application. It has pure informational purpose |
| 450 | and there is not guarantee that it is present. |
| 451 | |
| 452 | boolean Powered [readonly] |
| 453 | |
Simran Basi | 5307221 | 2012-05-01 15:06:04 -0700 | [diff] [blame] | 454 | Indicates whether the device is on or off. |
Paul Stewart | a4e618b | 2012-04-25 16:21:22 -0700 | [diff] [blame] | 455 | |
Simran Basi | 5307221 | 2012-05-01 15:06:04 -0700 | [diff] [blame] | 456 | This value does not influence the value of the |
Paul Stewart | a4e618b | 2012-04-25 16:21:22 -0700 | [diff] [blame] | 457 | Policy property. |
| 458 | |
| 459 | The value of this property can be changed by other |
| 460 | parts of the system (including the kernel). An |
| 461 | example would be modifications via the "ifconfig" |
| 462 | command line utility. |
| 463 | |
Paul Stewart | 6ff27f5 | 2012-07-11 06:51:41 -0700 | [diff] [blame] | 464 | uint64 ReceiveByteCount [readonly] |
| 465 | |
| 466 | The number of bytes received on this interface. |
| 467 | This value is persisted and accumulated across |
| 468 | connection manager restarts. Shill retrieves |
| 469 | these counters from all interfaces every 60 seconds |
| 470 | so this value returned might be slightly old. |
| 471 | |
Paul Stewart | a4e618b | 2012-04-25 16:21:22 -0700 | [diff] [blame] | 472 | uint16 ScanInterval [readwrite] |
| 473 | |
| 474 | (Defined in WiFi and Cellular) |
| 475 | |
| 476 | The scan interval is the time in seconds between |
| 477 | automated scan attempts. Setting this value to |
| 478 | 0 will disable the periodic scanning. |
| 479 | |
mukesh agrawal | b66c646 | 2012-05-07 11:45:25 -0700 | [diff] [blame] | 480 | The default value is 180 and so every 3 minutes |
Paul Stewart | a4e618b | 2012-04-25 16:21:22 -0700 | [diff] [blame] | 481 | a scan procedure will be triggered. |
| 482 | |
| 483 | This property is not available with all types |
| 484 | of devices. Some may not support background |
| 485 | scanning at all. |
| 486 | |
| 487 | boolean Scanning [readonly] |
| 488 | |
Darin Petkov | 9893d9c | 2012-05-17 15:27:31 -0700 | [diff] [blame] | 489 | (Defined in Cellular, WiFi and WiMAX) |
Paul Stewart | a4e618b | 2012-04-25 16:21:22 -0700 | [diff] [blame] | 490 | |
| 491 | Indicates that a device is currently performing a |
| 492 | network scan. |
| 493 | |
Paul Stewart | 6ff27f5 | 2012-07-11 06:51:41 -0700 | [diff] [blame] | 494 | uint64 TransmitByteCount [readonly] |
| 495 | |
| 496 | The number of bytes transmitted on this interface. |
| 497 | This value is persisted and accumulated across |
| 498 | connection manager restarts. Shill retrieves |
| 499 | these counters from all interfaces every 60 seconds |
| 500 | so this value returned might be slightly old. |
| 501 | |
Paul Stewart | a4e618b | 2012-04-25 16:21:22 -0700 | [diff] [blame] | 502 | string Type [readonly] |
| 503 | |
| 504 | The device type (for example "ethernet", "wifi" etc.) |