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.

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

nsGetModuleProc

This function prototype provides the XPCOM entry-point into a module.

nsIAbCard/Thunderbird3

The nsIAbCard interface is used to represent and manipulate cards in the address book. In a big change from the original nsIAbCard, properties are now stored in a hash table instead of as attributes on the interface, allowing it to be more flexible.

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.

Standard XPCOM components

There are a number of components provided in the standard implementation of XPCOM; these are as follows.

XPCOM glue classes

These "glue" classes are provided to make it easier to use XPCOM from C++ code.

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 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.

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.