[EME] Bug 23955 - Add optional MediaKeys.loadSession(DOMString sessionId) method
--- a/encrypted-media/encrypted-media.html Thu Dec 26 21:07:12 2013 -0800
+++ b/encrypted-media/encrypted-media.html Tue Jan 07 07:44:21 2014 -0800
@@ -56,7 +56,7 @@
<div class="head">
<p><a href="http://www.w3.org/"><img src="https://www.w3.org/Icons/w3c_home" alt="W3C" width="72" height="48"></a></p>
<h1>Encrypted Media Extensions</h1>
- <h2 id="draft-date">W3C Editor's Draft 17 December 2013</h2>
+ <h2 id="draft-date">W3C Editor's Draft 7 January 2014</h2>
<dl>
<dt>This Version:</dt>
<dd><a href="http://dvcs.w3.org/hg/html-media/raw-file/default/encrypted-media/encrypted-media.html">http://dvcs.w3.org/hg/html-media/raw-file/default/encrypted-media/encrypted-media.html</a></dd>
@@ -265,6 +265,7 @@
readonly attribute DOMString <a href="#dom-keysystem">keySystem</a>;
<a href="#dom-mediakeysession">MediaKeySession</a> <a href="#dom-createsession">createSession</a>(DOMString type, Uint8Array initData);
+ <a href="#dom-mediakeysession">MediaKeySession</a> <a href="#dom-loadsession">loadSession</a>(DOMString sessionId);
static bool <a href="#dom-istypesupported">isTypeSupported</a>(DOMstring <a href="#key-system">keySystem</a>, DOMString? type);
};
@@ -436,10 +437,93 @@
</li>
</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 responds to permission requests, etc.
- Applications should expect and handle such delays.</p>
+ <li>
+<p>Return the new object to the caller.</p>
+ <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 responds to permission requests, etc.
+ Applications should expect and handle such delays.</p>
+ </li>
+ </ol>
+
+ <p>The <dfn id="dom-loadsession"><code>loadSession(sessionId)</code></dfn> method must run the following steps:</p>
+ <ol>
+ <li><p>If the <code><a href="#dom-keysystem">keySystem</a></code> does not support loading previous sessions, 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>
+ <li>Create a new <code><a href="#dom-mediakeysession">MediaKeySession</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>
+ <li><p>Let the state of the session be <code><a href="#dom-statecreated">CREATED</a></code>.</p></li>
+ </ol>
+ </li>
+
+ <li><p>Add the new object to an internal list of session objects.</p></li>
+
+ <li>
+<p>Schedule a task to initialize the session, providing <var title="true">sessionId</var> and the new object.</p>
+ <p>The user agent will asynchronously execute the following steps in the task:</p>
+ <ol>
+ <li><p>Wait for the <a href="#dom-media-keys-constructor"><code>MediaKeys</code> constructor</a> task to complete.</p></li>
+ <li><p>
+ If there is a <code><a href="#dom-mediakeyerror">MediaKeyError</a></code> stored with the <code><a href="#dom-mediakeys">MediaKeys</a></code> object that occurred because of an error during the loading the <a href="#dom-media-keys-constructor"><code>MediaKeys</code> constructor</a> task
+ then <a href="http://www.w3.org/TR/html5/webappapis.html#queue-a-task">queue a task</a> to <a href="http://www.w3.org/TR/html5/webappapis.html#fire-a-simple-event">fire a simple event</a> named <code><a href="#dom-eventerror">error</a></code> at the <code><a href="#dom-mediakeysession">MediaKeySession</a></code> object and abort these steps.
+ </p></li>
+ <li><p>Let <var title="true">cdm</var> be the <var title="true">cdm</var> loaded in the <a href="#dom-media-keys-constructor"><code>MediaKeys</code> constructor</a>.</p></li>
+ <li>
+<p>Use <var title="true">cdm</var> to execute the following steps:</p>
+ <ol>
+ <li><p>Initialize the session with stored data for the <var title="true">sessionId</var>.</p></li>
+ <li>
+<p>If a message exchange <span class="non-normative">(e.g. a license request)</span> is required:</p>
+ <ol>
+ <li><p>Let <var title="true">request</var> be a request generated by the <a href="#cdm">CDM</a> using <var title="true">sessionId</var>.</p></li>
+ <li><p>If the stored data for <var title="true">sessionId</var> indicates a default URL relevant to <var title="true">keySystem</var>, let <var title="true">defaultURL</var> be that URL.</p></li>
+ </ol>
+ </li>
+ </ol>
+ </li>
+ <li><p>Set the <code><a href="#dom-sessionid">sessionId</a></code> attribute to <var title="true">sessionId</var></p></li>
+ <li>
+<p>If any of the preceding steps in the task failed, run the following steps:</p>
+ <ol>
+ <li>
+<p>Create a new <code><a href="#dom-mediakeyerror">MediaKeyError</a></code> object with the following attributes:</p>
+ <ul style="list-style-type:none"><li>
+ <code><a href="#dom-code">code</a></code> = the appropriate <code><a href="#dom-mediakeyerror">MediaKeyError</a></code> code<br>
+ <code><a href="#dom-systemcode">systemCode</a></code> = a Key System-specific value, if provided, and 0 otherwise
+ </li></ul>
+ </li>
+ <li><p>Set the <code><a href="#dom-mediakeysession">MediaKeySession</a></code> object's <code><a href="#dom-error">error</a></code> attribute to the error object created in the previous step.</p></li>
+ <li><p>Let the state of the session be <code><a href="#dom-stateerror">ERROR</a></code>.</p></li>
+ <li><p><a href="http://www.w3.org/TR/html5/webappapis.html#queue-a-task">queue a task</a> to <a href="http://www.w3.org/TR/html5/webappapis.html#fire-a-simple-event">fire a simple event</a> named <code><a href="#dom-eventerror">error</a></code> at the <code><a href="#dom-mediakeysession">MediaKeySession</a></code> object.</p></li>
+ <li><p>Abort the task.</p></li>
+ </ol>
+ </li>
+ <li>
+ <p>If the associated <a href="#media-element">media element(s)</a> are <a href="#waiting-for-a-key">waiting for a key</a>, <a href="http://www.w3.org/TR/html5/webappapis.html#queue-a-task">queue a task</a> to attempt to resume playback.</p>
+ <p class="non-normative">In other words, resume playback if the necessary key is provided.</p>
+ <p>The user agent may choose to skip this step if it knows resuming will fail <span class="non-normative">(i.e. no usable key was added)</span>.</p>
+ </li>
+ <li>
+<p>Follow the steps for the first matching condition from the following list:</p>
+ <dl class="switch">
+ <dt>If <var title="true">request</var> is not null</dt>
+ <dd>
+ <p>Run the <a href="algorithm-queue-message">Queue a "message" event</a> algorithm with the <var title="true">request</var>
+ and <var title="true">defaultURL</var>.</p>
+ </dd>
+ <dt>Otherwise</dt>
+ <dd>
+ <ol>
+ <li><p>Let the state of the session be <code><a href="#dom-stateready">READY</a></code>.</p></li>
+ <li>
+ <p><a href="http://www.w3.org/TR/html5/webappapis.html#queue-a-task">queue a task</a> to <a href="http://www.w3.org/TR/html5/webappapis.html#fire-a-simple-event">fire a simple event</a> named <code><a href="#dom-eventready">ready</a></code> at the new object.</p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </li>
+ </ol>
+ </li>
+ <li><p>Return the new object to the caller.</p></li>
</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>
--- a/encrypted-media/encrypted-media.xml Thu Dec 26 21:07:12 2013 -0800
+++ b/encrypted-media/encrypted-media.xml Tue Jan 07 07:44:21 2014 -0800
@@ -55,7 +55,7 @@
<div class="head">
<p><a href="http://www.w3.org/"><img src="https://www.w3.org/Icons/w3c_home" alt="W3C" width="72" height="48" /></a></p>
<h1>Encrypted Media Extensions</h1>
- <h2 id="draft-date">W3C Editor's Draft 17 December 2013</h2>
+ <h2 id="draft-date">W3C Editor's Draft 7 January 2014</h2>
<dl>
<dt>This Version:</dt>
<dd><a href="http://dvcs.w3.org/hg/html-media/raw-file/default/encrypted-media/encrypted-media.html">http://dvcs.w3.org/hg/html-media/raw-file/default/encrypted-media/encrypted-media.html</a></dd>
@@ -262,6 +262,7 @@
readonly attribute DOMString <precoderef>keySystem</precoderef>;
<precoderef>MediaKeySession</precoderef> <premethodref>createSession</premethodref>(DOMString type, Uint8Array initData);
+ <precoderef>MediaKeySession</precoderef> <premethodref>loadSession</premethodref>(DOMString sessionId);
static bool <premethodref>isTypeSupported</premethodref>(DOMstring <a href="#key-system">keySystem</a>, DOMString? type);
};
@@ -424,10 +425,86 @@
</li>
</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 responds to permission requests, etc.
- Applications should expect and handle such delays.</p>
+ <li><p>Return the new object to the caller.</p>
+ <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 responds to permission requests, etc.
+ Applications should expect and handle such delays.</p>
+ </li>
+ </ol>
+
+ <p>The <methoddfn name="loadSession">loadSession(<var title="true">sessionId</var>)</methoddfn> method must run the following steps:</p>
+ <ol>
+ <li><p>If the <coderef>keySystem</coderef> does not support loading previous sessions, throw a <not-supported-err/> exception and abort these steps.</p></li>
+ <li>Create a new <coderef>MediaKeySession</coderef> object.
+ <ol>
+ <li><p>Let the <coderef>keySystem</coderef> attribute be <var title="true">keySystem</var>.</p></li>
+ <li><p>Let the state of the session be <coderef prefix="state">CREATED</coderef>.</p></li>
+ </ol>
+ </li>
+
+ <li><p>Add the new object to an internal list of session objects.</p></li>
+
+ <li><p>Schedule a task to initialize the session, providing <var title="true">sessionId</var> and the new object.</p>
+ <p>The user agent will asynchronously execute the following steps in the task:</p>
+ <ol>
+ <li><p>Wait for the <a href="#dom-media-keys-constructor"><code>MediaKeys</code> constructor</a> task to complete.</p></li>
+ <li><p>
+ If there is a <coderef>MediaKeyError</coderef> stored with the <coderef>MediaKeys</coderef> object that occurred because of an error during the loading the <a href="#dom-media-keys-constructor"><code>MediaKeys</code> constructor</a> task
+ then <queue-a-task/> to <fire-a-simple-event/> named <coderef prefix="event">error</coderef> at the <coderef>MediaKeySession</coderef> object and abort these steps.
+ </p></li>
+ <li><p>Let <var title="true">cdm</var> be the <var title="true">cdm</var> loaded in the <a href="#dom-media-keys-constructor"><code>MediaKeys</code> constructor</a>.</p></li>
+ <li><p>Use <var title="true">cdm</var> to execute the following steps:</p>
+ <ol>
+ <li><p>Initialize the session with stored data for the <var title="true">sessionId</var>.</p></li>
+ <li><p>If a message exchange <span class="non-normative">(e.g. a license request)</span> is required:</p>
+ <ol>
+ <li><p>Let <var title="true">request</var> be a request generated by the <a href="#cdm">CDM</a> using <var title="true">sessionId</var>.</p></li>
+ <li><p>If the stored data for <var title="true">sessionId</var> indicates a default URL relevant to <var title="true">keySystem</var>, let <var title="true">defaultURL</var> be that URL.</p></li>
+ </ol>
+ </li>
+ </ol>
+ </li>
+ <li><p>Set the <coderef>sessionId</coderef> attribute to <var title="true">sessionId</var></p></li>
+ <li><p>If any of the preceding steps in the task failed, run the following steps:</p>
+ <ol>
+ <li><p>Create a new <coderef>MediaKeyError</coderef> object with the following attributes:</p>
+ <ul style="list-style-type:none"><li>
+ <coderef>code</coderef> = the appropriate <coderef>MediaKeyError</coderef> code<br></br>
+ <coderef>systemCode</coderef> = a Key System-specific value, if provided, and 0 otherwise
+ </li></ul>
+ </li>
+ <li><p>Set the <coderef>MediaKeySession</coderef> object's <coderef>error</coderef> attribute to the error object created in the previous step.</p></li>
+ <li><p>Let the state of the session be <coderef prefix="state">ERROR</coderef>.</p></li>
+ <li><p><queue-a-task/> to <fire-a-simple-event/> named <coderef prefix="event">error</coderef> at the <coderef>MediaKeySession</coderef> object.</p></li>
+ <li><p>Abort the task.</p></li>
+ </ol>
+ </li>
+ <li>
+ <p>If the associated <a href="#media-element">media element(s)</a> are <a href="#waiting-for-a-key">waiting for a key</a>, <queue-a-task/> to attempt to resume playback.</p>
+ <p class="non-normative">In other words, resume playback if the necessary key is provided.</p>
+ <p>The user agent may choose to skip this step if it knows resuming will fail <span class="non-normative">(i.e. no usable key was added)</span>.</p>
+ </li>
+ <li><p>Follow the steps for the first matching condition from the following list:</p>
+ <dl class="switch">
+ <dt>If <var title="true">request</var> is not null</dt>
+ <dd>
+ <p>Run the <a href="algorithm-queue-message">Queue a "message" event</a> algorithm with the <var title="true">request</var>
+ and <var title="true">defaultURL</var>.</p>
+ </dd>
+ <dt>Otherwise</dt>
+ <dd>
+ <ol>
+ <li><p>Let the state of the session be <coderef prefix="state">READY</coderef>.</p></li>
+ <li>
+ <p><queue-a-task/> to <fire-a-simple-event/> named <coderef prefix="event">ready</coderef> at the new object.</p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+ </li>
+ </ol>
+ </li>
+ <li><p>Return the new object to the caller.</p></li>
</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>