Creating XPCOM components

This guide is about Gecko, and about creating XPCOM components for Gecko-based applications. Though the emphasis is on the practical steps you take to make your C++ code into a component that can be used in Gecko, we hope that these steps will also give us an occasion to discuss all of the tools, techniques, and technologies that make up XPCOM. Accordingly, the book is arranged so that you can follow along and create your own components or learn about different XPCOM topics individually, as in a reference work. For example, the introduction includes a discussion of components and what they are, and the first chapter - in which you compile the basic code and register it with Mozilla - prompts a discussion of the relationship between components and modules, of XPCOM interfaces, and of the registration process in general.

Note: In general, you should try to avoid having to create XPCOM components. Add-ons should try to use the new Add-on SDK as much as possible; however, there may be cases when it's unavoidable.

Note:This article describes a method that uses xpidl but you should use webidl instead.

Preface

Who Should Read This Book

Organization of the Tutorial

Following Along with the Examples

Acknowledgements

An Overview of XPCOM

The XPCOM Solution

Interfaces and Encapsulation

The nsISupports Base Interface

XPCOM Identifiers

XPIDL and Type Libraries

Reference Counting

Variable Mappings

Common XPCOM Error Codes

Using XPCOM Components

Component Examples

The WebBrowserFind Component

The WebLock Component

Component Use in Mozilla

Finding Mozilla Components

Using XPCOM Components in Your Cpp

XPConnect: Using XPCOM Components From Script

Component Internals

Creating Components in Cpp

XPCOM Initialization

XPCOM Registry Manifests

Registration Methods in XPCOM

Autoregistration

The Shutdown Process

Three Parts of a XPCOM Component Library

The Glue Library

XPCOM String Classes

Creating the Component Code

What We'll Be Working On

Component Registration

The regxpcom Program

Registration Alternatives

Overview of the WebLock Module Source

Digging In: Required Includes and Constants

Identifiers in XPCOM

Coding for the Registration Process

The Registration Methods

Creating an Instance of Your Component

Using XPCOM Utilities to Make Things Easier

Generic XPCOM Module Macros

Common Implementation Macros

Declaration Macros

String Classes in XPCOM

nsEmbedString and nsEmbedCString

Starting WebLock

Getting Called at Startup

Registering for Notifications

Getting Access to the Category Manager

Providing Access to WebLock

Creating the WebLock Programming Interface

Defining the WebLock Interface in XPIDL

The XPIDL Syntax

Scriptable Interfaces

Subclassing nsISupports

The Web Locking Interface

Implementing WebLock

Declaration Macros

Representing Return Values in XPCOM

XPIDL Code Generation

Getting the WebLock Service from a Client

Implementing the iWebLock Interface

The Directory Service

Modifying Paths with nsIFile

Manipulating Files with nsIFile

Using nsILocalFile for Reading Data

Processing the White List Data

iWebLock Method By Method

Lock and Unlock

HasMoreElements

Finishing the Component

Using Frozen Interfaces

Copying Interfaces Into Your Build Environment

Implementing the nsIContentPolicy Interface

Receiving Notifications

Implementing the nsIContentPolicy

Uniform Resource Locators

Checking the White List

Creating nsIURI Objects

Building the WebLock UI

User Interface Package List

Client Code Overview

The XUL Document

Overlaying New User Interface Into Mozilla

webLockOverlay.xul

Other Resources

Image Resources

Packaging WebLock

Component Installation Overview

Archiving Resources

The WebLock Installation Script

The WebLock Trigger Script

Distributing Your Component

Appendix A - Setting up the Gecko SDK

Downloading and Setting the SDK

Building a Microsoft Visual Cpp Project

Creating a New Project

Adding the Gecko SDK to the Project Settings

Building a Windows Project

A Makefile for Unix

Appendix B - Resources

WebLock Resources

Gecko Resources

XPCOM Resources

General Development Resources

Copyright (c) 2003 by Doug Turner and Ian Oeschger. This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, v1.02 or later. Distribution of substantively modified versions of this document is prohibited without the explicit permission of the copyright holder. Distribution of the work or derivative of the work in any standard (paper) book form is prohibited unless prior permission is obtained from the copyright holder.