IPDL/Five minute example

This page walks you through the steps of creating an IPDL protocol and writing the C++ code that implements the required interfaces. This guide walks you through the steps taken to implement the testing code in ipc/test-harness. You are encouraged to follow this guide step-by-step and change the code in ipc/test-harness as you follow along.

Write the IPDL specification

Put this in the file ipc/test-harness/Test.ipdl.

namespace mozilla {
namespace test {

sync protocol Test
{
both:
    sync Ping() returns (int status);

parent:
    GetValue(String key);
    GetValues(StringArray keys);
    sync SetValue(String key, String val) returns (bool ok);

child:
    TellValue(String key, String val);
    TellValues(StringArray keys, StringArray vals);

state START:
    recv Ping goto START;
    send Ping goto START;

    recv SetValue goto HAVE_VALUES;

state HAVE_VALUES:
    recv Ping goto HAVE_VALUES;
    send Ping goto HAVE_VALUES;

    recv SetValue goto HAVE_VALUES;

    recv GetValue goto TELLING_VALUE;
    recv GetValues goto TELLING_VALUES;

state TELLING_VALUE:
    send TellValue goto HAVE_VALUES;
state TELLING_VALUES:
    send TellValues goto HAVE_VALUES;
};

} // namespace test
} // namespace mozilla

Hook the IPDL file into our build system

• Add ipc/test-harness to the IPDLDIRS variable in ipc/ipdl/Makefile.in
• Create the file ipc/test-harness/ipdl.mk and add the following text to it.

IPDLSRCS = \
  Test.ipdl \
  $(NULL)

Create the C++ implementation stubs

• Run

ipc/test-harness$ python ../ipdl.py -d /tmp Test.ipdl

• Open /tmp/mozilla/test/TestProtocolParent.h. Look for the text "Skeleton implementation of abstract actor class."
  • copy the "Header file contents" into the file ipc/test-harness/TestParent.h
  • copy the "C++ file contents" into ipc/test-harness/TestParent.cpp
  • globally replace the text ActorImpl with TestParent in both files.
  • set up namespaces as you wish. The checked-in example puts TestParent in the mozilla::test namespace.
• Repeat the above step for TestProtocolChild.h and TestChild.(h, cpp)

Hook the C++ stubs into your build configuration

This is beyond the scope of this guide. See ipc/test-harness/Makefile.in for an example.

It's a good idea to check now that everything compiles.

Create the subprocess class

Create the files ipc/test-harness/TestProcessParent.h and ipc/test-harness/TestProcessParent.cpp with the following content.

// TestProcessParent.h
#ifndef mozilla_test_TestProcessParent_h
#define mozilla_test_TestProcessParent_h 1

#include "mozilla/ipc/GeckoChildProcessHost.h"

namespace mozilla {
namespace test {

class TestProcessParent : mozilla::ipc::GeckoChildProcessHost
{
public:
    TestProcessParent();
    ~TestProcessParent();

    /**
     * Asynchronously launch the plugin process.
     */
    // Could override parent Launch, but don't need to here
    //bool Launch();

private:
    DISALLOW_EVIL_CONSTRUCTORS(TestProcessParent);
};

} // namespace plugins
} // namespace mozilla
#endif // ifndef mozilla_test_TestProcessParent_h

// TestProcessParent.cpp
#include "mozilla/test/TestProcessParent.h"
using mozilla::ipc::GeckoChildProcessHost;

namespace mozilla {
namespace test {

TestProcessParent::TestProcessParent() :
    GeckoChildProcessHost(GeckoChildProcess_TestHarness)
{
}

TestProcessParent::~TestProcessParent()
{
}

} // namespace test
} // namespace mozilla

Now open nsXULAppAPI.h and add the new value GeckoChildProcess_TestHarness to the enumeration GeckoChildProcessType. (Yes, this sucks. Sorry.)

Hook this new code into your build system and verify that everything still compiles.