[EME] Improvements related to Bug 19096 - Add 'type' attribute to MediaKeyNeededEvent
authorDavid Dorwin <ddorwin@google.com>
Thu, 31 Oct 2013 14:59:50 -0700
changeset 188 5a818f7084c3
parent 187 aab3a46a5c9f
child 189 c76b35842338
[EME] Improvements related to Bug 19096 - Add 'type' attribute to MediaKeyNeededEvent

* Set the 'type' attribute when firing the event.
* Added 'type' to MediaKeyNeededEventInit.
* Added clarity on the presence of "audio/" and "video/" in the type attribute and parameter.
encrypted-media/encrypted-media.html
encrypted-media/encrypted-media.xml
--- a/encrypted-media/encrypted-media.html	Thu Oct 31 14:27:17 2013 -0700
+++ b/encrypted-media/encrypted-media.html	Thu Oct 31 14:59:50 2013 -0700
@@ -346,7 +346,13 @@
     <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>
-    <p class="non-normative">Note: The contents of <var title="true">initData</var> are container-specific <a href="#initialization-data">Initialization Data</a>.</p>
+    <p class="non-normative">Note: The contents of <var title="true">initData</var> are container-specific <a href="#initialization-data">Initialization Data</a>.
+    <var title="true">type</var> specifies the container type and thus how to interpret <var title="true">initData</var>. 
+    </p>
+    <p class="non-normative">Note: MIME types usually include "audio/" or "video/", and these should be included in <var title="true">type</var> as appropriate.
+    However, user agents and <a href="#cdm">CDMs</a> should not treat sessions created with "audio/" differently than those created with "video/".
+    That is, there is no such thing as an "audio session" or a "video session" - all sessions are used for all media streams processed by <var title="true">cdm</var>.
+    </p>
 
     <ol>
       <li><p>If <var title="true">type</var> contains a MIME type that is not supported or is not supported by the <code><a href="#dom-keysystem">keySystem</a></code>, 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> exception and abort these steps.</p></li>
@@ -378,7 +384,7 @@
             <ol>
               <li>
 <p>Process <var title="true">type</var> and <var title="true">initData</var>.</p>
-              <p class="non-normative">Note: <var title="true">type</var> may be used to determine how to interpret <var title="true">initData</var>.</p>
+              <p class="non-normative">Note: <var title="true">type</var> should be used to determine how to interpret <var title="true">initData</var>.</p>
               </li>
               <li>
 <p>If a message exchange <span class="non-normative">(e.g. a license request)</span> is required:</p>
@@ -708,6 +714,7 @@
 };
 
 dictionary <dfn id="dom-mediakeyneededeventinit">MediaKeyNeededEventInit</dfn> : <a href="https://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#eventinit">EventInit</a> {
+  DOMString <a href="#dom-type">type</a>;
   Uint8Array? <a href="#dom-initdata">initData</a>;
 };</pre>
 
@@ -751,6 +758,10 @@
     </dl>
     <div class="impl">
     <p>The <dfn id="dom-type"><code>type</code></dfn> attribute contains the MIME type of the <a href="http://www.w3.org/TR/html5/embedded-content-0.html#media-data">media data</a> specific to the event. The format of the <code><a href="#dom-initdata">initData</a></code> will depend on the <code><a href="#dom-type">type</a></code>.</p>
+    <p class="non-normative">Note: MIME types usually include "audio/" or "video/", and user agents should include these in <var title="true">type</var> as appropriate.
+    However, either variant may be returned for any stream of a given MIME type, and this is does not reflect the type(s) of stream(s) in the <a href="http://www.w3.org/TR/html5/embedded-content-0.html#media-data">media data</a>.
+    Applications processing this attribute should handle all such variants.
+    </p>
     <p>The <dfn id="dom-initdata"><code>initData</code></dfn> attribute contains <a href="#initialization-data">Initialization Data</a> specific to the event.</p>
     <p>The <dfn id="dom-message"><code>message</code></dfn> attribute contains a message from the CDM. Messages are Key System-specific. <span class="non-normative">In most cases, it should be sent to a key server.</span></p>
     <p>The <dfn id="dom-destinationurl"><code>destinationURL</code></dfn> is the URL to send the <code><a href="#dom-message">message</a></code> to.
@@ -891,6 +902,7 @@
         </dl>
         <p>The event is of type <code><a href="#dom-mediakeyneededevent">MediaKeyNeededEvent</a></code> and has:</p>
         <ul style="list-style-type:none"><li>
+          <code><a href="#dom-type">type</a></code> = the MIME type of the <a href="http://www.w3.org/TR/html5/embedded-content-0.html#media-data">media data</a> container format
           <code><a href="#dom-initdata">initData</a></code> = <var title="">initData</var>
         </li></ul>
         <p class="non-normative">Firing this event allows the application to begin acquiring the key process before it is needed.</p>
--- a/encrypted-media/encrypted-media.xml	Thu Oct 31 14:27:17 2013 -0700
+++ b/encrypted-media/encrypted-media.xml	Thu Oct 31 14:59:50 2013 -0700
@@ -341,7 +341,13 @@
     <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>
-    <p class="non-normative">Note: The contents of <var title="true">initData</var> are container-specific <a href="#initialization-data">Initialization Data</a>.</p>
+    <p class="non-normative">Note: The contents of <var title="true">initData</var> are container-specific <a href="#initialization-data">Initialization Data</a>.
+    <var title="true">type</var> specifies the container type and thus how to interpret <var title="true">initData</var>. 
+    </p>
+    <p class="non-normative">Note: MIME types usually include "audio/" or "video/", and these should be included in <var title="true">type</var> as appropriate.
+    However, user agents and <a href="#cdm">CDMs</a> should not treat sessions created with "audio/" differently than those created with "video/".
+    That is, there is no such thing as an "audio session" or a "video session" - all sessions are used for all media streams processed by <var title="true">cdm</var>.
+    </p>
 
     <ol>
       <li><p>If <var title="true">type</var> contains a MIME type that is not supported or is not supported by the <coderef>keySystem</coderef>, throw a <not-supported-err/> exception and abort these steps.</p></li>
@@ -370,7 +376,7 @@
           <li><p>Use <var title="true">cdm</var> to execute the following steps:</p>
             <ol>
               <li><p>Process <var title="true">type</var> and <var title="true">initData</var>.</p>
-              <p class="non-normative">Note: <var title="true">type</var> may be used to determine how to interpret <var title="true">initData</var>.</p>
+              <p class="non-normative">Note: <var title="true">type</var> should be used to determine how to interpret <var title="true">initData</var>.</p>
               </li>
               <li><p>If a message exchange <span class="non-normative">(e.g. a license request)</span> is required:</p>
                 <ol>
@@ -672,6 +678,7 @@
 };
 
 dictionary <precodedfn>MediaKeyNeededEventInit</precodedfn> : <dom4ref name="eventinit">EventInit</dom4ref> {
+  DOMString <precoderef>type</precoderef>;
   Uint8Array? <precoderef>initData</precoderef>;
 };</pre>
 
@@ -707,6 +714,10 @@
     </dl>
     <div class="impl">
     <p>The <codedfn>type</codedfn> attribute contains the MIME type of the <videoanchor name="media-data">media data</videoanchor> specific to the event. The format of the <coderef>initData</coderef> will depend on the <coderef>type</coderef>.</p>
+    <p class="non-normative">Note: MIME types usually include "audio/" or "video/", and user agents should include these in <var title="true">type</var> as appropriate.
+    However, either variant may be returned for any stream of a given MIME type, and this is does not reflect the type(s) of stream(s) in the <videoanchor name="media-data">media data</videoanchor>.
+    Applications processing this attribute should handle all such variants.
+    </p>
     <p>The <codedfn>initData</codedfn> attribute contains <a href="#initialization-data">Initialization Data</a> specific to the event.</p>
     <p>The <codedfn>message</codedfn> attribute contains a message from the CDM. Messages are Key System-specific. <span class="non-normative">In most cases, it should be sent to a key server.</span></p>
     <p>The <codedfn>destinationURL</codedfn> is the URL to send the <coderef>message</coderef> to.
@@ -839,6 +850,7 @@
         </dl>
         <p>The event is of type <coderef>MediaKeyNeededEvent</coderef> and has:</p>
         <ul style="list-style-type:none"><li>
+          <coderef>type</coderef> = the MIME type of the <videoanchor name="media-data">media data</videoanchor> container format
           <coderef>initData</coderef> = <var title="">initData</var>
         </li></ul>
         <p class="non-normative">Firing this event allows the application to begin acquiring the key process before it is needed.</p>