This is a book 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.
The top of each chapter provides a list of the major topics covered. Sidebar sections are included to highlight technical details. By the end of the book, if we've done our job, you will have learned how to build a component and you will know something about the framework for these components in Gecko, which is XPCOM.
Who Should Read This Book
XPCOM stands for the Cross Platform Component Object Model. As this name implies, XPCOM is similar to Microsoft COM. If you have any experience with this technology, much of it can be applied to XPCOM. However, this book does not assume any prior knowledge of COM - all of the basic COM ideas will be introduced.
This book provides a tutorial about building an XPCOM component that controls browsing behavior. Although, XPCOM can be used in many environments which are unrelated to web browsing, XPCOM's main client is Gecko, an open source, standards compliant, embeddable web browser, where it's easiest and most practical to illustrate XPCOM's functionality. A full description of the component in this tutorial can be found in the What We'll Be Working On section of the tutorial.
Despite what old documentation says, XPCOM should not be used to make NPAPI plugins scriptable. Starting with Gecko 1.7.5 (Firefox 1.0) a special NPAPI extension for scriptability is supported, see Scripting plugins.
Organization of the Tutorial
The following list provides an overview of the steps that we will take to build an XPCOM component called WebLock, which provides site blocking functionality to Gecko-based browsers. Each one of these steps has its own chapter, in which a number of topics associated with the step are discussed.
- Create the generic module code for the component.
- Use C++ macros, special string classes and smart pointers to optimize your code.
- Define the functionality for the component; create an XPIDL interface for that functionality; create the implementation code specific to the custom WebLock component interface.
- Finish implementing the WebLock component:
nsIContentPolicy, file I/O, locking, etc.
- Creating the user interface for the WebLock component.
- Packaging WebLock for distribution and installation.
Following Along with the Examples
There are a couple of different ways to get XPCOM onto your machine so you can begin to create components. If you already have a Mozilla build or the source from Mozilla 1.2 or later, then you can use the XPCOM framework available there. If you don't already have the Mozilla source, then an even easier way to get and use XPCOM is to download the Gecko SDK, which is a collection of libraries and tools that features the XPCOM component framework.
Whether you compile your code in the Mozilla source tree or use the Gecko SDK, you can build your own components which leverage components that already exist in Gecko. The WebLock component we describe in this tutorial is a practical (and, we hope, genuinely useful) addition to the browser. In order to build it, your Gecko SDK or Mozilla source tree needs to be version 1.2 or later (XPCOM interfaces were not fully frozen in prior releases).
This book assumes you are using the SDK rather than compiling in a Mozilla source tree, though the difference between these two approaches is minimal. Details about downloading the SDK, building, and getting programmatic access to Gecko components are provided in the appendix to this book, Setting up the Gecko SDK.
The formatting conventions listed below are used to designate specific types of information in the book and make things easier to scan. The goal is to use as few formats as possible, but to distinguish the various different types of information clearly.
|bold||component names appear in bold in the text|
|italic||variables appear in italic. Important terms and new concepts are also italicized the first time they appear in the text. Those terms are either explained immediately after they are cited, or else the reader is referred to a section in the book where they are described in detail.|
|link||References to other sections and to figures and tables are links to those sections.|
Thanks to Peter Lubczynski, John Gaunt, Ellen Evans, and Alec Flett for technical reviews. A special thanks goes to Darin Fisher for his very acute observations, close reading, and attention to detail.
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.