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.
WebExtensions are becoming the new standard for creating add-ons. Eventually support for XPCOM add-ons will be deprecated, so you should begin to investigate porting your add-ons to use the WebExtensions API, and report any missing functionality so we can be sure to address your concerns. Work is ongoing on WebExtension capabilities, so your input will help prioritize and plan the work. To learn more about the kinds of changes that will be needed, see Comparison with XUL/XPCOM extensions. In addition, any binaries you use will then need to be converted for use with the WebExtensions native messaging API, or compiled using WebAssembly or Emscripten.
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
nsMsgMessageFlagsinterface describes possible flags for messages. Equivalent flags are also defined in nsMsgMessageFlags.h. - nsMsgNavigationType
- The
nsMsgNavigationTypeinterface 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
nsMsgViewCommandCheckStateinterface contains constants used for command status in Thunderbird. It is (as far as I can tell) not currently used anywhere in Thunderbird. - nsMsgViewCommandType
- The
nsMsgViewCommandTypeinterface contains constants used for commands in Thunderbird. For example to mark a message read, you would call: - nsMsgViewFlagsType
- The
nsMsgViewFlagsTypeinterface 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
nsMsgViewSortOrderinterface 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
nsMsgViewSortTypeinterface 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
nsMsgViewTypeinterface 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.