W3C home > Mailing lists > Public > public-dap-commits@w3.org > December 2009

2009/dap/system-info Overview.html,1.16,1.17

From: Max Froumentin via cvs-syncmail <cvsmail@w3.org>
Date: Wed, 02 Dec 2009 12:35:09 +0000
To: public-dap-commits@w3.org
Message-Id: <E1NFoQH-0002Y8-Ig@lionel-hutz.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 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Wednesday, 2 December 2009 12:35:19 GMT