SysInfo notes

Hi,

here are some random notes from reading SysInfo.

  - "to avoid side-channel attacks" It would be good to include an example here (e.g. sampling AmbientNoise fast enough to be able to interpolate a microphone).

  - "webIDL" -> WebIDL (multiple times).

  - Properties are given two equivalent identifiers, a name and a URI. It would be useful to tell readers (and implementers) why there are two. Also this seems to say that if I create my own extension property, say http://berjon.com/props/Toaster then that URI and the name "Toaster" are equivalent, which they probably shouldn't be. I guess that it should be clarified the that name/URI equivalence and mapping only holds for properties defined in this specification. This discussion could go into section 5, and be pointed to from here.

  - "through calls to the get or monitor() functions" They should either both have (), or neither. Adding <code> around them might be good too.

  - This is confusing: we have a section called "The SystemInfo interface" and it starts by defining the NavigatorSystem interface. In general, each interface should have its own section, it's a lot clearer.

  - NavigatorSystem is missing a "Navigator implements NavigatorSystem;" IDL statement (see section 3.2 in http://dev.w3.org/2009/dap/device/).

  - "An instance of NavigatorSystem would then be obtained by using binding-specific casting methods on an instance of Navigator." I'm not sure that this sentence is needed, it assumes that bindings are in languages that support a specific type of casting. That's not universal (and certainly not what JS does).

  - "Objects implementing the Navigator interface (e.g. the window.navigator object) must also implement the NavigatorSystem interface [NAVIGATOR]." That should be a MUST (but using the implements statement ought to handle that). The [NAVIGATOR] should probably be next to Navigator.

  - "The root node from which the system information functionality can be accessed." The word "node" is loaded in a DOM context. I would use "object" instead.

  - The get() method should be clearer on how its error cases are handled. It currently says that if there's an error, then the error cb (if any) gets called with the error object. Using the descriptions of the error codes one can reverse engineer when errors are fired, but one should not have to reverse engineer: the error conditions need to be specified. It also doesn't say what happens to the PendingOp upon error? Is it just cancelled? We need prose that says:

When an error occurs, the following steps take place:
  • the PendingOp is cancelled as if by a call to PendingOp.cancel()
  • the error callback, if any, is called with an Error object configured as follows:

  • if the property is not known to the system, the code MUST be set to UNKNOWN_PROPERTY;
  • ...

Furthermore, processing of the options needs to be specified as well. Is it an error if an unknown option field is passed? I think it shouldn't be, but that needs to be clear. Handling of unexpected values for known fields also needs to be specified (part of it can be delegated to specific properties). For instance, the prose around Error says in passing that it's an error for highThreshold on CPU to be above 1.0. Why not just clamp it down to 1.0? Ditto for negative numbers? Then handling of non-numbers can be an error (or map to zero).

It is also not clear whether get() is affected by filtering or not. If I'm doing a get(), I assume it's not being filtered, but the options parameter still allows me to specify thresholds. (It's specified elsewhere, but that should be indicated).

  - The same issues apply to monitor. Furthermore, the way that filtering applies isn't clear. The prose seems to be saying that one gets events unconditionally, which is probably not the case. What happens to monitor if what it's monitoring is unplugged? Say I'm monitoring available space on an external drive and it's removed?

  - Is has() under the same privacy restrictions as the others? I believe that it should be (otherwise fingerprinting becomes even more powerful, and people might be able to find out that you own a SuperRich UltraHaptics interface, or a Donkey Dildonics 3000 extension).

  - "An implementation may define additional error codes, but those must not use the numeric values defined here." Is there a reason for this? Numeric values are very much non-extensible. If they start using code 5 and we issue v1.1 which also defines it, we'll screw them over. Or we'll find out and be forced to start at 6, which could get weird. I would strike that, and state that if an implementation wants to provide more specific information about an error they can add vendor-prefixed fields with that information.

  - "The property accessed is either unknown or unavailable on this device" Those two cases should be quite different. If I don't understand property "Unicorn", there's no point in asking again; if I do but happen not to have any Unicorns currently connected, you might want to poll to find out when they come here.

  - "the battery level on a device that only has an external power source" Does that make Power information unavailable? The Power interface says it just returns null for the level.

  - "is only be triggered" -> will only be triggered (several times)

  - Is it just me who's troubled by highThreshold/lowThreshold? If you specify both, the highThreshold has to be lower than the lowThreshold (if you hope to get any events). How about range: [0.1, 0.8] instead? What are the default values when these options are unspecified?

  - "on the get() method" / "on the get method" Pick one or the other.

  - "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." Doesn't it have to be *both*?

  - What's the default timeout value? If there isn't one, it should be specified that the request never times out.

  - Random question: should id be freeform, or should we try to make sure that it can be used in an URI? Given the latter, we could have http://.../StorageUnit/foo. I'm not sure it's a good idea though. Also, what stability do we expect from this identifier? If a system is reconfigured but a given component stays, should it still be the same for any given device? If it can't be guaranteed to be the same, should it at least never map to a different one? I don't think that we can constrain it strongly, but consider the case of a user picking one drive to monitor which is given id 2 out of set {1,2}, and that preference is stored. Months later a new drive is inserted and the drive that used to be 2 is now 3 (out of {1,2,3}) — the result might be quite unexpected for the user.

  - In Power, the example uses a value of 0.2 for lowThreshold to indicate 20%, whereas the description for level says it's a value between 0 and 100.

  - "If batteryBeingCharged is true". There is no such field, I think you mean isCharging.

  - Should we have, for each interface, a default threshold target? In some cases it'll save some typing and make sense.

  - Again we need greater clarity about what happens when no filters are specified. If I'd like to monitor all power-related events (something rather useful if implementing a UI for it) do I do:

   navigator.system.monitor("Power", success);

or do I have to resort to:

  navigator.system.monitor("Power", success, null, { lowThreshold: 1.0, thresholdTarget: "level" });

I would prefer the former.

  - The example for CPU assigns a value to the string s but does nothing with it. I think that line should be dropped.

  - When an interface is not enumerable, the specification should say "This interface is not enumerable." That way it's obvious that it was intentional. And interfaces that aren't enumerable but that correspond to things that in reality may be multiple (CPUs, batteries...) should explain how the singular value is obtained. Likewise, when there is no way to filter on any threshold level, it should be clarified.

  - "navigator.system.get("Network",success,null);" This ought to be "navigator.system.get("Network", success);" If it's not possible it should be (because it's what authors will expect).

  - "navigator.system.monitor("Connection", {id: active.id}, wifiMonitorCB);" That should be "navigator.system.monitor("Connection", wifiMonitorCB, {id: active.id});"

  - "document.getElementById(indicator, "Wireless signal at "+(connection.signalStrength*100)+"%");" This example is wrong, I suspect there's a missing innerHTML or textContent.

  - We've had this discussion before but I can't recall nor find the rationale for the decision. Why does one first request the Network property just to get the active connection IDs and types just to then have to fetch that again with an ID? Couldn't we just get("ActiveConnections") and react on the enumerable list that would be provided? It seems more straightforward.

  - "In the meantime vendors may define non-standard values, but must use the prefix x-." That's a known bad approach to extensibility. Vendors wishing to add more properties should prefix with "-vendorID-" (as in CSS).

  - Might be a stupid question, but is unsigned long Kbits forward-looking enough for foreseeable bandwidth?

  - "Details on the meaning of the number and reported as well as its unit are given" Parse error.

  - Why is there an "Ambient Light" section which has as its only content a "The AmbientLight Property"? Ditto for the following properties.

  - I could be completely wrong here but I believe that measuring in decibels doesn't mean anything as it needs a reference level. This seems to agree http://en.wikipedia.org/wiki/Decibels#Acoustics_2

  - "Space-separated list of MIME types for supported compression formats, e.g. "G.711", "MP3", "MIDI"." The examples aren't media types.

  - If this was discussed I can't recall it. Is there a reason why the video codecs does not expose the encode/decode thing?

  - Aren't there media types for container formats as well?

  - The hwAccel field has a trailing ";" in its name (ReSpec should detect that, but in the meantime it can be corrected in the draft).

  - "hard Disk" -> hard disk

  - "This property is enumerable, i.e. an id parameter must be passed to the API function call to indicate which unit is requested." That's not true, it MAY be passed in order to only get one.

  - Are network drives expected to be reflected in the list? If so we should perhaps add TYPE_NETWORK (or isNetworked?).

  - "true if this device supports software modification, else otherwise." This should be "false otherwise". And just modification is probably enough, every disk supports hardware modification if you have big enough an axe.

  - "type is set to this value..." Those should all use <code>, not just the first one.

  - Have we checked with WAI that brailleDevices makes sense?

  - For output, is the foo/activeFoo distinction better than just having foo with each featuring an active boolean field?

  - For DisplayDeviceAttributes, shouldn't it also inherit from SystemProperty to get the "info" from there (same for others)? Would it make sense to split OutputDevices into AudioDevices, DisplayDevices, etc. making each one enumerable?

  - Would it make sense to have supportsVideo for display devices? I'm thinking of e-Ink devices that don't. Or perhaps refreshRate?

  - What does it mean for a display to be blanked?

  - Each FooDeviceAttribute should have its own section.

  - Largely similar comments on the InputDevices.

  - What about software emulation of a pointer device based on a 5-way joystick (I actually use such a device)?

  - "else otherwise" (look for all occurrences of "else", many of them should be "false")

  - For keyboards, I'd have isSoftware instead of isHardware since it's the special case (but that's a minor point).

  - Why do microphones have a name that's suitable for use in an input form, whereas cameras don't?

  - The mapping table shouldn't have a Notes column if it has no notes. Also, is the table that empty because it's not filled out, or because those are the only mappings? If the latter, we might just list the mappings that apply, instead of having a mostly empty table.


That's all for now!

-- 
Robin Berjon - http://berjon.com/

Received on Wednesday, 20 October 2010 18:16:10 UTC