Changes

This raises a question: what are 'XPCOM components' components of exactly? The answer is Gecko, Mozilla's standards compliant, embeddable web browser and toolkit for creating web browsers and other applications. XPCOM is the means of accessing Gecko library functionality and embedding or extending Gecko.  Much has been [http://developer.mozilla.org/en/docs/XPCOM written about XPCOM] elsewhere, and you are encouraged to read more on the theory behind this technology in conjunction with this walkthrough.

In this walkthrough we will be creating a simple binary XPCOM component using the build system, called '''FirstXpcom'''. While this component won't do very much yet, it will provide a starting point for many other types of components you may wish to build down the road. The functionality of this component will become part of a Gecko-enabled application (in this case, a Firefox binary extension). However, it is important to remember that this is only one of many possible uses for it.

The code this component will become part '''NOTE: the following assumes you have used an objdir. Replace all occurrences of a Gecko-enabled application $(in this case, a Firefox binary extensionobjdir). However, it is important to remember that this is only one of many possible uses for itwith your objdir name.'''

= Starting Writing FirstXpcom =

For this walkthrough we will use the Mozilla build system to create our component. It is also possible to us use the '''Gecko SDK''' ([http://developer.mozilla.org/en/docs/How_to_build_a_binary_XPCOM_component_using_Visual_Studio instructions are here]). NOTE: this assumes that you have already done a successful objdir-Firefox build.

Create an IDL file for the component in the public directory::

Here are the contents of the '''IFirstXpcom.idl'''

[scriptable, uuid(''...see below...'')]

=== nsISupports (defined [http://developer.mozilla.org/en/docs/nsISupports here]) is the base interface for all XPCOM components (i.e., it is possible to pass any XPCOM component around as an nsISupports object). The methods in nsISupports define basic bookkeeping for an interface's lifetime (it also defines a way to check at runtime if a component implements a given interface, but more on that later).===

[http://developer.mozilla.org/en/docs/nsISupports nsISupports] is the base interface for all XPCOM components (i.e., it is possible to pass any XPCOM component around as an nsISupports object). The [http://developer.mozilla.org/en/docs/nsISupports methods] in nsISupports define basic bookkeeping for an interface's lifetime (they also define a way to check at runtime if a component implements a given interface, but more on that later). Components need to keep track of how many clients hold references to them via an interface. We call this This is known as '''reference counting ''' on an interface, and it is used to determine when a component can be safely unloaded so that it doesn't leak (i.e., no one holds a reference any more, but the interface is still in memory).

One point worth mentioning is that '''pointers in XPCOM are to interfaces'''. Interface pointers are known to implement nsISupports, so you can access all of the object lifetime and discovery functionality described above.

=== UUID ===  [scriptable, uuid(...see below...)] What does line three 3 mean? This says that our component is '''scriptable''', and can be used or implemented in scripting languages, JavaScript for example (see http://developer.mozilla.org/en/docs/Interfaces:About_Scriptable_Interfaces). Each interface needs to be uniquely identifiable, and Mozilla uses a 128-bit number called a '''UUID''' (Universally Unique Identifier) for this purpose. You can generate one in a number of ways: * at the command prompt using the command '''uuidgen''':

Each interface needs to be uniquely identifiable, and Mozilla uses a 128 $ uuidgen 78af1749-014a-47aa-bit number called a '''UUID''' (Universally Unique Identifier) for this purpose. You can generate one using a number of methods:baec-2669670b7601

Next comes the body of your interface. Our interface defines one attribute and one method. An attribute is a value you can '''Get''' and '''Set''' (NOTE: you can specify attributes that are Get only, that is read-only). We have an attribute called '''name''' of type '''AString''' (a unicode, or two-byte string class. For more details More information about strings generating UUIDs in Mozilla, see different forms is available [http://developer.mozilla.org/en/docsEn/XPCOM_string_guide)Generating_GUIDs here].

Our interface also defines a single method called '''add''', which takes two long integers as input, adds them, === Attributes and returns the result as a long integer.Methods ===

Because we are using the Mozilla build system to help us create our component attribute AString name; long add(in long a, we can get it to translate our IDL into .h and .cpp stub files automatically. But first we have to generate some makefiles.in long b);

== MakefileNext comes the body of your interface. Our interface defines one '''attribute''' and one '''method'''. An attribute is a value you can '''Get''' and '''Set''' (NOTE: you can specify attributes that are Get only, that is read-only). We have an attribute called '''name''' of type '''AString''' (a unicode, or two-byte string class. For more details about strings in ==Mozilla, see the [http://developer.mozilla.org/en/docs/XPCOM_string_guide XPCOM String Guide]).

The first step in making the build system aware of our component is to generate an Our interface also defines a single method called '''add''', which takes two long integers as input file for autoconf to use during , adds them, and returns the configure step, which will build our Makefile automaticallyresult as a long integer; we'll write that code below.

Because we are using the Mozilla build system to help us create our component, we can get it to translate our IDL into .h and .cpp stub files automatically. $ cd mozilla/extensions/firstxpcom $ touch MakefileTo do this we first have to generate some makefiles.in

DEPTH = The first step in making the build system aware of our component is to generate an input file for autoconf to use during the configure step, which will build the necessary Makefile automatically../..topsrcdir = @top_srcdir@srcdir = @srcdir@VPATH = @srcdir@

include $(DEPTH)=== mozilla/configextensions/autoconffirstxpcom/Makefile.mkin ===

DEPTH = ../.. topsrcdir = @top_srcdir@ srcdir = @srcdir@ VPATH = @srcdir@ include $(DEPTH)/config/autoconf.mk MODULE = firstxpcom DIRS = public \ src \ $(NULL) XPI_NAME = firstxpcom # A Unique ID for your extension INSTALL_EXTENSION_ID = firstxpcom@senecac.on.ca # Will create a .xpi in /mozilla/$(MOZ_OBJDIR)/dist/xpi-stage/ XPI_PKGNAME = firstxpcom # install.rdf will tell Firefox how to install our extension and # this says, "copy install.rdf into our extension dir and xpi" DIST_FILES = install.rdf include $(topsrcdir)/config/rules.mk

# A Unique ID for your extensionINSTALL_EXTENSION_ID = == mozilla/extensions/firstxpcom@senecac/public/Makefile.on.cain ===

# Will create Next we need a Makefile.xpi in /mozilla/$(MOZ_OBJDIR)/dist/xpi-stage/XPI_PKGNAME = firstxpcomthe '''public''' directory

DEPTH = ../../.. topsrcdir = @top_srcdir@ srcdir = @srcdir@ VPATH = @srcdir@ include $(DEPTH)/config/autoconf.mk MODULE = firstxpcom XPIDL_MODULE = firstxpcom XPI_NAME = firstxpcom # install.rdf will tell Firefox how The files under EXPORTS are copied directly to install our extension # /mozilla/$(MOZ_OBJDIR)/dist/include/firstxpcom # and are thus accessible from other modules # this says, "copy installEXPORTS = \ # myHeader.rdf into our extension dir and xpi"h \ # $(NULL) DIST_FILES XPIDLSRCS = installIFirstXpcom.idl include $(topsrcdir)/config/rules.rdfmk

include $(topsrcdir)/config/rulesHere we tell the build system about our component's name and where its XPIDL file can be found.mk

Note the DIRS variable. It says that the two directories, public and src, will be entered. We also need Now a Makefile.in files in each of those.the '''src''' directory:

Next we need a Makefile.in public directory -----------start--------------  DEPTH = ../../.. topsrcdir = @top_srcdir@ srcdir = @srcdir@ VPATH = @srcdir@ include $(DEPTH)/config/autoconf.mk IS_COMPONENT = 1 MODULE = firstxpcom LIBRARY_NAME = firstxpcom XPI_NAME = firstxpcom # The REQUIRES section tells make which modules your # components uses. This causes the relevant subdirectories # of /mozilla/$(MOZ_OBJDIR)/dist/include/ to be added to the # C++ compiler's include path. If you're including Mozilla # headers and the compiler isn't finding them, it could well # mean that you haven't listed all of the necessary modules here. REQUIRES = xpcom \ string \ $(NULL) # The .cpp source files to be compiled CPPSRCS = FirstXpcom.cpp \ $(NULL) include $(topsrcdir)/config/rules.mk EXTRA_DSO_LDOPTS += \ $(XPCOM_GLUE_LDOPTS) \ $(NSPR_LIBS) \ $(NULL)

include $(DEPTH)=== mozilla/configextensions/autoconffirstxpcom/install.mkrdf ===

XPI_NAME <pre> <?xml version= "1.0" encoding="UTF-8"?> <RDF xmlns="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:em="http://www.mozilla.org/2004/em-rdf#"> <Description about="urn:mozilla:install-manifest"> <em:id>firstxpcom@senecac.on.ca</em:id> <em:name>firstxpcom</em:name> <em:version>0.1</em:version> <em:creator>David Humphrey</em:creator> <em:description>A Simple XPCOM Extension.</em:description> <em:homepageURL>http://zenit.senecac.on.ca/wiki</em:homepageURL> <em:targetApplication> <Description> <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id> <!-- firefox --> <em:minVersion>2.0</em:minVersion> <em:maxVersion>3.0b2pre</em:maxVersion> <!-- trunk build Nov 11, 2007 --> </Description> </em:targetApplication> </Description> </RDF></pre>

# The files under EXPORTS are copied directly to# /mozilla/$(MOZ_OBJDIR)/dist/include/myextension/# and are thus accessible from other modules#EXPORTS = \# myHeader.h \# $(NULL)= Building FirstXpcom ==

XPIDLSRCS = IFirstXpcomNow we're ready to build our component.idl Add the following line to your '''.mozconfig''' file in order to include firstxpcom during the build process:

Now you can (BUT DON'T, see below for quick way!!)re----------end-------------------build your tree (also known as "rebuilding world") by doing:

Here we tell the build system about our component's name and where it's XPIDL file can be found. Now a Makefile.in for src -----------start-------------- DEPTH = ../../..topsrcdir = @top_srcdir@srcdir = @srcdir@VPATH = @srcdir@ include $(DEPTH)/config/autoconf.mk IS_COMPONENT = 1MODULE = firstxpcomLIBRARY_NAME = firstxpcom XPI_NAME = firstxpcom # The REQUIRES section tells make which modules your # components uses. This causes the relevant subdirectories# of /mozilla/$(MOZ_OBJDIR)/dist/include/ to be added to the# C++ compiler's include path. If you're including Mozilla# headers and the compiler isn't finding them, it could well# mean that you haven't listed all of the necessary modules here.REQUIRES = xpcom \ string \ $(NULL) # The .cpp source files to be compiledCPPSRCS = FirstXpcom.cpp \ $(NULL) EXTRA_DSO_LDOPTS += \ $(XPCOM_GLUE_LDOPTS) \ $(NSPR_LIBS) \ $(NULL) include $(topsrcdir)/config/rules.mk ----------end------------------- Last, we need to create a file telling Firefox how to install our extension, install.rdf (see http://developer.mozilla.org/en/docs/Install_Manifests for details). -----------start-------------- <?xml version="1.0"?> <RDF xmlns="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:em="http://www.mozilla.org/2004/em-rdf#"> <Description about="urn:mozilla:install-manifest"> <em:id>firstxpcom@senecac.on.ca</em:id> <em:version>0.1</em:version> <em:type>2</em:type>  <em:targetApplication> <!-- Firefox --> <Description> <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id> <em:minVersion>2.0+</em:minVersion> <em:maxVersion>3.0a3</em:maxVersion> </Description> </em:targetApplication> <!-- front-end metadata --> <em:name>My First XPCOM Extension</em:name> <em:description>Just a simple XPCOM component.</em:description> <em:creator>David Humphrey</em:creator> <em:homepageURL>http://zenit.senecac.on.ca/wiki</em:homepageURL> </Description></RDF> ----------end-------------------  * Now let's build our component Add the following line to your .mozconfig file in order to enable your extension in the build system: ac_add_options --enable-extensions=default,firstxpcom Now you can re-build your tree (also known as "rebuilding world") by doing:  $ cd mozilla $ make -f client.mk build

$ cd $(objdir) $ ../build/autoconf/make-makefile extensions/firstxpcom

$ cd $(objdir)/extensions/firstxpcom $ make

This will create the '''public ''' and '''src ''' directories, as well as generate the Makefiles necessary in each. Go into the public directory and call make again, in order to have your .h and .cpp stubs generated(NOTE: this will cause errors, see below):

$ cd $(objdir)/extensions/firstxpcom/public $ make

<code> IFirstXpcom.idl ../../../dist/bin/xpidl.exe -m header -w -I../../../../extensions/firstxpcom/public -I../../../dist/idl -o _xpidlgen/IFirstXpcom </c/temp/proj/ff-trunk/mozilla/obj-fftrunk/extensions/firstxpcom/public/../../../../extensions/firstxpcom/public/IFirstXpcom.idlcode>

Here it is we can see the build processing our IDL file. As a result of this first (partially ) successful run of make, exported and generated header files (i.e.,from our IDL) will be placed in '''$(objdir)/dist/include/firstxpcom'''.

Within '''$(obdirobjdir)/dist/include/firstxpcom/IFirstXpcom.h ''' you'll see a the following block that beginsof code:

#if 0 /* Use the code below as a template for the implementation class for this interface. */ ... /* End of implementation class template. */ #endif

The code in the middle of this block is what you want to start working with in order to implement use as the basis for implementing your .cpp file (and .h if you choose to split it out, which we won't). Copy and paste this implementation stub into the following file:'''mozilla/extensions/firstxpcom/src/FirstXpcom.cpp'''

mozilla/extensions/firstxpcom/FirstXpcom.cpp You'll need to do a search/replace on '''_MYCLASS_ ''' and change it to the name of your class, in our case, '''FirstXpcom'''. _MYCLASS_ > FirstXpcom

$ cd $(objdir)/extensions/firstxpcom $ make

This will produce a host of errors, mostly related to the fact that we don't have proper includes setup set-up and it can't find declarations it needs. You need to add an include for your interface's generated .hfile:

#include "IFirstXpcom.h"

Now reRe-run make.

Discuss https://bugzilla== Examining IFirstXpcom.mozilla.org/show_bug.cgi?idh ==371201 at this point, and problems I had making this work, how luser helped me, and in the end a bug was filed on the build system.

Let's examine the code more closely and try to make sense of things (. Here is the code in '''$(objdir)/dist/include/firstxpcom/IFirstXpcom.h)''':

-----------start--------------  /* * DO NOT EDIT. THIS FILE IS GENERATED FROM c:/temp/proj/ff-trunk/mozilla/obj-fftrunk/extensions/firstxpcom/public/../../../../extensions/firstxpcom/public/IFirstXpcom.idl */ #ifndef __gen_IFirstXpcom_h__ #define __gen_IFirstXpcom_h__ #ifndef __gen_nsISupports_h__ #include "nsISupports.h" #endif /* For IDL files that don't want to include root IDL files. */ #ifndef NS_NO_VTABLE #define NS_NO_VTABLE #endif /* starting interface: IFirstXpcom */ #define IFIRSTXPCOM_IID_STR "78af1749-014a-47aa-baec-2669670b7601" #define IFIRSTXPCOM_IID \ {0x78af1749, 0x014a, 0x47aa, \ { 0xba, 0xec, 0x26, 0x69, 0x67, 0x0b, 0x76, 0x01 }} class NS_NO_VTABLE IFirstXpcom : public nsISupports { public: NS_DECLARE_STATIC_IID_ACCESSOR(IFIRSTXPCOM_IID) /* attribute AString name; */ NS_IMETHOD GetName(nsAString & aName) = 0; NS_IMETHOD SetName(const nsAString & aName) = 0; /* long add (in long a, in long b); */ NS_IMETHOD Add(PRInt32 a, PRInt32 b, PRInt32 *_retval) = 0; }; NS_DEFINE_STATIC_IID_ACCESSOR(IFirstXpcom, IFIRSTXPCOM_IID) /* Use this macro when declaring classes that implement this interface. */ #define NS_DECL_IFIRSTXPCOM \ NS_IMETHOD GetName(nsAString & aName); \ NS_IMETHOD SetName(const nsAString & aName); \ NS_IMETHOD Add(PRInt32 a, PRInt32 b, PRInt32 *_retval); /* Use this macro to declare functions that forward the behavior of this interface to another object. */ #define NS_FORWARD_IFIRSTXPCOM(_to) \ NS_IMETHOD GetName(nsAString & aName) { return _to GetName(aName); } \ NS_IMETHOD SetName(const nsAString & aName) { return _to SetName(aName); } \ NS_IMETHOD Add(PRInt32 a, PRInt32 b, PRInt32 *_retval) { return _to Add(a, b, _retval); } /* Use this macro to declare functions that forward the behavior of this interface to another object in a safe way. */ #define NS_FORWARD_SAFE_IFIRSTXPCOM(_to) \ NS_IMETHOD GetName(nsAString & aName) { return !_to ? NS_ERROR_NULL_POINTER : _to->GetName(aName); } \ NS_IMETHOD SetName(const nsAString & aName) { return !_to ? NS_ERROR_NULL_POINTER : _to->SetName(aName); } \ NS_IMETHOD Add(PRInt32 a, PRInt32 b, PRInt32 *_retval) { return !_to ? NS_ERROR_NULL_POINTER : _to->Add(a, b, _retval); } #if 0 /* Use the code below as a template for the implementation class for this interface. */ /* Header file */ class _MYCLASS_ : public IFirstXpcom { public: NS_DECL_ISUPPORTS NS_DECL_IFIRSTXPCOM _MYCLASS_(); private: ~_MYCLASS_(); protected: /* additional members */ }; /* Implementation file */ NS_IMPL_ISUPPORTS1(_MYCLASS_, IFirstXpcom) _MYCLASS_::_MYCLASS_() { /* member initializers and constructor code */ } _MYCLASS_::~_MYCLASS_() { /* destructor code */ } /* attribute AString name; */ NS_IMETHODIMP _MYCLASS_::GetName(nsAString & aName) { return NS_ERROR_NOT_IMPLEMENTED; } NS_IMETHODIMP _MYCLASS_::SetName(const nsAString & aName) { return NS_ERROR_NOT_IMPLEMENTED; } /* long add (in long a, in long b); */ NS_IMETHODIMP _MYCLASS_::Add(PRInt32 a, PRInt32 b, PRInt32 *_retval) { return NS_ERROR_NOT_IMPLEMENTED; } /* End of implementation class template. */ #endif #endif /* __gen_IFirstXpcom_h__ */ What things do you notice? What strikes you?

Header guards (see [http://* long add (in long a, in long ben.wikipedia.org/wiki/Include_guard Include Guards]); */NS_IMETHODIMP _MYCLASS_::Add(PRInt32 are aportable technique for ensuring that includes or defines are only done once, PRInt32 bfor example, PRInt32 *_retval){ return NS_ERROR_NOT_IMPLEMENTED;}that nsISupports.h only be included once:

/* End of implementation class template #ifndef __gen_nsISupports_h__ #include "nsISupports. */h" #endif

#endif /* __gen_IFirstXpcom_h__ */ ----------end------------------- What things do you notice? What strikes you? * Use of header guards Header guards (or Include Guards, see http://en.wikipedia.org/wiki/Include_guard) are a portable technique for ensuring that includes or defines are only done once. Another way of doing this, especially with the Microsoft compiler, is to use #pragma once

* Use Mozilla provides many convenience macros to help C++ developers do common tasks more efficiently. Much of the code involved in making a module/component is generic, and has to be repeated every time. You can spot macrosin the code by the fact that they are all capitals, and often begin with '''NS_*'''. Examples include:

Mozilla provides many convenience macros to help C++ developers do common tasks more efficiently. Much of the code involved in making a module* NS_DECL_ISUPPORTS* NS_ENSURE_TRUE* NS_IMPL_NSGETMODULE* see http://component is generic, and has to be repeated ever timedeveloper. You can spot macros in the code by the fact that they are all capitals, and often begin with NS_*mozilla. Examples includeorg/en/docs/Category:XPCOM_Macros for more examples

NS_DECL_ISUPPORTSNS_ENSURE_TRUENS_IMPL_NSGETMODULENS_DECL_ appended with any interface name in all caps will declare all of the methods of that interface for you (see http://developernsIFoo --> NS_DECL_NSIFOO). Looking at the code above shows you how this is possible. For example, NS_DECL_NSIFOO will declare all of the methods of nsIFoo, provided that it exists and that nsIFoo.mozillah was generated by the XPIDL compiler.org/en/docs/CategoryConsider the following real class:XPCOM_Macros for more examples)

NS_DECL_ appended with any interface name in all caps will declare all of the methods of that interface for you. Looking at the code above shows you how this is possible. For example, NS_DECL_NSIFOO will declare all of the methods of nsIFoo provided that it exists and that nsIFoo.h was generated by the XPIDL compiler. Consider the following real class: class myClass : public nsISomeClass { public: NS_DECL_ISUPPORTS // declares AddRef, Release, and QueryInterface NS_DECL_NSISOMECLASS // declares all methods of nsISomeClass myClass(); virtual ~myClass() {} };

The declaration of nsISomeClass doesn't include any methods other than the contructor constructor and destructor. Instead, the class uses the NS_DECL_ macro

Also note the use of NS_METHOD and NS_METHODIMP for return type signatures. All XPCOM functions are required to return a result code ([http://bonsai.mozilla.org/cvsblame.cgi?file=/mozilla/xpcom/base/nscore.h&rev=1.103&raw=1&mark=324-327&#324 nsresult], a integer), which indicates whether or not the function worked (e.g., NS_OK).

NS_IMPL_ISUPPORTS1(classname, interface1)

Also, if If your class implements more than one interface, you can simply change the number 1 in the macro to the number of interfaces you support and list the interfaces, separated by commas. For example:

NS_IMPL_ISUPPORTS2(classname, interface1, interface2) NS_IMPL_ISUPPORTSn(classname, interface1, ..., interfacen)

These macros automatically add the nsISupports entry for you, so you ''don't '' need to do something like thisthe following:

NS_IMPL_ISUPPORTS2(classname, interface1, nsISupports)

As an example, consider seamonkey[http://bonsai.mozilla.org/cvsblame.cgi?file=mozilla/xpcom/io/nsBinaryStream.cpp (http://lxr&rev=1.32&raw=1&mark=65&#65 mozilla.org/seamonkey/source/xpcom/io/nsBinaryStream.cpp#62)]:

62 NS_IMPL_ISUPPORTS3(nsBinaryOutputStream, nsIObjectOutputStream, nsIBinaryOutputStream, nsIOutputStream)

* Use A quick scan of never before-seen the code also reveals typesthat will be unfamiliar, including: nsAString, nsresult, and PRInt32. What are these?

nsAStringBecause Mozilla is cross-platform almost all of the standard types you are used to have Mozilla-specific versions. For example, PRInt32, which is defined as part of the Netscape Portable Runtime (hence the ''PR'' prefix), nsresultis a signed 32-bit integer, no matter the OS you are using (see http://developer.mozilla.org/en/docs/PRInt32 ). Depending on the platform you use this could mean a regular int or a long. The same is true of strings (Mozilla has it's own string classes --see http://developer.mozilla.org/en/docs/XPCOM_string_guide) because of the need for multi- what are these new types?language support and other things necessary to make Mozilla's products work around the world.

Because Mozilla is cross-platform almost all of the standard types you are used to have Mozilla-specific versions. For example, PRInt32, which is defined as part of the Netscape Portable Runtime (hence the PR prefix), is a signed 32-bit integer on all platforms (see http://developer.mozilla.org/en/docs/PRInt32). Depending on the platform you use this could mean a regular int or a long. The same is true of strings (Mozilla has it's own string classes -- see http://developer.mozilla.org/en/docs/XPCOM_string_guide) because of the need for multi-language support and other things necessary to make Mozilla's products work. At first there are so many of these to learn. But you quickly get accustomed to them, and looking at how other people code (via [http://lxr.mozilla.org lxr]) can help you in this process.

* Strange return types - You'll also notice differences between the original IDL and the autogenerated C++ signatures . In our IDL file, the IFirstXpcom::Add method took two longs and returned a long. However in the C++ code stub it says something different:

The return value of XPCOM methods generated from XPIDL is always of the type '''nsresult''', and the small macro used in these expansions, '''NS_IMETHOD''', actually represents nsresult. nsresult is returned even when in XPIDL you specify that the method return a void. If your IDL requires a return type, as ours does, that value will be added as a final parameter to the call list--in this case '''PRInt32 *_retval'''.

There are other things you should know about making your code compatible on all of the supported Mozilla platforms Mozilla supports. You can read about them here: http://www.mozilla.org/hacking/portable-cpp.html.

Continuing on, we We now have need to write a bit of code to get our component registered. Components reside in modules, and those modules are defined in shared library files (i.e., DLLs or DSOs) that typically sit in the components directory of an XPCOM application.

A set of default libraries stored in this components directory makes up When you build a component or module and compile it into a typical Gecko installationlibrary, providing functionality that consists it must export a single method named '''NSGetModule'''. This NSGetModule function is the entry point for accessing the library. It gets called during registration and unregistration of networking, layout, composition, a cross-platform user interfacethe component, and otherswhen XPCOM wants to discover what interfaces or classes the module/library implements.

When you build a component or In addition to implementing the module and compile it into a librarycode (i.e., it must export a single method named NSGetModule[http://developer. This NSGetModule function is the entry point for accessing the librarymozilla. It gets called during registration and unregistration of the org/en/docs/nsIModule nsIModule]), we also have to write code to allow our componentto be created at runtime based on an interface rather than concrete types--essentially, and when XPCOM wants abstracting the process of creation so that clients don't have to discover what know about real classes underneath the interfaces or classes . This means implementing the module[http://developer.mozilla.org/en/docs/library implementsnsIFactory nsIFactory] interface.

In addition Together, these two interfaces will require us to implementing the module code (iwrite [http://developer.mozilla.eorg/en/docs/Creating_XPCOM_Components:Creating_the_Component_Code#webLock1., nsIModule), we also have to write cpp hundreds lines of code to allow our component to be created at runtime based on interface rather than concrete types--esentially], abstracting the process majority of creation so that clients don't have to know about real classes underneath the interfaceswhich is generic boilerplate code. This means implementing In order to simplify the nsIFactory interface.work component developers must do, a number of macros help us with this task:

#include "nsIGenericFactory.h" ... // This will result in a function named FirstXpcomConstructor. NS_GENERIC_FACTORY_CONSTRUCTOR(FirstXpcom) // 19f3ef5e-759f-49a4-88e3-ed27f9c83011 #define FIRSTXPCOM_CID \ {0x19f3ef5e, 0x759f, 0x49a4, \ { 0x88, 0xe3, 0xed, 0x27, 0xf9, 0xc8, 0x30, 0x11} } static const nsModuleComponentInfo components[] = { { "FirstXpcom", FIRSTXPCOM_CID, "@senecac.on.ca/firstxpcom;1", FirstXpcomConstructor } }; NS_IMPL_NSGETMODULE(FirstXpcomModule, components)

#include "nsIGenericFactory.h".Note: we also could have provided an initialization function to be called after our object gets allocated (i.e., FirstXpcom->Init()):

// This will result in a function named FirstXpcomConstructor.NS_GENERIC_FACTORY_CONSTRUCTOR NS_GENERIC_FACTORY_CONSTRUCTOR_INIT(FirstXpcomnsYourConcreteClassName, Init)

// 19f3ef5e-759f-49a4-88e3-ed27f9c83011 #define FIRSTXPCOM_CID \ {0x19f3ef5eNext, 0x759fwe need to create proper identification for our component's module so that it can be passed to the module implementation macro, 0x49a4, \ { 0x88, 0xe3, 0xed, 0x27, 0xf9, 0xc8, 0x30'''NS_IMPL_NSGETMODULE'''. This macro takes an array of '''nsModuleComponentInfo''' so that you can define more than one component per module (remember that a module is a collection of components, 0x11} }and every component belongs to a module so it can get loaded by the system).

static const nsModuleComponentInfo components[] ={ { "FirstXpcom"Start by generating another '''uuid''', FIRSTXPCOM_CID, "@senecacwhich will be used for identifying our component/class (i.one.ca/firstxpcom;1", FirstXpcomConstructor }}; NS_IMPL_NSGETMODULE(FirstXpcomModulewe can't re-use our interface's uuid), components)for example:

19f3ef5e-759f-49a4-88e3-------end-------------------ed27f9c83011

First, we have to include nsIGenericFactoryNow [http://developer.h in order to get NS_GENERIC_FACTORY_CONSTRUCTORmozilla. Now we can add the following line, which will generate org/En/Generating_GUIDs write a function called FirstXpcomConstructordefine] to make it easier to pass this Class ID around in C++:

Note: Then we also could have provided an initialization function to be called after can populate our object gets allocated (i.e., array with a single entry for the FirstXpcom->Init())component:

NS_GENERIC_FACTORY_CONSTRUCTOR_INIT(nsYourConcreteClassName static const nsModuleComponentInfo components[] = { { "FirstXpcom", Init) // descriptive name FIRSTXPCOM_CID, // CID from above "@senecac.on.ca/firstxpcom;1", // Contract ID FirstXpcomConstructor // Factory Constructor } };

Next, we The last two entries need some explanation. The '''Component ID''' is a human-readable string that clients can use to get/create proper identification for our componentan instance of your class. We's module so that it can be passed ll see how to the module implementation macro NS_IMPL_NSGETMODULEdo this later on. This macro takes Here is an array of nsModuleComponentInfo so that you can define more than one component per module (remember that a module is a collection of components, example Component ID and every component belongs to a module so what it can get loaded by the system).means:

Start by generating another uuid that will be used for identifying our component "@mozilla.org/class, for example:network/ldap-operation;1"

19f3ef5e* domain = @mozilla.org* module = network* component = ldap-759f-49a4-88e3-ed27f9c83011operation* version = 1

Then we can populate our componets array with a single entry for the == FirstXpcom component:.cpp ==

static const nsModuleComponentInfo components[] ={ { "All that remains is our implementation. Here is the final version of '''FirstXpcom", // descriptive name FIRSTXPCOM_CID, // CID from above "@senecac.on.ca/firstxpcom;1", // Contract ID FirstXpcomConstructor // Factory Constructor }};cpp''' (emphasis added to highlight changes):

The last two need some explanation '''#include <stdio. h> // for printf()''' The Component ID is a human-readable string that clients can use to get#include "IFirstXpcom.h" // the CPP .h generated from our .idl #include "nsIGenericFactory.h" // for NS_GENERIC_FACTORY_CONSTRUCTOR() #include "nsStringAPI.h" //create an instance of your for nsString classFirstXpcom : public IFirstXpcom { public: NS_DECL_ISUPPORTS NS_DECL_IFIRSTXPCOM FirstXpcom(); private: ~FirstXpcom(); protected: '''nsString mName;''' }; NS_IMPL_ISUPPORTS1(FirstXpcom, IFirstXpcom) FirstXpcom::FirstXpcom() { /* member initializers and constructor code */ '''mName. Assign(NS_LITERAL_STRING("FirstXpcom Component"));''' We} FirstXpcom::~FirstXpcom() { /* destructor code */ } /* attribute AString name; */ NS_IMETHODIMP FirstXpcom::GetName(nsAString & aName) { '''ll see how to do this later onaName. Assign(mName);''' '''printf("FirstXpcom::GetName\n");''' '''return NS_OK;''' Here is an example Component ID and what it means} NS_IMETHODIMP FirstXpcom::SetName(const nsAString & aName) { '''mName.Assign(aName);''' '''printf("FirstXpcom::SetName\n"@mozilla.org);''' '''return NS_OK;''' } /network* long add (in long a, in long b); */ldap-operation NS_IMETHODIMP FirstXpcom::Add(PRInt32 a, PRInt32 b, PRInt32 *_retval) { '''printf("FirstXpcom::Add(%d, %d)", a, b);''' '''*_retval = a + b;''' '''return NS_OK;1"''' } domain = @mozilla // This will result in a function named FirstXpcomConstructor.orgmodule = network '''NS_GENERIC_FACTORY_CONSTRUCTOR(FirstXpcom)''' component = ldap '''// 19f3ef5e-759f-49a4-88e3-operationed27f9c83011 ''' '''#define FIRSTXPCOM_CID \''' '''{0x19f3ef5e, 0x759f, 0x49a4, \''' '''{ 0x88, 0xe3, 0xed, 0x27, 0xf9, 0xc8, 0x30, 0x11} }''' version '''static const nsModuleComponentInfo components[] = 1''' '''{'''The final line '''{ "FirstXpcom", the constructor''' '''FIRSTXPCOM_CID, is the name of the constructor automatically generated by the NS_GENERIC_FACTORY_CONSTRUCTOR''' '''"@senecac.on. It will be the name of your concrete class followed by ca/firstxpcom;1"Constructor," in our case ''' '''FirstXpcomConstructor. ''' '''}''' '''};''' '''NS_IMPL_NSGETMODULE(FirstXpcomModule, components)'''

And that's it! We've done it. Time to call make again:

$ cd $(objdir)/extensions/firstxpcom $ make

* Generated makefiles for your projects project were created in extensions/firstxpcom/ (remember, we’re we're under /mozilla/$(MOZ_OBJDIR)/.

* Static libraries for your modules in dist/lib/ (in case other modules want to link statically to your stuff instead of using XPCOM).

* Everything else in dist/bin/extensions/firstxpcom@senecac.on.ca/.

$ cd $(objdir)/dist/bin$ export MOZ_NO_REMOTE=1$ export MOZ_DEBUG_BREAK=warn$ firefox.exe Checking the Add-Profilemanageron Manager ==

Now letWe's try ll write formal tests and access this from JS code to use our component later. For now, make sure it gets loaded into Firefox and is visible in the browserAddon Manager. If Run Firefox and make sure you haven't done so already, download can see your extension in the Extension Developer's Extensionaddon manager:

http: $ cd $(objdir)/dist/tedbin $ export MOZ_DEBUG_BREAK=warn $ firefox.mielczarek.org/code/mozilla/extensiondev/index.htmlexe -Profilemanager -no-remote

This will allow you to use == Accessing FirstXpcom from the JavaScript Shell inside the browser, making it easy to try out the firstxpcom component (see http://developer.mozilla.org/en/docs/Introduction_to_the_JavaScript_shell).==

Lauch Now let's try and access this from JavaScript in the browser. If you haven't done so already, download and install the JSShell (Tools > [http://ted.mielczarek.org/code/mozilla/extensiondev/index.html Extension Developer > Javascript 's extension]. This will allow you to use the [http://developer.mozilla.org/en/docs/Introduction_to_the_JavaScript_shell JavaScript Shell) and write some code ] inside the browser, making it easy to access your XPCOM try out the firstxpcom component:.

// Define our Launch the JS Shell ('''Tools > Extension Developer > Javascript Shell''') and write some code to access your XPCOM component's ID so we . You can create an instance of it belowwork interactively without having to define functions, write a complete extension, etc.const cid = "@senecac.on.ca/firstxpcom;1"print(cid):

// This will * Define our component's ID so we can create an instance of our firstxpcom class and return it as nsISupportsvar obj = Components.classes[cid]below.createInstance()

const cid = "@senecac.on.ca// This will take the nsISupports object returned above and QI it to IFirstXpcomfirstxpcom;1"obj = obj.QueryInterface print(Components.interfaces.IFirstXpcomcid)

// Now we can use the IFirstXpcom methods and attributes var sumsum obj = objComponents.classes[cid].addcreateInstance(4,5)

var namename = * Next, take the the nsISupports object returned above and query it (i.e., see if it supports your interface type and if so, change to that interface) to IFirstXpcom, often referred to as QI (e.g., ''"Dave Humphrey...you need to QI it to IFirstXpcom..."'').

obj = obj.QueryInterface(Components.interfaces.IFirstXpcom) * At this point we have the ability to use the IFirstXpcom methods and attributes:  var sum sum = obj.add(4,5) var name name = "FirstXpcom!" obj.name = name print(obj.name) alert(obj.name)

When you run this code, also notice how your C++ '''printf ''' statements are sending causing messages to stdout in your shell console window (you may need to scrollback through all the other messages to find them).

* Close minefield* Open VS[[Makefile.NET and choose File > Open Project/Solution...* Open $(objdir)/dist/bin/firefox.exe* Right-click the firefox.exe item in the Solution Explorer and choose Properties* Add the following to "Command Arguments": Template for In-p <development_profile_name> or -Profilemanager if you don't have one yet.* Add the following to "Environment": XPCOM_DEBUG_BREAK=warn. Click OK* File > Open... mozilla/extensions/firstxpcom/src/FirstXpcom.cpp* Set a breakpoint on ::Add --> *_retval = a + b;* Click "Start Debugging" (the "play" button)* Follow the same steps above in the Javascript Shell in order to create and call add() on your component.* Use F11 to move line by line when you get dropped into the debugger, and F5 to continue.Tree Extensions]]