Mozilla gives you the opportunity not only to use a very powerful and complete DOM support, but also to work on a world-class implementation of one of the greatest Internet technology ever created.

Mozilla's DOM is coded almost entirely in C++. Seriously hacking on it requires excellent knownledge of C++ and XPCOM, Mozilla's own component model. In this document I will try to outline the main aspects of the implementation, begining with the Class Info mechanism, which lies at the heart of the DOM, then with the description of various interfaces and classes. Since I am myself still learning how it works, don't expect this to be a complete reference quite yet. If you can contribute any time or knowledge to this document, it is greatly appreciated!

Target audience: People interested in learning how the DOM is implemented. Prior knowledge of C++ and XPCOM is assumed. If you don't know XPCOM yet, and would like to be able to read this document quickly, you can read the introduction to XPCOM for the DOM. Otherwise, for more detailed XPCOM documentation, please see the XPCOM project page.

• Chapter 1. The Class Info mechanism.
  • 1.A. Introduction to Class Info
  • 1.B. Interface flattening
  • 1.C. Helper Classes
  • 1.D. The nsDOMClassInfo class
  • 1.E. nsDOMClassInfo::Init()
  • 1.F. nsDOMClassInfo::GetClassInfoInstance()
  • 1.G. nsWindowSH::GlobalResolve()
  • 1.H. User's Guide to Class Info
  • 1.I. Scriptable Helper flags
  • 1.J. Security features implementation

Chapter One: Class Info and Helper Classes

1.A. Introduction to Class Info

Class Info is what gives the DOM classes their correct behavior when used through XPConnect. It lies at the heart of the famous "XPCDOM landing" that happened in May. We will talk alot about XPConnect in this document, since it is so important for the DOM. By "correct behavior", I mean "the intended behavior with respect to the specification or de facto standard". We will see that Class Info is mainly used to implement the DOM Level 0. The W3C DOM is mainly implemented in IDL. The goals of Class Info are twofolds: Interface flattening, and implementing behaviors that are not possible with IDL alone.

A brief introduction to JavaScript and XPConnect.

Before we begin the explanation of Class Info, I'd like to introduce quickly the JavaScript engine and XPConnect. In JavaScript, there is no knowledge of types, like there is in C++. A function for example can be represented by a JSFunction, a JSObject, a jsval, ... This means that when we use the DOM from JavaScript, we pass arguments that have no type. However, since the DOM is coded in C++, we expect to receive an argument of the correct type for our function. This is one of the jobs of XPConnect. XPConnect will "wrap" the argument in a wrapper that will be of the type expected by our C++ function. Similarly, then return type of the C++ function will be wrapped by XPConnect so that JavaScript can use it safely.

When, in JavaScript, a client tries to access a DOM object or a DOM method on a DOM object, the JS engine asks XPConnect to search for the relevant C++ method to call. For example, when we ask for |document.getElementById("myID");|, XPConnect will find that |document| is a property of the window object, so it will look on the interface nsIDOMWindow, and it will find the GetDocument() method. The return value of GetDocument() is a nsIDOMDocument. So XPConnect will then try to find a method named GetElementById() on the nsIDOMDocument interface. And indeed it will find it, and thus call it.

This is the schema used most of the time when using W3C DOM objects and methods. It is however different for some DOM Level 0 objects and methods. I'll take two very different examples. The first one is the window.location object (the same holds true for document.location, actually). We can change the URL of the current window by assigning window.location. In IDL, location is declared to be a readonly attribute. This is because, if we had a SetLocation() method, it would take an nsIDOMLocation parameter, and not a URL string. Instead, in the helper class for the window object (nsWindowSH, see the next Section), we define the GetProperty() member function. GetProperty() is a function used by XPConnect when we are setting an unknown property on the object (window, in our case). In GetProperty(), we check if the property being set is "location". If that is the case, we call nsIDOMLocation::SetHref(). In fact, when setting window.location, we really set window.location.href. This is all possible thanks to the magic of the interaction between XPConnect and the DOM.

The second example is the history object. Other browsers allow the history object to be used like an array, e.g. history[1]. The behavior "act as an array" cannot be reflected in the IDL itself. Fortunately, XPConnect provides us with a way to make our class available as an array in JavaScript. I'm talking about the "scriptable flags". The nsIXPCScriptable interface, implemented by the nsDOMClassInfo class (see Section) defines several flags, one of which is the WANT_GETPROPERTY flag. When set, it allows us to define a GetProperty() function on nsHistorySH (the helper class for the history object), which will handle the array behavior. Indeed, it will forward the call history[1] to history.item(1), which is defined in the IDL and easily coded. The relevant code is at http://lxr.mozilla.org/seamonkey/source/dom/src/base/nsDOMClassInfo.cpp, around line 4520.

These two examples demonstrate the power of the DOM combined with XPConnect and the JavaScript engine. The possibilities are endless. "What do you want to code today?" ;-)

All the DOM classes are listed in an enum defined in nsIDOMClassInfo.h, nsDOMClassInfoID. There are classes for the DOM0, Core DOM, HTML, XML, XUL, XBL, range, css, events, etc...

The array sClassInfoData, defined in nsDOMClassInfo.cpp, maps each DOM class to its helper class and to the interfaces that are exposed to JavaScript. It is an array of type nsDOMClassInfoData, which is a structure defined in nsIDOMClassInfo.h. The array uses two macros to define its items: NS_DEFINE_CLASSINFO_DATA and NS_DEFINE_CLASSINFO_DATA_WITH_NAME. The first one calls the second one. The first argument passed to NS_DEFINE_CLASSINFO_DATA_WITH_NAME, _class, is used for debug purposes. The second argument, _name, is the name that should appear in JavaScript. The third argument, _helper, is the name of the helper class for this DOM class. Helper classes are detailed in Section 1.C. The fourth and last argument, _flags, is a bitvector of nsIXPCScriptable flags. The macros for those flags are defined nsDOMClassInfo.cpp. The flags give special behavior through XPConnect. See also Section 1.I.

The nsDOMClassInfoData objects are created in the sClassInfoData array by explicitly initializing it. Here is the description of the structure:

• const char *mName: C-style string that is passed as second argument to the macro. It is the name of the JavaScript object that will be available in the browser through the DOM.

• union {
    nsDOMClassInfoConstructorFnc mConstructorFptr;
    nsDOMClassInfoExternalConstructorFnc mExternalConstructorFptr;
  } u;
  

  This union is a pointer to a function typedef'ed:
  typedef nsIClassInfo* (*nsDOMClassInfoConstructorFnc)(nsDOMClassInfoID aID);
  or
  typedef nsIClassInfo* (*nsDOMClassInfoExternalConstructorFnc) (const char* aName); It is initialized with the doCreate member function of the helper class passed as third argument to the macro.
• nsIClassInfo *mCachedClassInfo: mCachedClassInfo holds an nsIClassInfo pointer to an instance of the relevant helper class.
• const nsIID *mProtoChainInterface: Pointer to the IID of the first interface available to JavaScript clients. This is used in global resolve functions, when XPConnect has to find the member function to call.
• const nsIID **mInterfaces: Pointer to the first element of an array of pointers to all the interfaces available through JS for this class.
• PRUInt32 mScriptableFlags: 31; : The fourth argument passed to NS_DEFINE_CLASSINFO_DATA_WITH_NAME.
• PRBool mHasClassInterface: 1; : Help me?

mName and mConstructorFptr, mScriptableFlags and mHasInterface are initialized by NS_DEFINE_CLASSINFO_DATA_WITH_NAME. mCachedClassInfo, mProtoChainInterface and mInterfaces, however, are initialized in nsDOMClassInfo::Init(), described in Section 1.E.

1.B. Interface flattening

One of the nicest -- and most important -- features of the XPConnect'ed DOM is the interface flattening. "Interface flattening is the ability to call methods on an object regardless of the interface it was defined on." For example, when we have the document object in JavaScript, we can call indistinctly document.getElementById(), or document.addEventListener(), although they are defined on two different interfaces ( DOMDocument and DOMEventTarget. Needless to say this is critical for the use of the DOM in real-world content.

In Mozilla interface flattening is obtained through the use of the nsIClassInfo interface. nsIClassInfo stores the interfaces available for an object and later on XPConnect uses those interfaces to lookup the right method to call.

The great thing is that one can easily see the interfaces available from JS through interface flattening by looking at the code. The interesting part is in nsDOMClassInfo::Init(). There we have a long list of macros. There is one set of macros per DOM class. There you can see, for each object, what interfaces are part of the "flattened" set. As an example, on the window object, we can call all the methods defined on the following interfaces: nsIDOMWindow, nsIDOMWindowInternal, nsIDOMJSWindow, nsIDOMEventReciever, nsIDOMEventTarget, nsIDOMViewCSS, and nsIDOMAbstractView. Again, without caring on what interface the method is defined. See Section 1.E for more information about the Init() method.

For the W3C DOM (Level 1, 2, 3) objects, for each object there is one "standards-compliant" interface, which is exactly the same as the W3C one, named nsIDOM<ObjectName>.idl, and a mozilla-specific extension interface, named nsIDOMNS<ObjectName>.idl, for compatibility with DOM Level 0. For example, the HTML "area" element has the following interfaces in its flattened set: nsIDOMHTMLAreaElement and nsIDOMNSHTMLAreaElement.

1.C. Helper Classes

nsDOMClassInfo.h defines several new classes. They all end in "SH", for "Scriptable Helper" e.g. nsWindowSH, nsElementSH, ... . We call these classes the "Helper Classes". All the helper classes inherit from the nsDOMClassInfo class. To demonstrate this, look in nsDOMClassInfo.h. We can see that the nsEventRecieverSH helper class inherits from nsDOMGenericSH:

class nsEventRecieverSH : public nsDOMGenericSH.

And nsDOMGenericSH is typedef'ed to nsDOMClassInfo:

typedef nsDOMClassInfo nsDOMGenericSH;.

Another example is nsWindowSH, which inherits from nsEventReceiverSH, thus inheriting from nsDOMClassInfo.

Each DOM class is mapped to its helper class during the initialization of the sClassInfoData array.

Each helper class has a public doCreate member function that is called by GetClassInfoInstance (see also Section 1.F) to create a new instance of the class if needed. Remember that the doCreate member function is called through a pointer to a function named mConstructorFptr, a member of the nsDOMClassInfoData struct. An instance of a helper class is created the first time XPConnect needs access to the flattened set of interfaces of an object. The instance is then cached for further use.

Most of the helper classes implement one or more nsIXPCScriptable methods. Those methods are used by XPConnect when we require something from JavaScript that was not defined in IDL. For example, GetProperty() is used when retrieving an attribute that was not defined in IDL, and NewResolve() is used when resolving for the first time an attribute or method that was not previously resolved. Please see the nsIXPCScriptable interface for more information.

1.D. The nsDOMClassInfo class

The heart of Class Info is the nsDOMClassInfo class, defined in nsDOMClassInfo.h. It implements two interfaces besides nsISupports: nsIXPCScriptable and nsIClassInfo.

We already know what nsIXPCScriptable is used for (see the previous Section).

nsIClassInfo is an XPCOM interface, very well described by Mike Shaver in this overview of nsIClassInfo. Basically it contains convenient methods to find out about the interfaces an object promises to support. In our case, this list of interfaces will be populated by "Class Info". See also Section 1.E on the Init() function and Section 1.B on interface flattening.

We saw in Section 1.C that nsDOMClassInfo is the base class for all the helper classes. Let's see what it's made of. Let's begin with the public interface.

• Constructor: It is called for each created helper class through the member initialization list. It simply initializes the mID data member with the aID argument.
• The nsIXPCScriptable, nsISupports, and nsIClassInfo member functions, declared with NS_DECL_X macros.
• static nsIClassInfo* GetClassInfoInstance(nsDOMClassInfoID aID):
  this helper method returns a non-refcounted nsIClassInfo pointer to an instance of the helper class corresponding to the ID passed in. The implementation is detailed in Section 1.F.
• static nsIClassInfo* GetClassInfoInstance(nsDOMClassInfoData* aData);:
  this helper method returns a non-refcounted nsIClassInfo pointer to an instance of the helper class corresponding to the Data passed in. The implementation is detailed in Section 1.F.
• static void ShutDown():
  Releases the interface pointers.
• static nsIClassInfo* doCreate(nsDOMClassInfoData* aData):
  Inline function that returns a nsIClassInfo pointer to a new instance of the nsDOMClassInfo class.
• static nsresult WrapNative(...): XPConnect fu, not our problem.
• static nsresult ThrowJSException(JSContext *cx, nsresult aResult);:
  help me!
• static nsresult InitDOMJSClass(JSContext *cx, JSObject *obj);:
  help me!
• static JSClass sDOMJSClass;:
  help me!

Protected section:

• const nsDOMClassInfoData* mData;: help me!
• static nsresult Init(): Called only once, it is used to initialize the remaining members of the nsDOMClassInfoData structure, as mentioned above. Once called, Init() sets sIsInitialized to true, to remember that the initialization has been performed. The implementation is described in Section 1.E.
• static nsresult RegisterClassName(PRInt32 aDOMClassInfoID): help me!
• static nsresult RegisterClassProtos(PRInt32 aDOMClassInfoID): help me!
• static nsresult RegisterExternalClasses();: help me!
• nsresult ResolveConstructor(JSContext *cx, JSObject *obj, JSObject **objp);: help me!
• static PRInt32 GetArrayIndexFromId(JSContext *cx, jsval id, PRBool *aIsNumber =
nsnull):
  If the JS value is an integer, then *aIsNumber is true, and the integer is returned. Else, *aIsNumber is false and -1 is returned.
• static inline PRBool IsReadonlyReplaceable(jsval id) { ... }: help me!
• static inline PRBool IsWritableReplaceable(jsval id) { ... }: help me!
• nsresult doCheckPropertyAccess(...): help me! (bug 90757)
• static JSClass sDOMConstructorProtoClass: XPConnect fu to expose the DOM objects constructors to JavaScript.
• static JSFunctionSpec sDOMJSClass_methods[];: help me! (bug 91557)
• static nsIXPConnect *sXPConnect: Used to call nsIXPConnect methods that we need. Initialized in Init().
• static nsIScriptSecurityManager *sSecMan: Used by the DOM security engine. Initialized in Init().
• static nsresult DefineStaticJSVals(JSContext *cx);: Used to define all the static JSString data members of nsDOMClassInfo.
• static PRBool sIsInitialized:
  Keeps track of wether Class Info was already initialized, because Init() shouldn't be called twice.
• static jsval *sX_id: strings used in the global resolve methods for comparison with the passed in arguments. They represent special words for the DOM. Initialized by DefineStaticJSVals().
• static const JSClass *sObjectClass: help me!
• static PRBool sDoSecurityCheckInAddProperty;: help me!

1.E. nsDOMClassInfo::Init()

This method is to be called only once. Its purpose is, well, to initialize... It does a lot of different things: Fill the blanks in the sClassInfoData array, initialize the sXPConnect and sSecMan data members, create a new JavaScript Context, define the JSString data members, and register class names and class prototypes. Finally it sets sIsInitialized to true. The actions that concern the DOM are described below.

First, the call to CallGetService() initializes sXPConnect. Then the Script Security Manager (sSecMan) is initialized. GetSafeJSContext() grabs us a cool JS context to run our JavaScript code in. The part about ComponentRegistrar is designed to allow external modules (in this case XPath) to be included in DOMClassInfo and as such benefit from the JavaScript benefits it provides. After that, we fill the blanks in the sClassInfoData array.

If you remember the discussion in the introduction to Class Info, there is the main array, sClassInfoData, filled with objects of type nsDOMClassInfoData. However when the array is created, three data members of the structure are left as null pointers: mCachedClassInfo, mProtoChainInterface, and mInterfaces. Init() uses a set of macros to fill the blanks: the DOM_CLASSINFO_MAP family. Each DOM class needs to use these macros, otherwise bad things will happen. I will use the example of the Window class to illustrate the use of the macros. Here is the relevant piece of code.

DOM_CLASSINFO_MAP_BEGIN(Window, nsIDOMWindow)
  DOM_CLASSINFO_MAP_ENTRY(nsIDOMWindow)
  ...
  DOM_CLASSINFO_MAP_ENTRY(nsIDOMAbstractView)
DOM_CLASSINFO_MAP_END

DOM_CLASSINFO_MAP_BEGIN(_class, _interface) maps to _DOM_CLASSINFO_MAP_BEGIN(_class, &NS_GET_IID(_interface), PR_TRUE). NS_GET_IID is a macro that expands to the IID of the interface passed in. We pass the address of this nsIID object to the second macro.

#define _DOM_CLASSINFO_MAP_BEGIN(_class, _ifptr, _has_class_if)
{
  nsDOMClassInfoData &d = sClassInfoData[eDOMClassInfo_##_class##_id];
  d.mProtoChainInterface = _ifptr;
  d.mHasClassInterface = _has_class_if;
  static const nsIID *interface_list[] = {

In this macro, |d| is a reference to the entry of the sClassInfoData array that corresponds to the class passed as an argument to the macro. The mProtoChainInterface member pointer is initialized to the address of the IID of the interface passed as an argument to DOM_CLASSINFO_MAP_BEGIN. A static array of pointers to objects of type nsIID is then declared. It is initialized explicitly with the DOM_CLASSINFO_MAP_ENTRY macro (see below).

There are two other similar macros :

#define DOM_CLASSINFO_MAP_BEGIN_NO_PRIMARY_INTERFACE(_class)
  _DOM_CLASSINFO_MAP_BEGIN(_class, nsnull, PR_TRUE)

This macro is used if the DOM class (for example XMLHTTPRequest) does not have any interface, yet you want the XMLHTTPRequest object to be available from JavaScript.

#define DOM_CLASSINFO_MAP_BEGIN_NO_CLASS_IF(_class, _interface)
  _DOM_CLASSINFO_MAP_BEGIN(_class, &NS_GET_IID(_interface), PR_FALSE)

This macro should be used for DOM classes that have no "leaf" interface. For example, there is no HTMLSpanElement in the W3C DOM specification. Therefore, the first interface in the prototype chain for the span element is HTMLElement. However we do want to be able to access HTMLSpanElement to modify it. This macro allows you to do that. See bug 92071 for more information. Let's now see how to specify the interfaces available from JavaScript for a particular DOM class.

#define DOM_CLASSINFO_MAP_ENTRY(_if)
    &NS_GET_IID(_if),

The array of pointers interface_list is filled with the addresses of the IID's of all the interfaces passed as arguments to the macro. In our Window example, the interfaces are nsIDOMWindow, nsIDOMJSWindow, nsIDOMWindowInternal, nsIDOMEventReciever, nsIDOMEventTarget, nsIDOMViewCSS, and nsIDOMAbstractView. Please see Section 1.B on interface flattening for an explanation of the use of these interfaces. The initialization for a class is finished by the DOM_CLASSINFO_MAP_END macro.

#define DOM_CLASSINFO_MAP_END
    nsnull
  };
  d.mInterfaces = interface_list;
}

The interface_list array is terminated by a null pointer. The line d.mInterfaces = interface_list assigns to mInterfaces the address of the first element of the interface_list array, which is itself a pointer. mInterfaces is thus correctly a pointer to a pointer to an object of type nsIID.

To define the jsvals, Init() simply calls DefineStaticJSVals(). To register the class names and class protos, Init() simply calls RegisterClassProtos and RegisterClassNames. This process might be described in a later document. Finally, sIsInitialized is set to true. Init() returns NS_OK if everything went fine.

1.F. nsDOMClassInfo::GetClassInfoInstance()

There are two versions of this function. The first one takes an ID as argument, the second takes a Data struct as argument. This function is very important so let's take a closer look at it. Here is the function definition.

nsIClassInfo* nsDOMClassInfo::GetClassInfoInstance(nsDOMClassInfoID aID)
{
  if(!sIsInitialized) {
    nsresult rv = Init();
  }

  if(!sClassInfoData[aID].mCachedClassInfo) {
    nsDOMClassInfoData &data = sClassInfoData[aID];
    data.mCachedClassInfo = data.u.mConstructorFptr(&data);
    NS_ADDREF(data.mCachedClassInfo);
  }

  return sClassInfoData[aID].mCachedClassInfo;
}

Here is the short explanation:
This method returns the mCachedClassInfo member of the nsDOMClassInfoData structure that corresponds to aID in the sClassInfoData array, if it exists, i.e. if this method has been called before. If it is called for the first time however, mCachedClassInfo is still a null pointer, and the function will create a new instance of the relevant helper class, and cache it in the mCachedClassInfo pointer, then return it.

And for those interested, here the longer explanation.

The first time GetClassInfoInstance() is called, passing in an aID, mCachedClassInfo for that class will still be null. The body of the "if" clause is thus executed. We initialize "data" to be a reference to the nsDOMClassInfoData object that corresponds to the DOM class we want to "help". On the next line, there is a call to data.mConstructorFptr(aID), which, if you remember the introduction to Class Info, maps to the doCreate static member function of the relevant helper class. doCreate creates a new instance of the helper class, and returns a pointer to the nsIClassInfo interface, which is then assigned into mCachedClassInfo. mCachedClassInfo is AddRef'ed to keep it from being destroyed without our permission. Finally it is returned.

On subsequent calls to this function with the same aID passed in, mCachedClassInfo will still be there, and thus the creation of a new helper class will not be necessary.

"Where is GetClassInfoInstance used and why should I use it", would be an excellent question for now. The short answer is, "to implement the QueryInterface for nsIClassInfo. Indeed, a QueryInterface to nsIClassInfo cannot be implemented the same way as other interfaces. If you don't like macros, you can see the full QueryInterface implementation in nsXMLElement.cpp. Two other GetClassInfoInstance member functions are defined in Mozilla, as member of class nsContentUtils and class nsDOMSOFactory. Both of these methods end up calling nsDOMClassInfo::GetClassInfoInstance so there is no real point in documenting them further. GetClassInfoInstance is used in the NS_INTERFACE_MAP_ENTRY_CONTENT_CLASSINFO macro, which is used to implement QueryInterface for the nsIClassInfo interface in most of the DOM classes, and in the NS_DOM_INTERFACE_MAP_ENTRY_CLASSINFO macro, which is used to implement QueryInterface for the nsIClassInfo interface in most global object properties.

I think that's all there is to say about this function. If you think of something else don't hesitate to contact me, as usual.

1.G. nsWindowSH::GlobalResolve()

This Section will describe in detail the absolutely horrific GlobalResolve() member function of the nsWindowSH helper, as an example of those functions. This is not for the faint of heart, and is not absolutely necessary, so you might want to skip this Section if you don't have too much time (and I suppose you don't).

1.H. User's guide to Class Info

1. How to add a new interface to an existing DOM object
2. How to expose a new DOM object to JavaScript
3. How to override the default behavior of XPConnect on DOM objects
4. How to make a property "replaceable" (To be written)
5. Examples (To be written)

3553     if (flags & JSRESOLVE_ASSIGNING) {
// Only define the property if we are setting it.
3554       if (str == sLocation_id) {
// Setting the location property.
3555         nsCOMPtr<nsIDOMWindowInternal>
window(do_QueryInterface(native));
3556         NS_ENSURE_TRUE(window, NS_ERROR_UNEXPECTED);
3557 
3558         nsCOMPtr<nsIDOMLocation> location;
3559         rv = window->GetLocation(getter_AddRefs(location));
3560         NS_ENSURE_SUCCESS(rv, rv);
// Use the DOM to get the Location object of the window object.
3561 
3562         jsval v;
3563 
3564         rv = WrapNative(cx, obj, location, NS_GET_IID(nsIDOMLocation),
&v);
// This XPConnect method creates a wrapper for the Location object on the //
Window object.
3565         NS_ENSURE_SUCCESS(rv, rv);
3566 
3567         if (!::JS_DefineUCProperty(cx, obj, ::JS_GetStringChars(str),
3568                                    ::JS_GetStringLength(str), v, nsnull,
3569                                    nsnull, 0)) {
3570           return NS_ERROR_FAILURE;
3571         }
// This JS API call defines the "location" property on the window object, its
// value being the XPConnect wrapper for the Location object.
3572
3573         *objp = obj;
3574 
3575         return NS_OK;
3576       }

2894     if (str == sLocation_id) {
// Setting the location property
2895       JSString *val = ::JS_ValueToString(cx, *vp);
2896       NS_ENSURE_TRUE(val, NS_ERROR_UNEXPECTED);
// Convert the value assigned to location (i.e. the url) to a JSString.
2897 
2898       nsCOMPtr<nsISupports> native;
2899       wrapper->GetNative(getter_AddRefs(native));
// Get the pointer to the content object that was wrapped.
2900 
2901       nsCOMPtr<nsIDOMWindowInternal>
window(do_QueryInterface(native));
2902       NS_ENSURE_TRUE(window, NS_ERROR_UNEXPECTED);
// QueryInterface to have a nsIDOMWindowInternal pointer to call
// GetLocation() on it.
2903 
2904       nsCOMPtr<nsIDOMLocation> location;
2905       nsresult rv = window->GetLocation(getter_AddRefs(location));
2906       NS_ENSURE_SUCCESS(rv, rv);
// Get the Location object for this window.
2907 
2908       nsDependentString href(NS_REINTERPRET_CAST(PRUnichar *,
2909                                                  ::JS_GetStringChars(val)),
2910                              ::JS_GetStringLength(val));
// Convert the JSString to a string that can be passed to SetHref()
2911 
2912       rv = location->SetHref(href);
2913       NS_ENSURE_SUCCESS(rv, rv);
// After this, we effectively mapped .location to .location.href
2914 
2915       return WrapNative(cx, obj, location, NS_GET_IID(nsIDOMLocation), vp);
// Create a wrapper for the location object with vp (the url) as value.
2916     }

Resources of interest:
The XPIDL reference
Mapping DOM Objects to their C++ class
Modularization techniques

1.I. Scriptable Helper flags

This chapter has not been written yet. If you want to help please contact me!

1.J. Security features implementation

This chapter has not been written yet. If you want to help please contact me!