Add PPAPI decryptor interfaces.

ppapi/api/dev/ppp_content_decryptor_dev.idl

Index: ppapi/api/dev/ppp_content_decryptor_dev.idl
diff --git a/ppapi/api/dev/ppp_content_decryptor_dev.idl b/ppapi/api/dev/ppp_content_decryptor_dev.idl
new file mode 100644
index 0000000000000000000000000000000000000000..5f3169abe7bc2fa2ce41ab5662316af0ffddf0de
--- /dev/null
+++ b/ppapi/api/dev/ppp_content_decryptor_dev.idl
@@ -0,0 +1,63 @@
+/* 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>PPP_ContentDecryptor_Dev</code>
+ * interface.
+ */
+label Chrome {
+  M22 = 0.1
+};
+
+/**
+ * <code>PPP_ContentDecryptor_Dev</code> structure contains the function
+ * pointers the decryption plugin MUST implement to provide services needed by
+ * the media stack.
+ */
+interface PPP_ContentDecryptor_Dev {

[dmichael (off chromium), 2012/07/31 03:36:31]

We're trying to get away from defining new PPP interfaces. brettw or
viettrungluu might have more information, but I think the intent would be that
the plugin passes a struct of function pointers in to a PPB call. Or, if it
makes sense, even better is just to use CompletionCallbacks as the only way for
the browser to call the plugin.

I might be more helpful after I read your design document.

[Tom Finegan, 2012/08/01 04:19:22]

So the PPB interface would have an OnCreate method (or something), and the
plugin would pass the function pointers in at that point?

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

Yes. You can use the same struct and typename, it just won't hook in to the
GetInterface string-based stuff.

There are a few reasons for this:
- It's easier to support backwards-compatibility, because we know that a
particular PPP interface version is always associated one-to-one with a
particular PPB version.
- We can support calling PPP functions on a background thread (whereas the "old"
way, it really only ever makes sense to invoke them on the main thread). The
idea is that whatever thread you use to register your PPP struct is the one we
call you on. That may not matter here, but it might.

+  /**
+   * Generates a key request. key_system specifies the key or licensing system
+   * from which to request the key when the plugin provides access to multiple
+   * systems. init_data is a data buffer containing initialization data from

[dmichael (off chromium), 2012/07/31 03:36:31]

Maybe it's just that I'm ignorant of content decryption, but I don't know what
sort of string to expect here. Could you provide an example?

[Tom Finegan, 2012/08/01 04:19:22]

Sure, here are two examples from webkit/media/crypto/key_systems.cc:

webkit-org.w3.clearkey
org.chromium.externalclearkey

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

I meant in the documentation :-)

+   * the media data that is required for use of the plugin's key system(s).
+   */
+  PP_Bool GenerateKeyRequest(
+      [in] PP_Instance instance,
+      [in] PP_Var key_system,       /* String. */
+      [in] PP_Resource init_data);  /* PPB_Buffer. */

[dmichael (off chromium), 2012/07/31 03:36:31]

FYI: Another option is an ArrayBuffer var. ArrayBuffers have some advantages:
1) Not in dev (if you think this will ever come out of dev, that might matter)
2) Can be posted to/from JavaScript as a JavaScript ArrayBuffer (also might not
matter to you.)

ArrayBuffer also currently doesn't use shared memory, though, so if this is
large, PPB_Buffer might be better.

[Tom Finegan, 2012/08/01 04:19:22]

We're not really sure what the maximum size of init_data will be, but currently
it's capped at 2KB. That doesn't seem to be that large-- I'll try changing this
over to an ArrayBuffer.

Update: seems to work; will test this some more.

+
+  /**
+   * Provides a key or license to use for decrypting media data for session_id.
+   */
+  PP_Bool AddKey(
+      [in] PP_Instance instance,
+      [in] PP_Var session_id,  /* String. */
+      [in] PP_Resource key);   /* PPB_Buffer. */
+
+  /**
+   * Cancels a key request for session_id.
+   */
+  PP_Bool CancelKeyRequest(
+      [in] PP_Instance instance,
+      [in] PP_Var session_id);  /* String. */
+
+  /**
+   * Decrypts the block and returns the unencrypted block. In the case of
+   * media, the block contains encoded data.
+   */
+  PP_Bool Decrypt(
+      [in] PP_Instance instance,
+      [in] PP_Resource encrypted_block,  /* PPB_Buffer. */
+      [in] PP_CompletionCallback callback);

[dmichael (off chromium), 2012/07/31 03:36:31]

We've never used a PP_CompletionCallback in the plugin side before, and it's not
clear what the semantics are. Can you document and explain this? Maybe once I
know what you're trying to do, I can help you come up with an alternative (or
maybe I'll be convinced that PP_CompletionCallback is fine here). But it
definitely needs to be explained.

[Tom Finegan, 2012/08/01 04:19:22]

In brief:

1) Media stack calls Decrypt on webkit::ppapi::PluginInstance
2) webkit::ppapi::PluginInstance passes things on the the CDM wrapper
3) CDMWrapper decrypts asynchronously using the CDM
4) Upon completion in the CDM DeliverBlock is called on the main thread
5) webkit::ppapi::PluginInstance invokes the callback to hand data off to the
media stack for decode/render

- I'm over simplifying things between steps three and four; the comms between
the wrapper an the CDM aren't worked out yet.

- The exact details of steps four and five are still being worked out as well.

+
+  /**
+   * Decrypts the block then decodes it and returns the unencrypted raw
+   * (decoded) frame.
+   */
+  PP_Bool DecryptAndDecode(
+      [in] PP_Instance instance,
+      [in] PP_Resource encrypted_block,  /* PPB_Buffer. */
+      [in] PP_CompletionCallback callback);
+};