native_client_sdk/src/project_templates/cc/project_file.cc

   1 /// @file <PROJECT_NAME>.cc
   2 /// This example demonstrates loading, running and scripting a very simple NaCl
   3 /// module.  To load the NaCl module, the browser first looks for the
   4 /// CreateModule() factory method (at the end of this file).  It calls
   5 /// CreateModule() once to load the module code from your .nexe.  After the
   6 /// .nexe code is loaded, CreateModule() is not called again.
   7 ///
   8 /// Once the .nexe code is loaded, the browser than calls the CreateInstance()
   9 /// method on the object returned by CreateModule().  It calls CreateInstance()
  10 /// each time it encounters an <embed> tag that references your NaCl module.
  11 ///
  12 /// The browser can talk to your NaCl module via the postMessage() Javascript
  13 /// function.  When you call postMessage() on your NaCl module from the browser,
  14 /// this becomes a call to the HandleMessage() method of your pp::Instance
  15 /// subclass.  You can send messages back to the browser by calling the
  16 /// PostMessage() method on your pp::Instance.  Note that these two methods
  17 /// (postMessage() in Javascript and PostMessage() in C++) are asynchronous.
  18 /// This means they return immediately - there is no waiting for the message
  19 /// to be handled.  This has implications in your program design, particularly
  20 /// when mutating property values that are exposed to both the browser and the
  21 /// NaCl module.
  22
  23 #include <cstdio>
  24 #include <string>
  25 #include "ppapi/cpp/instance.h"
  26 #include "ppapi/cpp/module.h"
  27 #include "ppapi/cpp/var.h"
  28
  29 /// The Instance class.  One of these exists for each instance of your NaCl
  30 /// module on the web page.  The browser will ask the Module object to create
  31 /// a new Instance for each occurence of the <embed> tag that has these
  32 /// attributes:
  33 ///     type="application/x-nacl"
  34 ///     src="<PROJECT_NAME>.nmf"
  35 /// To communicate with the browser, you must override HandleMessage() for
  36 /// receiving messages from the borwser, and use PostMessage() to send messages
  37 /// back to the browser.  Note that this interface is entirely asynchronous.
  38 class <ProjectName>Instance : public pp::Instance {
  39  public:
  40   /// The constructor creates the plugin-side instance.
  41   /// @param[in] instance the handle to the browser-side plugin instance.
  42   explicit <ProjectName>Instance(PP_Instance instance) : pp::Instance(instance)
  43   {}
  44   virtual ~<ProjectName>Instance() {}
  45
  46   /// Handler for messages coming in from the browser via postMessage().  The
  47   /// @a var_message can contain anything: a JSON string; a string that encodes
  48   /// method names and arguments; etc.  For example, you could use
  49   /// JSON.stringify in the browser to create a message that contains a method
  50   /// name and some parameters, something like this:
  51   ///   var json_message = JSON.stringify({ "myMethod" : "3.14159" });
  52   ///   nacl_module.postMessage(json_message);
  53   /// On receipt of this message in @a var_message, you could parse the JSON to
  54   /// retrieve the method name, match it to a function call, and then call it
  55   /// with the parameter.
  56   /// @param[in] var_message The message posted by the browser.
  57   virtual void HandleMessage(const pp::Var& var_message) {
  58     // TODO(sdk_user): 1. Make this function handle the incoming message.
  59   }
  60 };
  61
  62 /// The Module class.  The browser calls the CreateInstance() method to create
  63 /// an instance of your NaCl module on the web page.  The browser creates a new
  64 /// instance for each <embed> tag with type="application/x-nacl".
  65 class <ProjectName>Module : public pp::Module {
  66  public:
  67   <ProjectName>Module() : pp::Module() {}
  68   virtual ~<ProjectName>Module() {}
  69
  70   /// Create and return a <ProjectName>Instance object.
  71   /// @param[in] instance The browser-side instance.
  72   /// @return the plugin-side instance.
  73   virtual pp::Instance* CreateInstance(PP_Instance instance) {
  74     return new <ProjectName>Instance(instance);
  75   }
  76 };
  77
  78 namespace pp {
  79 /// Factory function called by the browser when the module is first loaded.
  80 /// The browser keeps a singleton of this module.  It calls the
  81 /// CreateInstance() method on the object you return to make instances.  There
  82 /// is one instance per <embed> tag on the page.  This is the main binding
  83 /// point for your NaCl module with the browser.
  84 Module* CreateModule() {
  85   return new <ProjectName>Module();
  86 }
  87 }  // namespace pp