Creating a C++ XPCOM component

About

This is a step-by-step tutorial on creating, building and registering an XPCOM component on Linux and MS Windows.

Download

The complete source code for this tutorial can be downloaded from here.

Creating the component

1. Download the Gecko SDK for your platform.
   1. You can find it at http://ftp.mozilla.org/pub/mozilla.org/mozilla/releases/mozilla1.7/.
   2. You can choose a different Mozilla release if you like.
   3. Extract the SDK to a local directory.
2. Create a GUID for your main interface.
   • On Windows you can use the guidgen utility.
   • On Linux you can use the uuidgen utility.
3. Create the interface definition file - IMyComponent.idl
   1. Use the following template, add methods and attributes to the interface.
   2. Fill in the GUID you have generated.

   	
   #include "nsISupports.idl"
   
   [scriptable, uuid(_YOUR_INTERFACE_GUID_)]
   interface IMyComponent : nsISupports
   {
     long Add(in long a, in long b);
   };
   	
   	

4. Generate the interface header and typelib files out of the interface definition file.
   • Use the xpidl utility that comes with Gecko SDK.
   • Substitute the "_DIR_" in the following commands with the full path to the xpcom/idl directory found under your Gecko SDK main directory.
   • xpidl -m header -I_DIR_ IMyComponent.idl will create the IMyComponent.h header file.
   • xpidl -m typelib -I_DIR_ IMyComponent.idl will create the IMyComponent.xpt typelib file.
5. The interface header file IMyComponent.h contains templates for building your component header and implementation files. You can copy and paste the templates to create these files, changing only your component name.
6. Create your component header file - MyComponent.h.
   1. Start by inserting double inclusion protection code (#ifndef _MY_COMPONENT_H_ ....).
   2. Add #include "IMyComponent.h" to include the interface definition.
   3. Create a GUID for your component.
   4. Add the following lines, which define your component name, contract ID, and GUID:

      
      #define MY_COMPONENT_CONTRACTID "@mydomain.com/XPCOMSample/MyComponent;1"
      #define MY_COMPONENT_CLASSNAME "A Simple XPCOM Sample"
      #define MY_COMPONENT_CID _YOUR_COMPONENT_GUID_ 
      
      

   5. Copy the header template from IMyComponent.h (starting with /* Header file */) into the MyComponent.h file.
   6. Replace all the instances of _MYCLASS_ with the name of your component.
7. Create your component implementation file - MyComponent.cpp.
   1. Add #include "MyComponent.h" to include your component definitions.
   2. Copy the implementation template from IMyComponent.h (starting with /* Implementation file */) into the MyComponent.cpp file.
   3. Replace all the instances of _MYCLASS_ with the name of your component.
   4. Add method implementation code.
8. Create your module definitions file - MyComponentModule.cpp.
   1. Add #include "nsIGenericFactory.h" to include Mozilla GenericFactory definitions.
   2. Add #include "MyComponent.h" to include your component definitions.
   3. Add NS_GENERIC_FACTORY_CONSTRUCTOR(MyComponent) to define the constructor for your component.
   4. Add

      
      static nsModuleComponentInfo components[] =
      {
          {
             MY_COMPONENT_CLASSNAME, 
             MY_COMPONENT_CID,
             MY_COMPONENT_CONTRACTID,
             MyComponentConstructor,
          }
      };
      
      

      to define the class name, contract ID and GUID of your component.
   5. Add NS_IMPL_NSGETMODULE("MyComponentsModule", components) to export the above information to Mozilla.
9. Create the makefiles and/or projects.
   • You can use the templates provided with this sample to create your custom makefile.
   • Alternatively, you can create a Visual C++ project with similar settings (on Windows).

Building the sample

1. Download the sample code from here.
   • Extract the sample to a local directory.
2. Edit the makefile.
   1. The makefile is located in the src directory of the sample.
   2. It is named Makefile for Linux, MyComponent.mak for Windows
   3. Edit the makefile, changing the GECKO_SDK_PATH variable to point to your Gecko SDK directory.
   4. Added: When using the included Visual Studio project:
      1. Open the project settings: Project > Settings...
      2. Choose Settings For: All Configurations in the upper left corner.
      3. Open the C/C++ tab and choose Preprocessor in the Category drop-down list.
      4. Make sure that "Additional include directories" points to your Gecko SDK.
      5. Open the Link tab and choose Input in the Category drop-down list.
      6. Make sure that the "Additional library path" points to your Gecko SDK.
3. Build the sample.
   1. Open a command shell (cmd on Windows; tcsh, bash, xterm etc. on Linux).
   2. Navigate to the sample src directory.
   3. On Linux issue a make command. MyComponent.so file is created.
   4. On Windows issue a nmake /f MyComponent.mak command. Debug\MyComponent.dll is created.
   5. Alternatively, on Windows, issue a nmake /f "MyComponent.mak" CFG="MyComponent - Win32 Release" command for a release build. Release\MyComponent.dll is created.
   6. Added: When using the included Visual Studio project:
      1. Select the wanted configuration (Debug/Release) in Build > Set Active Configuration...
      2. Choose Build > Build MyComponent.dll
4. Register the new component with Mozilla.
   1. Copy MyComponent.so/MyComponent.dll and IMyComponent.xpt file to the Mozilla components directory.
   2. On Windows this directory is typically located at:
      C:\Program Files\Mozilla Firefox\components.
   3. On Linux this directory is typically located at ~/firefox/components (or ~/mozilla/components).
   4. Run the regxpcom command supplied with the Gecko SDK to register the new component.
   5. You might need to provide an additional parameter:
      regxpcom -x _COMPONENTS_DIR_ where _COMPONENTS_DIR_ is the components directory.
   6. Delete the xpti.dat and compreg.dat files from your Mozilla profile directory.
      These files will be automatically rebuilt by Mozilla the next time it is restarted.
      Added: Alternatively you can "touch" (either create or update) a file called .autoreg in the main Mozilla/Firefox installation directory.
   7. The profile directory is typically located at:
      • ~/.mozilla/firefox/default.??? on Linux.
      • C:\Documents and Settings\USERNAME\Application Data\Mozilla\Firefox\Profiles\default.??? on Windows.
5. Test the new component.
   1. Restart Mozilla.
   2. Open the MyComponentTest.html file provided with the sample and click the "Go" button.
   3. If everything is OK you should see a dialog saying "3 + 4 = 7".

Links and Resources

• IBM developerWorks - XPCOM Overview [part 1] [part 2] [part 3] [part 4] [part 5]
• Creating XPCOM Components by Doug Turner.
• Creating Applications With Mozilla [chapter 8 - XPCOM]

Revision History

• June 3, 2005
1. Modified the Windows makefile (MyComponent.mak) to work with the latest Gecko SDK. The old version of the sample can be found here.
2. Added Visual Studio 6 project file to the sample.
3. Added a tip about using the ".autoreg" file for registering new components.