MozNet Tutorial - Javascript XPCOM Component

Now we're just a few steps away from having a working XPCOM component. So far we've taken the skeleton and filled it in with some code that will do something more than say 'Hello World!'. I'd say we're doing pretty good so far but, we can't count our chickens before they hatch. We've got more work ahead of us so don't say 'Look what I can do!' just yet.

IDL File Definition

Since we've got our javascript file taken care of we need a way to tell XPCom that we've got a component that we want to call methods on. This is done by creating a XPT file. But, before we can create that we need to make an IDL. IDL stands for Interface Definition Language and is the basic way of defining interfaces in XulRunner. To write your own components, like extending MozNet, you'll want to have the SDK version of XulRunner. Since the current version of MozNet is targeting XulRunner 3.6.28 you'll need the SDK for that build. You can download it here.

Let's define our IDL file. We'll use this file in the next step, creating the XPT file. In your text editor open a new, blank, document and paste or type the code below. Save the document next to the 'ExampleComponent.js' file we created earlier and name it 'nsIExampleComponent.idl'.

Our IDL file must retain the same structure and syntax as other XulRunner IDL files that you'll find in the SDK. The tool that will create the XPT from your IDL file expects a proper input file and is not forgiving of any mistakes.

OK. Now we have two of the three files we need for our custom component. The ExampleComponent.js file is our actual XPCOM component that XPCom will use when we call methods defined in our IDL. We need to build an XPT file, using our IDL, that we can use to register our javascript file with XPCom.

Taking Command

Dig through the junk drawers, dig through the closets and the attic. Find that dusty, old, cmd.exe application and blow out the cob webs. Fire up the engine.. we're takin her for a ride!

Once you have the program started 'cd' or 'pushd' your way into the '[xulrunner_directory]\sdk\bin\' folder and type the following:

x:\xulrunner_sdk_directory\sdk\bin>xpidl.exe -m typelib -I idl\ nsIExampleComponent.idl

If your IDL is valid and you don't have any errors, there will be a file named 'nsIExampleComponent.xpt' located in the '[xulrunner_directory]\sdk\bin\' folder. If you get to this point your almost done. If not, revise your IDL and try it again.

Register Your Component

We're almost done! On this page of the tutorial we're going to setup XulRunner to register our component the next time our application runs. This step does require a modification to a XulRunner file in order for the registration to complete.

UPDATE: MozNET no longer accepts a developer-supplied runtime directory but, instead uses an All-In-One assembly which contains the proper XulRunner build.
Hence the following paragraph no longer applies. Instead, you should use the freely available AIO Builder to add your component directly to the AIO library. You can find and download the AIO Builder from the MozNET information page.

Since we have to modify a XulRunner file let's go ahead and open up an Explorer window and navigate it to the XulRunner directory that our MozNet based application is using. This is probably a folder named 'xulrunner', located as a subfolder of your program's 'bin' folder. Next, navigate to and open the folder named 'components'. This folder is part of the XulRunner runtime and contains a bunch of javascript files and a couple other files. Find the file named 'components.list' and open it in your text editor. Let's append the name of our component - ExampleComponent.js - to the bottom of the list and save the file. Note that case is important when appending our components name.

Now copy your xpt file, 'nsIExampleComponent.xpt', and your javascript file, 'ExampleComponent.js', and paste them both into the 'components' directory where we modified 'components.list'. Now, find the files named: compreg.dat and xpti.dat and throw them away. They'll be rebuilt the next time we run our application, registering our XPCom component at the same time.

Before we can use our new component from either our application or from the MozNet source code we need to add a bit of code to either MozNet or our program. If you have the MozNet source and have done any extending on your own you already know what I'm talking about. Otherwise, just stay with me and I'll get you through it..