[NaCl SDK] Add a very simple getting_started example at top-level.

native_client_sdk/src/getting_started/part1/hello_tutorial.cc

+// Copyright (c) 2013 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.
+
+/// @file hello_tutorial.cc
+/// This example demonstrates loading, running and scripting a very simple NaCl
+/// module.  To load the NaCl module, the browser first looks for the
+/// CreateModule() factory method (at the end of this file).  It calls
+/// CreateModule() once to load the module code.  After the code is loaded,
+/// CreateModule() is not called again.
+///
+/// Once the code is loaded, the browser than calls the CreateInstance()
+/// method on the object returned by CreateModule().  It calls CreateInstance()
+/// each time it encounters an <embed> tag that references your NaCl module.
+///
+/// The browser can talk to your NaCl module via the postMessage() Javascript
+/// function.  When you call postMessage() on your NaCl module from the browser,
+/// this becomes a call to the HandleMessage() method of your pp::Instance
+/// subclass.  You can send messages back to the browser by calling the
+/// PostMessage() method on your pp::Instance.  Note that these two methods
+/// (postMessage() in Javascript and PostMessage() in C++) are asynchronous.
+/// This means they return immediately - there is no waiting for the message
+/// to be handled.  This has implications in your program design, particularly
+/// when mutating property values that are exposed to both the browser and the
+/// NaCl module.
+
+#include "ppapi/cpp/instance.h"
+#include "ppapi/cpp/module.h"
+#include "ppapi/cpp/var.h"
+
+/// The Instance class.  One of these exists for each instance of your NaCl
+/// module on the web page.  The browser will ask the Module object to create
+/// a new Instance for each occurrence of the <embed> tag that has these
+/// attributes:
+///     type="application/x-pnacl"
+///     src="hello_tutorial.nmf"
+/// To communicate with the browser, you must override HandleMessage() to
+/// receive messages from the browser, and use PostMessage() to send messages
+/// back to the browser.  Note that this interface is asynchronous.
+class HelloTutorialInstance : public pp::Instance {
+ public:
+  /// The constructor creates the plugin-side instance.
+  /// @param[in] instance the handle to the browser-side plugin instance.
+  explicit HelloTutorialInstance(PP_Instance instance) : pp::Instance(instance)
+  {}
+  virtual ~HelloTutorialInstance() {}
+
+  /// Handler for messages coming in from the browser via postMessage().  The
+  /// @a var_message can contain anything: a JSON string; a string that encodes
+  /// method names and arguments; etc.  For example, you could use
+  /// JSON.stringify in the browser to create a message that contains a method
+  /// name and some parameters, something like this:
+  ///   var json_message = JSON.stringify({ "myMethod" : "3.14159" });
+  ///   nacl_module.postMessage(json_message);
+  /// On receipt of this message in @a var_message, you could parse the JSON to
+  /// retrieve the method name, match it to a function call, and then call it
+  /// with the parameter.
+  /// @param[in] var_message The message posted by the browser.
+  virtual void HandleMessage(const pp::Var& var_message) {
+    // TODO(sdk_user): 1. Make this function handle the incoming message.
+  }
+};
+
+/// The Module class.  The browser calls the CreateInstance() method to create
+/// an instance of your NaCl module on the web page.  The browser creates a new
+/// instance for each <embed> tag with type="application/x-nacl".
+class HelloTutorialModule : public pp::Module {
+ public:
+  HelloTutorialModule() : pp::Module() {}
+  virtual ~HelloTutorialModule() {}
+
+  /// Create and return a HelloTutorialInstance object.
+  /// @param[in] instance The browser-side instance.
+  /// @return the plugin-side instance.
+  virtual pp::Instance* CreateInstance(PP_Instance instance) {
+    return new HelloTutorialInstance(instance);
+  }
+};
+
+namespace pp {
+/// Factory function called by the browser when the module is first loaded.
+/// The browser keeps a singleton of this module.  It calls the
+/// CreateInstance() method on the object you return to make instances.  There
+/// is one instance per <embed> tag on the page.  This is the main binding
+/// point for your NaCl module with the browser.
+Module* CreateModule() {
+  return new HelloTutorialModule();
+}
+}  // namespace pp