Whenever a XPCOM component is exposed to a public web page, the page knows nothing about what that component is, what interfaces it implements. Thus, Mozilla code treats it as if it implements only nsISupports, with the handy-dandy QueryInterface() method… and nothing else.

This means web pages would have to QI for every interface they needed, and they would know nothing about what’s available. However, by implementing one more interface, no more instanceof operators would be needed, and you’d have all the properties and methods of the object that you thought you’d have. That interface is nsIClassInfo.

The rest of this article is in the extended section.

From the nsIClassInfo overview:

nsIClassInfo is an interface that provides information about a specific implementation class, to wit:

• a contract ID and class ID through which it may be instantiated;
• the language of implementation (C++, JavaScript, etc.);
• a list of the interfaces implemented by the class;
• flags indicating whether or not the class is threadsafe or a singleton;
  and
• helper objects in support of various language bindings.

From the standpoint of a public component, the most important part of nsIClassInfo is the getInterfaces() method. This method returns an array of interfaces the component supports, much like what QueryInterface checks for. (In theory, you could have QueryInterface call getInterfaces() and do its lookups based on that, but it probably isn’t necessary.) In JavaScript, a sample getInterfaces method would look like:

// nsIClassInfo
getInterfaces: function getInterfaces(aCount) {
var array = [Components.interfaces.nsIDOMXPathNSResolver,
Components.interfaces.nsISecurityCheckedComponent,
Components.interfaces.nsIClassInfo];
aCount.value = array.length;
return array;
},

Two things to note about this method

. First, the aCount variable is really an “out” parameter, defined in the nsIClassInfo interface to refer to the length of the array. In JavaScript, that parameter becomes the value property of an aCount object. It’s just another quirk of XPIDL.

The other thing to note is the nsISupports interface is not listed. This is per the nsIClassInfo interface’s inline documentation.

Another important part of nsIClassInfo is the flags property. I freely admit to not understanding most of the flags, but SINGLETON should be turned on if your component is a service, and off if it is not. (Note: Declaring your component as both a service and a member of the “JavaScript global constructor” category probably won’t work too well.) DOM_OBJECT is also useful for granting content pages without special privileges access to your component.

The getHelperForLanguage method returns a nsISupports object, if so desired, that can QI to nsIXPCScriptable. For JavaScript-based components, nsIXPCScriptable is not scriptable, so don’t bother – just return null. The helpers are optional anyway.

The others are well-documented in the nsIClassInfo interface already. For JS-based components:

+  // nsIClassInfo
+  implementationLanguage: Components.interfaces.nsIProgrammingLanguage.JAVASCRIPT,

The classDescription property is just a string describing the component for humans. The classID and contractID should match the first and third arguments of the registerFactoryLocation calls in your factory code, respectively.

You may have noticed nsISecurityCheckedComponent above. As I’ll discuss in the third part of this series, it becomes important to include support for it, so that Mozilla knows what your component’s users can do with the component (like, what the component was designed to do).