NS_ADDREF
ns_addref(foo) is equivalent to foo->addref(); this macro exists mainly for historical reasons, but for consistency and for symmetry with ns_release it should still be used.
... syntax ns_addref(foo); see also ns_if_addref ns_release ...

Modularization techniques - Archive of obsolete content
the convenience macros ns_addref() and ns_release() are preferred over calling addref and release directly.
... nsresult getfoo(ifoo **afoores) { if (afoores == null) { return ns_error_null_pointer; } *afoores = mfoo; ns_addref(*afoores); return ns_ok; } remember that this applies to the interfaces returned by queryinterface(), createinstance() and ns_newx(), and you must call release() on them when you are done to avoid memory leaks.
... nsresult refreshfoo(ifoo **afoo) { if (afoo == null || *afoo == null) { return ns_error_null_parameter; } if ((*afoo)->stale()) { ns_release(*afoo); *afoo = mfoo; ns_addref(*afoo); } return ns_ok; } global and member variables both global and member variables have lifetimes that can be changed by any number of functions.
... ns_addref(mfoo); tweekfoo(mfoo); ns_release(mfoo); (soon to be) frequently asked questions why are we mimicking com?

Implementing QueryInterface
if ( aiid.equals(nscomtypeinfo<nsisupports>::getiid()) ) foundinterface = ns_static_cast(nsisupports*, ns_static_cast(nsix*, this)); // i (may) have multiple |nsisupports| in me, // so first i cast to a specific base to avoid ambiguity else foundinterface = 0; nsresult status; if ( !foundinterface ) status = ns_nointerface; else { ns_addref(foundinterface); status = ns_ok; } *ainstanceptr = foundinterface; return status; } what's so good about it?
... status = nsbaseimplementation::queryinterface(aiid, &foundinterface); else { ns_addref(foundinterface); status = ns_ok; } *ainstanceptr = foundinterface; return status; } note that if the base implementation's queryinterface finds an appropriate interface, your queryinterface must not addref it.
... status = nsbase1imp::queryinterface(aiid, &foundinterface); if ( !foundinterface ) status = nsbase2imp::queryinterface(aiid, &foundinterface); if ( !foundinterface ) status = nsbase3imp::queryinterface(aiid, &foundinterface); } else { ns_addref(foundinterface); status = ns_ok; } // ...

XPCOM array guide
// return it to the caller *aresult = array; ns_addref(*aresult); } javascript example function getlist() { var array = components.classes["@mozilla.org/array;1"] .createinstance(components.interfaces.nsimutablearray); // append some elements ...
... // old version, relied on automatic addref // melements is an nsisupportsarray* void getfirstobject(nsielement** aresult) { // no need to call ns_addref - this does it for you melements->queryelementat(0, ns_get_iid(nsielement), (void**)aresult); } // new version, make sure to call ns_addref() // melements is now a nscomarray<nsielement> void getfirstobject(nsielement** aresult) { *aresult = melements[0]; ns_addref(*aresult); } passing as a parameter when passing nscomarray<t> among functions, the convention is to pass by reference.

Starting WebLock
this is a simple thing to do, but it requires that you pay special attention to the ns_addref.
... ns_imethodimp weblock::getsites(nsisimpleenumerator * *asites) { myenumerator* enumerator = new myenumerator(mrooturlnode); if (!enumerator) return ns_error_out_of_memory; ns_addref(*asites = enumerator); return ns_ok; } addref, releasing, and deleting objects never forget to addref an xpcom object which you instantiate via new.

NS_IF_ADDREF
only use this macro if the pointer might be null; use ns_addref otherwise.
... ns_if_addref(foo) is equal to if (foo) foo->addref(); syntax ns_if_addref(foo); see also ns_addref ...

Obsolete: XPCOM-based scripting for NPAPI plugins - Archive of obsolete content
nsitestplugin *scriptablepeer = (nsitestplugin *)instance->pdata; // see if this is the first time and we haven't created it yet if (!scriptablepeer) { nsitestplugin *scriptablepeer = new nsscriptablepeer(); if (scriptablepeer) ns_addref(scriptablepeer); // addref for ourself, // don't forget to release on // shutdown to trigger its destruction } // add reference for the caller requesting the object ns_addref(scriptablepeer); *(nsisupports **)value = scriptablepeer; } else if (variable == nppvpluginscripta...

Mozilla DOM Hacking Guide
nsiclassinfo* nsdomclassinfo::getclassinfoinstance(nsdomclassinfoid aid) { if(!sisinitialized) { nsresult rv = init(); } if(!sclassinfodata[aid].mcachedclassinfo) { nsdomclassinfodata &data = sclassinfodata[aid]; data.mcachedclassinfo = data.u.mconstructorfptr(&data); ns_addref(data.mcachedclassinfo); } return sclassinfodata[aid].mcachedclassinfo; } here is the short explanation: this method returns the mcachedclassinfo member of the nsdomclassinfodata structure that corresponds to aid in the sclassinfodata array, if it exists, i.e.

Aggregating the In-Memory Datasource
eturn ns_error_null_pointer; if (aiid.equals(nscomtypeinfo<nsimyinterface>::getiid()) || aiid.equals(nscomtypeinfo<nsisupports>::getiid())) { *aresult = ns_static_cast(nsiglobalhistory*, this); } else if (aiid.equals(nscomtypeinfo<nsirdfdatasource>::getiid())) { return minner->queryinterface(aiid, aresult); } else { *aresult = nsnull; return ns_nointerface; } ns_addref(ns_static_cast(nsisupports*, aresult)); return ns_ok; } the only other thing that you'll need to be aware of is that you'll need to queryinterface() from nsisupports to nsirdfdatasource before you can actually do anything useful with the datasource from within your object.

An Overview of XPCOM
ns_addref calls addref on an nsisupports object.

Creating the Component Code
the variable kifactoryiid, for example, provides methods like equals() that can be used to facilitate comparisons in the code, as in the following example from the mozilla source: using class methods to handle identifiers if (aiid.equals(ns_get_iid(nsisupports))) { *ainstanceptr = (void*)(nsisupports*)this; ns_addref_this(); return ns_ok; } finally, sample_cid is an example of a cid that uniquely identifies the component.

Index
141 ns ensure success xpcom, xpcom_macros macro 142 ns ensure true xpcom, xpcom_macros macro 143 ns_abort_if_false this was removed in bug 1127201 144 ns_addref xpcom, xpcom_macros macro 145 ns_assertion xpcom, xpcom_macros macro 146 ns_ensure_arg_pointer xpcom, xpcom_macros macro 147 ns_error xpcom, xpcom_macros throws a assertion (ns_assertion) with the text "error: (error text)", so writes this text to console (stderr) and to debug logs (nspr logging).

mozIStorageAggregateFunction
data[i] - mean; data[i] = value * value; } total = 0; for (pruint32 i = 0; i < data.length(); i++) total += data[i]; nscomptr<nsiwritablevariant> result = do_createinstance("@mozilla.org/variant;1"); ns_ensure_true(result, ns_error_out_of_memory); rv = result->setasdouble(sqrt(double(total) / double(data.length()))); ns_ensure_success(rv, rv); ns_addref(*_result = result); return ns_ok; } private: nstarray<print32> mnumbers; }; // now, register our function with the database connection.

mozIStorageFunction
uearray *aarguments, nsivariant **_result) { print32 value; nsresult rv = aarguments->getint32(&value); ns_ensure_success(rv, rv); nscomptr<nsiwritablevariant> result = do_createinstance("@mozilla.org/variant;1"); ns_ensure_true(result, ns_error_out_of_memory); rv = result->setasint64(value * value); ns_ensure_success(rv, rv); ns_addref(*_result = result); return ns_ok; } }; // now, register our function with the database connection.

NS_IF_RELEASE
ns_if_release is exactly equivalent to the following function: inline void ns_if_release(nsisupports* foo) { if (foo) foo->release(); foo = 0; } syntax ns_if_release(foo); see also ns_addref, ns_release ...