Add PPAPI decryptor interfaces.

ppapi/api/private/ppb_content_decryptor_private.idl

+/* Copyright (c) 2012 The Chromium Authors. All rights reserved.
+ * Use of this source code is governed by a BSD-style license that can be
+ * found in the LICENSE file.
+ */
+
+/**
+ * This file defines the <code>PPB_ContentDecryptor_Private</code>
+ * interface. Note: This is a special interface, only to be used for Content
+ * Decryption Modules (CDM), not normal plugins.

[ddorwin, 2012/08/14 17:39:58]

singular acronym with plural expansion bugs me, but I don't have an easy fix for
this sentence.

[Tom Finegan, 2012/08/14 18:09:32]

Moved down to the comment block above the interface definition so it can be
"Content Decryption Module (CDM)" (in both files).

+ */
+label Chrome {
+  M23 = 0.1
+};
+
+/**
+ * <code>PPB_ContentDecryptor_Private</code> structure contains the function
+ * pointers the browser must implement to support plugins implementing the
+ * <code>PPP_ContentDecryptor_Private</code> interface. This interface provides
+ * browser side support for the CDM for v0.1 of the proposed Encrypted Media
+ * Extensions: http://goo.gl/rbdnR
+ */
+interface PPB_ContentDecryptor_Private {
+  /**
+   * The decryptor requires a key that has not been provided.
+   *
+   * Sent when the decryptor encounters encrypted content, but it does not have
+   * the key required to decrypt the data. The plugin will call this method in
+   * response to a call to the <code>Decrypt()</code> method on the
+   * <code>PPP_ContentDecryptor_Private<code> interface.
+   *
+   * For an internally implemented key system, the browser must provide a key to

[ddorwin, 2012/08/14 17:39:58]

What is "internally implemented key system"?

[Tom Finegan, 2012/08/14 18:09:32]

Internally/externally stuff removed...

+   * the decryptor plugin by calling <code>AddKey()</code> on the

[ddorwin, 2012/08/14 17:39:58]

I would replace these two paragraphs with something that just says:
The browser, likely at the direction of the Web application, should provide a
key using AddKey().

We don't need to explain the whole EME flow here.

[Tom Finegan, 2012/08/14 18:09:32]

Removed EME flow stuff-- spec is still being updated, and the information
doesn't really belong here at this level.

+   * <code>PPP_ContentDecryptor_Private<code> interface.
+   *
+   * For an external key system, the browser must notify the application that
+   * a key is needed by firing a <code>MediaKeyNeededEvent</code> at the
+   * <code>HTMLMediaElement</code>. In response the application must call
+   * <code>addKey()</code> on the <code>HTMLMediaElement</code> which results
+   * in the browser passing the application's key to <code>AddKey()</code> on
+   * the <code>PPP_ContentDecryptor_Private<code> interface.
+   *
+   * @param[in] key_system A <code>PP_Var</code> of type
+   * <code>PP_VARTYPE_STRING</code> containing the name of the key system.
+   *
+   * @param[in] session_id A <code>PP_Var</code> of type
+   * <code>PP_VARTYPE_STRING</code> containing the session ID.
+   *
+   * @param[in] init_data A <code>PP_Var</code> of type
+   * <code>PP_VARTYPE_ARRAYBUFFER</code> containing container-specific
+   * initialization data.
+   */
+  void NeedKey(
+      [in] PP_Instance instance,
+      [in] PP_Var key_system,
+      [in] PP_Var session_id,
+      [in] PP_Var init_data);
+
+  /**
+   * A key has been added as the result of a call to the <code>AddKey()</code>
+   * method on the <code>PPP_ContentDecryptor_Private</code> interface.
+   *
+   * Note: The above describes the most simple case. Depending on the key
+   * system, a series of <code>KeyMessage()</code> calls from the CDM will be
+   * sent to the browser, and then on to the application by firing a
+   * <code>MediaKeyMessageEvent</code> at the <code>HTMLMediaElement</code>.

[ddorwin, 2012/08/14 17:39:58]

Same, I don't think we need to go into the details of the EME calls.

[Tom Finegan, 2012/08/14 18:09:32]

Done.

+   * In response, the application must then provide more data via additional
+   * calls to the <code>addKey()</code> method on the
+   * <code>HTMLMediaElement</code>, which the browser must pass to the CDM via
+   * calls to <code>AddKey()</code> on the
+   * <code>PPP_ContentDecryptor_Private</code> interface.
+   * The CDM must call <code>KeyAdded()</code> when the sequence is completed,
+   * and, for external key systems, the browser must fire a
+   * <code>MediaKeyCompleteEvent</code> at the <code>HTMLMediaElement</code>.
+   *
+   * @param[in] key_system A <code>PP_Var</code> of type
+   * <code>PP_VARTYPE_STRING</code> containing the name of the key system.
+   *
+   * @param[in] session_id A <code>PP_Var</code> of type
+   * <code>PP_VARTYPE_STRING</code> containing the session ID.
+   */
+  void KeyAdded(
+      [in] PP_Instance instance,
+      [in] PP_Var key_system,
+      [in] PP_Var session_id);
+
+  /**
+   * A message or request has been generated for key_system in the CDM, and,
+   * when the key system is external, must be sent to the application.

[ddorwin, 2012/08/14 17:39:58]

Remove ", when the key system is external,"

[Tom Finegan, 2012/08/14 18:09:32]

Done.

+   *
+   * For example, when the browser invokes <code>GenerateKeyRequest()</code>
+   * on the <code>PPP_ContentDecryptor_Private</code> interface, the decryptor

[ddorwin, 2012/08/14 17:39:58]

s/decryptor/plugin/ ?

[Tom Finegan, 2012/08/14 18:09:32]

Done.

+   * must send a key message with the session ID.

[ddorwin, 2012/08/14 17:39:58]

must send a key message containing the key request.

[Tom Finegan, 2012/08/14 18:09:32]

Done.

+   *
+   * Note that <code>KeyMessage()</code> can be used for purposes other than
+   * responses to <code>GenerateKeyRequest()</code> calls. See also the text
+   * in the comment for <code>KeyAdded()</code>, which describes a sequence of
+   * <code>AddKey()</code> and <code>KeyMessage()</code> calls required to
+   * prepare for decryption.
+   *
+   * @param[in] key_system A <code>PP_Var</code> of type
+   * <code>PP_VARTYPE_STRING</code> containing the name of the key system.
+   *
+   * @param[in] session_id A <code>PP_Var</code> of type
+   * <code>PP_VARTYPE_STRING</code> containing the session ID.
+   *
+   * @param[in] resource A <code>PP_Resource</code> corresponding to a
+   * <code>PPB_Buffer_Dev</code> resource that contains the message.
+   *
+   * @param[in] default_url A <code>PP_Var</code> of type
+   * <code>PP_VARTYPE_STRING</code> containing the default URL for the message.
+   */
+  void KeyMessage(
+      [in] PP_Instance instance,
+      [in] PP_Var key_system,
+      [in] PP_Var session_id,
+      [in] PP_Resource message,
+      [in] PP_Var default_url);
+
+  /**
+   * An error occurred in a <code>PPP_ContentDecryptor_Private</code> method,
+   * or within the plugin implementing the interface.
+   *
+   * @param[in] key_system A <code>PP_Var</code> of type
+   * <code>PP_VARTYPE_STRING</code> containing the name of the key system.
+   *
+   * @param[in] session_id A <code>PP_Var</code> of type
+   * <code>PP_VARTYPE_STRING</code> containing the session ID.
+   *
+   * @param[in] media_error A MediaKeyError.
+   *
+   * @param[in] system_error A system error code.
+   */
+  void KeyError(
+      [in] PP_Instance instance,
+      [in] PP_Var key_system,
+      [in] PP_Var session_id,
+      [in] int32_t media_error,
+      [in] int32_t system_code);
+
+  /**
+   * Called after the <code>Decrypt()</code> method on the
+   * <code>PPP_ContentDecryptor_Private</code> interface completes to
+   * deliver decrypted_block to the browser for decoding and rendering.
+   *
+   * @param[in] decrypted_block A <code>PP_Resource</code> corresponding to a
+   * <code>PPB_Buffer_Dev</code> resource that contains a decrypted data
+   * block.
+   *
+   * @param[in] request_id A unique value the browser can use to associate
+   * decrypted_block with a decrypt call.
+   */
+  void DeliverBlock(
+      [in] PP_Instance instance,
+      [in] PP_Resource decrypted_block,
+      [in] int32_t request_id);
+
+  /**
+   * Called after the <code>DecryptAndDecode()</code> method on the
+   * <code>PPP_ContentDecryptor_Private</code> interface completes to deliver
+   * a decrypted and decoded video frame to the browser for rendering.
+   *
+   * @param[in] decrypted_frame A <code>PP_Resource</code> corresponding to a
+   * <code>PPB_Buffer_Dev</code> resource that contains a video frame.
+   *
+   * @param[in] request_id A unique value the browser can use to associate
+   * decrypted_frame with a decrypt call.
+   */
+  void DeliverFrame(
+      [in] PP_Instance instance,
+      [in] PP_Resource decrypted_frame,
+      [in] int32_t request_id);
+
+  /**
+   * Called after the <code>DecryptAndDecode()</code> method on the
+   * <code>PPP_ContentDecryptor_Private</code> interface completes to
+   * deliver a buffer of decrypted and decoded audio samples to the browser for
+   * rendering.
+   *
+   * @param[in] decrypted_samples A <code>PP_Resource</code> corresponding to a
+   * <code>PPB_Buffer_Dev</code> resource that contains a decrypted buffer
+   * of decoded audio samples.
+   *
+   * @param[in] request_id A unique value the browser can use to associate
+   * decrypted_samples with a decrypt call.
+   */
+  void DeliverSamples(
+      [in] PP_Instance instance,
+      [in] PP_Resource decrypted_samples,
+      [in] int32_t request_id);
+};