- From: Max Froumentin via cvs-syncmail <cvsmail@w3.org>
- Date: Thu, 03 Dec 2009 11:29:45 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/system-info
In directory hutz:/tmp/cvs-serv12197
Modified Files:
Overview.html
Log Message:
- make generic get/watch function for all properties
- use URLs for property identifiers
- put threshold in get/watch options
Index: Overview.html
===================================================================
RCS file: /sources/public/2009/dap/system-info/Overview.html,v
retrieving revision 1.20
retrieving revision 1.21
diff -u -d -r1.20 -r1.21
--- Overview.html 2 Dec 2009 16:37:32 -0000 1.20
+++ Overview.html 3 Dec 2009 11:29:43 -0000 1.21
@@ -37,13 +37,93 @@
<h2>API Description</h2>
<section>
- <h3>The <a>SystemInformation</a> interface</h3>
+ <h3>The <a>System</a> interface</h3>
- <p>Objects implementing the <code>NavigatorDevice</code> interface (e.g. the <code>window.navigator.device</code> object in Web browsers [NAVIGATOR]) provide access to the interfaces defined below through the <code>SystemInformation</code> interface. An instance of <code>SystemInformation</code> would be then obtained by using binding-specific casting methods on an instance of NavigatorDevice.</p>
+ <p>Objects implementing the <code>NavigatorDevice</code>
+ interface (e.g. the <code>window.navigator.device</code>
+ object in Web browsers [NAVIGATOR]) provide access to the
+ interfaces defined below through the
+ <code>System</code> interface. An instance of
+ <code>System</code> would be then obtained by using
+ binding-specific casting methods on an instance of
+ NavigatorDevice.</p>
- <dl title='[NoInterfaceObject] interface SystemInformation' class='idl'>
- <dt>readonly attribute Power power</dt>
- <dd>The attribute used to access the <a href="#power">Power API</a></dd>
+ <dl title='[NoInterfaceObject] interface System' class='idl'>
+ <dt>PendingOp get(DOMString propertyId, SuccessCB successCallback, optional ErrorCB? errorCallback, optional Options? options)</dt>
+
+ <dd>
+ The <code>get</code> function retrieves the current state
+ of any combination of system properties. When called, the
+ function MUST immediately return and asynchronously
+ acquires the current state of the values passed to the
+ filter. If it is successful the success callback is
+ invoked and is passed a <code>SystemState</code> object
+ containing the requested information. If an error occurs,
+ and an <code>errorCallback</code> function is passed, that
+ function is invoked and is passed a
+ <code>PowerError</code> object indicating the cause of
+ error.
+
+ <dl class="parameters">
+ <dt>DOMString propertyId</dt>
+ <dd>The URI or curie of the property to retrieve.</dd>
+ <dt>SuccessCB successCallback</dt>
+ <dd>function called when the properties have been successfully retrieved</dd>
+ <dt>ErrorCB? errorCallback</dt>
+ <dd>function called when an error occurred while retrieving the properties</dd>
+ <dt>Options? options</dt>
+ <dd>An object containing the various options for fetching the properties requested</dd>
+ </dl>
+ </dd>
+
+ <dt>PendingOp watch(DOMString propertyId, SuccessCB successCallback, optional ErrorCB? errorCallback, optional in Options? options)</dt>
+ <dd>The <code>watch</code> function allows tracking the change
+ of one or several system properties. When called, it MUST
+ immediately return and then asynchronously start a watch process
+ defined as the following set of steps:
+ <ol>
+ <li>Acquire a new <code>SystemState</code> object that reflects the system's
+ current state. If successful, invoke the associated
+ <code>successCallback</code> with a <code>SystemState</code> object as an
+ argument. If the attempt fails, and the method was invoked with a non-null
+ <code>errorCallback</code> argument, this method MUST invoke the
+ <code>errorCallback</code> with an <code>ErrorCB</code> object as an
+ argument.</li>
+ <li>Register to receive system events that indicate that the status of the requested properties may have changed</li>
+ <li>When a system event is successfully received, invoke
+ the associated <code>successCallback</code> with a
+ <code>SystemState</code> object as an argument. If an
+ error occurs, and the method was invoked with a
+ non-null <code>errorCallback</code> argument, this
+ method MUST invoke the <code>errorCallback</code> with
+ an <code>ErrorCB</code> object as an argument.</li>
+ <li>Repeat the previous step until the
+ <code>cancel</code> method of the <code>PendingOp</code>
+ object returned by this <code>watch</code> function is
+ invoked.</li>
+ </ol>
+ <dl class="parameters">
+ <dt>DOMString propertyId</dt>
+ <dd>URI or curie identifying the property to track.</dd>
+ <dt>SuccessCB successCallback</dt>
+ <dd>function called when the properties have been successfully retrieved</dd>
+ <dt>ErrorCB? errorCallback</dt>
+ <dd>function called when an error occurred while retrieving the properties</dd>
+ <dt>Options? options</dt>
+ <dd>An object containing the various options for fetching the properties requested</dd>
+ </dl>
+ </dd>
+ </dl>
+
+
+ <dl title="[NoInterfaceObject] interface Options" class="idl">
+ <dt>attribute double highThreshold</dt>
+ <dd>This attribute has no effect on the <code>get</code> method. On the <code>watch</code> method, it indicates that the successCallback MUST only
+ be triggered if the property is a number and its value is greater than or equal this number.</dd>
+
+ <dt>attribute double lowThreshold</dt>
+ <dd>This attribute has no effect on the <code>get</code> method. On the <code>watch</code> method, it indicates that the successCallback MUST only
+ be triggered if the property is a number and its value is lower than or equal this number.</dd>
</dl>
</section>
@@ -51,76 +131,48 @@
<section id="power">
<h3>Power</h3>
- <p>This API exposes the device's power state: whether it is running on internal or external power source, as well as its charge level. The API also allows monitoring power sources.</p>
-
-
- <dl title='[NoInterfaceObject] interface Power' class='idl'>
+ <p>The property and option below expose the device's power
+ state: whether it is running on internal or external power
+ source, as well as its charge level.</p>
- <dt>PendingOp getCurrentPower(in SuccessCB successCallback, [Optional] in ErrorCB errorCallback)</dt>
- <dd>The <code>getCurrentPower</code> function retrieves the
- current state of the power source. When called, the function
- MUST immediately return and asynchronously acquires the current
- state. If it is successful the success callback is invoked and
- is passed a <code>PowerState</code> object containing the
- requested information. If an error occurs, and an
- <code>errorCallback</code> function is passed, that function is
- invoked and is passed a <code>PowerError</code> object
- indicating the cause of error.</dd>
+ <section>
+ <h3>Example</h3>
+ <pre class="example">
+var success = function(power) {
+ alert("Low battery level: "+power.batteryLevel);
+}
+navigator.device.system.watch("power:batteryLevel",success,null,{lowThreshold:0.2});</pre>
+ </section>
- <dt>PendingOp watchPower(in SuccessCB successCallback, [Optional] in ErrorCB errorCallback, [Optional] in PowerOptions options)</dt>
- <dd>The <code>watchPowerSource</code> method takes one, two or
- three arguments. When called, it MUST immediately return and
- then asynchronously start a watch process defined as the
- following set of steps:
- <ol>
- <li>Acquire a new <code>PowerState</code> object that reflects the delivery
- context's current power state. If successful, invoke the associated
- <code>successCallback</code> with a <code>PowerSource</code> object as an
- argument. If the attempt fails, and the method was invoked with a non-null
- <code>errorCallback</code> argument, this method MUST invoke the
- <code>errorCallback</code> with a <code>PowerError</code> object as an
- argument. </li>
- <li>Register to receive system events that indicate that the power status may have changed</li>
- <li>When a system event is received:
- <ul>
- <li>If the <code>lowThreshold</code> attribute has a is
- non-null value, fire the <code>successCallback</code>
- function if the value of <code>powerLevel</code> is less
- than the value of <code>lowThreshold</code></li>
- <li>If the <code>highThreshold</code> attribute has a
- non-null value, fire the <code>successCallback</code>
- function if the value of <code>powerLevel</code> is
- greater than the value of <code>lowThreshold</code></li>
- <li>If both <code>highThreshold</code> and
- <code>lowThreshold</code> are null, fore the
- <code>successCallback</code> function if the power's
- state has changed significantly. The definition of what
- consitutes a significant change is left to the
- implementation.</li>
- </ul>
- </li>
- </ol>
- </dd>
- </dl>
+ <section>
+ <h4>Properties</h4>
+ <dl>
+ <dt>Battery Level</dt>
+ <dd>URI: <code>http://www.w3.org/2009/dap/SysInfo/Power#batteryLevel</code><br/>
+ Curie: <code>power:batteryLevel</code><br/>
+ Corresponding DCO property: <a href="http://www.w3.org/TR/dcontology/hardware.html#batteryLevel">batteryLevel</a></dd>
+ <dd>Specifies that the resulting <code>PowerState</code> object MUST contain a <code>batteryLevel</code> value.</dd>
- <section>
- <h4>PowerOptions</h4>
- <dl title='interface PowerOptions' class='idl'>
- <dt>attribute double highThreshold</dt>
- <dd>...</dd>
+ <dt>Time Remaining</dt>
+ <dd>URI: <code>http://www.w3.org/2009/dap/SysInfo/Power#timeRemaining</code><br/>
+ Curie: <code>power:timeRemaining</code></dd>
+ <dd>Specifies that the resulting <code>PowerState</code> object MUST contain a <code>timeRemaining</code> value.</dd>
- <dt>attribute double lowThreshold</dt>
- <dd>...</dd>
- </dl>
- </section>
+ <dt>External Power Source</dt>
+ <dd>URI: <code>http://www.w3.org/2009/dap/SysInfo/Power#externalSource</code><br/>
+ Curie: <code>power:externalSource</code></dd>
+ <dd>Specifies that the resulting <code>PowerState</code> object MUST contain a <code>externalSource</code> value.</dd>
+ </dl>
+ </section>
<section>
<h4>PowerState</h4>
<dl title='interface PowerState' class='idl'>
+
<dt>readonly attribute boolean usingExternalPowerSource</dt>
- <dd>The <code>usingExternalPowerSource</code> attribute must be
+ <dd>This attribute must be
<code>true</code> if the device is plugged into an external
power source. Otherwise, it must be <code>false</code>. If the
correct value cannot be obtained, or if the device does not have
@@ -262,12 +314,6 @@
CpuUsageOptions</code> parameter. </li>
</ol>
</dd>
- <dt>void clearWatch(in int watchId)</dt>
- <dd>The <code>watchCpuUsage() </code>method returns an integer value that uniquely
- identifies the watch process. When the <code>clearWatch()</code> method is called
- with this identifier, the watch process MUST stop monitoring device CPU utilization
- and MUST cease invoking any callbacks.
- </dd>
</dl>
<section>
<h4>CpuUsageCB</h4>
Received on Thursday, 3 December 2009 11:29:47 UTC