XPCOM reference

This reference describes the interfaces and functions provided by the XPCOM library. In addition, it details the various helper classes and functions, as well as the components, provided by the XPCOM glue library. The contents herein are oriented primarily toward extension developers and people embedding XPCOM in other projects.

Note: If you're working on a module in the Mozilla codebase that's compiled with the MOZILLA_INTERNAL_API flag set, some of these APIs -- the string functions and classes in particular -- are not the ones you should be using. See the XPCOM internal string guide for documentation of the internal string API used within the Mozilla codebase.

Core XPCOM functions
XPCOM provides a number of global functions which are used to initialize and shut down the XPCOM library, as well as to allocate memory, get access to services, and to instantiate interfaces.
Folders
The folder classes all implement the nsIMsgFolder interface. There are currently three folder classes - nsLocalMailFolder, nsImapMailFolder, and nsNewsFolder. They all inherit from nsMsgDBFolder, which implements a lot of the core functionality. RSS feeds are implemented by nsLocalMailFolder.
NS ENSURE SUCCESS
Macro
NS ENSURE TRUE
Macro
NS_ABORT_IF_FALSE
This was removed in bug 1127201
NS_ADDREF
Macro
NS_ASSERTION
Macro
NS_ENSURE_ARG_POINTER
Macro
NS_ERROR
Throws a assertion (NS_ASSERTION) with the text "Error: (error text)", so writes this text to console (stderr) and to debug logs (NSPR logging). This macro is meant for critical errors; like assertions, NS_ERRORs should not be reachable.
NS_IF_ADDREF
Macro
NS_IF_RELEASE
Macro
NS_RELEASE
Macro
NS_WARNING
Macro
Standard XPCOM components
There are a number of components provided in the standard implementation of XPCOM; these are as follows.
XPCOM Interface Reference
This is a reference to the XPCOM interfaces provided by the Mozilla platform.
XPCOM Interface Reference by grouping
This page lists the current (as of Dec. 01, 2010) list of Mozilla interfaces as listed on the XPCom interface Reference Page Where that page lists items by alphabetical sorting, this page attempts to group them by function. Grouping and category names were made by somewhat arbitrary decision by the author. (I'm fully aware that this will be a great point of discussion and probably will end in tears, but since I'm the first person to apparently take a swing at this, I get first dibs.)
XPCOM glue classes
These "glue" classes are provided to make it easier to use XPCOM from C++ code.
XPCOM primitive
An XPCOM primitive is an XPCOM object that "boxes" a value of a primitive type. All XPCOM primitives are scriptable, and they all implement an XPCOM interface from the table below.
XPCOM string functions
XPCOM provides these low-level string functions to let you work with strings; however, it's often better to use one of the string classes rather than directly using these functions.
nsGetModuleProc
This function prototype provides the XPCOM entry-point into a module.
nsIAbCard/Thunderbird3
nsICookie2 MOZILLA 1 8 BRANCH
nsIMsgSearchValue
Defined in comm-central/ mailnews/ base/ search/ public/ nsIMsgSearchValue.idl
nsMsgMessageFlags
The nsMsgMessageFlags interface describes possible flags for messages. Equivalent flags are also defined in nsMsgMessageFlags.h.
nsMsgNavigationType
The nsMsgNavigationType interface contains constants used for message navigation in Thunderbird. For example to move forward a message, you would call:
nsMsgSearchOpValue
Defined in comm-central/ mailnews/ base/ search/ public/ nsMsgSearchCore.idl
nsMsgViewCommandCheckState
The nsMsgViewCommandCheckState interface contains constants used for command status in Thunderbird. It is (as far as I can tell) not currently used anywhere in Thunderbird.
nsMsgViewCommandType
The nsMsgViewCommandType interface contains constants used for commands in Thunderbird. For example to mark a message read, you would call:
nsMsgViewFlagsType
The nsMsgViewFlagsType interface contains constants used for view flags in Thunderbird. This interface isn't ever implemented. It is only used to store constants. For example, the 'unread only' view would use the flag:
nsMsgViewSortOrder
The nsMsgViewSortOrder interface contains constants used for sort direction in Thunderbird. This interface isn't ever implemented. It is only used to store constants. For example to sort by date you would pass a function the value:
nsMsgViewSortType
The nsMsgViewSortType interface contains constants used for sorting the Thunderbird threadpane. This interface isn't ever implemented. It is only used to store constants. For example to sort by date you would pass a function the value:
nsMsgViewType
The nsMsgViewType interface contains constants used for views in Thunderbird. This interface isn't ever implemented. It is only used to store constants. For example, to request the 'show all threads' view use the constant:
nsStaticModuleInfo
This data structure is used by NS_InitXPCOM3 to specify static XPCOM modules.

Many XPCOM pages return an nsresult. Prior to Gecko 19 (Firefox 19 / Thunderbird 19 / SeaMonkey 2.16), this was an integer that simply returned an error code. It is now a strongly typed enum when XPCOM is built using a C++11 compiler. This causes compile-time errors to occur when improper values are returned as nsresult values, thereby making it easier to catch many bugs.

Document Tags and Contributors

 Contributors to this page: Sheppy
 Last updated by: Sheppy,