Preface

---

• "Who Should Read This Book"
• "Organization of the Tutorial"
• "Following Along with the Examples"
• "Conventions"
• "Acknowledgements"

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 leaned 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.

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 and 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. Releases prior to Mozilla 1.2 did not completely support XPCOM components with frozen interfaces, but changes since then have remedied this.

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 Platform.

Conventions

The formatting conventions listed in Table 1 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.

TABLE 1. Formatting Conventions Used in This Book

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. Longer code listings appear in gray boxes.
italic	variables, filenames and directory names terms 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. References to other chapters (e.g., Getting Social: Making Instances of Your Component Available) are also italicized.
"quoted"	References to other sections are double-quoted (e.g. "Organization of the Tutorial").

Acknowledgements

Thanks to Peter Lubczynski, John Gaunt, Ellen Evans, and Alec Flett for technical reviews. And a special thanks to Darin Fisher for his very acute observations, close reading, and attention to detail.