[EME] Updated setMediaKeys hints non-normative text for bug 19156
authorAdrian Bateman <adrianba@microsoft.com>
Thu, 14 Nov 2013 15:48:48 +0800
changeset 206 cda7de85614f
parent 205 83c54e4deffe
child 207 2719b617426e
[EME] Updated setMediaKeys hints non-normative text for bug 19156
encrypted-media/encrypted-media.html
encrypted-media/encrypted-media.xml
--- a/encrypted-media/encrypted-media.html	Thu Nov 14 12:21:37 2013 +0800
+++ b/encrypted-media/encrypted-media.html	Thu Nov 14 15:48:48 2013 +0800
@@ -289,14 +289,11 @@
     <p>The <dfn id="dom-setmediakeys"><code>setMediaKeys</code></dfn> method provides the <code><a href="#dom-mediakeys">MediaKeys</a></code> to use. When calling this method, the media element must run the following steps:</p>
     
     <ol>
-      <li>
-<p>If loading has not started, throw an <code><a href="https://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#dom-domexception-invalid_state_err">INVALID_STATE_ERR</a></code> exception and abort these steps.</p>
-      <p class="non-normative">In general, applications should wait for an event named <code><a href="#dom-needkey">needkey</a></code> or <code><a href="http://www.w3.org/TR/html5/embedded-content-0.html#event-media-loadstart">loadstart</a></code> (per the <a href="http://www.w3.org/TR/html5/embedded-content-0.html#concept-media-load-resource">resource fetch algorithm</a>) before calling this method.</p>
-      </li>
       <li><p>If the <code><a href="#dom-mediakeys">MediaKeys</a></code> object is already in use and the user agent is unable to re-use it with this element, throw a <code><a href="https://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#dom-domexception-quota_exceeded_err">QUOTA_EXCEEDED_ERR</a></code> exception and abort these steps.</p></li>
       <li>Set the <code><a href="#dom-keys">keys</a></code> attribute of the media element to <var>mediaKeys</var>.</li>
     </ol>
     
+    <p class="non-normative">Note: as a best practice, applications should create a MediaKeys object and call setMediaKeys before providing media data (for example, setting the src attribute of the media element). This avoids potential delays in some implementations.</p>
     <p class="non-normative">Note: In some implementations, <code><a href="#dom-mediakeysession">MediaKeySession</a></code> objects created by <code><a href="#dom-createsession">createSession()</a></code> may not fire any events until the <code><a href="#dom-mediakeys">MediaKeys</a></code> object is associated with a media element with <code><a href="#dom-setmediakeys">setMediaKeys()</a></code>.</p>
 
     <p>The <dfn id="dom-onneedkey"><code>onneedkey</code></dfn> event handler for the <code><a href="#dom-needkey">needkey</a></code> event must be supported by all HTMLMediaElements as both a content attribute and an IDL attribute.</p>
--- a/encrypted-media/encrypted-media.xml	Thu Nov 14 12:21:37 2013 +0800
+++ b/encrypted-media/encrypted-media.xml	Thu Nov 14 15:48:48 2013 +0800
@@ -286,13 +286,11 @@
     <p>The <methoddfn name="setMediaKeys">setMediaKeys</methoddfn> method provides the <coderef>MediaKeys</coderef> to use. When calling this method, the media element must run the following steps:</p>
     
     <ol>
-      <li><p>If loading has not started, throw an <invalid-state-err/> exception and abort these steps.</p>
-      <p class="non-normative">In general, applications should wait for an event named <coderef>needkey</coderef> or <videoref name="event-media-loadstart">loadstart</videoref> (per the <resource-fetch-algorithm/>) before calling this method.</p>
-      </li>
       <li><p>If the <coderef>MediaKeys</coderef> object is already in use and the user agent is unable to re-use it with this element, throw a <quota-exceeded-err/> exception and abort these steps.</p></li>
       <li>Set the <coderef>keys</coderef> attribute of the media element to <var>mediaKeys</var>.</li>
     </ol>
     
+    <p class="non-normative">Note: as a best practice, applications should create a MediaKeys object and call setMediaKeys before providing media data (for example, setting the src attribute of the media element). This avoids potential delays in some implementations.</p>
     <p class="non-normative">Note: In some implementations, <coderef>MediaKeySession</coderef> objects created by <methodref>createSession</methodref> may not fire any events until the <coderef>MediaKeys</coderef> object is associated with a media element with <methodref>setMediaKeys</methodref>.</p>
 
     <p>The <codedfn>onneedkey</codedfn> event handler for the <coderef>needkey</coderef> event must be supported by all HTMLMediaElements as both a content attribute and an IDL attribute.</p>