Mozilla Platform – XPCOM in C++

In the spirit of “you can never have too many”, I thought it would be a good idea to document my process of creating an XPCOM object in C++. XPCOM is Mozilla’s cross platform component object model, similar to Microsoft’s COM technology. XPCOM components can be implemented in C, C++, and JavaScript, and can be used from C, C++, and JavaScript. That means you can call JavaScript methods from C++ and vice versa.

Applications built on the Mozilla Platform use XUL and JavaScript (and XBL) for the UI. Much of the core technology is implemented in C/C++ and exposed to JavaScript as XPCOM components. I have been experimenting with XULRunner and thought it would be good experience to build some XPCOM components.

Step 1: Development Setup

The simplest way to get an XPCOM component built is to use the Gecko SDK. On Windows, the SDK is built using a Microsoft compiler, so you need to use one too. I am using Microsoft’s free Visual C++ Express. You could try to use a different compiler, but you are going to need to build XULRunner from source code. Not the simplest thing to do and it would be incompatible with production releases of XULRunner from Mozilla.

I am using XULRunner 1.8.0.4 which has a pre-built SDK at gecko-sdk-win32-msvc-1.8.0.4.zip. I extracted the SDK to a folder called xulrunner-1.8.0.4, but you can call yours whatever you want.

You also need to a couple pre-built libraries (glib-1.2.dll & libIDL-0.6.dll) from the wintools.zip archive. I copied glib-1.2.dll & libIDL-0.6.dll into the bin subfolder of gecko-sdk.

Note: wintools.zip seems old and lots of newer MDC documentation refers to moztools.zip archive, but the version of xpidl.exe that comes with the gecko-sdk crashes with the DLL’s from moztools.

Recap:

  • Use the right Gecko SDK for your XULRunner release
  • Use a Microsoft compiler
  • Use pre-built glib-1.2.dll & libIDL-0.6.dll libraries from wintools.zip

Here is what my folder structure looks like:

xpcom-folders.png

Step 2: Create a VC++ Project

I wish Visual Studio project and file templates (or wizards) existed for creating XPCOM modules and components, but they don’t. I am considering building some, but for now, I offer a XPCOM project that contains a simple XPCOM component. You can use the project as a starting point and modify the component files to add your own functionality.

I started with a standard multi-thread DLL project. Then I made the following tweaks:

  • Added “..\gecko-sdk\include” to Additional Include Directories
  • Added “..\gecko-sdk\lib” to Additional Library Directories
  • Added “nspr4.lib xpcom.lib xpcomglue_s.lib” to Additional Dependencies
  • Added “XP_WIN;XP_WIN32″ to Preprocessor Definitions
  • Turned off precompiled headers (just to keep it simple)
  • Used a custom build step for the XPCOM IDL file (spawned xpidl-build.bat to process the IDL with Mozilla toolset, not MIDL)

VC++ Express Project: xpcom-test.zip

Note: I am using xpcom_glue as described in this MDC article. I am using frozen linkage (dependent on XPCOM). I am not defining XPCOM_GLUE and I am linking against xpcomglue_s.lib

Step 3: Create an XPCOM Component

A full tutorial of XPCOM is beyond the scope of this posting. Check out these resources for more information on the world of XPCOM:

Ok then, on with the basic, oversimplified example. Your XPCOM component is made up of 3 parts:

  • Component interface described using IDL. The interface defines the methods, including arguments and return types, of the component.
  • Component implementation using C++. The implementation is where the methods actually do the work.
  • Component factory module, also in C++. The factory is in charge of creating instances of the implementations.

Let’s specify a simple interface:


#include "nsISupports.idl"

[scriptable, uuid(263ed1ba-5cc1-11db-9673-00e08161165f)]
interface ISpecialThing : nsISupports
{
  attribute AString name;

  long add(in long a, in long b);
};

Remember to generate your own GUID. The next step is to compile the IDL into a type-library (*.XPT) and a C++ header file (*.H), which we can use to define our implementation object. The blank VC++ project has a BAT file that will create the XPT and the H files. The command executes XPIDL.EXE twice, like this:


{path_to_geckosdk}\bin\xpidl.exe -m header -I..\gecko-sdk\idl {your_idl_file}
{path_to_geckosdk}\bin\xpidl.exe -m typelib -I..\gecko-sdk\idl {your_idl_file}

The generated H file actually has a skeleton implemenation (commented out). You can take the code and create implementation H and CPP files. They could look like this:


H file:

#ifndef __SPECIALTHING_IMPL_H__
#define __SPECIALTHING_IMPL_H__

#include "comp.h"
#include "nsStringAPI.h"

#define SPECIALTHING_CONTRACTID "@starkravingfinkle.org/specialthing;1"
#define SPECIALTHING_CLASSNAME "SpecialThing"
#define SPECIALTHING_CID { 0x245626, 0x5cc1, 0x11db, { 0x96, 0x73, 0x0, 0xe0, 0x81, 0x61, 0x16, 0x5f } }

class CSpecialThing : public ISpecialThing
{
public:
	NS_DECL_ISUPPORTS
	NS_DECL_ISPECIALTHING

	CSpecialThing();

private:
	~CSpecialThing();

protected:
	/* additional members */
	nsString mName;
};

#endif

CPP file:

#include "comp-impl.h"

NS_IMPL_ISUPPORTS1(CSpecialThing, ISpecialThing)

CSpecialThing::CSpecialThing()
{
	/* member initializers and constructor code */
	mName.Assign(L"Default Name");
}

CSpecialThing::~CSpecialThing()
{
	/* destructor code */
}

/* attribute AString name; */
NS_IMETHODIMP CSpecialThing::GetName(nsAString & aName)
{
	aName.Assign(mName);
	return NS_OK;
}
NS_IMETHODIMP CSpecialThing::SetName(const nsAString & aName)
{
	mName.Assign(aName);
	return NS_OK;
}

/* long add (in long a, in long b); */
NS_IMETHODIMP CSpecialThing::Add(PRInt32 a, PRInt32 b, PRInt32 *_retval)
{
	*_retval = a + b;
	return NS_OK;
}

Lastly, we need to create the module implementation. I put this together from some samples I found on the MDC site:


#include "nsIGenericFactory.h"
#include "comp-impl.h"

NS_GENERIC_FACTORY_CONSTRUCTOR(CSpecialThing)

static nsModuleComponentInfo components[] =
{
    {
       SPECIALTHING_CLASSNAME, 
       SPECIALTHING_CID,
       SPECIALTHING_CONTRACTID,
       CSpecialThingConstructor,
    }
};

NS_IMPL_NSGETMODULE("SpecialThingsModule", components) 

Assuming you have the right SDK and setup the include and LIB folders correctly, the project should build your XPCOM component.

Step 4: Test Component in a XULRunner Application

In order to test your component in a XULRunner application, you need to “install” the component, “clear” the component registry, and use the component from JavaScript.

  1. Install Component: Copy your XPT and DLL files to the {app}/components folder. You should not put your component in the xulrunner/components folder.
  2. Clear Registry: Increment the BuildID in your {app}/application.ini.
  3. Use in JavaScript:

function doXPCOM() {
  try {
    const cid = "@starkravingfinkle.org/specialthing;1";
    var obj = Components.classes[cid].createInstance();
    obj = obj.QueryInterface(Components.interfaces.ISpecialThing);
  }
  catch (err) {
    alert(err);
    return;
  }

  var res = obj.add(3, 4);
  alert('3+4 = ' + res);

  var name = obj.name;
  alert('Name = ' + name);

  obj.name = 'New Name';
  name = obj.name;
  alert('Name = ' + name);
}

As I find errors and new information, I’ll be sure to update this post.

Update: Updated doXPCOM per Christian’s comments.

5 Comments

  1. Christian Biesinger said,

    November 11, 2006 @ 11:54 am

    The moztools/wintools issue is that libIDL/glib must use the same C runtime as xpidl.exe. That basically means that the two must have been compiled with the same version of the compiler. As the official 1.8.x builds are compiled with VC6, you need the VC6-compiled wintools.zip instead of the vc8 compiled vc8-moztools.zip.

  2. Christian Biesinger said,

    November 11, 2006 @ 12:01 pm

    Also note that you don’t need to use enablePrivilege when you’re a xulrunner application (assuming the file is loaded from a chrome:// URI).

    I’d also declare the “obj” variable, instead of making it an implicit global variable.

  3. Andrey L. Fisunenko said,

    November 22, 2006 @ 1:40 pm

    Project xpcom-test.zip does not contain required definition MOZILLA_STRICT_API.
    (Preprocessor Definitions). Without it compiler can’t recognize nsString.

  4. Mark Finkle said,

    November 22, 2006 @ 5:56 pm

    Andrey,

    The MDC article (http://developer.mozilla.org/en/docs/XPCOM_Glue) says you only need to use MOZILLA_STRICT_API when using Gecko 1.7 or earlier. I am using Gecko 1.8, I don’t need it.

  5. Kevin said,

    December 2, 2006 @ 3:46 am

    IT WORKED!!!

    I have tried sooo many XPCOM examples and nothing seems to work. I was doing something wrong, and I could never figure out what that was. So when I found your example I just thought “Well, I’ll try again, but it will probably have some other flaw just like the others.” Au contraire! It worked.

    I’m so happy. I can now really get moving on my XULRunner app. Thank you so much.

RSS feed for comments on this post