fix handling of bad state errors
authorJim Barnett <Jim.Barnett@genesyslab.com>
Thu, 23 May 2013 10:00:57 -0400
changeset 421 d2d236d9252a
parent 420 75fb0c6939c8
child 422 04916c504edf
fix handling of bad state errors
media-stream-capture/MediaRecorder.html
--- a/media-stream-capture/MediaRecorder.html	Tue May 21 12:04:08 2013 +0300
+++ b/media-stream-capture/MediaRecorder.html	Thu May 23 10:00:57 2013 -0400
@@ -16,7 +16,7 @@
                             company: "Microsoft Corp.",
                             url: "mailto:travis.leithead@microsoft.com?subject=MediaStream Capture Scenarios Feedback",
                             companyURL: "http://www.microsoft.com"}],
-                  publishDate:  "2013-05-07",
+                  publishDate:  "2013-05-23",
                   edDraftURI:   "http://dvcs.w3.org/hg/dap/raw-file/tip/media-stream-capture/RecordingProposal.html",
                   previousPublishDate: null,
                   prevED: "",
@@ -187,11 +187,10 @@
           	<dt>attribute EventHandler onwarning</dt><dd>Called to handle the recordingwarning event. </dd>
           	<dt>void start()</dt>
 <dd>When a <code>MediaRecorder</code> object’s <code>start()</code> method is invoked,
-			then, if the <code>state</code> is not "inactive", the UA MUST
-				raise an <code>INVALID_STATE</code> exception and return immediately.  
-			Otherwise, it MUST queue a task, using the DOM manipulation task source, 
+			the UA <em title="must" class="rfc2119">must</em> queue a task, using the DOM manipulation task source, 
 			that runs the following steps:
 		<ol>
+			<li>If the <code>state</code> is not "inactive", 	raise a DOM <code>InvalidStateError</code> event and terminate these steps. Otherwise:</li>
 				<li>Set <code>state</code> to 'recording' and wait until media
 					
 					becomes available from <code>stream</code>.</li>
@@ -217,7 +216,7 @@
 			MediaStream is muted at any time (i.e., if its <code>readyState</code> is set to <code>muted</code>), the UA
 			<em title="must" class="rfc2119">must</em> insert black frames or silence until the Track is unmuted. If the UA is 
 			unable to start recording or at any point is unable to contine recording, it <em title="must" class="rfc2119">must</em> raise 
-			a <code>DOMError</code> event, follwowed by a <code>dataavailable</code> event containing
+			a <code>DOMError</code> event, followed by a <code>dataavailable</code> event containing
 			the Blob it has gathered, follwed by the <code>stoprecording</code> event.    
 		</p>
 		<dl class='parameters'>
@@ -231,10 +230,11 @@
     <dt>void stop()</dt>
     
     <dd>When a <code>MediaRecorder</code> object’s <code>stop</code> method is invoked,
-          then if <code>state</code> is "inactive", the user agent MUST
-          raise an INVALID_STATE exception and return immediately.  Otherwise it MUST 
+          the UA <em title="must" class="rfc2119">must</em> 
           queue a task, using the DOM manipulation task source, that runs the following steps:
-		<ol>	
+		<ol>
+			<li>If <code>state</code> is "inactive", raise a DOM <code>InvalideStateError</code>event and terminate these steps.
+          Otherwise:</li>	
 			<li>Set <code>state</code> to 'inactive' and stop gathering data. </li>
 			<li>Raise a <code>dataavailable</code> event containing the Blob of data that has been gathered.</li>
 			<li>Raise a <code>done</code> event</li>		
@@ -242,11 +242,12 @@
 			</dd>
 			<dt>void pause()</dt>
 			<dd>When a <code>MediaRecorder</code> object’s <code>pause()</code>method is invoked,
-	then if <code>state</code> is  "inactive"
-          the user agent <em title="must" class="rfc2119">must</em> raise an INVALID_STATE exception
-          and return immediately.  Otherwise it <em title="must" class="rfc2119">must</em>
+	the UA <em title="must" class="rfc2119">must</em>
           queue a task, using the DOM manipulation task source, that runs the following steps:
 		<ol>
+		<li>If <code>state</code> is  "inactive"
+          raise a DOM 
+          <code>InvalidStateError</code> event and terminate these steps.  Otherwise: </li>
 		<li>Set <code>state</code> to "paused".</li>
 		<li>Stop gathering data into its current Blob (but keep the Blob available so that 
 			recording can be resumed in the future).</li>
@@ -255,11 +256,12 @@
 	</dd>
 	<dt>void resume()</dt>
 	<dd>When a <code>MediaRecorder</code> object’s <code>resume()</code> method is invoked,
-	then if <code>state</code> is  "inactive"
-          the user agent <em title="must" class="rfc2119">must</em> raise an INVALID_STATE exception
-          and return immediately.  Otherwise it <em title="must" class="rfc2119">must</em>
+	the UA <em title="must" class="rfc2119">must</em>
           queue a task, using the DOM manipulation task source, that runs the following steps:
 		<ol>
+			<li>If <code>state</code> is  "inactive"
+          raise a DOM <code>InvalidStateError</code>
+          event and terminate these steps.  Otherwise: </li>
 		<li>Set <code>state</code> to "recording".</li>
 		<li>Resume (or continue) gathering data into its current Blob.</li>
 		<li>Raise a <code>resume</code> event.</li>
@@ -268,11 +270,13 @@
    	<dt>void requestData()</dt>
    	<dd>
    	When a <code>MediaRecorder</code>object’s <code>requestData()</code> method is invoked,
-	then if <code>state</code> is not "recording"
-          the user agent <em title="must" class="rfc2119">must</em> raise an INVALID_STATE exception
-          and return immediately.  Otherwise it <em title="must" class="rfc2119">must</em>
+	the UA <em title="must" class="rfc2119">must</em>
           queue a task, using the DOM manipulation task source, that runs the following steps:
 		<ol>
+			<li>If <code>state</code> is not "recording"
+         raise a DOM
+          <code>InvalidStateError</code> event and terminate these steps.
+          Otherwise:</li>
 		<li>Raise a <code>dataavailable</code> event containing the current Blob of saved data.</li>
 		<li>Create a new Blob and gather subsequent data into it.</li>
 	</ol>	
@@ -290,11 +294,13 @@
 <dd>
 	When a 
 			<code>MediaRecorder</code> object’s <code>setOptions()</code> method is invoked,
-				then if <code>state</code> is not
-					"inactive", the user agent <em title="must" class="rfc2119">must</em> raise an INVALID_STATE
-					exception and return immediately.  Otherwise it <em title="must" class="rfc2119">must</em>
+				the UA <em title="must" class="rfc2119">must</em>
 					run the following steps before returning:
 		<ol>
+			<li>If <code>state</code> is not
+					"inactive", raise a DOM
+					<code>InvalidStateError</code> event and terminate these steps.
+					Otherwise:</li>
 				<li>Let <em>currentOptions</em> be the current set of options that are specified
 					to be used for recording by the MediaRecorder.  (If setOptions() has not yet been called, these will
 					be the UA's defaults.)</li>
@@ -341,7 +347,7 @@
 	<dl title='[Constructor] interface BlobEvent : Event' class='idl'>
   <dt>readonly attribute Blob data</dt>
   <dd>
-    Returns a Blob object whose type attribute indicates the encoding of the blob data. An implementation must return a Blob in a format that is capable of being viewed in an HTML <code>&lt;img&gt;</code> tag. .
+    Returns a Blob object whose type attribute indicates the encoding of the blob data. 
   </dd>
 </dl>
 
@@ -360,7 +366,10 @@
 	<dl title='dictionary AvailableSettings' class='idl'>
           <dt>CapabilityList MimeType</dt>
           <dd>
-            A list of the MIME types that can be selected as encodings for recording.
+            A list of the MIME types that can be selected as encodings for recording.  The UA
+            <em title="should" class="rfc2119">should</em> be able to play back any of the MIME types it supports for recording.  
+            For example, it <em title="should" class="rfc2119">should</em> be able to display a video
+            recording in the HTML <code>&lt;img&gt;</code> tag. 
           </dd>
           <dt>CapabilityRange imageWidth</dt>
           <dd>The maximum and minimum width, in pixels, for the capture of video or photo
@@ -392,25 +401,11 @@
 
         <p>Errors are indicated in two ways: exceptions and objects passed to
         error callbacks. In the former case, a <a href="http://www.w3.org/TR/2012/WD-dom-20121206/#exception-domexception">DOMException</a> is raised (see [[!DOM4]]).
-        An exception <em title="must" class="rfc2119">must</em> be thrown in the
-        following cases:</p>
-
-        <ul>
-          <li>The type of any argument passed to a function did not match what
-          was expected. An appropriate name from the
-          <code>RecordingExceptionName</code> enum <em title="must" class="rfc2119">must</em> be used as the error
-          name.</li>
-
-          <li>A function call was made when the Recorder is in an
-          invalid state, or a state in which that particular function is not
-          allowed to be executed. In this case, the name
-          <code>INVALID_STATE</code> <em title="must" class="rfc2119">must</em> be used as the error name.</li>
-        </ul>
-
-        <p>In all other cases, an <a href="http://www.w3.org/TR/2012/WD-dom-20121206/#interface-domerror">DOMError</a> object(see [[!DOM4]]) <em title="must" class="rfc2119">must</em> be provided to the failure
+        An exception <em title="must" class="rfc2119">must</em> be thrown when the
+        error can be detected at the time that the call is made. In all other cases, an <a href="http://www.w3.org/TR/2012/WD-dom-20121206/#interface-domerror">DOMError</a> object(see [[!DOM4]]) <em title="must" class="rfc2119">must</em> be provided to the failure
         callback. The error name in the object provided <em title="must" class="rfc2119">must</em> be picked from
          the <code>RecordingErrorName</code>
-        enums.  After raising the error, the UA <em title="must" class="rfc2119">must</em>
+        enums.  If recording has been started and not yet stopped when the error occurs, then after raising the error, the UA <em title="must" class="rfc2119">must</em>
    	raise a  dataavailable event, containing any data that it has gathered,
    	and then a recordingdone event. The UA  <em title="may" class="rfc2119">may</em> set platform-specific
    	limits, such those for the minimum and maximum Blob size that it will support, or the number of 
@@ -492,14 +487,6 @@
           	event contains a Blob of recorded data.</td>
         </tr>
         
-         <tr>
-          <td><dfn id="event-mediarecorder-photo"><code>photo</code></dfn></td>
-
-          <td><a href="#idl-def-BlobEvent"><code>BlobEvent</code></a></td>
-
-          <td>The UA uses this event to return a  photo to the application (as a Blob).  The 'data' attribute of this 
-          	event contains a Blob of recorded snapshot data.</td>
-        </tr>
         
         <tr>
           <td><dfn id="event-mediarecorder-pause"><code>pause</code></dfn></td>
@@ -541,7 +528,7 @@
   </section>
 
   	
- <section class="appendix" id="openissues"><!--OddPage--><h2><span class="secno">A. </span>Open Issues</h2>
+ <section class="appendix" id="openissues"><!--OddPage--><h2>Open Issues</h2>
  	<ol>
  		<li>Do we need an MTI
         	format?</li>