Changes

[[Dive into Real World Mozilla]] > [[Dive into Real World Mozilla Day 3]] > First XPCOM Component

'''NOTE: the following assumes you have used an objdir. Replaced Replace all occurrences of $(objdir) with your objdir name.'''

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.

[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 defines 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. 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.

What does line three mean? This says that our component is '''[scriptable''', and can be used or implemented in scripting languages, JavaScript for example uuid(...see http://developerbelow..mozilla.org/en/docs/Interfaces:About_Scriptable_Interfaces).]

Each interface needs to be uniquely identifiable, and Mozilla uses a 128-bit number called a What does line 3 mean? This says that our component is '''UUIDscriptable''' , and can be used or implemented in scripting languages, JavaScript for example (Universally Unique Identifiersee http://developer.mozilla.org/en/docs/Interfaces:About_Scriptable_Interfaces) for this purpose. You can generate one using a number of methods:

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: * in MSYS, use at the command prompt using the command-line program '''uuidgen.exe''':

attribute AString name; long add(in long a, in long b); 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 about strings in Mozilla, see the [http://developer.mozilla.org/en/docs/XPCOM_string_guideXPCOM String Guide]).

Our interface also defines a single method called '''add''', which takes two long integers as input, adds them, and returns the result 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. But To do this we first we have to generate some makefiles.

Note the '''DIRS''' variable. It says that the two directories, public and src, will be entered during the build. That means Because Mozilla's build system [http://developer.mozilla.org/en/docs/How_Mozilla%27s_build_system_works uses recursive make], we also need Makefile.in files in each of these.

Here we tell the build system about our component's name and where it's its XPIDL file can be found.

The last build-related file we need to write is a file telling Firefox's addon manager about our extension and how to install it--'''install.rdf'''. Put this in '''mozilla/extensions/firstxpcom''': (see http://developer.mozilla.org/en/docs/Install_Manifests for details).:

<em:maxVersion>3.0a3pre0b2pre</em:maxVersion> <!-- trunk build Feb 27Nov 11, 2007 -->

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

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):

''As an aside, and while you are thinking about Makefiles, you might take a moment to read [https://bugzilla.mozilla.org/show_bug.cgi?id=371201 bug 371201]. This is a bug that was identified while the author was trying to debug his Makefile.in files. Ted Mielczarek (luser ted on IRC) was finally able to spot the problem--a trailing space on XPI_NAME. I share this anecdote as a way to introduce https://bugzilla.mozilla.org, to emphasize the necessity of the community, and to show the kind of problems that one can have writing files for the build system.--UPDATE: this bug has now been fixed by Ted (March 26, 2007).''

NS_DECL_ appended with any interface name in all caps will declare all of the methods of that interface for you(nsIFoo --> 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.h was generated by the XPIDL compiler. Consider the following real class:

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

As an example, consider [http://lxrbonsai.mozilla.org/seamonkey/sourcecvsblame.cgi?file=mozilla/xpcom/io/nsBinaryStream.cpp&rev=1.32&raw=1&mark=65&#62 65 seamonkeymozilla/xpcom/io/nsBinaryStream.cpp]:

Now [http://developer.mozilla.org/En/Generating_GUIDs write a define ] to make it easier to pass this Class ID aroundin C++:

'''mName.Assign(LNS_LITERAL_STRING("FirstXpcom Component"));'''

$ firefox.exe -Profilemanager --no-remote

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