A proposal and implementation for an initial postMessage interface. These in...

ppapi/c/dev/ppb_messaging_dev.h

+/* Copyright (c) 2011 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.
+ */
+#ifndef PPAPI_C_DEV_PPB_MESSAGING_DEV_H_
+#define PPAPI_C_DEV_PPB_MESSAGING_DEV_H_
+
+#include "ppapi/c/pp_instance.h"
+#include "ppapi/c/pp_var.h"
+
+#define PPB_MESSAGING_DEV_INTERFACE_0_1 "PPB_Messaging(Dev);0.1"
+
+#define PPB_MESSAGING_DEV_INTERFACE PPB_MESSAGING_DEV_INTERFACE_0_1

[polina, 2011/03/22 22:00:59]

Is this necessary at this point?
Other headers don't have this, do they? And I was under the impression that we
are still working out the details of how versioning will work.

[dmichael(do not use this one), 2011/03/23 17:03:18]

Ah yes, I meant to bring this up.  I found it convenient to have this when I was
trying to do backwards compatibility.

I was thinking of proposing we start doing this.  It may only matter for
PPP_Instance.  However, if the NaCl proxy (which is in a separate repo) needs to
refer to a _particular_ version of an interface, it can only do it with a raw
string literal right now.  I definitely wanted something like this when I was
trying to stick backwards compatibility in for PPP_Instance.

I think it might be useful when we start putting in backwards compatibility
(which I'll try doing as I rev these interfaces), but I can cut it if it's
objectionable.

[polina, 2011/03/24 05:42:33]

Before we start adding any such hooks to the code, we should first reach a
global consensus on what interface changes we will allow (adding methods?
removing methods? changing signatures? all of the above?) and how multiple
versions will be delivered by the browser and the proxy.

NaCl can't ship without this, so I am happy to draft a proposal for this if
nobody is working on one already.

[dmichael(do not use this one), 2011/03/25 20:21:05]

Sure, that would be helpful.  

+
+/**
+ * @file
+ * This file defines the PPB_Messaging_Dev interface implemented by the browser
+ * and containing pointers to functions that are specific to a module instance
+ * and related to sending messages.
+ *
+ * @addtogroup Interfaces
+ * @{
+ */
+
+/**
+ * The PPB_Messaging_Dev interface contains pointers to functions related to
+ * sending messages for a specific module instance.

[polina, 2011/03/22 22:00:59]

"for" is ambiguous as it can mean "to" or "from". Also it is not clear which
direction this one is for.

How about  "functions for passing messages to the module instance on a web
page"?

Please also use the same description in the file comment.

[dmichael(do not use this one), 2011/03/23 17:03:18]

Reworded.

+ */
+struct PPB_Messaging_Dev {
+  /**
+   * @a PostMessage is a pointer to a function which asynchronously invokes the

[polina, 2011/03/22 22:00:59]

I would suggest being more specific than just saying "asynchronously" and note
that the onmessage handler won't be invoked until the user call stack is popped.

[brettw, 2011/03/23 01:59:17]

Personally I think asynchronously is more clear here than "popping the stack".
Popping the stack is also incorrect for a totally asynchronous proxy. The spec
also says "asynchronously" and I don't think it's at all ambiguous in this
context.

[dmichael(do not use this one), 2011/03/23 17:03:18]

I tried to add a little wording to make it clearer what I mean, but I agree with
Brett that it's not worth talking about the stack (etc).  I think it would be
more confusing than helpful.

[polina, 2011/03/24 05:42:33]

We don't have to talk about  the call stack and reentrancy (although it might be
nice to tell users not to worry about it in some overview doc) in header
comments, but we do need to make it clear that posting a message and handling
that message are guaranteed to be two disjoint events. If I learned anything
from all of the recent internal discussions, it's that using a single magic
keyword (like "asynchronous") is likely to result in misinterpretation.

[dmichael(do not use this one), 2011/03/25 20:21:05]

It's not just handling a response message that won't happen;  the thread won't
handle any other events (e.g. assuming it's called from the main thread,
completion callbacks, input events, etc won't happen).
I actually think that in this case saying something like "the calling thread
will not handle other events while in PostMessage" would be more confusing than
helpful.  I don't think developers would expect it to do anything like that, so
reading a comment about what *won't* happen is probably just going to make it
harder to understand the description of what *will* happen.

+   * onmessage handler on the DOM element for the given module instance, if one
+   * exists. @a message is a PP_Var containing the data to be sent to
+   * JavaScript. Currently, it can have an int32_t, double, bool, or string
+   * value (objects are not currently supported.)

[polina, 2011/03/22 22:00:59]

you have "currently" twice in the same sentence

[dmichael(do not use this one), 2011/03/23 17:03:18]

Fixed.

+   *
+   * The onmessage handler in JavaScript code will receive an object conforming
+   * to the MessageEvent interface. In particular, the value of @a message will
+   * be contained as a property called @a data in the received MessageEvent.
+   * This is analogous to listening for messages from Web Workers.
+   *
+   * See:
+   *   http://www.whatwg.org/specs/web-workers/current-work/
+   *
+   * For example:
+   *
+   * \verbatim
+   *
+   * <body>
+   *   <object id="plugin"
+   *           type="application/x-ppapi-postMessage-example"/>
+   *   <script type="text/javascript">
+   *     document.getElementById('plugin').onmessage = function(message) {
+   *       alert(message.data);
+   *     }
+   *   </script>
+   * </body>
+   *
+   * \endverbatim
+   *
+   * If the module instance then invokes @a PostMessage() as follows:
+   * <code>
+   *  char hello_world[] = "Hello world!";
+   *  PP_Var hello_var = ppb_var_if->VarFromUtf8(instance,
+   *                                             hello_world,
+   *                                             sizeof(hello_world));
+   *  ppb_messaging_if->PostMessage(instance, hello_var);
+   * </code>
+   *
+   * The browser will pop-up an alert saying "Hello world!".
+   */
+  void (*PostMessage)(PP_Instance instance, struct PP_Var message);
+};
+/**
+ * @}
+ */
+
+#endif  /* PPAPI_C_DEV_PPB_MESSAGING_DEV_H_ */
+