WebIDL bindings

  • Revision slug: Mozilla/WebIDL_bindings
  • Revision title: WebIDL bindings
  • Revision id: 293920
  • Created:
  • Creator: Bzbarsky
  • Is current revision? No
  • Comment one or more formatting changes

Revision Content

The WebIDL bindings are generated at build time based on two things: the actual WebIDL file and a configuration file that lists some metadata about how the WebIDL should be reflected into Gecko-internal code.

All WebIDL files should be placed in dom/webidl and added to the list in the WebIDL.mk file in that directory.

The configuration file, dom/bindings/Bindings.conf, is basically a Python dict that maps interface names to information about the interface, called a descriptor.  There are all sorts of possible options here that handle various edge cases, but most descriptors can be very simple.

Adding WebIDL bindings to a class


To add a WebIDL binding for interface MyInterface to a class MyClass that's supposed to implement that interface, you need to do the following:

  1. Inherit from nsWrapperCache and hook up the class to the cycle collector so it will trace the wrapper cache properly.
  2. Implement a GetParentObject override that, for any given instance of your class, returns the same object every time.  The idea is that walking the GetParentObject chain will eventually get you to a Window, so that every WebIDL object is associated with a particular Window.  For example, nsINode::GetParentObject returns the node's owner document.  The return value of GetParentObject must either singly-inherit from nsISupports or have a corresponding ToSupports() method that can produce an nsISupports from it.

C++ reflections of WebIDL constructs

 

C++ reflections of WebIDL operations (methods)

 

C++ reflections of WebIDL attributes

 

C++ reflections of WebIDL constructors

 

C++ reflections of WebIDL types

 

Throwing exceptions from WebIDL methods, getters, and setters

All WebIDL methods, getters, and setters that are not explicitly marked as infallible have an ErrorResult& argument as their last argument.  To throw an exception, simply call Throw() on the ErrorResult& and return from your C++ back into the binding code.

Note: at the moment Throw() can only be called with an error nsresult, but in the future we expect to add ways to communicate more informative exception strings and other metainformation about the exception.

Revision Source

<p>The <a class="external" href="http://www.w3.org/TR/WebIDL/" title="http://www.w3.org/TR/WebIDL/">WebIDL</a> bindings are generated at build time based on two things: the actual WebIDL file and a configuration file that lists some metadata about how the WebIDL should be reflected into Gecko-internal code.</p>
<p>All WebIDL files should be placed in <a class="external" href="http://mxr.mozilla.org/mozilla-central/source/dom/webidl/" title="http://mxr.mozilla.org/mozilla-central/source/dom/webidl/"><code>dom/webidl</code></a> and added to the list in the <a class="external" href="http://mxr.mozilla.org/mozilla-central/source/dom/webidl/WebIDL.mk" title="http://mxr.mozilla.org/mozilla-central/source/dom/webidl/WebIDL.mk"><code>WebIDL.mk</code></a> file in that directory.</p>
<p>The configuration file, <code><a class="external" href="http://mxr.mozilla.org/mozilla-central/source/dom/bindings/Bindings.conf" title="http://mxr.mozilla.org/mozilla-central/source/dom/bindings/Bindings.conf">dom/bindings/Bindings.conf</a>,</code> is basically a Python dict that maps interface names to information about the interface, called a <em>descriptor</em>.  There are all sorts of possible options here that handle various edge cases, but most descriptors can be very simple.</p>
<h2>Adding WebIDL bindings to a class</h2>
<p><br> To add a WebIDL binding for interface <code>MyInterface</code> to a class <code>MyClass</code> that's supposed to implement that interface, you need to do the following:</p>
<ol> <li>Inherit from <code>nsWrapperCache</code> and hook up the class to the cycle collector so it will trace the wrapper cache properly.</li> <li>Implement a GetParentObject override that, for any given instance of your class, returns the same object every time.  The idea is that walking the GetParentObject chain will eventually get you to a Window, so that every WebIDL object is associated with a particular Window.  For example, nsINode::GetParentObject returns the node's owner document.  The return value of GetParentObject must either singly-inherit from <code>nsISupports</code> or have a corresponding ToSupports() method that can produce an <code>nsISupports</code> from it.</li>
</ol><h2>C++ reflections of WebIDL constructs</h2>
<p> </p>
<h3>C++ reflections of WebIDL operations (methods)</h3>
<p> </p>
<h3>C++ reflections of WebIDL attributes</h3>
<p> </p>
<h3>C++ reflections of WebIDL constructors</h3>
<p> </p>
<h3>C++ reflections of WebIDL types</h3>
<p> </p>
<h2>Throwing exceptions from WebIDL methods, getters, and setters</h2>
<p>All WebIDL methods, getters, and setters that are not explicitly marked as infallible have an <code>ErrorResult&amp;</code> argument as their last argument.  To throw an exception, simply call <code>Throw()</code> on the <code>ErrorResult&amp;</code> and return from your C++ back into the binding code.</p>
<div class="note"><strong>Note:</strong> at the moment <code>Throw()</code> can only be called with an error <code>nsresult</code>, but in the future we expect to add ways to communicate more informative exception strings and other metainformation about the exception.</div>
Revert to this revision