diff options
| author | dmichael@google.com <dmichael@google.com@0039d316-1c4b-4281-b951-d872f2087c98> | 2011-03-23 21:07:15 +0000 |
|---|---|---|
| committer | dmichael@google.com <dmichael@google.com@0039d316-1c4b-4281-b951-d872f2087c98> | 2011-03-23 21:07:15 +0000 |
| commit | 9888f134c655a95c5922c980eb59d3337341d653 (patch) | |
| tree | 8ec7b6849cd94196df9bf3ee7810f6a838242e8d /ppapi/c/dev | |
| parent | 2752bf6a3120e172d216ab7bde42222a3ae4b5cb (diff) | |
| download | chromium_src-9888f134c655a95c5922c980eb59d3337341d653.zip chromium_src-9888f134c655a95c5922c980eb59d3337341d653.tar.gz chromium_src-9888f134c655a95c5922c980eb59d3337341d653.tar.bz2 | |
A proposal and implementation for an initial postMessage interface. These interfaces will allow JavaScript to send data asynchronously to a module instance, and the module instance to asynchronously send data to a JavaScript message handler.
Note, I did something differently from other per-instance interfaces. While the C interface has 'PPB_Messaging' and 'PPP_Messaging' separate from the Instance interfaces, I stuck the per-instance messaging in to pp::Instance. It seems more intuitive to me, and doesn't have the drawbacks of having too many functions in the C layer instance interfaces. Happy to back off of that position, but it's worth a shot.
Overview:
From JavaScript, you can invoke 'postMessage' on the embedded module. That results in a call to 'PPP_Messaging::HandleMessage'.
From Native Code, you can invoke 'PPB_Messaging::PostMessage', which results
in a call to an 'onmessage' function on the DOM element for the module
instance in the JavaScript code (if one has been registered).
Please see the included example or the examples in the comments of
PPB_Messaging and PPP_Messaging.
Restrictions:
- This implementation is synchronous. A later CL will make it asynchronous.
- This implementation supports only intrinsic values and strings (all types that PP_Var supports except for objects). Object & array support will come later.
- This implementation only allows for 1 channel per instance. You can not expose other 'channels' or 'ports'. Future CLs will add support for MessagePorts.
BUG=None
TEST=test_post_message.h/.cc
(This CL replaces http://codereview.chromium.org/6538028/ )
Review URL: http://codereview.chromium.org/6716005
git-svn-id: svn://svn.chromium.org/chrome/trunk/src@79178 0039d316-1c4b-4281-b951-d872f2087c98
Diffstat (limited to 'ppapi/c/dev')
| -rw-r--r-- | ppapi/c/dev/ppb_messaging_dev.h | 82 | ||||
| -rw-r--r-- | ppapi/c/dev/ppp_messaging_dev.h | 63 |
2 files changed, 145 insertions, 0 deletions
diff --git a/ppapi/c/dev/ppb_messaging_dev.h b/ppapi/c/dev/ppb_messaging_dev.h new file mode 100644 index 0000000..8ae1ac5 --- /dev/null +++ b/ppapi/c/dev/ppb_messaging_dev.h @@ -0,0 +1,82 @@ +/* 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 "PPB_Messaging(Dev);0.1" + +/** + * @file + * This file defines the PPB_Messaging_Dev interface implemented by the browser. + * The PPB_Messaging_Dev interface contains pointers to functions related to + * sending messages to the JavaScript onmessage handler on the DOM element + * associated with a specific module instance. + * + * @addtogroup Interfaces + * @{ + */ + +/** + * The PPB_Messaging_Dev interface contains pointers to functions related to + * sending messages to the JavaScript onmessage handler on the DOM element + * associated with a specific module instance. + */ +struct PPB_Messaging_Dev { + /** + * @a PostMessage is a pointer to a function which asynchronously invokes the + * onmessage handler on the DOM element for the given module instance, if one + * exists. This means that a call to @a PostMessage will not block while the + * message is processed. + * + * @param 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 supported.) + * + * 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_ */ + diff --git a/ppapi/c/dev/ppp_messaging_dev.h b/ppapi/c/dev/ppp_messaging_dev.h new file mode 100644 index 0000000..8a65986 --- /dev/null +++ b/ppapi/c/dev/ppp_messaging_dev.h @@ -0,0 +1,63 @@ +/* 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_PPP_MESSAGING_DEV_H_ +#define PPAPI_C_DEV_PPP_MESSAGING_DEV_H_ + +#include "ppapi/c/pp_instance.h" + +struct PP_Var; + +#define PPP_MESSAGING_DEV_INTERFACE "PPP_Messaging_Dev;0.1" + +/** + * @file + * This file defines the PPP_Messaging_Dev structure - a series of pointers to + * methods that you must implement if you wish to handle messages posted to the + * module instance via calls to postMessage on the associated DOM element. + * + */ + +/** @addtogroup Interfaces + * @{ + */ + +/** + * The PPP_Messaging_Dev interface contains pointers to a series of functions + * that you must implement if you wish to handle messages posted to the module + * instance via calls to postMessage on the associated DOM element. + */ +struct PPP_Messaging_Dev { + /** + * HandleMessage is a pointer to a function that the browser will call when + * @a postMessage() is invoked on the DOM element for the module instance in + * JavaScript. Note that @a postMessage() in the JavaScript interface is + * asynchronous, meaning JavaScript execution will not be blocked while + * @a HandleMessage() is processing the given @a message. + * + * For example: + * + * @verbatim + * + * <body> + * <object id="plugin" + * type="application/x-ppapi-postMessage-example"/> + * <script type="text/javascript"> + * document.getElementById('plugin').postMessage("Hello world!"); + * </script> + * </body> + * + * @endverbatim + * + * This will result in @a HandleMessage being invoked, passing the module + * instance on which it was invoked, with @a message being a string PP_Var + * containing "Hello world!". + */ + void (*HandleMessage)(PP_Instance instance, struct PP_Var message); +}; +/** + * @} + */ +#endif /* PPAPI_C_DEV_PPP_MESSAGING_DEV_H_ */ + |