]> Table of Contents

Comments (useful for licensing) Create a template component from scratch. Create a module to register your component. Create a Makefile.in to build your component within Mozilla's source tree. Get a new instance of a component. Get a component as a service. Add an interface to your component for QueryInterface support. Query a component for support of a particular interface. Report a XPCOM error code to XPCOM. Handle a XPCOM error code. Check if a value is null. Set a value to null. Pass an argument you already have to a component's method (in parameter). Pass an argument you created to a component's method (in parameter). Pass a return argument you already have to a component's method. Pass a return argument you created to a component's method. Return a value from a component's method. Pass more than one return value to a component's method. Return more than one value from a component's method. Pass an array to a component's method. Handle a passed-in array in a component's method. Access properties of an interface. Access properties of a component. Define a component's property, and getters and setters therein. Dump a string to the debug console.

Comments (useful for licensing) Create a template component from scratch.


#include "nsISupports.idl"

Replace the uuid string below with a new UUID.
On irc://irc.mozilla.org, /msg firebot uuid
On Linux or Windows with CygWin, from the command line, type uuidgen.

[scriptable, uuid(1a956d87-4399-4f2d-ab8e-b57e8c932c38)]
interface fooIBar : nsISupports {
};


Find the generated fooIBar.h file in a subdirectory of
$(MOZ_OBJDIR)/dist/include.
It will contain a section resembling:
/* Header file */
class fooBar : public fooIBar
{
public:
  NS_DECL_ISUPPORTS
  NS_DECL_FOOIBAR

  fooIBar();

private:
  ~fooIBar();

protected:
  /* additional members */
};

Copy this section, stopping before the line:
/* Implementation file */


Find the generated fooIBar.h file in a subdirectory of 
$(MOZ_OBJDIR)/dist/include.
It will contain a section resembling:
/* Implementation file */
NS_IMPL_ISUPPORTS1(fooBar, fooIBar)


fooBar::fooBar()
{
  /* member initializers and constructor code */
}

fooBar::~fooBar()
{
  /* destructor code */
}

Copy this section, stopping before the line:
/* End of implementation class template. */

Don't forget to create a module cpp file for your component!


JavaScript components, unlike C++ components, include their
factory and module constructs in the same file.  Copy the code from
templateComponent.js,
filling in the license boilerplate (or removing it per licensing requirements),
and then changing these lines:

// Do a global replace of "fooIBar" with your component's implemented interface name.
var componentIDL = "fooIBar";
// Do a global replace of "fooBar" with your component's constructor function name.
var componentConstructor = "fooBar";
/* Replace this UUID with a new one.  Do not use the one you used in the IDL file.
   See the above instructions on how to get a UUID.
 */
var componentId   = Components.ID("{758cfec1-0b29-4f39-aeae-7083f80eda5c}");
/* Replace this contract id with an appropriate one.  Use your website domain
   name, and a short component title.
 */
var contractId    = "@foo.org/bar-contract-id;1";

Create a module to register your component. Nothing to do here. Nothing to do here.


If you copied templateComponent.js and updated it for your needs,
there is nothing to do here.

Create a Makefile.in to build your component within Mozilla's source tree. Build your component without modifying Mozilla's source tree.


You'll need to build the XPIDL executable.  This will require you
have checked out the mozilla source code and set the $(MOZCONFIG) environment
variable.  Then:

cd mozilla
make -f client.mk configure
cd $(MOZ_OBJDIR)
make tier_0 tier_1 tier_2

Then change to your IDL's source directory.  XPT_LIB is the name
of the .xpt file you want to create, minus the extension.

$(MOZ_OBJDIR)/dist/bin/xpidl -m typelib -o $(TARGET_DIR)/$(XPT_LIB) $(IDL_FILE)


Follow the steps for IDL building.
Then copy the JS file to your target directory.

Get a new instance of a component.


nsresult rv;
nsCOMPtr<fooIBar> obj = do_CreateInstance(contractId, &rv);
if (NS_FAILED(rv))
  return rv;


var obj = Components.classes[contractId]
                    .createInstance(Components.interfaces.fooIBar);

Get a component as a service.


nsresult rv;
nsCOMPtr<fooIBar> obj = do_GetService(contractId, &rv);
if (NS_FAILED(rv))
  return rv;


var obj = Components.classes[contractId]
                    .getService(Components.interfaces.fooIBar);

Add an interface to your component for QueryInterface support.


Add the interface name as a public base class for your class.
class bazBaz : public fooIBar,
               public bazIWop
{
public:
  // nsISupports
  NS_DECL_NSISUPPORTS

  // fooIBar
  NS_DECL_FOOIBAR

Add the interface name, prefixed by "NS_DECL_", and all in capital
letters, to the public portion of your component's class.
  // bazIWop
  NS_DECL_BAZIWOP
}


Find the generated fooIBar.h file in a subdirectory of 
$(MOZ_OBJDIR)/dist/include.
It will contain a section resembling:
/* Implementation file */
NS_IMPL_ISUPPORTS1(fooBar, fooIBar)

fooBar::fooBar()
{
  /* member initializers and constructor code */
}

fooBar::~fooBar()
{
  /* destructor code */
}

Copy this section, after the NS_IMPL_ISUPPORTS1 line, stopping
before the line:
/* End of implementation class template. */
In your C++ file, find the line that says NS_IMPL_ISUPPORTS with
a number at the end (NS_IMPL_ISUPPORTS1, NS_IMPL_ISUPPORTS2,
NS_IMPL_ISUPPORTS3, etc.)
Add one to that number (1 -> 2, 2 -> 3, etc.) and add the new
interface name as a new argument.  Using the example above, it might be:


NS_IMPL_ISUPPORTS2(fooBar, fooIBar, bazIWop)

If you implement nsIClassInfo, adjust it accordingly.


For each method of the new interface, add a method to the
prototype which throws Components.results.NS_ERROR_NOT_IMPLEMENTED.  Using the
templateComponent.js
example, this might look like: 
fooIBar.prototype = {
  // bazIWop
  wop: function wop(arg1, arg2)
  {
    NOT_IMPLEMENTED();
  },

  /* ... */
}
In the QueryInterface method of your constructor's prototype, add
a line for the new component.  If you're nice enough to have implemented
nsIClassInfo, add a line for that one too.  From the
templateComponent.js
example:
    if (aIID.equals(Components.interfaces.fooIBar) ||
        aIID.equals(Components.interfaces.bazIWop) ||
        aIID.equals(Components.interfaces.nsISupports))
      return this;

Query a component for support of a particular interface.



// Test for an error code on rv.


if (bar instanceof Components.interfaces.fooIBar)
{
  /* ... */
}

Report to XPCOM that everything happened normally.


return NS_OK;


Do not throw any exceptions, just return your out value.

Report a XPCOM error code to XPCOM.


return NS_ERROR_(ERROR_NAME);


throw Components.results.NS_ERROR_(ERROR_NAME);

Handle a XPCOM error code.


C++ treats an XPCOM error as a returned value from a function.
So if you want a XPCOM error code to propagate, you need to call:
NS_ENSURE_SUCCESS(rv, rv);

// Or

if (NS_FAILED(rv))
  return rv;

If you want to selectively handle the error, use:

if (rv == NS_ERROR_(ERROR_NAME))
{
  // ...
}

Generally speaking, it is bad form not to check for XPCOM errors
in C++.


JavaScript treats XPCOM errors as thrown exceptions.  If you want
a XPCOM error to propagate, you need do nothing.

If you want to selectively handle the error, use:
try
{
  // do method
}
catch (e)
{
  // Within XPCOM component code, e is a number.
  // Outside XPCOM component code, e is an error.
}

Check if a value is null.


With nsCOMPtr's, you just need to check if the value itself evaluates to null in a condition.
bar = do_QueryInterface(fooIBar);
if (!bar)
{
  // the value is null.
}

With DOM strings, there is a convenience function.
if (DOMStringIsNull(string))
{
  // the value is null.
}


You should explicitly check against the null object.
if (bar === null)
{
  // the value is null.
}

If you know your value is an object, you can do this instead:
var node = walker.nextNode();
if (!node)
{
  // the value is null.
}

Set a value to null.


With nsCOMPtr's, you use the nsnull value.
bar = nsnull;

With DOM strings, you use the SetDOMStringToNull method.
SetDOMStringToNull(bar);


bar = null;

Pass an argument you already have to a component's method (in parameter).


nsresult
nsXPathGenerator::GetStep(nsINode* iterator,
                          nsINode* aRoot,
                          nsXPathBaseNodeFilter * nodeListFilter,
                          nsString & currentStep,
                          generatorWrapper & data)
{
  // ...
  rv = traversal->CreateTreeWalker(rootAsDOM,
                                   whatToShow,
                                   nodeFilter,
                                   PR_TRUE,
                                   getter_AddRefs(walker));
 // ...
}


fooBar = {
  getWop: function getWop(baz)
  {
    return this.getRealWop(baz);
  }
}

Pass an argument you created to a component's method (in parameter).


  nsCOMPtr<nsIDOMNode> rootAsDOM = do_QueryInterface(aRoot, &rv);
  NS_ENSURE_SUCCESS(rv, rv);

  rv = traversal->CreateTreeWalker(rootAsDOM,
                                   whatToShow,
                                   nodeFilter,
                                   PR_TRUE,
                                   getter_AddRefs(walker));


const nsIDOMNodeFilter = Components.interfaces.nsIDOMNodeFilter;
var filter = {
  acceptNode: function acceptNode(aNode)
  {
    return Components.interfaces.nsIDOMNodeFilter.FILTER_SKIP;
  }
};

var walker = document.createTreeWalker(document, nsIDOMNodeFilter.SHOW_ELEMENT, filter, true);

Pass a return argument you already have to a component's method.


nsresult
nsTreeWalker::FirstChildOf(nsINode* aNode,
                           PRBool aReversed,
                           PRInt32 aIndexPos,
                           nsINode** _retval)
{
    /* These lines don't matter for this example */
    *_retval = nsnull;
    PRInt32 start = aReversed ? (PRInt32)aNode->GetChildCount() : -1;

    return ChildOf(aNode, start, aReversed, aIndexPos, _retval);
}

/*
nsresult
nsTreeWalker::ChildOf(nsINode* aNode,
                      PRInt32 childNum,
                      PRBool aReversed,
                      PRInt32 aIndexPos,
                      nsINode** _retval)
 */


Just return what the component returns.
return obj.doSomething();

Pass a return argument you created to a component's method.

If it is a nsCOMPtr, do the following:
nsresult rv = foo->bar(getter_AddRefs(ptr));
If it is a primitive type (PRBool, PRUint, etc.), do the following:
nsresult rv = foo->bar(&value);


You don't actually pass it in; it'll be what the method returns (if no exceptions
were thrown).
retval = foo.bar();

Return a value from a component's method.


Objects you must NS_ADDREF (except for null values).  If the value
may be null, use NS_IF_ADDREF(value).
Primitive types, or variants, do not get NS_ADDREF or NS_IF_ADDREF
called on them.
// fooIBaz
NS_IMETHODIMP
fooBar::GetBaz(PRUint32 *aBaz)
{
  *aBaz = mBaz;
  return NS_OK;
}

//fooIBaz
NS_IMETHODIMP
fooBar::GetWop(nsIWop** aWop)
{
  NS_ADDREF(*aWop = mWop);
  return NS_OK;
}


return val;

Pass more than one return value to a component's method.


IDL allows you to prefix params with the out keyword, for return values.
PRBool test(in AString aTarget, out PRBool otherValue);

Incidentally, the above IDL method declaration is equivalent to:
void test(in AString aTarget, out PRBool otherValue, out PRBool _retval);

XPIDL also allows you to prefix params with the inout keyword,
 for values that are passed in and return something different.

void test(in AString aTarget, inout PRBool otherValue);


Just set the out arguments as you normally would.
The function declaration will have the correct arrangement of arguments
you need to create.


The last out parameter of the IDL becomes the return value of the
method call.
Other out parameters should be passed in as objects.
Their .value property will be set to the returned value for that parameter.


var otherValue = {};
var _retval = obj.test("foo", otherValue);
otherValue = otherValue.value;

For inout parameters, set the value property to the value you are
passing in, and the method will set the value property to the value it returns.

var otherValue = {value: true};
var _retval = obj.test("foo", otherValue);
otherValue = otherValue.value;

Return more than one value from a component's method.


IDL allows you to prefix params with the out keyword, for return values.
PRBool test(in AString aTarget, out PRBool otherValue);

Incidentally, the above IDL method declaration is equivalent to:
void test(in AString aTarget, out PRBool otherValue, out PRBool _retval);

XPIDL also allows you to prefix params with the inout keyword,
 for values that are passed in and return something different.

void test(in AString aTarget, inout PRBool otherValue);


If you are able to set a return value for one parameter in a C++
based component, you can set as many return values as you want.  Just repeat
the same process.


If the IDL specifies a void return, the last out param of the IDL definition
becomes your return value.
If the IDL specifies a non-void return, that becomes your return value.
For all other out parameters, you must set each out parameter's value property
to the value you intend to return.
var _retval = false;
otherValue.value = true;
return _retval;

Pass an array to a component's method.


There are actually two ways IDL can define an array.  The first is as a pair of arguments:
the length of the array, and the actual array itself.
void PrintIntegerArray(in PRUint32 count, 
                       [array, size_is(count)] in PRInt32 valueArray);
The second is to declare a 
nsIArray
or
nsIMutableArray
argument.  nsIArray is read-only, while nsIMutableArray is read and write.
void CreateEncrypted(in nsIArray aRecipientCerts);
For nsIArray and nsIMutableArray, the class name is:
"@mozilla.org/array;1"
As a rule of thumb, use XPIDL-based arrays for arrays of a single
primitive type, in or out (not inout). For anything else, use nsIArray or
nsIMutableArray.
Note XPIDL-based arrays do not do refcounting (AddRef, Release) on members.


You treat XPIDL-based arrays and multiple objects in the same way.
The following is borrowed from
http://lxr.mozilla.org/seamonkey/source/js/src/xpconnect/src/xpcwrappednativeinfo.cpp .

    nsIID** iidArray = nsnull;
    PRUint32 iidCount = 0;
    nsresult rv = classInfo->GetInterfaces(&iidCount, &iidArray);


You treat XPIDL-based arrays and multiple objects in the same way.
var count = {};
var valueArray = obj.printIntegerArray(count);
// valueArray.length should be count.value;

Handle a passed-in XPIDL-based array in a component's method.


This code was borrowed from
http://lxr.mozilla.org/seamonkey/source/extensions/xforms/nsXFormsStubElement.cpp .
NS_IMETHODIMP
nsXFormsStubElement::GetScriptingInterfaces(PRUint32 *aCount, nsIID ***aArray)
{
  return nsXFormsUtils::CloneScriptingInterfaces(sScriptingIIDs,
                                                 NS_ARRAY_LENGTH(sScriptingIIDs),
                                                 aCount, aArray);
}

This code was borrowed from
http://lxr.mozilla.org/seamonkey/source/extensions/xforms/nsXFormsUtils.cpp .
Keep your eyes on the pointers (*aOutArray, **iids, ***aOutArray).
/* static */ nsresult
nsXFormsUtils::CloneScriptingInterfaces(const nsIID *aIIDList,
                                        unsigned int aIIDCount,
                                        PRUint32 *aOutCount,
                                        nsIID ***aOutArray)
{
  nsIID **iids = NS_STATIC_CAST(nsIID**,
                                nsMemory::Alloc(aIIDCount * sizeof(nsIID*)));
  if (!iids) {
    return NS_ERROR_OUT_OF_MEMORY;
  }
 
  for (PRUint32 i = 0; i < aIIDCount; ++i) {
    iids[i] = NS_STATIC_CAST(nsIID*,
                             nsMemory::Clone(&aIIDList[i], sizeof(nsIID)));
 
    if (!iids[i]) {
      for (PRUint32 j = 0; j < i; ++j)
        nsMemory::Free(iids[j]);
      nsMemory::Free(iids);
      return NS_ERROR_OUT_OF_MEMORY;
    }
  }
 
  *aOutArray = iids;
  *aOutCount = aIIDCount;
  return NS_OK;
}


Remember to set the length of the array as the value of the length object.
/* 
  void exec(in AString aTarget,
            out unsigned long aCount,
            [retval, array, size_is(aCount)] out wstring aValues);
 */
function exec(aTarget, aCount)
{
  var aValues = this.regexp.exec(aTarget);
  aCount.value  = aValues.length;
  return aValues;
}

Access properties of an interface.


fooIBar::PROPERTY_NAME


Components.interfaces.fooIBar.PROPERTY_NAME

Access properties of a component.


nsCOMPtr<nsIFooBar> fooBarPtr = do_QueryInterface(component, &rv);
NS_ENSURE_SUCCESS(rv, rv);
PRBool myBaz;
rv = fooBarPtr->GetBaz(&myBaz);
NS_ENSURE_SUCCESS(rv, rv);

nsCOMPtr<nsIWop> myWop;
rv = fooBarPtr->GetWop(myWop);
NS_ENSURE_SUCCESS(rv, rv);

// Your value now lives in *myWop.


// QI the component to the interface first.
myWop = component.wop;

Define a component's property, and getters and setters therein.


  attribute PRUint32 baz;
  attribute nsIWop wop;


This should be handled by your importing the IDL header.


fooBar::fooBar() :
  mBaz(0),
  mWop(nsnull)
{
}

// fooIBar baz property 
NS_IMETHODIMP
fooBar::GetBaz(PRUint32 *aBaz)
{
  *aBaz = mBaz;
  return NS_OK;
}
NS_IMETHODIMP
fooBar::SetBaz(PRUint32 aBaz)
{
  mBaz = aBaz;
  return NS_OK;
}

// fooIBar wop property
NS_IMETHODIMP
fooBar::GetWop(nsIWop** aWop)
{
  NS_ADDREF(*aWop = mWop);
  return NS_OK;
}
NS_IMETHODIMP
fooBar::SetWop(nsIWop* aWop)
{
  mWop = aWop;
}


One way is just to name the property in the constructor.
function fooBar() {
  // fooIBar
  this.baz = 0;
}

A more flexible way is to use getters and setters.
function fooBar() {
  this.mBaz = 0;
}
fooBar.prototype = {

  // fooIBaz
  get baz() {
    return this.mBaz;
  }
  set baz(aBaz) {
    this.mBaz = aBaz;
  }

}

Dump a string to the debug console.


#ifdef DEBUG
printf "This is going to the console.\n";
#endif


var str = "This is going to the console.\n";
dump(str);

Your basic QueryInterface, AddRef, Release implementation. For JS-based components, you only need to implement QueryInterface.