top

Hello World in C++

This tutorial performs a step by step decomposition of the NaCl "Hello world" demo application in C++.

Introduction

This article will discuss the structure of the most basic NaCl application written in the C++ programming language. The source code can be found in Tizen Studio or you can click here. The downloaded zip file can be imported into Tizen Studio or extracted and compiled using a separately downloaded NaCl toolchain. Build instructions are available in the demo package.

Important

Please note that you need at least pepper_42 toolchain version to compile this sample application.

We recommend to go through this tutorial along with analyzing the downloaded source code. This analysis will only focus on the native part of the NaCl application, the web part (.html and .js code) will be omitted because it’s trivial and almost identical for every demo presented on this website. If you want to learn more about NaCl or how to implement a basic NaCl application from scratch, read Getting Started with NaCl and How to Create a NaCl App.
There is also a cheat sheet for this demo available in Tizen Studio that explains the application functionality by highlighting the most important code fragments. Cheat sheets are available from the Help menu.



The analyzed application is a simple Hello World application. It waits for messages sent from the JavaScript and upon receiving one it prepares a reply message by appending the received string to the end of the reply. When such a reply is ready it sends the message back to the JavaScript where it’s handled by the appropriate function and displayed on the screen.

C++ Code Analysis

In order to write a NaCl application in C++ you have to implement two classes. The first one derives from the pp::Module class that implements module logic. The second one derives from the pp::Instance class and implements instance specific behavior. In this tutorial these classes are named respectively HelloWorldModule and HelloWorldInstance. There is also a need to implement one global function.

First we will focus on the Module, because it’s the main entry point of every NaCl application. The first function to be called when embedding a NaCl application on a webpage is the pp::CreateModule() function. It should just create a HelloWorldModule object and return a pointer to it. The function implementation needs to be placed inside a pp namespace. Its implementation is shown below:

namespace pp {
/**
 * This function is an entry point to a NaCl application.
 * It must be implemented.
 */
Module* CreateModule() {
  return new HelloWorldModule();
}
}  // namespace pp

The next thing we need to do is to implement the HelloWorldModule class itself. The module class needs to define only one method called CreateInstance(). The constructor and destructor are declared explicit in this demo, but they are left empty. The CreateInstance() method is responsible for creating a HelloWorldInstance object and returns a pointer to newly created instance. Implementation of the module is as follows:

/**
 * A NaCl app must have one class that implements <code>pp::Module</code>.
 * Basically you don't need to implement anything more than it's done in this
 * class. Just change names of HelloWorldModule and HelloWorldInstance classes
 * and implement you own class that inherits <code>pp::Instance</code>.
 */
class HelloWorldModule : public pp::Module {
 public:
  HelloWorldModule()
      : pp::Module() {
  }

  virtual ~HelloWorldModule() {
  }

  /**
   * This method is called every time a browser encounters an <embed> element
   * on a web page.
   * It has to be implemented to launch a NaCl application.
   */
  virtual pp::Instance* CreateInstance(PP_Instance instance) {
    return new HelloWorldInstance(instance);
  }
};

The last thing to do is the implementation of the HelloWorldInstance class itself. Classes that inherit from pp::Instance may overload multiple methods which are handlers to different plugin events. We only need to overload the HandleMessage() method in order to receive messages from the JavaScript. Additionally we need an explicit constructor for the class which takes one argument of PP_Instance type. This demo also implements a destructor and an Init() method. These are presented for good coding practice. The benefit of using Init() is a fact that it can return boolean to the browser indicating that Instance initialization failed or succeeded. In the HandleMessage()method we verify the received object, convert to the std::string object and append it to the original message. The it is sent to the JavaScript by calling the PostMessage() method.

const char* kEcho = "Echo from NaCl: ";

/**
 * This is a base of your NaCl application. There is one instance of
 * <code>pp::Instance</code> class object per <embed> element on a web page.
 */
class HelloWorldInstance : public pp::Instance {
 public:
  /**
   * Your constructor needs to call the base class <code>pp::Instance(PP_Instance)</code>
   * constructor to properly initialize itself - it's the only way because
   * <code>pp::Instance(PP_Instance)</code> is the only public constructor.
   */
  explicit HelloWorldInstance(PP_Instance instance)
      : pp::Instance(instance) {
  }

  virtual ~HelloWorldInstance() {
  }

  /**
   * Handles messages from JS sent by <code>nacl_module.postMessage(...)</code>.
   * @see <code>HandleMessage</code> in instance.h file for more details.
   */
  virtual void HandleMessage(const pp::Var& message) {
    if (message.is_string()) {
      PostMessage(kEcho + message.AsString() + "\n");
    }
  }

  /**
   * Initializes this instance with provided arguments listed in the <embed>
   * tag.
   * @see <code>Init()</code> in instance.h file for more details.
   */
  virtual bool Init(uint32_t argc, const char* argn[], const char* argv[]) {
    return true;
  }
};

Summary

This application can be compiled using Tizen Studio or manually with the make program. The application compiled manually can be run in Google Chrome. To run it on Smart TV Emulator you have to build it with Tizen Studio.

When the NaCl module loads, the Status field text will change to “Loaded”. In the NaCl messages section the log will appear: “Echo from NaCl: Hello World from JS” just like on the image below.