Language bindings 编辑

An XPCOM Language Binding is a bridge between a particular language and XPCOM to provide access to XPCOM objects from that language, and to let modules written in that language be used as XPCOM objects by all other languages for which there are XPCOM bindings.

More specifically, an XPCOM language binding:

• Enables access to XPCOM objects from that language (where access means reading/writing/creating XPCOM objects as well as calling methods on them).
• Exposes modules written in the bound language as XPCOM objects, thereby enabling all other languages for which XPCOM bindings exist to access these modules.

Since the XPCOM layer itself is written in C/C++, its API can be accessed out-of-the-box using C or C++. In order to allow any other language to use the XPCOM API, a bridging layer is required.

The following bridging layers are currently available:

Components object

The Components object is the object through which XPConnect functionality is reflected into JavaScript. The Components object is actually a native instance of the nsIXPCComponents interface which is reflected into JavaScript as a top level object using XPConnect.

Components.classes

Components.classes is a read-only object whose properties are classes indexed by ContractID.

Components.classesByID

Components.classesByID is a read-only object whose properties are classes indexed by CID.

Components.Constructor

Creates a JavaScript function which can be used to create or construct new instances of XPCOM components.

Components.Exception

Components.Exception is a JavaScript constructor to create nsIXPCException objects. These exception objects may be thrown when implementing xpcom interfaces in JavaScript, and they can provide better diagnostics in the error console if not caught than simply throwing an nsresult's value will.

Components.ID

Components.ID is a constructor that creates native objects that conform to the nsIJSID interface.

Components.interfaces

Components.interfaces is a read-only object whose properties are interfaces indexed by their names.

Components.interfacesByID

Components.interfacesByID is a read-only array of classes indexed by IID.

Components.isSuccessCode

Determines whether a given XPCOM return code (that is, an nsresult value) indicates the success or failure of an operation, returning true or false respectively.

Components.lastResult

Components.manager

Components.manager is a convenience reflection of the global native component manager service. The scriptable methods on the nsIComponentManager interface can be called directly on this object.

Components.results

Components.results is a read-only object whose properties are the names listed as the first parameters of the macros in js/xpconnect/src/xpc.msg (also at Table Of Errors), with the value of each corresponding to that constant's value.

Components.returnCode

Components.stack

Components.stack is a read only property of type nsIStackFrame (IDL definition) that represents a snapshot of the current JavaScript callstack. This can be used for various diagnostic purposes.

Components.utils

Components.utils is a collection of various useful XPConnect features. Its interface is defined at js/xpconnect/idl/xpccomponents.idl.

Components.utils.cloneInto

This function provides a safe way to take an object defined in a privileged scope and create a structured clone of it in a less-privileged scope. It returns a reference to the clone:

Components.utils.createObjectIn

Components.utils.createObjectIn creates a new JavaScript object in the scope of the specified object's compartment.

Components.utils.evalInSandbox

The evalInSandbox() function enables you to evaluate JavaScript code inside a sandbox you've previously created using the Components.utils.Sandbox constructor.

Components.utils.evalInWindow

This function enables code running in a more-privileged JavaScript context to evaluate a string in a less-privileged JavaScript context. The result is structured cloned back to the original context, unless it is native (for example, if it returns a DOM node, this is not structured cloned, because the original context will see that through an XrayWrapper already), so it's guaranteed to behave predictably.

This is useful for privileged code, such as add-on code, to access variables and APIs defined in web content.

Components.utils.exportFunction

This function provides a safe way to expose a function from a privileged scope to a less-privileged scope.

Components.utils.forceGC

Components.utils.forceGC lets scripts force a garbage collection cycle. The Mozilla JavaScript engine will perform garbage collection automatically when the JavaScript heap grows beyond a certain size. This mechanism doesn't account for any native (C++) XPCOM objects hanging off JavaScript objects though. In many cases a JavaScript application will have internal knowledge of JavaScript objects referencing large (trees of) XPCOM objects and know when they are no longer reachable. In this case it can be important to be able to force a garbage collection cycle from JavaScript.

Components.utils.getGlobalForObject

This method is used to determine the global object with which an object is associated. This is the global object in place at the time the object was created, which is to say the global object used when executing the script that created the object.

Components.utils.getWeakReference

This method was introduced in Firefox 3 and is used for obtaining a weak reference for an object. To obtain the object reference, you have to call get() on the resulting object.

Components.utils.import

Components.utils.import was introduced in Firefox 3 and is used for sharing code between different scopes easily. For example, you can import XPCOMUtils.jsm to avoid copy/pasting long XPCOM component registration boilerplate in your component files.

Components.utils.importGlobalProperties

Imports various objects into a system scope.

Components.utils.isXrayWrapper

When privileged JavaScript in Gecko accesses objects belonging to less-privileged code (such as untrusted web content), it does so, by default, with "Xray vision": a mechanism that filters out certain changes to the objects that could cause them to behave in unexpected ways. For example, privileged code using an Xray to a DOM object sees only  the original, native version of the DOM object. Any expando properties are not visible, and if any native properties have been redefined, this has no effect.

Components.utils.makeObjectPropsNormal

Ensures that the specified object's methods are all in the object's scope, and aren't cross-component wrappers.

Components.utils.reportError

Components.utils.reportError reports a JavaScript Error object to the Error Console, and returns. It is meant for use by extension developers who have exception handler blocks which want to "eat" an exception, but still want to report it to the console.

Components.utils.Sandbox

Components.utils.Sandbox is used to create a sandbox object for use with evalInSandbox().

Components.utils.schedulePreciseGC

This method lets scripts schedule a garbage collection cycle. The garbage collection cycle will occur sometime in the future, when no JavaScript code is executing. This is useful particularly when testing for memory leaks, because normal garbage collection is conservative when JavaScript code is running to ensure that in-use memory isn't inadvertently collected.

Components.utils.setGCZeal

This method lets scripts set the zeal level for garbage collection. You can get details on what this method does in JS_SetGCZeal. This method calls through to that thusly:

Components.utils.unload

Components.utils.unload was introduced in Firefox 7 and is used to unload JavaScript code modules. This can be particularly handy with restartless (boostrapped) extensions, so that you can unload an old version of a code module when a new version of your add-on is installed.

Components.utils.unwaiveXrays

Undo a previous call to Components.utils.waiveXrays(), restoring Xray vision for the caller.

Components.utils.waiveXrays

Waives Xray vision for an object, giving the caller a transparent wrapper to the underlying object.

JavaXPCOM

JavaXPCOM allows for communication between Java and XPCOM, such that a Java application can access XPCOM objects, and XPCOM can access any Java class that implements an XPCOM interface. JavaXPCOM is not actively maintained.

PlXPCOM

plXPCOM (Perl XPCOM) provides language bindings letting you use XPCOM from Perl code. The resources here provide information about this language binding and how to use it.

PyXPCOM

PyXPCOM allows for communication between Python and XPCOM, such that a Python application can access XPCOM objects, and XPCOM can access any Python class that implements an XPCOM interface. PyXPCOM is actively used in ActiveState Komodo products, for example.

RbXPCOM

RbXPCOM (Ruby Cross-Platform COM) provides bindings between the popular Ruby programming language and XPCOM. You can find additional information using the resource links below.

XPConnect

XPConnect is a bridge between JavaScript and XPCOM. With XPConnect, you can use XPCOM components from JavaScript code, and interact with JavaScript objects from within XPCOM components. XPConnect is part of Firefox and is actively used in XUL applications.