- From: Max Froumentin via cvs-syncmail <cvsmail@w3.org>
- Date: Tue, 23 Mar 2010 16:36:01 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/system-info
In directory hutz:/tmp/cvs-serv31235
Modified Files:
Overview.html
Log Message:
- removed sequences and used arrays instead
- clarify Storage
- add target for threshold (closes ACTION-117)
- removed empty interfaces and fixed OutputDevices and InputDevices interfaces (closes ACTION-118)
Index: Overview.html
===================================================================
RCS file: /sources/public/2009/dap/system-info/Overview.html,v
retrieving revision 1.89
retrieving revision 1.90
diff -u -d -r1.89 -r1.90
--- Overview.html 9 Mar 2010 12:42:57 -0000 1.89
+++ Overview.html 23 Mar 2010 16:35:59 -0000 1.90
@@ -389,12 +389,12 @@
<dt>const unsigned short INFORMATION_UNAVAILABLE = 1</dt>
<dd>The property accessed is unavailable on this device (e.g. the battery level on a device that only has an external power source).</dd>
-
+
<dt>const unsigned short INVALID_VALUE = 2</dt>
<dd>One or more of the values in the <a>Options</a>
object passed was invalid. For example, if the
<a>highThreshold</a> attribute is set to a value
- greater than 1.0 for the CpuLoad property.</dd>
+ greater than 1.0 for the CPU property.</dd>
<dt>const unsigned short READ_ONLY = 3</dt>
<dd>The property that has been passed to the
@@ -441,6 +441,17 @@
either lower than the value of <a>lowThreshold</a> or
higher than the value of <a>highThreshold</a>.</dd>
+ <dt>attribute DOMString thresholdTarget</dt>
+ <dd>This option specifies which attribute of the requested
+ property is to be considered for thresholds in a
+ <a>watch</a> operation. The value of
+ <a>thresholdTarget</a> must be the name of an attribute
+ marked as <dfn>threshold target</dfn> in its
+ definition. If the value passed is not the name of an
+ attribute that is defined as a threshold target, a user
+ agent MUST call the error callback with the
+ <a>INVALID_VALUE</a> code.</dd>
+
<dt>attribute DOMString id</dt>
<dd>In order to differentiate between instances, this
attribute is used to indicate the request's target
@@ -456,16 +467,6 @@
<a>INVALID_VALUE</a>.</dd>
</dl>
- <p class="issue">Some properties have more than one numeric attribute, and so we need a way to specify which one a threshold applies to. The current best idea would be to add an attribute to the <a>options</a> interface indicating which attribute the thresholds are compared against. e.g.<br/>
- <code>attribute unsigned const THRESHOLD_NETWORK_UPLOAD = 0;<br/>
-const unsigned short THRESHOLD_NETWORK_DOWNLOAD = 1;<br/>
-const unsigned short THRESHOLD_NETWORK_SIGNAL = 2;<br/>
-...<br/>
-attribute unsigned short thresholds_target;
-</code></p>
-
-
-
</section>
</section>
@@ -494,7 +495,7 @@
<pre class="sh_javascript example">// Alert the user when the power level is below 20%
if (navigator.system.has("Power"))
- navigator.system.watch("Power",success,null,{lowThreshold:0.2});
+ navigator.system.watch("Power",success,null,{lowThreshold:0.2, thresholdTarget:"level"});
function success(power) {
alert("Low battery level: "+power.level);
@@ -509,11 +510,13 @@
<dt>readonly attribute float? level</dt>
<dd>
Specifies how much the internal power source remains,
- scaled from 0 to 100. A value of 0 means that the battery
- level is lowest before the system enters shutdown mode,
- and 100 indicates that the system's charge is maximal. Any
- threshold parameter used in a <a>watch</a> function to
- monitor this property applies to this attribute.
+ scaled from 0 to 100. A value of 0 means that the
+ battery level is lowest before the system enters
+ shutdown mode, and 100 indicates that the system's
+ charge is maximal. Any threshold parameter used in a
+ <a>watch</a> function to monitor this property applies
+ to this attribute. This attribute can be used as a
+ <a>threshold target</a>.
</dd>
<dt>readonly attribute unsigned long? timeRemaining</dt>
@@ -524,7 +527,8 @@
<code>true</code>, 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.</dd>
+ power were removed. This attribute can be used as a
+ <a>threshold target</a>.</dd>
<dt>readonly attribute boolean isExternal;</dt>
<dd>If <code>true</code>, then the device is currently
@@ -544,7 +548,6 @@
<!--******************** /Power **********************************-->
<!--******************* CPU *******************************************-->
-
<section>
<h2>CPU</h2>
<p>This section defines interfaces that expose the system's
@@ -572,9 +575,10 @@
<dd>
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. Any
- threshold parameter used in a <a>watch</a> function to
- monitor this property applies to this attribute.
+ maximum values allowed on this system. Any threshold
+ parameter used in a <a>watch</a> function to monitor
+ this property applies to this attribute. This attribute
+ can be used as a <a>threshold target</a>.
</dd>
</dl>
</section>
@@ -607,12 +611,13 @@
<dl title="[NoInterfaceObject] interface Thermal : SystemProperty" class="idl">
<dt>readonly attribute float state</dt>
<dd>
- This attribute indicates the current thermal status, as a
- number between 0 and 1 representing the minimum and
+ This attribute indicates the current thermal status, as
+ a number between 0 and 1 representing the minimum and
maximum operating values allowed by this system. On
devices that have multiple thermometers, this
implementation-defined value should reflect the global
- temperature of the system.
+ temperature of the system. This attribute can be used as
+ a <a>threshold target</a>.
</dd>
</dl>
</section>
@@ -649,12 +654,14 @@
<dl title='[NoInterfaceObject] interface Network : SystemProperty' class='idl'>
<dt>readonly attribute unsigned long currentDownloadBandwidth</dt>
<dd>
- The current real-time download bandwidth, in Kbits/s.
+ The current real-time download bandwidth, in Kbits/s. This attribute can be used as a
+ <a>threshold target</a>.
</dd>
<dt>readonly attribute unsigned long currentUploadBandwidth</dt>
<dd>
- The current real-time upload bandwidth, in Kbits/s.
+ The current real-time upload bandwidth, in Kbits/s. This attribute can be used as a
+ <a>threshold target</a>.
</dd>
<dt>readonly attribute unsigned long maxDownloadBandwidth</dt>
@@ -686,11 +693,9 @@
<section>
<h4>The <a>WiredNetwork</a> Property</h4>
<p>This Property describes a wired network connection
- (e.g. Ethernet). It does not hold any specific attributes,
- since the necessary information is found in its
- superclass.</p>
- <dl title='[NoInterfaceObject] interface WiredNetwork : Network' class='idl'>
- </dl>
+ (e.g. Ethernet). Since it does not hold any specific
+ attributes, requesting this property yields an object of
+ the <a>SytemInfo</a> generic type.</p>
</section>
<section>
<h4>The <a>WiFiNetwork</a> Property</h4>
@@ -699,7 +704,8 @@
<dt>readonly attribute float currentSignalStrength</dt>
<dd>This connection's signal strength, as a normalized
value between 0 (no signal detected) and 1 (the level is
- at its maximum value).</dd>
+ at its maximum value). This attribute can be used as a
+ <a>threshold target</a>.</dd>
<dt>readonly attribute DOMString? SSID</dt>
<dd>The Service Set Identifier (SSID) of this
@@ -753,7 +759,7 @@
<h4>ECMAScript Example</h4>
<pre class="sh_javascript example">// Automatically adjust the screen brightness if the ambient brightness is above a certain level
-navigator.system.watch("AmbientLight",success, {highThreshold: 0.9});
+navigator.system.watch("AmbientLight",success, {highThreshold: 0.9, thresholdTarget:"normalizedValue"});
function success() {
navigator.system.get("OutputDevices",
@@ -770,13 +776,23 @@
<dl title="[NoInterfaceObject] interface Sensor: SystemProperty" class="idl">
<dt>readonly attribute float? value</dt>
- <dd>The numerical value of this sensor, at the time of sampling. Details on the meaning of the number and reported as well as its unit are given for each sensor property defined below.</dd>
- <dt>readonly attribute float? min</dt>
- <dd>The minimum value that the sensors measuring the property are able to report</dd>
- <dt>readonly attribute float? max</dt>
- <dd>The maximum value that the sensors measuring the property are able to report</dd>
+ <dd>The numerical value of this sensor, at the time of
+ sampling. Details on the meaning of the number and
+ reported as well as its unit are given for each sensor
+ property defined below. This attribute can be used as a
+ <a>threshold target</a>.</dd>
+ <dt>readonly attribute float? min</dt>
+ <dd>The minimum value that the sensors measuring the
+ property are able to report</dd>
+ <dt>readonly attribute float? max</dt>
+ <dd>The maximum value that the sensors measuring the
+ property are able to report</dd>
<dt>readonly attribute float? normalizedValue</dt>
- <dd>The numerical value of this sensor, at the time of sampling, normalized on a 0 to 1 scale, where 0 represents the minimum value that the sensor can report and 1 the maximum value.</dd>
+ <dd>The numerical value of this sensor, at the time of
+ sampling, normalized on a 0 to 1 scale, where 0 represents
+ the minimum value that the sensor can report and 1 the
+ maximum value. This attribute can be used as a
+ <a>threshold target</a>.</dd>
</dl>
@@ -901,10 +917,12 @@
<section>
<h4>The <a>AVCodecs</a> property</h4>
- <p>This property exposes information about the audio/video codecs available to this system. It is <a>enumerable</a></p>
+ <p>This property exposes information about the audio/video
+ codecs available to this system. It is
+ <a>enumerable</a>. Since it does not hold any specific
+ attributes, requesting this property yields an object of the
+ <a>SytemInfo</a> generic type.</p>
- <dl title='[NoInterfaceObject] interface AVCodec : SystemProperty' class='idl'>
- </dl>
</section>
<section>
@@ -934,50 +952,36 @@
<dl title='[NoInterfaceObject] interface VideoCodec : AVCodec' class='idl'>
- <dt>readonly attribute sequence<DOMString> compFormats</dt>
+ <dt>readonly attribute DOMString compFormats[]</dt>
<dd>Supported compression format names. Example : "AVI", "ogg"</dd>
- <dt>readonly attribute sequence<DOMString> containerFormats</dt>
+ <dt>readonly attribute DOMString containerFormats[]</dt>
<dd>Supported container format names. Example : "AVI", "ogg"</dd>
<dt>readonly attribute boolean hwAccel</dt>
<dd><code>true</code> if the codec includes hardware acceleration support, <code>false</code> otherwise.</dd>
- <dt>readonly attribute sequence<VideoProfile> profiles</dt>
- <dd>The list of profiles available for this codec.</dd>
+ <dt>readonly attribute DOMString profiles[]</dt>
+ <dd>The list of profiles available for this codec. For
+ example, "Simple", "Main", "High" or "Advanced"</dd>
- <dt>readonly attribute sequence<FrameType> frametypes</dt>
- <dd>The list of frame types supported by the codec</dd>
+ <dt>readonly attribute DOMString frameTypes[]</dt>
+ <dd>The list of frame types supported by the codec. For example, "Progressive" or "Interlaced"</dd>
- <dt>readonly attribute sequence<RateControl> ratetypes</dt>
- <dd>The list of rate control options supported by the codec</dd>
+ <dt>readonly attribute DOMString rateTypes[]</dt>
+ <dd>The list of rate control options supported by the codec. For example, "CBR" or "VBR"</dd>
</dl>
</section>
<section>
<h3>The <a>VideoProfile</a> Property</h3>
<p>The name attribute of this property (inherited from <a>SystemProperty</a>) describes a video profile. For example: "Simple", "Main", "High" or "Advanced"</p>
- <dl title='[NoInterfaceObject] interface VideoProfile : SystemProperty' class='idl'>
- </dl>
+
<p class="issue">Those properties could be replaced by an array of DOMString in VideoCodec. The reason they are currently defined as a separate property is that we may add specific fields later. But is that ever going to be necessary?</p>
</section>
- <section>
- <h3>The <a>FrameType</a> Property</h3>
- <p>The name attribute of this property (inherited from <a>SystemProperty</a>) describes a frame type. For example: "Progressive" or "Interlaced"</p>
- <dl title='[NoInterfaceObject] interface FrameType : SystemProperty' class='idl'>
- </dl>
- </section>
-
- <section>
- <h3>The <a>RateControl</a> Property</h3>
- <p>The name attribute of this property (inherited from <a>SystemProperty</a>) describes a rate control. For example: "CBR" or "VBR"</p>
- <dl title='[NoInterfaceObject] interface RateControl : SystemProperty' class='idl'>
- </dl>
- </section>
- </section>
<!-- ********* /Codecs ************************************************************** -->
<!-- ********* Storage ************************************************************** -->
@@ -1001,13 +1005,26 @@
</section>
<section>
- <h4>The <a>Storage</a> Property</h4>
+ <h4>The <em>Storage</em> Property</h4>
<p>This property exposes the data storage devices
- connected to this system. It is <a>enumerable</a>,
- i.e. requests to this property will yield an array of
- <a>StorageUnit</a> objects, unless an <a>id</a> parameter
- is passed as an option in which case a single
- <a>StorageUnit</a> object is returned.</p>
+ connected to this system. When requested through API
+ functions, this property returns an array of objects of
+ type <a>StorageUnit</a>, corresponding to the storage
+ devices available to this unit.</p>
+
+ <h4>The <em>StorageUnit</em> Property</h4>
+ <p>This property exposes a single data storage device
+ connected to this system. When requested through API
+ functions, this property returns an object of type
+ <a>StorageUnit</a>, corresponding to the storage unit
+ specified. This property is <a>enumerable</a>, i.e. an
+ <a>id</a> parameter must be passed to the API function
+ call to indicate which unit is requested.</p>
+
+ <h4>The <a>StorageUnit</a> Interface</h4>
+
+ <p>This interface defines the type of object returned by API functions using the <em>Storage</em> and <em>StorageUnit</em> properties</p>
+
<dl title="interface StorageUnit : SystemProperty" class="idl">
<dt>const unsigned short TYPE_UNKNOWN=0</dt>
<dd><code>type</code> is set to this value when the type of this device is unknown to this API.</dd>
@@ -1026,7 +1043,9 @@
<dt>readonly attribute unsigned long capacity</dt>
<dd>The amount of data that this device can hold, in bytes. A <a>watch</a> operation operating on an object of type <a>StorageUnit</a> must invoke the success callback only when this attribute has changed</dd>
<dt>readonly attribute unsigned long availableCapacity</dt>
- <dd>The amount of available data that this device can hold, in bytes</dd>
+ <dd>The amount of available data that this device can
+ hold, in bytes. This attribute can be used as a
+ <a>threshold target</a>.</dd>
<dt>readonly attribute boolean isRemoveable</dt>
<dd><code>true</code> if this unit can be removed from the system (e.g. a memory card unplugged, or a disk ejected), <code>false</code> otherwise</dd>
</dl>
@@ -1065,14 +1084,15 @@
<h4>The <a>OutputDevices</a> Property</h4>
<p>This property provides information on the output
- devices (displays, audio) available on this system. It is
- <a>enumerable</a>, i.e. requests for this property will
- yield an array of objects of type <a>OutputDevice</a> (or
- one of its subtypes), unless an <a>id</a> parameter is
- passed as an option in which case a single object of class
- <a>InputDevice</a> (or subtype) is returned.</p>
+ devices (displays or audio) available on this system.</p>
<dl title='[NoInterfaceObject] interface OutputDevice : SystemProperty' class='idl'>
+ <dt>attribute Display displayDevices[]</dt>
+ <dd>The list of display devices connected to this system</dd>
+ <dt>attribute Display audioDevices[]</dt>
+ <dd>The list of audio devices connected to this system</dd>
+
+
</dl>
<p class="issue">There is no indication of current/active display(s) or audio(s). Is that necessary/possible/desired?</p>
@@ -1171,22 +1191,26 @@
<h3>The <a>InputDevices</a> Property</h3>
<p>This property provides information on input
- devices (cameras, mice) available on this system. It is
- <a>enumerable</a>, i.e. requests for this property will
- yield an array of objects of type <a>InputDevice</a> (or
- one of its subtypes), unless an <a>id</a> parameter is
- passed as an option in which case a single object of class
- <a>InputDevice</a> (or subtype) is returned.</p>
+ devices (cameras, mice) available on this system.</p>
- <dl title='interface InputDevice : SystemProperty' class='idl'>
+ <dl title='interface InputDevices : SystemProperty' class='idl'>
+ <dt>attribute PointingDevice pointingDevices[]</dt>
+ <dd>The list of pointing devices available on this system.</dd>
+ <dt>attribute Keyboard keyboards[]</dt>
+ <dd>The list of keyboards available on this system.</dd>
+ <dt>attribute Camera cameras[]</dt>
+ <dd>The list of cameras available on this system.</dd>
+ <dt>attribute Microphone microphones[]</dt>
+ <dd>The list of microhones available on this system.</dd>
</dl>
- <h4>The <a>PointingDevice</a> Property</h4>
+ <h4>The <em>PointingDevice</em> Property</h4>
- <p>This interface describes a pointing device. It inherits from the <a>InputDevice</a> interface.</p>
+ <p>This interface describes a pointing device. It is
+ <a>enumerable</a>.</p>
- <dl title="interface PointingDevice : InputDevice" class="idl">
+ <dl title="interface PointingDevice" class="idl">
<dt>const unsigned short TYPE_UNKNOWN=0</dt>
<dd>When the <a>type</a> attribute has this value, then the type of this pointing device is unknown.</dd>
<dt>const unsigned short TYPE_MOUSE=1</dt>
@@ -1205,7 +1229,13 @@
<dd><code>true</code> when this device supports the multi-touch method of interaction, <code>else</code> otherwise.</dd>
</dl>
- <p>The <a>Keyboard</a> interface describe a keyboard or keypas connected to this system.</p>
+ <h4>The <em>Keyboard</em> Property</h4>
+
+ <p>The <em>Keyboard</em> property describes a keyboard or
+ keypads connected to this system. When this property is
+ requested through the API, an object of type
+ <a>Keyboard</a>, defined below, is returned.</p>
+
<dl title="interface Keyboard : InputDevice" class="idl">
<dt>const unsigned short TYPE_UNKNOWN=0</dt>
<dd>When the <a>type</a> attribute has this value, then this device is of a type unknown to this API.</dd>
@@ -1219,7 +1249,14 @@
<dd><code>true</code> when this device is a physical keyboard, <code>else</code> if it is a software keyboard.</dd>
</dl>
- <p>The <a>Camera</a> interface describes a cameras connected to this system.</p>
+ <h4>The <em>Camera</em> Property</h4>
+
+ <p>The <em>Camera</em> property describes a camera or
+ similar video capture device connected to this
+ system. When this property is requested through the API,
+ an object of type <a>Camera</a>, defined below, is
+ returned.</p>
+
<dl title="interface Camera : InputDevice" class="idl">
<dt>readonly attribute boolean supportsVideo</dt>
<dd><code>true</code> when this device supports recording video, <code>else</code> otherwise.</dd>
@@ -1235,7 +1272,14 @@
<p class="issue">Use focal length instead? And shutter speed/aperture/ISO/sensor type?</p></dd>
</dl>
- <p>The <a>Microphone</a> interface describes a microphones connected to this system.</p>
+ <h4>The <em>Microphone</em> Property</h4>
+
+ <p>The <em>Microphone</em> property describes a microphone
+ or similar audio capture device connected to this
+ system. When this property is requested through the API,
+ an object of type <a>Microphone</a>, defined below, is
+ returned.</p>
+
<dl title="interface Microphone : InputDevice" class="idl">
<dt>const unsigned short TYPE_UNKNOWN=0</dt>
<dd><code>type</code> is set to this value when the type of this device is unknown to this API.</dd>
Received on Tuesday, 23 March 2010 16:36:08 UTC