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.
+ */
+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:

[ddorwin, 2012/08/11 22:08:57]

... support for the CDM for...

[Tom Finegan, 2012/08/13 16:27:17]

Done.

+ * 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 <code>Decrypt()</code> on the
+   * <code>PPP_ContentDecryptor_Private<code> interface, In response, the

[ddorwin, 2012/08/11 22:08:57]

s/,/./

[Tom Finegan, 2012/08/13 16:27:17]

Done.

+   * browser should provide a key to the decryptor plugin by calling
+   * <code>AddKey()</code> on the <code>PPP_ContentDecryptor_Private<code>
+   * interface. The key could be provided by the browser, or from the

[ddorwin, 2012/08/11 22:08:57]

I think this last sentence is unnecessary.

[Tom Finegan, 2012/08/13 16:27:17]

Removed.

+   * application via a call to <code>addkey()</code> on the media element.
+   *
+   * @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

[ddorwin, 2012/08/11 22:08:57]

s/content/container/ ?

[Tom Finegan, 2012/08/13 16:27:17]

Done.

+   * 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

[ddorwin, 2012/08/11 22:08:57]

s/the/The/

[Tom Finegan, 2012/08/13 16:27:17]

Done.

+   * 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.
+   *
+   * @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] default_url A <code>PP_Var</code> of type
+   * <code>PP_VARTYPE_STRING</code> containing the default URL for key system.

[ddorwin, 2012/08/11 22:08:57]

s/key system/the message/

[Tom Finegan, 2012/08/13 16:27:17]

Done.

+   */
+  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.

[ddorwin, 2012/08/11 22:08:57]

error_code A MediaKeyError.

[Tom Finegan, 2012/08/13 16:27:17]

Done.

+   *
+   * @param[in] system_error A system error code.

[ddorwin, 2012/08/11 22:08:57]

system_code

[Tom Finegan, 2012/08/13 16:27:17]

Done.

+   */
+  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] 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 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);

[ddorwin, 2012/08/11 22:08:57]

We usually prefer signed ints. Is there a reason it must be unsigned (and 64
bits)? Are there other examples of this in Pepper?

[Tom Finegan, 2012/08/13 16:27:17]

Taken directly from a suggestion in an offline disccusion-- changed to signed
32. Even at 60 frames/second we still have 414 days before rollover.

+
+  /**
+   * 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.
+   *
+   * @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 user agent can use to associate
+   * decrypted_frame with a decrypt call.
+   */
+  void DeliverFrame(

[ddorwin, 2012/08/11 22:08:57]

Thoughts on whether to include "Video" in the name since it is only for video?
Same for the next method.

Actually, if the answer to my next question is no, do we need separate functions
to deliver decoded blocks? The request_id could be used to determine audio vs.
video. Maybe it's simpler to be explicit since the plugin knows, though.

[Tom Finegan, 2012/08/13 16:27:17]

I would be fine w/DeliverVideoFrame or just DeliverVideo (in case we ever want
to send more than one frame at a time).

[ddorwin, 2012/08/13 17:43:50]

I think the signature would be different for more than one frame.

+      [in] PP_Instance instance,
+      [in] PP_Resource decrypted_frame,

[ddorwin, 2012/08/11 22:08:57]

Are we going to meed more information than this?
This is fine for now, but I wonder if we should just leave these out until we
have a better idea.

[Tom Finegan, 2012/08/13 16:27:17]

Probably not when returning the uncompressed data-- I think the request_id would
be enough to get the data to where it needs to go from PI.

+      [in] uint64_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.
+   *
+   * @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 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);
+};