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
GetParentObjectoverride that, for any given instance of your class, returns the same object every time. The idea is that walking the
GetParentObjectchain will eventually get you to a Window, so that every WebIDL object is associated with a particular Window. For example,
nsINode::GetParentObjectreturns the node's owner document. The return value of
GetParentObjectmust either singly-inherit from
nsISupportsor have a corresponding
ToSupports()method that can produce an
nsISupportsfrom it. If many instances of
MyClassare expected to be created quicky, the return value of
GetParentObjectshould itself inherit from
nsWrapperCachefor optimal performance.
- Add the WebIDL for
dom/webidland to the list in
- Add an entry to
dom/bindings/Bindings.confthat sets the
MyClassis not in the header file one gets by replacing '::' with '/' and appending '
.h', the add a corresponding
- Implement a
MyClassthat just calls through to
'wrapperCache': Falseto your descriptor. If your object already has classinfo, it should be using the
nsNewDOMBindingNoWrapperCacheSHscriptable helper in this case. You will need to flag the functions that return your object as
[Creator]in the WebIDL.
C++ reflections of WebIDL constructs
C++ reflections of WebIDL operations (methods)
A WebIDL operation is turned into a method call on the underlying C++ object. The return type is determined as described below under
C++ reflections of WebIDL attributes
C++ reflections of WebIDL constructors
C++ reflections of WebIDL argument 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.