NS_IF_ADDREF
ns_if_addref(foo) is equal to if (foo) foo->addref(); syntax ns_if_addref(foo); see also ns_addref ...

Getting Started Guide
*/ ns_if_addref(afooptr); nsifoo* temp = mfooptr; mfooptr = afooptr; ns_if_release(temp); // |nscomptr|...
... */ ns_if_release(mfooptr); mfooptr = afooptr; ns_if_addref(mfooptr); // |nscomptr|...
... */ ns_if_release(mfooptr); // error: |release| is private mfooptr = afooptr; ns_if_addref(mfooptr); // error: |addref| is private second: you can't just pass the address of an nscomptr to a getter expecting to return a result through a raw xpcom interface pointer parameter.

Using XPCOM Utilities to Make Things Easier
this is a common pattern when you have a local nscomptr in a function and you must pass back a reference to it, as in the following: someclass::get(nsisupports** aresult) { if (!aresult) return ns_error_null_pointer; nscomptr<nsisupports> value; object->method(getter_addrefs(value)); *aresult = value.get(); ns_if_addref(*aresult); return ns_ok; } the first thing that this method does is check to see that the caller passed a valid address.
...this raw pointer can then be assigned to a variable and have its reference updated by ns_if_addref.

NS_ADDREF
do not use when the pointer might be null; use ns_if_addref in those cases.
... syntax ns_addref(foo); see also ns_if_addref ns_release ...

An Overview of XPCOM
ns_if_addref same as above but checks for null before calling addref.

Index
148 ns_if_addref xpcom, xpcom_macros macro 149 ns_if_release xpcom, xpcom_macros macro 150 ns_release xpcom, xpcom_macros macro 151 ns_warning xpcom, xpcom_macros macro 152 standard xpcom components components, landing, mozilla, needscontent, xpcom there are a number of components provided in the standard implementation ...

XPCOM reference
this macro is meant for critical errors; like assertions, ns_errors should not be reachable.ns_if_addrefmacrons_if_releasemacrons_releasemacrons_warningmacronsgetmoduleprocthis function prototype provides the xpcom entry-point into a module.nsiabcard/thunderbird3the nsiabcard interface is used to represent and manipulate cards in the address book.

already_AddRefed
already_addrefed<nsifoo> getfoo() { nsifoo* foo = mfoo; ns_if_addref(foo); return foo; } // or already_addrefed<nsifoo> getfoo() { nscomptr<nsifoo> foo = mfoo; // ...