Add PPAPI decryptor interfaces.

ppapi/api/dev/ppb_content_decryptor_dev.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_Dev</code>
+ * interface.
+ */
+label Chrome {
+  M23 = 0.1
+};
+
+/**
+ * <code>PPB_ContentDecryptor_Dev</code> structure contains the function
+ * pointers the browser MUST implement to support plugins implementing the
+ * <code>PPP_ContentDecryptor_Dev</code> interface.

[dmichael (off chromium), 2012/08/08 03:38:10]

can you reference the spec?

[Tom Finegan, 2012/08/08 19:02:15]

Done; referenced in the PPB IDL as well.

+ */
+interface PPB_ContentDecryptor_Dev {
+
+  /**
+   * The media stack needs a key to decrypt content, and uses this method to
+   * notify the decryptor of the requirement and provide content specific
+   * decryptor initialization data. <code>NeedKey</code> is used in the
+   * typical playback start up case, after playback resumes, or because a
+   * key already in use has expired.

[dmichael (off chromium), 2012/08/08 03:38:10]

PPB functions are telling the browser to do something. I know this case is a
little weird, in that it's kind of more like a callback, but I'd still like this
to say what the plugin expects the browser to do in this case. Best I can tell,
it expects the browser to inform the client application that a key is needed via
a DOM event.

Same comment for other PPB methods...  what does the browser do when you make
the call?

[Tom Finegan, 2012/08/08 19:02:15]

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.

[dmichael (off chromium), 2012/08/08 03:38:10]

Is this the point at which the session_id is determined (if the CDM supports
session ids)? If so, that seems worth noting somewhere.

[Tom Finegan, 2012/08/08 19:02:15]

GenerateKeyRequest on the PPP interface creates session IDs. 

+   *
+   * @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_Dev</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.
+   */
+  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. For example,
+   * a key request has been generated as the result of call to the

[dmichael (off chromium), 2012/08/08 03:38:10]

nit: of +a+ call

[Tom Finegan, 2012/08/08 19:02:15]

Done.

+   * <code>GenerateKeyRequest()</code> method on the
+   * <code>PPP_ContentDecryptor_Dev</code> interface or another message
+   * must be sent in response to an <code>AddKey()</code> call. Note that
+   * <code>KeyMessage</code> can be used for purposes other than results to
+   * <code>AddKey()</code> calls.
+   *
+   * @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
+   * <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_Dev</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_Dev</code> interface completes to
+   * deliver decrypted_block to the media stack.
+   *
+   * @param[in] resource 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 value used in <code>ppapi::PluginInstance</code> to

[dmichael (off chromium), 2012/08/08 03:38:10]

I would rather we avoid talking about Chrome-specific implementation details.
How about something more like "A unique value the user agent can use to
associate @a decrypted_block with a prior call to Decrypt()."
or something.

[Tom Finegan, 2012/08/08 19:02:15]

Done; basically stole your wording. :)

+   * match returned decrypted data to a callback sent from the media stack.
+   */
+  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
+   * <code>PPP_ContentDecryptor_Dev</code> interface completes to
+   * deliver decrypted_frame to the media stack.
+   *
+   * @param[in] resource A <code>PP_Resource</code> corresponding to a
+   * <code>PPB_Buffer_Dev</code> resource that contains a decrypted video
+   * frame.
+   *
+   * @param[in] request_id A value used in <code>ppapi::PluginInstance</code> to
+   * match returned decrypted data to a callback sent from the media stack.
+   */
+  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_Dev</code> interface completes to
+   * deliver decrypted_samples to the media stack.
+   *
+   * @param[in] resource A <code>PP_Resource</code> corresponding to a
+   * <code>PPB_Buffer_Dev</code> resource that contains a decrypted buffer
+   * of audio samples.
+   *
+   * @param[in] request_id A value used in <code>ppapi::PluginInstance</code> to
+   * match returned decrypted data to a callback sent from the media stack.
+   */
+  void DeliverSamples(
+      [in] PP_Instance instance,
+      [in] PP_Resource decrypted_samples,
+      [in] uint64_t request_id);
+};