[NaCl SDK Docs] Check in the generated NaCl SDK Documentation.

native_client_sdk/src/doc/_developer.chrome.com_generated/devguide/coding/native-client-modules.html

Index: native_client_sdk/src/doc/_developer.chrome.com_generated/devguide/coding/native-client-modules.html
diff --git a/native_client_sdk/src/doc/_developer.chrome.com_generated/devguide/coding/native-client-modules.html b/native_client_sdk/src/doc/_developer.chrome.com_generated/devguide/coding/native-client-modules.html
new file mode 100644
index 0000000000000000000000000000000000000000..7c063f17e560891fed20faf43be9c0c05fa2b0bd
--- /dev/null
+++ b/native_client_sdk/src/doc/_developer.chrome.com_generated/devguide/coding/native-client-modules.html
@@ -0,0 +1,178 @@
+{{+bindTo:partials.standard_nacl_article}}
+
+<section id="native-client-modules">
+<span id="devcycle-native-client-modules"></span><h1 id="native-client-modules"><span id="devcycle-native-client-modules"></span>Native Client Modules</h1>
+<p>This document describes the classes and functions that you need to implement in
+a Native Client module in order for Chrome to load, initialize, and run it.  The
+requirements are the same regardless of whether or not the module uses PNaCl,
+but depend on whether the module is written in C or C++.</p>
+<div class="contents local topic" id="contents">
+<ul class="small-gap">
+<li><a class="reference internal" href="#introduction" id="id2">Introduction</a></li>
+<li><a class="reference internal" href="#writing-modules-in-c" id="id3">Writing modules in C</a></li>
+<li><a class="reference internal" href="#id1" id="id4">Writing modules in C++</a></li>
+</ul>
+</div>
+<section id="introduction">
+<h2 id="introduction">Introduction</h2>
+<p>Native Client modules do not have a <code>main()</code> function. When a module loads,
+the Native Client runtime calls the code in the module to create an instance and
+initialize the interfaces for the APIs the module uses. This initialization
+sequence depends on whether the module is written in C or C++ and requires that
+you implement specific functions in each case.</p>
+</section><section id="writing-modules-in-c">
+<h2 id="writing-modules-in-c">Writing modules in C</h2>
+<p>The C API uses a prefix convention to show whether an interface is implemented
+in the browser or in a module. Interfaces starting with <code>PPB_</code> (which can be
+read as &#8220;Pepper <em>browser</em>&#8221;) are implemented in the browser and they are called
+from your module. Interfaces starting with <code>PPP_</code> (&#8220;Pepper <em>plugin</em>&#8221;) are
+implemented in the module; they are called from the browser and will execute on
+the main thread of the module instance.</p>
+<p>When you implement a Native Client module in C you must include these components:</p>
+<ul class="small-gap">
+<li>The functions <code>PPP_InitializeModule</code> and <code>PPP_GetInterface</code></li>
+<li>Code that implements the interface <code>PPP_Instance</code> and any other C interfaces
+that your module uses</li>
+</ul>
+<p>For each PPP interface, you must implement all of its functions, create the
+struct through which the browser calls the interface, and insure that the
+function <code>PPP_GetInterface</code> returns the appropriate struct for the interface.</p>
+<p>For each PPB interface, you must declare a pointer to the interface and
+initialize the pointer with a call to <code>get_browser</code> inside
+<code>PPP_InitializeModule</code>.</p>
+<p>These steps are illustrated in the code excerpt below, which shows the
+implementation and initialization of the required <code>PPP_Instance</code>
+interface. The code excerpt also shows the initialization of three additional
+interfaces which are not required: <code>PPB_Instance</code> (through which the Native
+Client module calls back to the browser) and <code>PPB_InputEvent</code> and
+<code>PPP_InputEvent</code>.</p>
+<pre class="prettyprint">
+#include &lt;stdlib.h&gt;
+#include &lt;string.h&gt;
+#include &quot;ppapi/c/pp_errors.h&quot;
+#include &quot;ppapi/c/ppp.h&quot;
+// Include the interface headers.
+// PPB APIs describe calls from the module to the browser.
+// PPP APIs describe calls from the browser to the functions defined in your module.
+#include &quot;ppapi/c/ppb_instance.h&quot;
+#include &quot;ppapi/c/ppp_instance.h&quot;
+#include &quot;ppapi/c/ppb_input_event.h&quot;
+#include &quot;ppapi/c/ppp_input_event.h&quot;
+
+// Create pointers for each PPB interface that your module uses.
+static PPB_Instance* ppb_instance_interface = NULL;
+static PPB_InputEvent* ppb_input_event_interface = NULL;
+
+// Define all the functions for each PPP interface that your module uses.
+// Here is a stub for the first function in PPP_Instance.
+static PP_Bool Instance_DidCreate(PP_Instance instance,
+                                  uint32_t argc,
+                                  const char* argn[],
+                                  const char* argv[]) {
+        return PP_TRUE;
+}
+// ... more API functions ...
+
+// Define PPP_GetInterface.
+// This function should return a non-NULL value for every interface you are using.
+// The string for the name of the interface is defined in the interface's header file.
+// The browser calls this function to get pointers to the interfaces that your module implements.
+PP_EXPORT const void* PPP_GetInterface(const char* interface_name) {
+        // Create structs for each PPP interface.
+        // Assign the interface functions to the data fields.
+         if (strcmp(interface_name, PPP_INSTANCE_INTERFACE) == 0) {
+                static PPP_Instance instance_interface = {
+                        &amp;Instance_DidCreate,
+                        // The definitions of these functions are not shown
+                        &amp;Instance_DidDestroy,
+                        &amp;Instance_DidChangeView,
+                        &amp;Instance_DidChangeFocus,
+                        &amp;Instance_HandleDocumentLoad
+                };
+                return &amp;instance_interface;
+         }
+
+         if (strcmp(interface_name, PPP_INPUT_EVENT_INTERFACE) == 0) {
+                static PPP_InputEvent input_interface = {
+                        // The definition of this function is not shown.
+                        &amp;Instance_HandleInput,
+                };
+                return &amp;input_interface;
+         }
+         // Return NULL for interfaces that you do not implement.
+         return NULL;
+}
+
+// Define PPP_InitializeModule, the entry point of your module.
+// Retrieve the API for the browser-side (PPB) interfaces you will use.
+PP_EXPORT int32_t PPP_InitializeModule(PP_Module a_module_id, PPB_GetInterface get_browser) {
+        ppb_instance_interface = (PPB_Instance*)(get_browser(PPB_INSTANCE_INTERFACE));
+        ppb_input_event_interface = (PPB_InputEvent*)(get_browser(PPB_INPUT_EVENT_INTERFACE));
+        return PP_OK;
+}
+</pre>
+</section><section id="id1">
+<h2 id="id1">Writing modules in C++</h2>
+<p>When you implement a Native Client module in C++ you must include these components:</p>
+<ul class="small-gap">
+<li>The factory function called <code>CreateModule()</code></li>
+<li>Code that defines your own Module class (derived from the <code>pp::Module</code>
+class)</li>
+<li>Code that defines your own Instance class (derived from the <code>pp:Instance</code>
+class)</li>
+</ul>
+<p>In the &#8220;Hello tutorial&#8221; example (in the <code>getting_started/part1</code> directory of
+the NaCl SDK), these three components are specified in the file
+<code>hello_tutorial.cc</code>. Here is the factory function:</p>
+<pre class="prettyprint">
+namespace pp {
+Module* CreateModule() {
+  return new HelloTutorialModule();
+}
+}
+</pre>
+<p>The <code>CreateModule()</code> factory function is the main binding point between a
+module and the browser, and serves as the entry point into the module. The
+browser calls <code>CreateModule()</code> when a module is first loaded; this function
+returns a Module object derived from the <code>pp::Module</code> class. The browser keeps
+a singleton of the Module object.</p>
+<p>Below is the Module class from the &#8220;Hello tutorial&#8221; example:</p>
+<pre class="prettyprint">
+class HelloTutorialModule : public pp::Module {
+ public:
+  HelloTutorialModule() : pp::Module() {}
+  virtual ~HelloTutorialModule() {}
+
+  virtual pp::Instance* CreateInstance(PP_Instance instance) {
+    return new HelloTutorialInstance(instance);
+  }
+};
+</pre>
+<p>The Module class must include a <code>CreateInstance()</code> method. The browser calls
+the <code>CreateInstance()</code> method every time it encounters an <code>&lt;embed&gt;</code> element
+on a web page that references the same module. The <code>CreateInstance()</code> function
+creates and returns an Instance object derived from the <code>pp::Instance</code> class.</p>
+<p>Below is the Instance class from the &#8220;Hello tutorial&#8221; example:</p>
+<pre class="prettyprint">
+class HelloTutorialInstance : public pp::Instance {
+ public:
+  explicit HelloTutorialInstance(PP_Instance instance) : pp::Instance(instance) {}
+  virtual ~HelloTutorialInstance() {}
+
+  virtual void HandleMessage(const pp::Var&amp; var_message) {}
+};
+</pre>
+<p>As in the example above, the Instance class for your module will likely include
+an implementation of the <code>HandleMessage()</code> function. The browser calls an
+instance&#8217;s <code>HandleMessage()</code> function every time the JavaScript code in an
+application calls <code>postMessage()</code> to send a message to the instance. See the
+<a class="reference internal" href="/native-client/devguide/coding/message-system.html"><em>Native Client messaging system</em></a> for more information about
+how to send messages between JavaScript code and Native Client modules.</p>
+<p>While the <code>CreateModule()</code> factory function, the <code>Module</code> class, and the
+<code>Instance</code> class are required for a Native Client application, the code
+samples shown above don&#8217;t actually do anything. Subsequent documents in the
+Developer&#8217;s Guide build on these code samples and add more interesting
+functionality.</p>
+</section></section>
+
+{{/partials.standard_nacl_article}}