As we mentioned, one advantage of using XPCOM is that it separates the implementation from the interface so you can write a component in a language-agnostic manner. The services your component provides are available to all other components despite the language used to implement it. This means, for example, that you can use JavaScript not only to access the services of an XPCOM component, but also to create those services. As described in Chapter 5, using JavaScript as a modularized application programming language provides the deepest level of scripting in Mozilla.
In your Mozilla build or distribution, you will find a subdirectory named components. Inside this directory, you will see many compiled components. You will also see a number of JavaScript components. If you look at the source of these components, you can get an idea of how a JavaScript component is created. For example, look at the files nsFilePicker.js and nsSidebar.js. These JavaScript components are used in the Mozilla distribution.
JavaScript XPCOM components have the advantage over regular scripts of being fast, reusable, and globally accessible to any caller. They also have the advantage over C++-based XPCOM components of being easier to write and maintain. The next few sections describe the creation of a JavaScript-based XPCOM component. If you would rather do your work in C++, then skip to the C++ implementation section in this chapter.
To create a JavaScript component, you need to create an IDL interface source file and a JavaScript implementation source file. In the Mozilla sources, naming source files with an ns prefix is common practice, so the implementation file should be called something like nsSimple.js. The interface source file, or IDL file, uses a similar convention: it is typical for interfaces to begin with nsI, using an I to distinguish them as interfaces rather than implementations. Call the IDL source file nsISimple.idl.
In addition to these two source files (nsSimple.js and nsISimple.idl), you will compile a cross platform binary interface file, or type library, with the XPIDL compiler, calling it nsISimple.xpt. This .xpt file tells Mozilla that the interface is available and scriptable. You can use it on any platform that Mozilla supports. In other words, you can pick up nsISimple.xpt, which may have been compiled on Unix, drop it into Windows or Mac OS, and use it.
All .xpt interface files for Mozilla live in the components directory located in mozilla/dist/bin if you are developing with the Mozilla source code. Otherwise, for binary distributions of Mozilla, they are located in mozilla/components. Mozilla checks this directory upon start up, looking for any new components to register automatically.
Usually, the first step in creating a new component is writing the interface. To begin, open up your favorite text editor and create a new file called nsISimple.idl.
The complete source code for the nsISimple.idl interface file is:
#include "nsISupports.idl"
[scriptable, uuid(ce32e3ff-36f8-425f-94be-d85b26e634ee)]
interface nsISimple : nsISupports
{
attribute string yourName;
void write( );
void change(in string aValue);
};The #include line above includes the file nsISupports.idl, which defines this interface's base class. The [scriptable, uuid..] line declares the interface scriptable and assigns a UUID to the interface. You can use the UUID provided, but creating your own using one of the UUID generation tools described earlier is usually better. The third line, next to the interface keyword, declares the interface's name, nsISimple, and says that it derives from nsISupports.
Various attributes and methods are defined within the definition of the nsISimple interface. Attributes are properties of interface objects. They may be read-only or read/write variables. In nsISimple, an attribute called yourName is of the type string. In this implementation, you may get and set this attribute's value. Of the methods defined in this interface, the write( ) method takes no arguments and the change( ) method takes an argument of type string called aValue. The parameter aValue will be a new value that replaces the current value held by yourName. The complete interface IDL is:
#include "nsISupports.idl"
[scriptable, uuid(ce32e3ff-36f8-425f-94be-d85b26e634ee)]
interface nsISimple : nsISupports
{
attribute string yourName;
void write( );
void change(in string aValue);
};Once you have created an interface file that publicly defines the component's methods and attributes, the next step is to implement those methods and attributes in a separate source file. The listings below walk through the implementation of nsISimple step by step.
First, you must declare an empty function called SimpleComponent, which is a standard constructor for a JavaScript object prototype. It's a good idea to name the component in a way that clearly describes both the component and the interface, as SimpleComponent does (i.e., SimpleComponent is an implementation of the nsISimple interface):
function SimpleComponent( ) {}With the function declared, we start defining the JavaScript class prototype.
SimpleComponent.prototype = {
mName : "a default value",In the prototype, we first create a member variable called mName that will be the string placeholder for the IDL attribute yourName. The variable assigns the string a default value. Remember to place commas after all definitions in a prototype. IDL attributes are always implemented as getter functions. Methods marked with [noscript] will not be available for use with scripting languages.
Next we implement the functions below for our definition of attribute string yourName in our file nsISimple.idl.
get yourName( ) { return this.mName; },
set yourName(aName) { return this.mName = aName; },When someone calls an IDL attribute in an interface, getters and setters are used to get or set values for the attribute:
simple.yourName='foo';
Or similarly read values from the attribute:
var foo = simple.yourName;
We first call on the setter function to set a value to the attribute yourName and then use the getter function to obtain the currently set value of yourName.
The first function defined in nsISimple is called void write( ). For this method, the implementation can be as simple as the following code:
write : function ( ) { dump("Hello " + this.mName + "\n"); },This example implements the declaration void write( ) by dumping the current value of the variable mName to stdout. The code uses the this keyword to indicate that you are calling to the component's own member variable mName.
The void change( ) method is then implemented as follows:
change : function (aValue) { this.mName = aValue; },change( ) is a method used to change the value variable.
Once the definitions in the nsISimple interface are implemented, you need to implement required methods and factories that make this JavaScript implementation class an XPCOM component. Recall that all XPCOM components must implement the nsISupports interface.
Example 8-3 shows an implementation of QueryInterface specific to our new component. QueryInterface ensures that the correct interface (nsISimple) is used by matching the iid with the nsISimple interface that this component implements. If the interface doesn't match, then the argument is invalid. In this case, the exception Components.results.NS_ERROR_NO_INTERFACE is thrown, which maps to the error code number 2147500034, and code execution is stopped. If the interface identifier parameter matches the interface, then an instance of the implementation class object SimpleComponent with its interface is returned as a ready-to-use XPCOM component. In XPCOM, every component you implement must have a QueryInterface method.
The next requirement is to create a JavaScript object called Module. This module implements the methods needed for autoregistration and component return type objects.
var Module = {
firstTime : true,The Boolean firstTime is a flag used only when the component is initially registered:
registerSelf: function (compMgr, fileSpec, location, type) {
if (this.firstTime) {
dump("*** first time registration of Simple JS component\n");
this.firstTime = false;
throw Components.results.NS_ERROR_FACTORY_REGISTER_AGAIN;
}The Component Manager can do a lot in the registration process, but you have to add some logic for first time registration so the Component Manager has the information it needs. RegisterSelf is called at registration time (component installation) and is responsible for notifying the component manager of all components implemented in this module. The fileSpec, location, and type parameters can be passed on to the registerComponent method unmolested. Next, register the component with the Component Manager using code like the following example. The parameters include the CID, a description, a progID, and the other parameters you can pass without changing:
dump(" ***** Registering: Simple JS component! ****\n");
compMgr.registerComponentWithType(this.myCID,
"My JS Component",
this.myProgID, fileSpec,
location, true, true,
type);
},The GetClassObject method produces Factory and SingletonFactory objects. Singleton objects are specialized for services that allow only one instance of the object. Upon success, the method returns an instance of the components factory, which is the implementation class less its interface:
getClassObject : function (compMgr, cid, iid) {
if (!cid.equals(this.myCID))
throw Components.results.NS_ERROR_NO_INTERFACE;
if (!iid.equals(Components.interfaces.nsIFactory))
throw Components.results.NS_ERROR_NOT_IMPLEMENTED;
return this.myFactory;
},In the previous list, the member variables myCID and myProgID are the class ID and the human-readable canonical program ID, respectively:
myCID: Components.ID("{98aa9afd-8b08-415b-91ed-01916a130d16}"),
myProgID: "@mozilla.org/js_simple_component;1",The member object myFactory is the components factory, which through its own member function, createInstance( ), constructs and returns an instance of the complete component (if the iid parameter is specified and is the correct interface). Otherwise, if no iid parameter is used, the iid of nsISupports is used and an instance of the module is created that will then need a subsequent call to QueryInterface to instantiate the object as a component.
myFactory: {
createInstance: function (outer, iid) {
dump("CI: " + iid + "\n");
if (outer != null)
throw Components.results.NS_ERROR_NO_AGGREGATION;
return (new SimpleComponent( )).QueryInterface(iid);
}
},The method canUnload unloads the module when shutdown occurs and is the last function in the module. The componentManager calls the method NSGetModule to initialize these required XPCOM methods and objects:
canUnload: function(compMgr) {
dump("****** Unloading: Simple JS component! ****** \n");
return true;
}
function NSGetModule(compMgr, fileSpec) { return Module; }The code in Example 8-4 shows the implementation for the nsISimple interface in its entirety.
Once you create an IDL source file and a JavaScript implementation file, you need to compile nsISimple.idl into a .xpt type library.
To compile the XPIDL interface file nsISimple.idl, you need to add the path of the XPIDL compiler to your environment. As mentioned earlier, the XPIDL compiler is located at mozilla/xpcom/typelib/xpidl. Here is the output of a Unix/cygwin/OSX session showing the compilation starting with the source file (nsISimple.idl) created earlier in the chapter. Afterwards, nsISimple.xpt and nsSimple.js are copied to the components directory:
$ ls nsISimple.idl nsSimple.js $ PATH=$PATH:/usr/src/mozilla/xpcom/typelib/xpidl $ echo $PATH /sbin:/bin:/usr/sbin:/usr/bin:/usr/games:/usr/local/bin:/usr/X11R6/bin:/root/bin:/usr/src/mozilla/xpcom/typelib/xpidl $ export XPIDL_INC=/usr/src/mozilla/xpcom/base $ echo $XPIDL_INC /usr/src/mozilla/xpcom/base $ xpidl -m typelib -w -v -I $XPIDL_INC \ > -o nsISimple nsISimple.idl $ ls nsISimple.idl nsISimple.xpt nsSimple.js $ cp nsISimple.xpt nsSimple.js \ > /usr/src/mozilla/dist/bin/components/
This output illustrates the compilation of the nsISimple.idl source file into the nsISimple.xpt typelib file. The newly compiled typelib file and the JavaScript implementation file are then copied to the Mozilla distribution components directory where component registration will occur automatically when Mozilla is launched.
All previous steps were done manually. You can also create a Makefile to automate this process by using GNU make, in which case you would create a Makefile with the following variables and targets defined:
TOP_SRC=/usr/src/mozilla INST_DIR=$(TOP_SRC)/dist/bin/components XPIDL=$(TOP_SRC)/xpcom/typelib/xpidl XPIDL_INC=$(TOP_SRC)/xpcom/base FLAGS=-m typelib -w -v -I $(XPIDL_INC) -o all: $(XPIDL)/xpidl $(FLAGS) \ nsISimple nsISimple.idl install: cp nsISimple.xpt nsSimple.js $(INST_DIR) clean: rm -rf *.xpt uninstall: rm -f $(INST_DIR)/nsISimple.xpt rm -f $(INST_DIR)/nsSimple.js
Remember that you must indent after your targets with a <tab>.
In this file, which can be used on Unix, Windows using cygwin, or Mac OS X, the TOP_SRC environment variable points to the Mozilla source tree's top-level directory, the INST_DIR points to the directory where the component should be installed, and the XPIDL variables drive the XPIDL executable and its environment and compiler flags. The "all" Makefile target compiles and creates the type library nsISimple.xpt.
Note that in addition to the type libraries, the XPIDL compiler compiles header files, Java class files, and special HTML documentation, if necessary.
When you start up xpcshell, the Component Manager finds the new nsISimple component and registers it. The result of your test should look similar to Example 8-5.
Once the component is tested and registered as an XPCOM object, you can use JavaScript from a local web page or from the chrome to create an nsISimple object and use it as you would any ordinary JavaScript object:
<script type="application/x-JavaScript">
netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect");
var Simple=new Components.Constructor("@mozilla.org/js_simple_component;1", "nsISimple");
var s = new Simple( );
for(var list in s)
document.write(list+"<br>\n");
</script>In addition to creating a component in JavaScript, you can implement XPCOM components in C++ and Python. The next sections cover the C++ implementation of the nsISimple interface.
Before you begin working on an actual implementation of a C++ component, familiarize yourself with some of the tools that make C++ programming for XPCOM a little easier. Templates, special types, and macros can ease some of the extra housekeeping that programming XPCOM requires.
More tools than we can cover in this introduction are available, but this section reviews some of the most common, including a macro that implements the nsISupports methods QueryInterface, AddRef, and Release, macros for testing nsresults, smart pointers, and special types.
Rather than having to implement QueryInterface, AddRef, and the Release methods like we did in our JavaScript component, the NS_IMPL_ISUPPORTS macro inserts the implementation code for you.
To use this macro for the nsISimple interface, type:
NS_IMPL_ISUPPORTS1_CI(nsSimpleImpl, nsISimple)
The following lines define this macro:
#define NS_IMPL_ISUPPORTS1(_class, _interface) \ NS_IMPL_ADDREF(_class) \ NS_IMPL_RELEASE(_class) \ NS_IMPL_QUERY_INTERFACE1(_class, _interface)
As you can see, the macro is made up of other macros that implement basic methods of the nsISupports interface. Unless you need to modify these macros, they should be left as is. This macro is used later on when we create our C++ component.
Example 8-6 shows a reference implementation of the QueryInterface method in C++.
Since all XPCOM methods return result codes called nsresults, another useful macro is the NS_SUCCEEDED macro. This indicates whether an XPCOM accessor has returned a successful result. It is defined in nsError.h:
#define NS_SUCCEEDED(_nsresult) (!((_nsresult) & 0x80000000))
A related macro, NS_FAILED, is indicates whether an XPCOM accessor returned a failure code result. It too is defined in nsError.h. The following code demonstrates the typical use of these two macros:
nsresult rv;
nsCOMPtr<nsILocalFile> file(do_CreateInstance("@mozilla.org/file/local;1", &rv));
if (NS_FAILED(rv)) {
printf("FAILED\n");
return rv;
}
if (NS_SUCCEEDED(rv)) {
printf(" SUCCEEDED \n");
return rv;
}You may have noticed that the declaration of the identifier rv as the type nsresult. nsresult is a 32-bit unsigned integer declared in nscore.h:
typedef PRUint32 nsresult;
We assign an nsCOMPtr or smart pointer named file to a newly created instance of the nsILocalFile component. Using the NS_FAILED and NS_SUCCEEDED macros, we test for the nsresult to see if our attempt to create an instance of the component failed. If it did, rv would be assigned an integer with a specific error return code. Return codes are defined in nsError.h. Alternatively, you can test your results for the success code:
nsresult rv = nsComponentManager::CreateInstance("@mozilla.org/file/local;1",
nsnull,
NS_GET_IID(nsILocalFile),
(void **)&refp);If a result is successful, the value of rv returns NS_OK, which is 0.
Return codes are used in XPCOM instead of exceptions. Exceptions are not allowed because of their inconsistent implementation across different compilers. All error code numbers equate to a specific type of error. For example NS_ERROR_FAILURE and NS_ERROR_NULL_POINTER are common types of error code return values used throughout the Mozilla code base. If a value returned to rv was NS_ERROR_NULL_POINTER, the test for failure would be true and the code would return the numerical result code for NS_ERROR_NULL_POINTER.
Another widely use type is nsnull, defined in nscore.h. Here is the definition:
#define nsnull 0
This definition, nsnull, is the most common way to use null. The following code shows how to use nsnull:
nsresult rv;
nsCOMPtr<nsILocalFile> file =
do_CreateInstance("@mozilla.org/file/local;1", &rv);
if (NS_SUCCEEDED(rv)) {
char* msg = "we successfully created an instance of file\n";
*_retval = (char*) nsMemory::Alloc(PL_strlen(msg) + 1);
if (!*_retval)
return NS_ERROR_OUT_OF_MEMORY;
PL_strcpy(*_retval, msg);
} else {
*_retval = nsnull;
}If you look in the Mozilla C++ source code, you will see the macro NS_IMETHODIMP used frequently. This macro identifies the type of your interface implementation method. It is also defined in nscore.h, as shown in Example 8-7.
Example 8-8 shows a typical use of the NS_IMETHODIMP macro. All methods that implement an interface are of the type NS_IMETHODIMP.
The macro in Example 8-8 declares the method GetSomeString as an XPCOM implementation.
As described earlier, XPCOM provides a C++ tool called a smart pointer to manage reference counting. A smart pointer is a template class that acts syntactically, just like an ordinary pointer in C or C++. You can apply * to dereference the pointer, ->, or access what the pointer refers to. Unlike a raw COM interface pointer, however, nsCOMPtr manages AddRef, Release, and QueryInterface for you, thereby preventing memory leaks.
Here is how to create a raw pointer:
nsILocalFile *refp(nsnull);
nsresult rv = nsComponentManager::CreateInstance("@mozilla.org/file/local;1",
nsnull,
NS_GET_IID(nsILocalFile),
(void **)&refp);
if (refp)
printf("%p\n", (void*)refp);After you create a new object that refp points to, refp is considered an owning reference, and any other pointers that point to it must be "refcounted." Example 8-9 uses anotherPtr and oneMorePtr to point to refp, and