- From: Max Froumentin via cvs-syncmail <cvsmail@w3.org>
- Date: Wed, 02 Dec 2009 12:35:09 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/system-info
In directory hutz:/tmp/cvs-serv9783
Modified Files:
Overview.html
Log Message:
Rewrote a lot of the Power interface:
- there is now a single watch function which reflect any change in power state
- the power attributes have been replaced by the asynchronous getCurrentPower function
- thresholds are now used to control when the watchPower function triggers a callback
- removed sampleInterval: an implementation is free to callback as it sees fit
- level is now 0.0 to 1.0 and remainingTime is not milliseconds
- we're now using cancellableOperation and generic error and callbacks, like in Contacts
Index: Overview.html
===================================================================
RCS file: /sources/public/2009/dap/system-info/Overview.html,v
retrieving revision 1.16
retrieving revision 1.17
diff -u -d -r1.16 -r1.17
--- Overview.html 2 Dec 2009 11:29:48 -0000 1.16
+++ Overview.html 2 Dec 2009 12:35:07 -0000 1.17
@@ -38,257 +38,134 @@
<section>
<h3>Power</h3>
- <p>This API exposes available power sources such as: batteries,
- wall outlet, etc. It also expose if the device is on battery power
- and its charge level.</p>
-
- <dl title='[NoInterfaceObject] interface Power' class='idl'>
- <dt>readonly attribute boolean usingExternalPowerSource</dt>
- <dd>The <code>usingExternalPowerSource</code> 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
- an internal power source, an implementation MUST return
- <code>true</code>.</dd>
+ <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>
- <dt>readonly attribute unsigned short powerLevel</dt>
- <dd>The <code>powerLevel</code> attribute MUST indicate what
- percent of the internal power source remains. The maximum value
- is 100, the minimum value is 0. If the value cannot be obtained,
- or if the device does not have an internal power source, the
- attribute value must be 0. </dd>
- <!--dt>readonly attribute int rate</dt>
- <dd>The <code>rate</code> attribute denotes the current rate
- (mW) of power change for the internal power sources. Discharge
- rate is a negative value. Charge rate is a positive value.
- </dd-->
-
- <dt>readonly attribute unsigned int timeRemaining</dt>
- <dd>The <code>timeRemaining </code>attribute should indicate the
- estimated time remaining (seconds) at the current rate before
- the system enters shutdown mode. If
- <code>usingExternalPowerSource</code> is true and
- <code>rate</code> is greater than or equal to 0, this value MUST
- be 0, meaning that there is essentially infinite time
- remaining. If <code>usingExternalPowerSource</code> is true and
- <code>rate </code> is less than 0 (indicating that even though
- the system is plugged into an external power source, the battery
- is still being drained), <code>timeRemainging </code>should be
- greater than 0. </dd>
+ <dl title='[NoInterfaceObject] interface Power' class='idl'>
+ <dt>PendingOperation getCurrentPower(in SuccessCallback successCallback, [Optional] in ErrorCallback 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>
- <dt>long watchPowerSource(in PowerSourceCallback successCallback, [Optional] in PowerErrorCallback errorCallback)</dt>
- <dd>The <code>watchPowerSource()</code> method takes one, two or
+ <dt>PendingOperation watchPower(in SuccessCallback successCallback, [Optional] in ErrorCallback 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>PowerSource</code> object that reflects the delivery
- context's current power source. If successful, invoke the associated
+ <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>
- <dt>long watchPowerLevel(in PowerLevelCallback successCallback, [Optional] in PowerErrorCallback errorCallback, [Optional] in PowerLevelOptions options)</dt>
- <dd>The <code>watchPowerLevel()</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>PowerLevel</code> object. If successful, invoke the
- associated <code>successCallback</code> with <code>PowerLevel</code> object
- as an argument. If the attempt fails, and the method was invoked with a
- non-null <code>errorCallback</code> argument, the implementation MUST
- invoke the <code>errorCallback</code> with a <code>PowerError</code> object
- as an argument.</li>
- <li>Invoke the appropriate callback with a new <code>PowerLevel</code>
- object every time the implementation determines that the power level of the
- hosting device has changed.</li>
- </ol>
- </dd>
-
- <dt>void clearWatch(in int watchId)</dt>
- <dd>Both <code>watchPowerLevel()</code> and
- <code>watchPowerSource()</code> methods return an integer value
- that uniquely identifies the watch process. When the
- <code>clearWatch()</code> method is called with this identifier,
- the watch process MUST cease invoking any callbacks.
- </dd>
</dl>
<section>
- <h4>PowerLevelCallback</h4>
- <dl title='[Callback=FunctionOnly, NoInterfaceObject] interface PowerLevelCallback' class='idl'>
- <dt>void handleEvent(in PowerLevel level)</dt>
- <dd>This function is supplied by a call to
- <code>watchPowerLevel()</code>. Use the parameter to retrieve
- information about system power level.</dd>
- </dl>
- </section>
-
- <section>
- <h4>PowerSourceCallback</h4>
- <dl title='[Callback=FunctionOnly, NoInterfaceObject] interface PowerSourceCallback' class='idl'>
- <dt>void handleEvent(in boolean usingExternalPowerSource)</dt>
- <dd>This function is supplied by a call to
- <code>watchPowerSource()</code>. Use the parameter to retrieve
- information about system power source.</dd>
- </dl>
- </section>
-
- <section>
- <h4>PowerLevelOptions</h4>
- <dl title='interface PowerLevelOptions' class='idl'>
- <dt>attribute unsigned int sampleInterval</dt>
- <dd>The <code>sampleInterval</code> attribute specifies in
- milliseconds how often the implementation SHOULD check to see
- if the power level has changed. While the specification allows
- the caller to sample at very small intervals, on many
- implementations, this may be wasteful because the battery
- device may update its level information at a frequency
- significantly below the <code>sampleInterval</code>. On
- implementations that are event driven, this value MAY be
- ignored. The caller should be aware that setting a value too
- small can adversely affect the battery life. The default
- value SHOULD be 10,000, or once every 10 seconds.</dd>
+ <h4>PowerOptions</h4>
+ <dl title='interface PowerOptions' class='idl'>
- <dt>attribute unsigned int highThreshold</dt>
+ <dt>attribute double highThreshold</dt>
<dd>If the <code>highThreshold</code> is greater than zero,
when system power level rises above the specified value, the
<code>PowerLevelCallback</code> MUST be invoked with the
<code>crossedHighThreshold</code> value of the
<code>PowerLevel</code> parameter set to <code>true</code>.
If the <code>PowerLevelOptions</code> object is not null, and
- the <code>highThreshold</code> value is 100 (default), the
+ the <code>highThreshold</code> value is 1.0 (the default), the
<code>PowerLevelCallback</code> MUST not be invoked with the
<code>crossedHighThreshold</code> value set to
- <code>true</code>. The value must be greater or equal to 0,
- and no greater than 100. </dd>
+ <code>true</code>. The value must be greater or equal to 0.0,
+ and no greater than 1.0. If the value is different from null, then the callback in only called when the power level is higher than the value passed</dd>
- <dt>attribute unsigned int lowThreshold</dt>
- <dd>If the <code>lowThreshold</code> is less than 100, when
+
+ <dt>attribute double lowThreshold</dt>
+ <dd>If the <code>lowThreshold</code> is less than 1.0, when
the system power level falls below the specified value, the
<code>PowerLevelCallback</code> MUST be invoked with the
<code>crossedLowThreshold</code> value of the
<code>PowerLevel</code> parameter set to <code>true</code>. If
the <code>PowerLevelOptions</code> object is not null, and the
- <code>lowThreshold</code> value is 0 (default), the
+ <code>lowThreshold</code> value is 0.0 (default), the
<code>PowerLevelCallback</code> MUST not be invoked with the
<code> crossedLowThreshold</code> value set to
<code>true</code>. The value MUST be greater than or equal to
- 0, and no greater than 100.</dd>
+ 0.0, and no greater than 1.0. If the value is different from null, then the callback in only called when the power level is higher than the value passed</dd>
</dl>
</section>
<section>
- <h4>PowerLevel</h4>
- <dl title='interface PowerLevel' class='idl'>
- <dt>readonly attribute unsigned short percentRemaining</dt>
- <dd>The <code>percentRemaining</code> attribute should specify
- what percent of the device internal power remains. For
- implementations where the internal power source differentiates
- between the Design Maximum Capacity and the Current Maximum
- Capacity, the Current Maximum Capacity SHOULD be used. The
- maximum value MUST be 100; the minimum value MUST be 0,
- although that value MAY never be reported.
- </dd>
-
- <dt>readonly attribute boolean crossedHighThreshold</dt>
- <dd>
- When a <code>PowerLevelCallback</code> is invoked with a
- <code>PowerLevel</code> object whose
- <code>crossedHighThreshold</code> attribute set to
- <code>true</code>, the power level high threshold has been
- crossed. This threshold value is set in the
- <code>PowerOptions</code> parameter of a call to
- <code>watchPowerLevel() </code>. The
- <code>crossedHighThreshold</code> value MUST be false if any
- one of the following is true:
- <ul>
- <li>The <code>PowerLevel</code> object is obtained by
- directly accessing the <code>Power.PowerLevel</code>
- attribute;</li>
-
- <li>The <code>PowerLevelOption</code>
- <code>highThreshold</code> value was either not set or set
- to 100 in a prior call to
- <code>watchPowerLevel()</code>;</li>
-
- <li>The current power level is not greater than the value
- specified by the <code>PowerLevelOption
- highThreshold</code> value specified in a prior call to
- <code>watchPowerLevel()</code>; </li>
-
- <li>The current power level is greater than the value
- specified by the <code>PowerLevelOption
- highThreshold</code> value specified in a prior call to
- <code>watchPowerLevel()</code> but the
- <code>highThresholdHysteresis</code> attribute in the
- <code>PowerLevelOption</code> was either not set or set to
- a value greater than the <code>highThreshold</code>;</li>
-
- <li>The current power level is greater than the value
- specified by the <code>PowerLevelOption
- highThreshold</code> value in a prior call to
- <code>watchPowerLevel()</code>, but the high threshold
- event has already been called once, and the system power
- level has not yet dropped below the value specified by the
- <code>highThresholdHysteresis</code> attribute in the
- <code>PowerLevelOption</code>. </li>
- </ul>
- </dd>
- <dt>readonly attribute boolean crossedLowThreshold</dt>
- <dd>When a <code>PowerLevelCallback</code> is invoked with a
- <code>PowerLevel</code> object whose
- <code>crossedLowThreshold</code> attribute set to
- <code>true</code>, the power level low threshold has been
- crossed. This threshold value MUST be set in the
- <code>PowerOptions</code> parameter of a prior call to
- <code>watchPowerLevel()</code>. The
- <code>crossedLowThreshold</code> value will be
- <code>false</code> if any one of the following is true:
- <ul>
- <li>The <code>PowerLevel</code> object is obtained by
- directly accessing the <code>Power.PowerLevel</code>
- attribute; </li>
+ <h4>PowerState</h4>
+ <dl title='interface PowerState' class='idl'>
+ <dt>readonly attribute boolean usingExternalPowerSource</dt>
+ <dd>The <code>usingExternalPowerSource</code> 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
+ an internal power source, an implementation MUST return
+ <code>true</code>.</dd>
- <li>The <code>PowerLevelOption lowThreshold</code> value
- was either not set or set 0 in a prior call to
- <code>watchPowerLevel()</code>;</li>
+ <dt>readonly attribute double powerLevel</dt>
+ <dd>The <code>powerLevel</code> attribute MUST indicate what
+ percent of the internal power source remains. The maximum value
+ is 100, the minimum value is 0. If the value cannot be obtained,
+ or if the device does not have an internal power source, the
+ attribute value must be 0. </dd>
- <li>The current power level is not less than the value
- specified by the <code>PowerLevelOption
- lowThreshold</code> value in a prior call to
- <code>watchPowerLevel()</code>;</li>
+ <!--dt>readonly attribute int rate</dt>
+ <dd>The <code>rate</code> attribute denotes the current rate
+ (mW) of power change for the internal power sources. Discharge
+ rate is a negative value. Charge rate is a positive value.
+ </dd-->
- <li>The current power level is less than the value
- specified by the <code>PowerLevelOption
- lowThreshold</code> value in a prior call to
- <code>watchPowerLevel()</code> but the
- <code>lowThresholdHysteresis</code> attribute in the
- <code> PowerLevelOption</code> was either not set or set
- to a value less than the <code>lowThreshold</code>;</li>
+ <dt>readonly attribute unsigned long timeRemaining</dt>
+ <dd>The <code>timeRemaining </code>attribute should indicate the
+ estimated time remaining (in milliseconds) at the current rate before
+ the system enters shutdown mode. If
+ <code>usingExternalPowerSource</code> is true and
+ <code>rate</code> is greater than or equal to 0, this value MUST
+ be 0, meaning that there is essentially infinite time
+ remaining. If <code>usingExternalPowerSource</code> is true and
+ <code>rate </code> is less than 0 (indicating that even though
+ the system is plugged into an external power source, the battery
+ is still being drained), <code>timeRemainging </code>should be
+ greater than 0. </dd>
- <li>The current power level is less than the value
- specified by the <code>PowerLevelOption
- lowThreshold</code> value in a prior call to <code>
- watchPowerLevel()</code>, but the low threshold event has
- already been called once, and the system power level has
- not yet risen above the value specified by the
- <code>lowThresholdHysteresis</code> attribute in the
- <code>PowerLevelOption</code>.</li>
- </ul>
- </dd>
</dl>
</section>
-
<section>
<h4>PowerError</h4>
- <dl title='interface PowerError' class='idl'>
+ <dl title='interface PowerError : GenericError' class='idl'>
<dt>readonly attribute unsigned short UNKNOWN_ERROR</dt>
<dd><code>UNKNOWN_ERROR</code> (numeric value 0): The
implementation failed to retrieve either power source or power
@@ -309,13 +186,8 @@
internal power source, or if the system does provide this
information.</dd>
- <dt>readonly attribute unsigned short TIMEOUT</dt>
- <dd><code>TIMEOUT</code> (numeric value 3): The specified
- maximum length of time has elapsed before the implementation
- could successfully acquire power information.</dd>
-
<dt>readonly attribute unsigned short INVALID_VALUE</dt>
- <dd><code>INVALID_VALUE</code> (numeric value 4): The
+ <dd><code>INVALID_VALUE</code> (numeric value 3): The
implementation failed to retrieve power source or power level
information because one or more of the values in the
<code>PowerLevelOptions</code> or
@@ -323,14 +195,14 @@
<code>watchPowerLevel()</code> or
<code>watchPowerSource()</code> calls was invalid. For
example, if the <code>PowerLevelOptions highThreshold</code>
- attribute is set to a value greater than 100, the
- <code>PowerErrorCallback</code> MUST be invoked with the
+ attribute is set to a value greater than 1.0, the
+ <code>errorCallback</code> function MUST be invoked with the
<code>PowerError</code> <code>code</code> attribute set with a
- value of <code>INVALID_VALUE</code> (4).</dd>
+ value of <code>INVALID_VALUE</code>.</dd>
<dt>readonly attribute unsigned short code</dt>
<dd>The <code>code</code> attribute SHOULD contain one of the
- errors defined in this specification. An implementation MAY
+ error values defined in this specification. An implementation MAY
define additional error codes, but MUST NOT use the numeric
values defined here.</dd>
@@ -2297,6 +2169,83 @@
</dl>
</section>
</section>
+
+ <section>
+ <h2>General API Support</h2>
+
+ This section defines the general API interfaces required by this specification that MAY also be in use in other DAP APIs.
+
+ <p class='note'>These interfaces MAY be general interfaces for use throughout all APIs. They are included here for now for completion.</p>
+
+ <section>
+ <h2><a>SuccessCallback</a> interface</h2>
+
+ <!-- interface intro here -->
+
+ <dl title='[Callback=FunctionOnly, NoInterfaceObject] interface SuccessCallback' class='idl'>
+ <dt>
+ void onSuccess ()
+ </dt>
+ <dd>
+ <!-- interface description here -->
+
+ <dl class='parameters'>
+ <dt>
+ [Optional] Object obj
+ </dt>
+ <dd>
+ The return object of a successful asynchronous operation. This parameter is OPTIONAL.
+ </dd>
+ </dl>
+ </dd>
+ </dl>
+
+ </section>
+
+ <section>
+ <h2><a>ErrorCallback</a> interface</h2>
+
+ <!-- interface intro here -->
+
+ <dl title='[Callback=FunctionOnly, NoInterfaceObject] interface ErrorCallback' class='idl'>
+ <dt>
+ void onError ()
+ </dt>
+ <dd>
+ <!-- interface description here -->
+
+ <dl class='parameters'>
+ <dt>
+ GenericError error
+ </dt>
+ <dd>
+ The error object of an unsuccessful asynchronous operation.
+ </dd>
+ </dl>
+ </dd>
+ </dl>
+
+ </section>
+
+ <section>
+ <h2><a>PendingOperation</a> interface</h2>
+
+ <!-- interface intro here -->
+
+ <dl title='[NoInterfaceObject] interface PendingOperation' class='idl'>
+ <dt>
+ void cancel ()
+ </dt>
+ <dd>
+ Cancel/clear the pending asynchronous operation. Callbacks related to the operation cancelled MUST NOT be called.
+ </dd>
+ </dl>
+
+ </section>
+
+ </section>
+ <!-- end api description section -->
+
</section>
<!--************************************* Requirements ***************************************************-->
<section class="informative appendix">
Received on Wednesday, 2 December 2009 12:35:18 UTC