ppapi/c/ppp_instance.h - Issue 6538028: A proposal for an initial postMessage interface. This will allow JavaScript ...

Side by Side Diff: ppapi/c/ppp_instance.h

Issue 6538028: A proposal for an initial postMessage interface. This will allow JavaScript ... (Closed) Base URL: svn://svn.chromium.org/chrome/trunk/src/

Patch Set: '' Created 9 years, 10 months ago

Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.

Jump to:

View unified diff | Download patch | Annotate | Revision Log

OLD	NEW
1 /* Copyright (c) 2010 The Chromium Authors. All rights reserved.	1 /* Copyright (c) 2010 The Chromium Authors. All rights reserved.

2 * Use of this source code is governed by a BSD-style license that can be	2 * Use of this source code is governed by a BSD-style license that can be

3 * found in the LICENSE file.	3 * found in the LICENSE file.

4 */	4 */

5 #ifndef PPAPI_C_PPP_INSTANCE_H_	5 #ifndef PPAPI_C_PPP_INSTANCE_H_

6 #define PPAPI_C_PPP_INSTANCE_H_	6 #define PPAPI_C_PPP_INSTANCE_H_

7	7

	8 #include "ppapi/c/dev/pp_message_event_dev.h"

8 #include "ppapi/c/pp_bool.h"	9 #include "ppapi/c/pp_bool.h"

9 #include "ppapi/c/pp_instance.h"	10 #include "ppapi/c/pp_instance.h"

10 #include "ppapi/c/pp_rect.h"	11 #include "ppapi/c/pp_rect.h"

11 #include "ppapi/c/pp_resource.h"	12 #include "ppapi/c/pp_resource.h"

12	13

13 struct PP_InputEvent;	14 struct PP_InputEvent;

14 struct PP_Var;	15 struct PP_Var;

15	16

16 #define PPP_INSTANCE_INTERFACE "PPP_Instance;0.4"	17 #define PPP_INSTANCE_INTERFACE "PPP_Instance;0.5"

17	18

18 /**	19 /**

19 * @file	20 * @file

20 * Defines the API ...	21 * Defines the API ...

21 *	22 *

22 */	23 */

23	24

24 /** @addtogroup Interfaces	25 /** @addtogroup Interfaces

25 * @{	26 * @{

26 */	27 */

(...skipping 93 matching lines...) Expand 10 before \| Expand all \| Expand 10 after Loading...
120 * Returns a Var representing the instance object to the web page. Normally	121 * Returns a Var representing the instance object to the web page. Normally

121 * this will be a PPP_Class object that exposes certain methods the page	122 * this will be a PPP_Class object that exposes certain methods the page

122 * may want to call.	123 * may want to call.

123 *	124 *

124 * On Failure, the returned var should be a "void" var.	125 * On Failure, the returned var should be a "void" var.

125 *	126 *

126 * The returned PP_Var should have a reference added for the caller, which	127 * The returned PP_Var should have a reference added for the caller, which

127 * will be responsible for Release()ing that reference.	128 * will be responsible for Release()ing that reference.

128 */	129 */

129 struct PP_Var (*GetInstanceObject)(PP_Instance instance);	130 struct PP_Var (*GetInstanceObject)(PP_Instance instance);

	131

	132 /**

	133 * This method is invoked when postMessage is invoked on the DOM object for

	134 * this instance in JavaScript.

	135 *

	136 * For example:

	137 *

	138 * <body>

	139 * <object id="plugin"

	140 * type="application/x-ppapi-postMessage-example"/>

	141 * <script type="text/javascript">

	142 * document.getElementById('plugin').postMessage("Hello world!");

	143 * </script>

	144 * </body>

	145 *

	146 * This will result in OnMessage being invoked on the instance, with

	147 * message.data being a string PP_Var containing "Hello world!".

	148 */

	149 void (*OnMessage)(PP_Instance instance, struct PP_MessageEvent_Dev message);
	darin (slow to review) 2011/02/17 19:20:52 nit: pass message by const pointer. Stepping back nit: pass message by const pointer. Stepping back, I thought that David Sehr made a good suggestion the other day. Instead of this model for PostMessage (which I know I had suggested), maybe we could have the notion of PPB_MessagePort that you can operate on. Then the plugin can assign a message port to the instance. PPB_MessagePort would have methods to post and pop messages. The pop function would take a PP_CompletionCallback as we could say that post always completes quickly by placing the message in an outbound queue. struct PPB_MessagePort { PP_Resource (Create)(PP_Instance, struct PP_Var origin); int32_t (PostMessage)(PP_Resource message_port, const struct PP_Var message, const struct PP_Var target_origin); int32_t (PopMessage)(PP_Resource message_port, struct PP_Message_Dev message, PP_CompletionCallback callback); void (Close)(PP_Resource message_port); }; The Close function is needed so that the caller of PopMessage has a way to interrupt the call, allowing them to free the memory associated with the given PP_Message_Dev struct. (I'm not sure that the "Event" suffix to PP_MessageEvent_Dev is necessary. A message is a kind of event, right?) Here's what PPB_Instance could look like for binding a message port: struct PPB_Instance { ... void (BindMessagePort)(PP_Instance instance, PP_Resource message_port); ... }; There is one thing I'm not sure of, which is what happens if JS calls postMessage on the plugin element before the plugin has called BindMessagePort. Should we just queue messages on behalf of the plugin, or should we drop them on the floor? We can say that BindMessagePort should be called during DidCreate, but I'm not sure if DidCreate runs synchronously to plugin construction or not. Note: I've added an origin parameter to the PPB_MessagePort::Create function as a way of identifying the origin of the message port. Normally, this is derived from the script context, but we don't have that in Pepper. This origin will be used as the "origin" field for MessageEvent seen by JS. We can also go one step further and say that PopMessage will not return any messages that do not match the origin of the message port. This forces message ports to be origin-restricted, which is certainly fine for NaCl, and probably fine for others too. dmichael(do not use this one) 2011/02/17 20:07:04 I thought about doing MessagePort based on his sug Show quoted text On 2011/02/17 19:20:52, darin wrote: > nit: pass message by const pointer. > > Stepping back, I thought that David Sehr made a good suggestion the other day. > Instead of this model for PostMessage (which I know I had suggested), maybe we > could have the notion of PPB_MessagePort that you can operate on. Then the > plugin can assign a message port to the instance. I thought about doing MessagePort based on his suggestion, and I want to support that model eventually. But after seeing how it's done in JS, I realized there are postMessage functions sprinkled all over the place (Workers, iframes, MessagePorts), and so I thought we could go with a simple approach for now and expand later with an appropriate implementation of MessagePort. Show quoted text > > PPB_MessagePort would have methods to post and pop messages. The pop function > would take a PP_CompletionCallback as we could say that post always completes > quickly by placing the message in an outbound queue. Interesting... I wasn't thinking of a polling model. That would certainly make it easier to define. Show quoted text > > struct PPB_MessagePort { > PP_Resource (Create)(PP_Instance, struct PP_Var origin); > > int32_t (PostMessage)(PP_Resource message_port, > const struct PP_Var message, > const struct PP_Var target_origin); > > int32_t (PopMessage)(PP_Resource message_port, > struct PP_Message_Dev message, > PP_CompletionCallback callback); > > void (Close)(PP_Resource message_port); > }; > > The Close function is needed so that the caller of PopMessage has a way to > interrupt the call, allowing them to free the memory associated with the given > PP_Message_Dev struct. > > (I'm not sure that the "Event" suffix to PP_MessageEvent_Dev is necessary. A > message is a kind of event, right?) > I'm mirroring the spec for MessageEvent to make it more familiar to those who know the spec. Show quoted text > Here's what PPB_Instance could look like for binding a message port: > > struct PPB_Instance { > ... > void (BindMessagePort)(PP_Instance instance, > PP_Resource message_port); > ... > }; > > There is one thing I'm not sure of, which is what happens if JS calls > postMessage on the plugin element before the plugin has called BindMessagePort. > Should we just queue messages on behalf of the plugin, If so, when do we stop? Show quoted text > or should we drop them on > the floor? We can say that BindMessagePort should be called during DidCreate, > but I'm not sure if DidCreate runs synchronously to plugin construction or not. > I think these problems go away if we're willing to do OnMessage directly on PPP_Instance for now and add separate MessagePorts (and a way to expose them) later. Show quoted text > Note: I've added an origin parameter to the PPB_MessagePort::Create function as > a way of identifying the origin of the message port. Normally, this is derived > from the script context, but we don't have that in Pepper. This origin will be > used as the "origin" field for MessageEvent seen by JS. We can also go one step > further and say that PopMessage will not return any messages that do not match > the origin of the message port. This forces message ports to be > origin-restricted, which is certainly fine for NaCl, and probably fine for > others too. brettw 2011/02/17 20:40:01 In reality, 99% of people will use the simplest po In reality, 99% of people will use the simplest postMessage between JS and the plugin and won't need to talk between plugins or do other message port stuff. It would be nice if this was easy to explain and difficult to mess up. I tried to do a minimal implementation both ways using a hypothetical C++ wrapper: class MyInstance : public pp::Instance { void OnMessage(const PP_MessageEvent_Dev& msg) { if (msg.data.AsString() == "doit") DoIt(); } }; class MyInstance : public pp::Instance { MyInstance() : factory_(this), port_(origin) { BindMessagePort(port_); if (port_.PopMessage(factory.NewCompletionCallback(&OnMessage)) == PP_OK) OnMessage(); // I bet people will forget this synchronous case. } ~MyInstance() { port_.Close(); // In case you passed the port_ ref anywhere else. } void OnMessage(int32_t result) { if (result != PP_OK) return; // I bet people will forget this check. if (message_.data.AsString() == "doit") DoIt(); } private: pp::CompletionCallbackFactory factory_; PP_Message_Dev message_; pp::MessagePort port_; }; I found 2 bugs in my initial implementation of the MessagePort way as I was writing this, and 0 bugs in the OnMessage way. And if you're writing to the C API, the difference will be even greater. I think I prefer the simple way for now as long as we're not going to be in a place later where we wished it was more expressive. dmichael(do not use this one) 2011/02/17 22:18:22 Done. Show quoted text On 2011/02/17 19:20:52, darin wrote: > nit: pass message by const pointer. > Done.
130 };	150 };

131 /**	151 /**

132 * @}	152 * @}

133 */	153 */

134	154

135 #endif /* PPAPI_C_PPP_INSTANCE_H_ */	155 #endif /* PPAPI_C_PPP_INSTANCE_H_ */

136	156

OLD	NEW

« ppapi/c/dev/pp_message_event_dev.h ('K') | « ppapi/c/ppb_instance.h ('k') | no next file » | no next file with comments »