Add PPAPI decryptor interfaces.

ppapi/api/private/ppb_content_decryptor_private.idl

Index: ppapi/api/private/ppb_content_decryptor_private.idl
diff --git a/ppapi/api/private/ppb_content_decryptor_private.idl b/ppapi/api/private/ppb_content_decryptor_private.idl
new file mode 100644
index 0000000000000000000000000000000000000000..b24361d4aab3dfb358f2a551060f5056aacd87b1
--- /dev/null
+++ b/ppapi/api/private/ppb_content_decryptor_private.idl
@@ -0,0 +1,177 @@
+/* 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.
+ */
+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 v0.1 of the proposed Encrypted Media Extensions:
+ * http://goo.gl/rbdnR

[xhwang, 2012/08/10 16:41:30]

I am not sure if we should use short URL in this file.

[Tom Finegan, 2012/08/10 17:13:06]

Originally I was using the full URL, but generators.py mangles the comment
because it exceeds 80 columns. You end up with a C interface include that looks
like this
/**
 * Normal comment text blah blah blah
 *
   *
http://dvcs.w3.org/hg/html-media/raw-file/tip/encrypted-media/encrypted-media...
 */

Note that contrary to the display in this page the '*' and the link are on the
same line.

Hand editing it would work, but to do that I have to bypass the presubmit. No
problems doing that if the full link is preferred. 

+ */
+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 a decrypt method on the

[xhwang, 2012/08/10 16:41:30]

s/decrypt/<code>Decrypt()<code>

[Tom Finegan, 2012/08/10 17:13:06]

Done.

+   * <code>PPP_ContentDecryptor_Private<code> interface, In response, the
+   * application must provide a key to the decryptor plugin by calling
+   * <code>AddKey()</code> on the <code>PPP_ContentDecryptor_Private<code>

[xhwang, 2012/08/10 16:41:30]

The application cannot call the PPP interface directly, it calls addkey method
on the media element (http://goo.gl/2RWNI). It's the browser that calls the PPP
interface's AddKey(), usually as a result of the addkey call from the
application, but in theory nothing prevents the browser from grabbing a key
magically somewhere and calling AddKey() without involving the application. 

How about something like "In response, the browser should provide a key ...."

[Tom Finegan, 2012/08/10 17:13:06]

Done.

+   * 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 content 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, and
+   * decryption of content can proceed.

[xhwang, 2012/08/10 16:41:30]

Remove "and decryption of content can proceed"? This message just tells the
browser that the key has been added. But there's no guarantee that this key
applies to the content being blocked/decrypted.  

[Tom Finegan, 2012/08/10 17:13:06]

Done.

+   *
+   * Note: the above describes the most simple case. Depending on the key
+   * system, a series of <code>KeyMessage()</code> calls with the application
+   * providing more data via additional calls to <code>AddKey()</code> could be
+   * required. <code>KeyAdded()</code> is sent once the sequence is completed,
+   * and the decryptor plugin is ready to begin decryption of data.

[xhwang, 2012/08/10 16:41:30]

ditto about the last sentence.

[Tom Finegan, 2012/08/10 17:13:06]

Done.

+   *
+   * @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 by or for key_system, and needs to
+   * be sent to a key server.
+   *
+   * For example, in response to successful key request generation resulting
+   * from a call to the <code>GenerateKeyRequest()</code> method on the
+   * <code>PPP_ContentDecryptor_Private</code> interface, the decryptor will
+   * send a key message with the session ID.
+   *
+   * Note that <code>KeyMessage()</code> can be used for purposes other than
+   * responses to <code>GenerateKeyRequest()</code> calls. Of note is 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] session_id A <code>PP_Var</code> of type

[xhwang, 2012/08/10 16:41:30]

s/session_id/default_url

[Tom Finegan, 2012/08/10 17:13:06]

Done.

+   * <code>PP_VARTYPE_STRING</code> containing the default URL for key system.
+   */
+  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 media stack error code.
+   *
+   * @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_error);
+
+  /**
+   * Called after the <code>Decrypt()</code> method on the
+   * <code>PPP_ContentDecryptor_Private</code> interface completes to
+   * deliver decrypted_block to the browser.
+   *
+   * @param[in] resource A <code>PP_Resource</code> corresponding to a

[xhwang, 2012/08/10 16:41:30]

s/resource/decrypted_block

[Tom Finegan, 2012/08/10 17:13:06]

Done.

+   * <code>PPB_Buffer_Dev</code> resource that contains a decrypted data
+   * block.
+   *
+   * @param[in] request_id A unique value the user agent can use to associate
+   * decrypted_block with a decrypt call.
+   */
+  void DeliverBlock(
+      [in] PP_Instance instance,
+      [in] PP_Resource decrypted_block,
+      [in] uint64_t request_id);
+
+  /**
+   * Called after the <code>DecryptAndDecode</code> method on the

[xhwang, 2012/08/10 16:41:30]

s/DecryptAndDecode/DecryptAndDecode()

[Tom Finegan, 2012/08/10 17:13:06]

Done.

+   * <code>PPP_ContentDecryptor_Private</code> interface completes to
+   * deliver decrypted_frame to the browser.
+   *
+   * @param[in] resource A <code>PP_Resource</code> corresponding to a

[xhwang, 2012/08/10 16:41:30]

s/resource/decrypted_frame

[Tom Finegan, 2012/08/10 17:13:06]

Done.

+   * <code>PPB_Buffer_Dev</code> resource that contains a decrypted video
+   * frame.
+   *
+   * @param[in] request_id A unique value the user agent can use to associate
+   * decrypted_frame with a decrypt call.
+   */
+  void DeliverFrame(
+      [in] PP_Instance instance,
+      [in] PP_Resource decrypted_frame,
+      [in] uint64_t request_id);
+
+  /**
+   * Called after the <code>DecryptAndDecode()</code> method on the
+   * <code>PPP_ContentDecryptor_Private</code> interface completes to
+   * deliver decrypted_samples to the browser.

[xhwang, 2012/08/10 16:41:30]

Should we mention this is for audio and DeliverFrame is for video? Otherwise
it's not obvious what's the difference b/w DeliverFrame and DeliverSamples.

[Tom Finegan, 2012/08/10 17:13:06]

Done.

+   *
+   * @param[in] resource A <code>PP_Resource</code> corresponding to a

[xhwang, 2012/08/10 16:41:30]

s/resource/decrypted_samples

[Tom Finegan, 2012/08/10 17:13:06]

Done.

+   * <code>PPB_Buffer_Dev</code> resource that contains a decrypted buffer
+   * of audio samples.
+   *
+   * @param[in] request_id A unique value the user agent can use to associate
+   * decrypted_samples with a decrypt call.
+   */
+  void DeliverSamples(
+      [in] PP_Instance instance,
+      [in] PP_Resource decrypted_samples,
+      [in] uint64_t request_id);
+};