[EME] Add note about potential delay in firing initial event.
authorDavid Dorwin <ddorwin@google.com>
Tue, 05 Nov 2013 12:58:26 -0800
changeset 192 c6e105c755b9
parent 191 84be32b27d5d
child 193 cf1786f8f616
[EME] Add note about potential delay in firing initial event.

Also correct object destruction text.
encrypted-media/encrypted-media.html
encrypted-media/encrypted-media.xml
--- a/encrypted-media/encrypted-media.html	Mon Nov 04 17:41:16 2013 -0800
+++ b/encrypted-media/encrypted-media.html	Tue Nov 05 12:58:26 2013 -0800
@@ -305,11 +305,7 @@
 
     <ol>
       <li><p>If <var title="true">keySystem</var> is null or an empty string, throw an <code><a href="https://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#dom-domexception-invalid_access_err">INVALID_ACCESS_ERR</a></code> exception and abort these steps.</p></li>
-
       <li><p>If <var title="true">keySystem</var> is not one of the user agent's supported <a href="#key-system">Key Systems</a>, throw a <code><a href="https://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#dom-domexception-not_supported_err">NOT_SUPPORTED_ERR</a></code> and abort these steps. Key system string comparison is case-sensitive.</p></li>
-
-      <li><p>Let <var title="true">cdm</var> be the <a href="#cdm">content decryption module</a> corresponding to <var title="true">keySystem</var>.</p></li>
-            
       <li>Create a new <code><a href="#dom-mediakeys">MediaKeys</a></code> object.
         <ol>
           <li><p>Let the <code><a href="#dom-keysystem">keySystem</a></code> attribute be <var title="true">keySystem</var>.</p></li>
@@ -319,6 +315,7 @@
       <li>
         <p>The user agent will asynchronously execute the following steps:</p>
         <ol>
+          <li><p>Let <var title="true">cdm</var> be the <a href="#cdm">content decryption module</a> corresponding to <var title="true">keySystem</var>.</p></li>
           <li><p>Load <var title="true">cdm</var> if necessary.</p></li>
           <li>
             <dl class="switch">
@@ -341,8 +338,6 @@
       <li>Return the new <code><a href="#dom-mediakeys">MediaKeys</a></code> object to the caller.</li>
     </ol>
 
-    <p>When destroying a <code><a href="#dom-mediakeys">MediaKeys</a></code> object, follow the steps in <code><a href="#dom-close">close()</a></code>.</p>
-    
     <p>The <dfn id="dom-keysystem"><code>keySystem</code></dfn> attribute is an identifier for the <a href="#key-system">Key System</a> being used.</p>
 
     <p>The <dfn id="dom-createsession"><code>createSession(type, initData)</code></dfn> method must run the following steps:</p>
@@ -445,6 +440,9 @@
         </ol>
       </li>
       <li>Return the new object to the caller.</li>
+      <p class="non-normative">Note: User agents should always fire an event at the returned object in response to this call.
+      For some implementations, it is possible - especially the first time a <a href="#key-system">Key System</a> is used - that the first event will be delayed significantly while the client is initialized, the user responsds to permission requests, etc.
+      Applications should expect and handle such delays.</p> 
     </ol>
 
     <p>The <dfn id="dom-istypesupported"><code>isTypeSupported(keySystem, type)</code></dfn> method returns whether <var title="true">keySystem</var> is supported with the specified container and codec <var title="true">type</var>(s).</p>
@@ -578,6 +576,8 @@
       <li><p>⌛ If <var title="">candidate</var> has a <code><a href="#dom-sourcekeysystem">keySystem</a></code> attribute whose value represents a <a href="#key-system">Key System</a> that the user agent knows it cannot use with <code><a href="http://www.w3.org/TR/html5/embedded-content-0.html#attr-source-type">type</a></code>, then end the <a href="http://www.w3.org/TR/html5/webappapis.html#synchronous-section">synchronous section</a>, and jump down to the <i title="">failed</i> step below.</p></li>
     </ol>
 
+    <p>When destroying a <code><a href="#dom-mediakeysession">MediaKeySession</a></code> object, follow the steps in <code><a href="#dom-close">close()</a></code>.</p>
+
     <h3 id="error-codes">2.1. Error Codes</h3>
     <div class="issue">
 <div class="issue-title"><span>Issue 1</span></div>
--- a/encrypted-media/encrypted-media.xml	Mon Nov 04 17:41:16 2013 -0800
+++ b/encrypted-media/encrypted-media.xml	Tue Nov 05 12:58:26 2013 -0800
@@ -301,11 +301,7 @@
 
     <ol>
       <li><p>If <var title="true">keySystem</var> is null or an empty string, throw an <invalid-access-err/> exception and abort these steps.</p></li>
-
       <li><p>If <var title="true">keySystem</var> is not one of the user agent's supported <a href="#key-system">Key Systems</a>, throw a <not-supported-err/> and abort these steps. Key system string comparison is case-sensitive.</p></li>
-
-      <li><p>Let <var title="true">cdm</var> be the <a href="#cdm">content decryption module</a> corresponding to <var title="true">keySystem</var>.</p></li>
-            
       <li>Create a new <coderef>MediaKeys</coderef> object.
         <ol>
           <li><p>Let the <coderef>keySystem</coderef> attribute be <var title="true">keySystem</var>.</p></li>
@@ -315,6 +311,7 @@
       <li>
         <p>The user agent will asynchronously execute the following steps:</p>
         <ol>
+          <li><p>Let <var title="true">cdm</var> be the <a href="#cdm">content decryption module</a> corresponding to <var title="true">keySystem</var>.</p></li>
           <li><p>Load <var title="true">cdm</var> if necessary.</p></li>
           <li>
             <dl class="switch">
@@ -336,8 +333,6 @@
       <li>Return the new <coderef>MediaKeys</coderef> object to the caller.</li>
     </ol>
 
-    <p>When destroying a <coderef>MediaKeys</coderef> object, follow the steps in <methodref>close</methodref>.</p>
-    
     <p>The <codedfn>keySystem</codedfn> attribute is an identifier for the <a href="#key-system">Key System</a> being used.</p>
 
     <p>The <methoddfn name="createSession">createSession(<var title="true">type</var>, <var title="true">initData</var>)</methoddfn> method must run the following steps:</p>
@@ -432,6 +427,9 @@
         </ol>
       </li>
       <li>Return the new object to the caller.</li>
+      <p class="non-normative">Note: User agents should always fire an event at the returned object in response to this call.
+      For some implementations, it is possible - especially the first time a <a href="#key-system">Key System</a> is used - that the first event will be delayed significantly while the client is initialized, the user responsds to permission requests, etc.
+      Applications should expect and handle such delays.</p> 
     </ol>
 
     <p>The <methoddfn name="isTypeSupported">isTypeSupported(<var title="true">keySystem</var>, <var title="true">type</var>)</methoddfn> method returns whether <var title="true">keySystem</var> is supported with the specified container and codec <var title="true">type</var>(s).</p>
@@ -557,6 +555,8 @@
       <li><p>&#8987; If <var title="">candidate</var> has a <coderef prefix="source">keySystem</coderef> attribute whose value represents a <a href="#key-system">Key System</a> that the user agent knows it cannot use with <videoref name="attr-source-type">type</videoref>, then end the <synchronous-section/>, and jump down to the <i title="">failed</i> step below.</p></li>
     </ol>
 
+    <p>When destroying a <coderef>MediaKeySession</coderef> object, follow the steps in <methodref>close</methodref>.</p>
+
     <h3 id="error-codes">2.1. Error Codes</h3>
     <div class="issue"><div class="issue-title"><span>Issue 1</span></div><p class=""><a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=21798">Bug 21798</a> - Some errors may change or be removed.</p></div>
     <p><videoref name="mediaerror">MediaError</videoref> is extended, and a new error type is added.</p>