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.
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:
- Inherit from
nsWrapperCacheand hook up the class to the cycle collector so it will trace the wrapper cache properly.
- 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
nsISupportsor have a corresponding ToSupports() method that can produce an
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.
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.