Creating a New Protocol

  • Revision slug: IPDL/Creating_a_New_Protocol
  • Revision title: Creating a New Protocol
  • Revision id: 76286
  • Created:
  • Creator: Benjamin Smedberg
  • Is current revision? No
  • Comment Mechanics... the tutorial has most of the meat.; page created, 345 words added

Revision Content

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 will need to edit or create an ipdl.mk file in the directory. See dom/ipc/ipdl.mk for an example. When creating a new ipdl.mk file, add the directory to ipc/ipdl/Makefile.in.

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 PContentProcess. 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 managed by PIFrameEmbedding 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.

Revision Source

<p>This is a quick-start on details of how to add a new IPDL protocol to the build. You should <a href="/en/IPDL/Tutorial" title="en/IPDL/Tutorial">know how IPDL works</a> first!</p>
<h3>Create the Protocol File</h3>
<p>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.</p>
<p>To hook up the file to the build, you will need to edit or create an ipdl.mk file in the directory. See <a class=" external" href="http://hg.mozilla.org/projects/electrolysis/file/tip/dom/ipc/ipdl.mk" title="http://hg.mozilla.org/projects/electrolysis/file/tip/dom/ipc/ipdl.mk">dom/ipc/ipdl.mk</a> for an example. When creating a new ipdl.mk file, add the directory to <a class=" external" href="http://hg.mozilla.org/projects/electrolysis/file/tip/ipc/ipdl/Makefile.in" title="http://hg.mozilla.org/projects/electrolysis/file/tip/ipc/ipdl/Makefile.in">ipc/ipdl/Makefile.in</a>.</p>
<h3>The Protocol Hierarchy</h3>
<p>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 PContentProcess. 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.</p>
<h3>Building the New Protocol</h3>
<p>To build the new protocol declaration and generate headers, make in ipc/ipdl:</p>
<pre>make -C <em>objdir</em>/ipc/ipdl
</pre>
<p>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 <code><em>objdir</em>/ipc/ipdl/_ipdlheaders</code> .</p>
<h3>Creating the Implementation</h3>
<p>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.</p>
<h3>Writing the Tests</h3>
<p>Protocols which managed by PIFrameEmbedding must be tested using the mochitest-chrome test framework with a <code>&lt;browser remote="true"&gt;</code>. 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.</p>
Revert to this revision