Creating a New Protocol

This is a quick-start on details of how to add a new IPDL protocol to the build. You should know how IPDL works first!

Create the Protocol File

The protocol file should live in the same directory as the code which will implement it. Protocol names start with P, and protocol files must be named PProtocolName.ipdl. IPDL protocols should be in the mozilla namespace or a sub-namespace.

To hook up the file to the build, you need to add your IPDL file to IPDL_SOURCES in the nearest moz.build file. See dom/ipc/moz.build for an example.

The Protocol Hierarchy

Unless you are working on some special project, your protocol will fit into the protocol hierarchy for multi-process plugins or tabs. The toplevel protocol for plugins is PPluginModule. The toplevel protocol for tabs is PContent. You should know what protocol will manage the new protocol and what lifetime issues that creates. If there is any doubt, ask on IRC in the #content channel.

Building the New Protocol

To build the new protocol declaration and generate headers, make in ipc/ipdl:

make -C objdir/ipc/ipdl

If there are any protocol-level errors, the IPDL compiler will print the relevant error messages and stop. To view the generated headers, look in objdir/ipc/ipdl/_ipdlheaders .

Creating the Implementation

The C++ implementation inherits from the abstract IPDL-generated classes PNewProtocolParent and PNewProtocolChild. It must implement abstract methods for receiving the appropriate messages on each side. The method signatures can be read from the generated PNewProtocolParent.h and PNewProtocolChild.h headers.

Writing the Tests

Protocols which are managed by PBrowser must be tested using the mochitest-chrome test framework with a <browser remote="true">. It is acceptable to use synchronous calls on JPW wrappers for testing purposes. It may be possible to test protocols unrelated to a particular window using the xpcshell testing framework, which has additional primitives in Electrolysis for launching and running JS commands in a content process.

Document Tags and Contributors

Tags: 
 Contributors to this page: jswisher, billmccloskey, MatthewKastor, ddahl, bsmedberg
 Last updated by: jswisher,