Re: Pre-LC Review Requested: System Information API

Please note, that like Jonas, I'm not endorsing any of this.

http://dev.w3.org/2009/dap/system-info/

> the system which they are running on.

... on which they are running.

> Specifically, properties pertaining to the device hardware are addressed.

exposed?

> Therefore, a conforming implementation of this specification MUST ... SHOULD

Wow, that's incredibly expensive. I'm pretty sure this will be death
by a thousand papercuts to the computer user, and we'll suffer from
the same problems that the java security dialogs gave us in 1996.

> user's express permission

Please end sentences (and paragraphs) with periods :).

> The user interface MUST include the URI of the document origin, as defined in [[!HTML5]].

If the URL is 50,000 characters long and has a bidi domain, and my
screen is tiny, must I show the whole URI?

>  User Agents MUST respect revoked permissions.

What does this mean?

> permission to access one API ... does not... granted permission... to access the same method with ... different ... arguments

This sounds like more papercuts.

> permission ... to... access the... battery level, ... seek... permission ...when any... function is called on this API.

More papercuts.

> Some User Agents will have prearranged trust relationships that do not require such user interfaces.

require [][showing] ?


> Privacy considerations for recipients of system information

Jonas suggested removing this section, since it's just misleading to
everyone. I concur. Most content providers will ignore this and it's
unenforceable.

> Recipients should clearly and conspicuously disclose the fact that they
> are collecting system data, the purpose for the collection, how long the
> data is retained, how the data is secured, how the data is shared if it is
> shared, how users can access, update and delete the data, and any
> other choices that users have with respect to the data.

So after giving me hundreds of papercuts you're going to drown me in
HIPA forms, to ensure my eyes glaze over?

>    * An interface, whose name is the same as the property's name, and which contains its attributes

attributes[][.]

> identify the property accessed.

accessed property

> (through the id attributes of the options parameter,

attribute[s][]

>        The URI or name of the property to retrieve.

... requested property.

can I pass http://www.w3.org/2010/../2009/dap/SysInfo/Power?

> PendingOp watch()

Object.watch is taken, please don't step on it.
https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference:Global_Objects:Object:watch

monitor() if you mean continuous, inspect(), if this is merely a one
time polling operation.

>       2. ... have changed

changed[][.]

>       3. When a system event is successfully received

received?

received[][,]

>        Property URI or name identifying the property to track.
>        function called when the properties have been successfully retrieved

[f][F]unction ... retrieved[][.]

>        function called when an error occurred while retrieving the properties

[f][F]unction ... properties[][.]

>        An object containing the various options for fetching the properties requested

requested[][.]

I think property should be in the singular....

>        The URI or the name of the property to check for.

[for][][Don't end a sentence with a preposition.]

> All functions except has return a PendingOp object,

has[][()]

> defined in [[!CORE-DEVICE]], which has a cancel function allowing the asynchronous operation to be interrupted.

cancel[][()] ... [interrupted][stopped]

>    The application context does not have permission to access this property

>    The property that has been passed to the set function that has triggered this callback cannot be modified.

set() or setter

>    The number of milliseconds beyond which the operation must be interrupted and the cancel method of the PendingOp object must be called.

cancel[][()]

attribute double highThreshold
attribute double lowThreshold
>    This attribute has no effect on the get method. On the watch method, it indicates that the

get() or getter
On the inspect() method...

> If both highThreshold and lowThreshold parameters are specified, the success callback is triggered if and only if the property value is either lower than the value of lowThreshold or higher than the value of highThreshold.

It's odd that you've stuck this into lowThreshold but not high

>   If this property is enumerable,

[this][the]

> this device (e.g. the microphones attribute of the InputDevices property).

In the first blob you used 'this property', in the second 'this
device'. Both are problematic (as can be seen by the fact that you
used two), please find something else.


>   navigator.system.watch("Power",success,null,{lowThreshold:0.2, thresholdTarget:"level"});
> function success(power) {
>   alert("Low battery level: "+power.level);

So, there's no timeout, to me "watch" implies continuous, is the UA
supposed to call success repeatedly until it does succeed in running
out of power?

>    Specifies how much the internal power source remains,

much [][of] the [internal][]

> A value of 0 means that the battery level is lowest before the system enters shutdown mode,

Could I please get that in English?

>     Represents the estimated time remaining in seconds before the
> battery will be depleted, based upon current power usage. If
> batteryBeingCharged is true, then this value represents the
> estimated time remaining in seconds before the battery is depleted,
> based upon current power usage, if external power were removed.
> This attribute can be used as a threshold target.

The n900 can't tell you anything about its power level while charging.
What would one do if implementing this interface on the n900?

>    Indicates whether the internal power source is currently charging.
> A value of true, indicates that the battery is being charged. If false
> then the battery is not being charged.

What if I have an external battery which is being charged?

>    This attribute indicates the current CPU load, as a number between 0.0 and 1.0, representing the minimum and maximum values allowed on this system.

CPU load in Linux is roughly the number of tasks waiting on a cpu, it
goes from 0 to +INF. -- There is no fixed maximum for CPU load.

You probably mean usage.

> This property provides information on the global temperature state of the system

system[][.]

> to the connections available.

the available connections

>    The list of all the network connections

Sentence.
If I have a network adapter with an unplugged cable, do you want me to list it?

> attribute Connection activeConnection
>     The connection currently used for network access.

What if I'm using 2 or more connections concurrently?

The VPN case worries me.

The Connection Property
const unsigned short TYPE_UNKNOWN=0
const unsigned short TYPE_WIRED=1
const unsigned short TYPE_WIFI=2
const unsigned short TYPE_PLMN=3

TYPE_BLUETOOTH?

>    The type of network connection. The value is one of the constants defined for this attribute.

Or a UA defined type?

>    The MAC address of this connection. The format of this string MUST be
> the standard notation for MAC addresses: six groups of two hexadecimal
> digits, separated by colons (:), e.g. 01:23:45:67:89:ab [[!IEEE802-3]]

Sentence.

> A user agent MUST be able to report both IPv4 and IPv6 addresses.

What does this mean? What if my UA only supports ipv6 or only supports ipv4?
On average, I'm likely to have both, which do you want? What format do
you want the ipv6 one in?

>    The Access Point Name associated to a network bearer

bearer[][.]

>    A value of true indicates that the connection is roaming

No distinction between local roaming and international roaming?

>    The minimum value that the sensors measuring the property are able to report
>    The maximum value that the sensors measuring the property are able to report

report[][.]

>    * min represents the minimum illuminance that the device's ambient lightsensors can report, in lux.
>    * max represents the maximum illuminance that the device's ambient lightsensors can report, in lux.

light[][ ]sensors

>    * normalizedValue represents the measured illuminance normalized to a 0 to 1 range
>    * normalizedValue represents the measured ambient noise level, normalized to a 0 to 1 range
>    * normalizedValue represents the measured ambient temperature, normalized to a 0 to 1 range

range[][.]

>     * normalizedValue represents the measured ambient temperature, normalized to a 0 to 1 range.

>    Supported compression format names. Example : "H.264", "Theora"
>    Supported container format names. Example : "AVI", "Ogg"
>    The list of profiles available for this codec. For example, "Simple", "Main", "High" or "Advanced"
readonly attribute DOMString frameTypes[]

Why "For Example" v. "Example"?

> This section describe properties that expose a device's storage units,
> like the unit's type (hard Disk, memory card, etc.) or capacity

capacity[][.]

>    When type has this value, then this device is a hard disk
>    When type has this value, then this device is a floppy disk

disk[][.]

>    When type has this value, then this device uses optical storage technology (CD, DVD, Holographic)

Sentence.


> const unsigned short TYPE_RAM=4
>    ... this device uses solid-state RAM technology (chip, memory card)

This is not what I think about when I read RAM. I'd rather "FLASH"
even if it's terribly inaccurate.

>     attribute has changed

changed[][.]

>    true if this unit can be removed from the system ... false otherwise
>    true if this display is currently blanked, false otherwise

otherwise[][.]

>    The list of display devices connected to this system
>    The list of audio devices connected to this system

system[][.]

> The Display interface defined below inherits from the Screen interface as defined in [[!CSSOM-VIEW]]

Sentence.

>    The current brightness, from 0 to 1
>    The current contrast, from 0 to 1

1[][.]

>    The display's physical width in centimeters
>    The display's physical height in centimeters

centimeters[][.]

>    type is set to this value when the type of this device is unknown
>    type is set to this value when this device is a loud speaker
>    type is set to this value when this device is a set of headphones

[t][T]ype
Sentence.

>    Frequency range, low value, in Hz
>    Frequency range, high value, in Hz
>    The volume level of a speaker, on a 0 to 100 scale

Sentence.

>    The list of microhones available on this system.
>    The list of microhones available on this system that are currently in use.

micro[][p]hones

My colleagues have only seen Mirophones and Micorophones, I'll have to
tell them to be on the look out for Microhones.

>    When the type attribute has this value, then the type of this pointing device is unknown.
>    When the type attribute has this value, then this device is of a type unknown to this API.
>    type is set to this value when the type of this device is unknown to this API.

Kinda inconsistent, no?

>    When the type attribute has this value, then this device is a mouse
>    When the type attribute has this value, then this device is a touch screen
>    When the type attribute has this value, then this device is a light pen
>    When the type attribute has this value, then this device is a gesture device
>    When the type attribute has this value, then this device is a graphics tablet
>    When the type attribute has this value, then this device is a full keyboard
>    When the type attribute has this value, then this device is a keypad

[then][]
Sentence.

>    type is set to this value when this device is a microphone
>    type is set to this value when this device is a line-in connector

Kinda inconsistent with the preceding group.

>    true when this device supports recording video, else otherwise.
>    true when this device supports has a flash, else otherwise.

[when][if]

>    The number of image sensor elements (pixels) of this camera

camera[][.]

This is a strange way to write what you're trying to say.

>    Frequency range, low value, in Hz
>    Frequency range, high value, in Hz

Hz[][.]

Received on Monday, 10 May 2010 09:13:01 UTC