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>PPP_ContentDecryptor_Dev</code>

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

nit: PPB

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

Done.

+ * interface.
+ */
+label Chrome {
+  M22 = 0.1
+};
+
+/**
+ * <code>PPB_ContentDecryptor_Dev</code> structure contains the function
+ * pointers the browser may implement to support plugins implementing the

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

why "may" implement? Can the browser choose to not implement some of these? Are
you implying that some of them may be NULL? (For the record, if what you mean is
that the browser may not actually do anything in some of these calls, then it's
probably worth being explicit that all the function pointers will be valid)

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

That should have said MUST-- I missed an earlier comment/or possibly rebased the
change out. Sorry about that.

+ * <code>PPP_ContentDecryptor_Dev</code> interface.

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

Can you describe more about what this API is for? Do plugins actually use this,
or is it really just a surface for a content decryptor to use to interact with
the Browser? Can you point to a spec or anything? If it's not an actual API for
a plugin to use, it should be pointed out that it's special and why.

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

EME and PPAPI CDM design links sent offline.

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

I mean in the documentation :-)

I don't want other people to come across this and think they can use it in their
plugin. In fact...  make sure you consider that case so that nothing weird
happens.

+ */
+interface PPB_ContentDecryptor_Dev {
+
+  /**
+   * A key or license is needed to decrypt media data.

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

Can you rephrase this to say what the method actually does?

[Tom Finegan, 2012/08/02 01:12:04]

Done.

+   */
+  void NeedKey(
+      [in] PP_Instance instance,
+      [in] PP_Var key_system,       /* String. */
+      [in] PP_Var session_id,       /* String. */
+      [in] PP_Resource init_data);  /* PPB_Buffer. */
+
+  /**
+   * 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.

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

If Chrome is calling AddKey first, why would the content decryptor thingy call
back to Chrome? Shouldn't the browser already know?

[Tom Finegan, 2012/08/02 01:12:04]

AddKey is asynchronous, so all the browser will know is that the attempt is in
progress when AddKey reports success.

+   */
+  void KeyAdded(
+      [in] PP_Instance instance,
+      [in] PP_Var key_system,   /* String. */
+      [in] PP_Var session_id);  /* String. */
+
+  /**
+   * A message or request has been generated by or for key_system. For example,

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

Again, I'd rather an active voice statement of what the Browser does when you
call this.

[Tom Finegan, 2012/08/02 01:12:04]

I tweaked the comment to make this a little bit more clear, but per the
Encrypted Media Extensions specification KeyMessage is somewhat general purpose.
Providing an exhaustive list of the potential uses would result in a _very_
lengthy comment. If the tweaked version isn't enough, just let me know and I'll
come up with some more information.

+   * a key request has been generated as the result of call to the
+   * <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.
+   */
+  void KeyMessage(
+      [in] PP_Instance instance,
+      [in] PP_Var key_system,     /* String. */
+      [in] PP_Var session_id,     /* String. */
+      [in] PP_Resource message,   /* PPB_Buffer. */
+      [in] PP_Var default_url);   /* String. */
+
+  /**
+   * An error occured in a <code>PPP_ContentDecryptor_Dev</code> method,
+   * or within the plugin implementing the interface.
+   */
+  void KeyError(
+      [in] PP_Instance instance,
+      [in] PP_Var key_system,   /* String. */
+      [in] PP_Var session_id,   /* String. */
+      [in] uint16_t media_error,
+      [in] uint16_t system_error);

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

We tend to use int32_t for error codes...  are these from a spec? Even if they
are 16 bits in the spec, it might be a good idea to use int32_t and maybe define
an enum for each if you can enumerate all possible errors.

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

Done.

+
+  /**
+   * Called after the <code>Decrypt</code> method on the
+   * <code>PPP_ContentDecryptor_Dev</code> interface completes to
+   * deliver decrypted_block to the media stack.
+   */
+  void DeliverBlock(
+      [in] PP_Instance instance,
+      [in] PP_Resource decrypted_block,  /* PPB_Buffer. */
+      [in] PP_CompletionCallback callback);
+
+  /**
+   * Called after the <code>DecryptAndDecode</code> method on the
+   * <code>PPP_ContentDecryptor_Dev</code> interface completes to
+   * deliver decrypted_frame to the media stack.
+   */
+  void DeliverFrame(
+      [in] PP_Instance instance,
+      [in] PP_Resource decrypted_frame,  /* PPB_Buffer. */
+      [in] PP_CompletionCallback callback);
+
+  /**
+   * Called after the <code>DecryptAndDecode</code> method on the
+   * <code>PPP_ContentDecryptor_Dev</code> interface completes to
+   * deliver decrypted_samples to the media stack.
+   */
+  void DeliverSamples(
+      [in] PP_Instance instance,
+      [in] PP_Resource decrypted_samples,  /* PPB_Buffer. */
+      [in] PP_CompletionCallback callback);
+};