| {{+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" id="contents" style="display: none"> |
| <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><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> |
| <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 “Pepper <em>browser</em>”) are implemented in the browser and they are called |
| from your module. Interfaces starting with <code>PPP_</code> (“Pepper <em>plugin</em>”) 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 <stdlib.h> |
| #include <string.h> |
| #include "ppapi/c/pp_errors.h" |
| #include "ppapi/c/ppp.h" |
| // 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 "ppapi/c/ppb_instance.h" |
| #include "ppapi/c/ppp_instance.h" |
| #include "ppapi/c/ppb_input_event.h" |
| #include "ppapi/c/ppp_input_event.h" |
| |
| // 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 = { |
| &Instance_DidCreate, |
| // The definitions of these functions are not shown |
| &Instance_DidDestroy, |
| &Instance_DidChangeView, |
| &Instance_DidChangeFocus, |
| &Instance_HandleDocumentLoad |
| }; |
| return &instance_interface; |
| } |
| |
| if (strcmp(interface_name, PPP_INPUT_EVENT_INTERFACE) == 0) { |
| static PPP_InputEvent input_interface = { |
| // The definition of this function is not shown. |
| &Instance_HandleInput, |
| }; |
| return &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> |
| <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 “Hello tutorial” 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 “Hello tutorial” 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><embed></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 “Hello tutorial” 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& 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’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’t actually do anything. Subsequent documents in the |
| Developer’s Guide build on these code samples and add more interesting |
| functionality.</p> |
| </section> |
| |
| {{/partials.standard_nacl_article}} |