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 the CDM for v0.1 of the proposed Encrypted Media
+ * Extensions: http://goo.gl/rbdnR

[dmichael (off chromium), 2012/08/14 03:31:37]

Please note (preferrably early in the comment) that this is *not* for use by
conventional plugins, and is only for Content Decryption Modules (make sure you
spell that out at least once).

[Tom Finegan, 2012/08/14 16:39:40]

Done; added missing note to this file, and put it up above with the "This file
defines..."

+ */
+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
+   * browser should provide a key to the decryptor plugin by calling
+   * <code>AddKey()</code> on the <code>PPP_ContentDecryptor_Private<code>
+   * interface.

[dmichael (off chromium), 2012/08/14 03:31:37]

I still think it's important that the browser might *not* call AddKey, since
it's the responsibility of the application in some cases. Doesn't that
potentially affect how you code the CDM? That's why I think it's worth pointing
out.

[Tom Finegan, 2012/08/14 16:39:40]

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.
+   *
+   * @param[in] init_data A <code>PP_Var</code> of type
+   * <code>PP_VARTYPE_ARRAYBUFFER</code> containing container specific

[dmichael (off chromium), 2012/08/14 03:31:37]

nit: "container specific"->"container-specific"

[Tom Finegan, 2012/08/14 16:39:40]

Done.

+   * initialization data.
+   */
+  void NeedKey(

[dmichael (off chromium), 2012/08/14 03:31:37]

I actually think RequestKey would be more appropriate here, but if this matches
the spec better, that's OK for a private interface.

[Tom Finegan, 2012/08/14 16:39:40]

NeedKey is from the spec.

+      [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 with the application
+   * providing more data via additional calls to <code>AddKey()</code> could be

[dmichael (off chromium), 2012/08/14 03:31:37]

I find this wording a bit confusing...  can you make sure you say which party is
responsible for which calls? The browser calls KeyMessage? Is that always
because the app calls the browser, or does the browser do it without app
intervention? And the CDM invokes AddKey? (in general: please prefer active
voice and add subjects for these phrases; it's unclear who does what right now).

[Tom Finegan, 2012/08/14 16:39:40]

Done.

+   * required. <code>KeyAdded()</code> is sent once the sequence is completed.

[dmichael (off chromium), 2012/08/14 03:31:37]

as above, "The CDM invokes <code>KeyAdded()</code> once the sequence is
completed." (or similar)

[Tom Finegan, 2012/08/14 16:39:40]

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

[dmichael (off chromium), 2012/08/14 03:31:37]

Maybe it would be clearer to say something like:
"For example, if the browser invokes
PPP_ContentDecryptor_Private::GenerateKeyRequest and the CDM successfully
generates a key, the decryptor ..."

[Tom Finegan, 2012/08/14 16:39:40]

Done.

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

[dmichael (off chromium), 2012/08/14 03:31:37]

"Of note is" -> "See also"

[Tom Finegan, 2012/08/14 16:39:40]

Done.

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

[dmichael (off chromium), 2012/08/14 03:31:37]

This is another method name that's a bit opaque to me. "DidGenerateKeyMessage"?
(Feel free to ignore for now, especially if this matches the spec better; but I
really would prefer clearer names down the road if possible)

[Tom Finegan, 2012/08/14 16:39:40]

From spec.

+      [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.

[dmichael (off chromium), 2012/08/14 03:31:37]

As I mentioned before, we usually say what the browser does in response to
calls. In this case, is it something like "The browser delivers the decrypted
block to the application."? As I think I mentioned before, for any of these that
map to a DOM event in the spec that the browser must deliver, you should say
that the browser dispatches a DOM event (and specify which DOM event).

[Tom Finegan, 2012/08/14 16:39:40]

All I can really add here is that the block is sent back for decode/render.
That's done.

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

[dmichael (off chromium), 2012/08/14 03:31:37]

same as above; what does the browser do?

[Tom Finegan, 2012/08/14 16:39:40]

Done.

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

[dmichael (off chromium), 2012/08/14 03:31:37]

ditto

[Tom Finegan, 2012/08/14 16:39:40]

Done.

+   *
+   * @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);
+};