A proposal for an initial postMessage interface. This will allow JavaScript ...

ppapi/c/dev/pp_message_event_dev.h

Index: ppapi/c/dev/pp_message_event_dev.h
===================================================================
--- ppapi/c/dev/pp_message_event_dev.h	(revision 0)
+++ ppapi/c/dev/pp_message_event_dev.h	(revision 0)
@@ -0,0 +1,65 @@
+/* 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_PP_MESSAGE_EVENT_DEV_H_
+#define PPAPI_C_DEV_PP_MESSAGE_EVENT_DEV_H_
+
+#include "ppapi/c/pp_macros.h"
+#include "ppapi/c/pp_var.h"
+
+/**
+ * PP_MessageEvent_Dev defines a PPAPI version of MessageEvent, as defined
+ * in:
+ *   http://dev.w3.org/html5/postmsg/#event-definitions
+ * Note that PPAPI does not currently support @a lastEventId or @a ports.
+ */
+struct PP_MessageEvent_Dev {
+  /** @a data represents the contents of the message.  Currently, it can be an
+   *  instrinsic type or string (but not structured data such as an object or

[Mark Seaborn, 2011/02/17 19:18:47]

"instrinsic" -> "intrinsic"

Does "intrinsic type or string" mean "number or string"?  (AFAIK, "intrinsic
type" is not a technical term in Javascript.)

I wouldn't have thought sending a single number as a message is very useful.

[dmichael(do not use this one), 2011/02/17 20:07:04]

I agree, it's not.  But the postMessage spec allows for it, and it's easy to
provide.

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

I reworded it.

+   *  array).
+   *  DESIGN ISSUE:  I want to support structured data and the structured

[darin (slow to review), 2011/02/17 19:20:52]

SGTM2

+   *                 clone algorithm in the future.  I believe that will
+   *                 require adding a new type for PP_Var, which is perhaps a
+   *                 tree structure encompassing the object, or a serialized
+   *                 blob.  In the latter case, the wire format becomes part
+   *                 of the PPAPI interface.  In the former case, the wire
+   *                 format is more hidden but still needs to be carefully
+   *                 managed by the proxy code to maintain backwards
+   *                 compatibility.  This does not need to be resolved now.
+   */
+  struct PP_Var data;

[Mark Seaborn, 2011/02/17 19:18:47]

I thought the purpose of this async messaging was to get rid of PP_Var?  I think
it would be better to support just strings (preferably byte strings) initially.

[dmichael(do not use this one), 2011/02/17 20:07:04]

The proposal is more about getting rid of PPB_Var, PPB_Var_Deprecated,
PPP_Class_Deprecated, and PPB_Class.  PP_Var will remain as a variant data type.
 Its ability to reference an object may or may not go away.

+
+  /** @a origin is a UTF string containing the origin of the message.  It is
+   *  strongly recommended that message handlers check @a origin before doing

[Mark Seaborn, 2011/02/17 19:18:47]

This is contradictory.  On the one hand you say this field should be checked. 
On the other hand you say it can only have one value.  What is a NaCl process
supposed to check this against?

I think you should omit this field.  If you want to extend the message format
later you can add more callback types.

[dmichael(do not use this one), 2011/02/17 20:07:04]

PP_MessageEvent_Dev is based around the spec for MessageEvent (see above link),
which applies not only to postMessage, and not only to this one case of
postMessage.  For NaCl usage of postMessage, same-origin will always be true,
but not for all possible uses of PP_MessageEvent_Dev.  Taking Darin's comment
below in to account, I think we need this now (not just for future-proofing,
which was my original intent.)

+   *  any processing of the message data, to ensure it was received from the
+   *  expected @a origin.
+   *  DESIGN ISSUE:  There was discussion of omitting this parameter.  For now,

[darin (slow to review), 2011/02/17 19:20:52]

OK, yeah...

While NaCl has a same-origin restriction, other pepper plugins do not.  We
should design with that in mind.

Unlike the postMessage API exposed to JS, we don't really know the origin of the
target--the plugin.  NaCl knows this, but the pepper plugin host in Chrome does
not.  All Chrome knows is the origin of the Document embedding the plugin.

So, I think this data structure should include both source_origin and
target_origin fields.  That will enable trusted pepper plugins that are loading
restricted content (think flash) to perform origin checks because only the
plugin may know the origin of the content it has loaded into an instance.

This may impact the PostMessage function call too.

[dmichael(do not use this one), 2011/02/17 20:07:04]

Ah, thanks for pointing that out!
The spec doesn't met a target origin...  I'm not sure what it would be used for.
 In the Flash plugin, what would it be?  A file URL?

+   *                 there is no way to send messages to other origins or
+   *                 receive messages from other origins, so this is arguably
+   *                 not necessary.
+   *
+   *                 I think we can provide it anyway for now.  That frees us
+   *                 up to relax that restriction in the future without changing
+   *                 this structure.  It also makes this structure a little more
+   *                 familiar to people used to the JavaScript postMessage.
+   */
+  struct PP_Var origin;
+
+  /** @a source is a reference to the WindowObject that sent this message.
+   *  DESIGN ISSUE:  Part of me originally wanted to yank out the 'object id'
+   *                 type for PP_Var eventually.  But...  maybe it's okay to
+   *                 keep the ID if we can only ever use it asynchronously.  I
+   *                 think in this case, source fills the role of a WindowProxy
+   *                 and allows us to respond to the same iframe/window that
+   *                 invoked postMessage on us.  Currently, I'm not showing an
+   *                 interface that would allow you to post a message to just
+   *                 any PP_Var (only to instances), so we could omit this.  But
+   *                 like origin, we can provide it now easily and possibly make
+   *                 use of it later.
+   */
+  struct PP_Var source;

[darin (slow to review), 2011/02/17 19:20:52]

it is an interesting idea to include this here.  i'm OK adding it in later as we
can just rev the structure once we know how we would use this.

[brettw, 2011/02/17 20:40:01]

Yeah, I would probably just delete this.

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

Done.

+};
+
+#endif  /* PPAPI_C_DEV_PP_MESSAGE_EVENT_DEV_H_ */
+
Property changes on: ppapi/c/dev/pp_message_event_dev.h
___________________________________________________________________
Added: svn:eol-style
   + LF