Please note, this is a STATIC archive of website developer.mozilla.org from 03 Nov 2016, cach3.com does not collect or store any user information, there is no "phishing" involved.

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

Creating XPCOM Components is meant for C++ developers. Though you can create XPCOM components in JavaScript and other languages, and though you might be able to follow along as a C programmer, the component implementation code is written in C++, and much of the discussion of how to make your code into an XPCOM component starts from C++. You don't need to be a C++ expert, however. Although basic ideas such as inheritance and encapsulation should be familar to you, wherever possible they are explained in the book as they are used. Also many of the examples are in JavaScript, which is used in Mozilla to access XPCOM components as scriptable objects, and so familiarity with that language is useful as well.

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.

Conventions

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.

Format Description
bold component names appear in bold in the text
monospace code listings, interface names and members of interfaces (e.g., createInstance()) appear in monospaced font. Lines of code are placed in separate boxes. Additionally, filenames and directories appear in monospaced font.
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.

Acknowledgements

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.

Document Tags and Contributors

Tags: 
 Contributors to this page: mail2vcnu, Sheppy, kscarfone, trevorh, fscholz, Nickolay, Tonci, Ptak82, Ja7R6b, Mgjbot, Waldo
 Last updated by: mail2vcnu,