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.


Who Should Read This Book
Organization of the Tutorial
Following Along with the Examples

An Overview of XPCOM

The XPCOM Solution
Interfaces and Encapsulation
The nsISupports Base Interface
XPCOM Identifiers
Contract ID
XPIDL and Type Libraries
XPCOM Services
Method Types
Reference Counting
Status Codes
Variable Mappings
Common XPCOM Error Codes

Using XPCOM Components

Component Examples
Cookie Manager
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
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

XPCOM Macros
Generic XPCOM Module Macros
Common Implementation Macros
Declaration Macros
String Classes in XPCOM
Using Strings
nsEmbedString and nsEmbedCString
Smart Pointers

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

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
The Locking UI
Site Adding UI
Overlaying New User Interface Into Mozilla
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.

Document Tags and Contributors

 Last updated by: ignisvulpis,