nsIXPConnect

To access the XPConnect service, use code like this:

nsresult rv;
nsCOMPtr<nsIXPConnect> xpconnect = do_GetService(nsIXPConnect::GetCID(), &rv);
if (NS_SUCCEEDED(rv)) {
  /* use the object */
}

Method overview

Attributes

Constants

Methods

Root JS objects held by aHolder.

void addJSHolder(
  in voidPtr aHolder,
  in nsScriptObjectTracerPtr aTracer
);

Parameters

aHolder

The object that hold the JS objects that should be rooted.

aTracer

Missing Description

Exceptions thrown

Missing Exception

Missing Description

clearAllWrappedNativeSecurityPolicies()

void clearAllWrappedNativeSecurityPolicies();

Parameters

None.

Exceptions thrown

Missing Exception

Missing Description

Create a sandbox for evaluating code in isolation using evalInSandboxObject().

nsIXPConnectJSObjectHolder createSandbox(
  in JSContextPtr cx,
  in nsIPrincipal principal
);

Parameters

cx

A context to use when creating the sandbox object.

principal

The principal (or null to use the null principal) to use when evaluating code in this sandbox.

Return value

Missing Description

Exceptions thrown

Missing Exception

Missing Description

createStackFrameLocation()

nsIStackFrame createStackFrameLocation(
  in PRUint32 aLanguage,
  in string aFilename,
  in string aFunctionName,
  in PRInt32 aLineNumber,
  in nsIStackFrame aCaller
);

Parameters

aLanguage

Missing Description

aFilename

Missing Description

aFunctionName

Missing Description

aLineNumber

Missing Description

aCaller

Missing Description

Return value

Missing Description

Exceptions thrown

Missing Exception

Missing Description

debugDump()

void debugDump(
  in short depth
);

Parameters

depth

Missing Description

Exceptions thrown

Missing Exception

Missing Description

debugDumpEvalInJSStackFrame()

void debugDumpEvalInJSStackFrame(
  in PRUint32 aFrameNumber,
  in string aSourceText
);

Parameters

aFrameNumber

Missing Description

aSourceText

Missing Description

Exceptions thrown

Missing Exception

Missing Description

debugDumpJSStack()

void debugDumpJSStack(
  in PRBool showArgs,
  in PRBool showLocals,
  in PRBool showThisProps
);

Parameters

showArgs

Missing Description

showLocals

Missing Description

showThisProps

Missing Description

Exceptions thrown

Missing Exception

Missing Description

debugDumpObject()

void debugDumpObject(
  in nsISupports aCOMObj,
  in short depth
);

Parameters

aCOMObj

Missing Description

depth

Missing Description

Exceptions thrown

Missing Exception

Missing Description

defineDOMQuickStubs()

Define quick stubs on the given object, @a proto.

[noscript,notxpcom] PRBool defineDOMQuickStubs(
  in JSContextPtr cx,
  in JSObjectPtr proto,
  in PRUint32 flags,
  in PRUint32 interfaceCount,
  [array, size_is(interfaceCount)] in nsIIDPtr interfaceArray
);

Parameters

cx

A context. Requires request.

proto

The (newly created) prototype object for a DOM class. The JS half of an XPCWrappedNativeProto.

flags

Property flags for the quick stub properties--should be either JSPROP_ENUMERATE or 0.

interfaceCount

The number of interfaces the class implements.

interfaceArray

The interfaces the class implements; interfaceArray and interfaceCount are like what nsIClassInfo.getInterfaces returns.

Return value

Missing Description

Exceptions thrown

Missing Exception

Missing Description

Evaluate script in a sandbox, completely isolated from all other running scripts.

jsval evalInSandboxObject(
  in AString source,
  in JSContextPtr cx,
  in nsIXPConnectJSObjectHolder sandbox,
  in PRBool returnStringOnly
);

Parameters

source

The source of the script to evaluate.

cx

The context to use when setting up the evaluation of the script. The actual evaluation will happen on a new temporary context.

sandbox

The sandbox object to evaluate the script in.

returnStringOnly

The only results to come out of the computation (including exceptions) will be coerced into strings created in the sandbox.

Return value

The result of the evaluation as a jsval. If the caller intends to use the return value from this call, the caller is responsible for rooting the jsval before making a call to this method.

Exceptions thrown

Missing Exception

Missing Description

flagSystemFilenamePrefix()

Preconfigure XPCNativeWrapper automation so that when a scripted caller whose filename starts with filenamePrefix accesses a wrapped native that is not flagged as "system", the wrapped native will be automatically wrapped with an XPCNativeWrapper.

void flagSystemFilenamePrefix(
  in string aFilenamePrefix,
  in PRBool aWantNativeWrappers
);

Parameters

aFilenamePrefix

The UTF-8 filename prefix to match, which should end with a slash (/) character.

aWantNativeWrappers

Whether XPConnect should produce native wrappers for scripts whose paths begin with this prefix.

Exceptions thrown

Missing Exception

Missing Description

GarbageCollect()

Trigger a JS garbage collection.

void GarbageCollect();

Parameters

None.

Exceptions thrown

Missing Exception

Missing Description

getCaller()

Return the caller object of the current call from JS.

[noscript,notxpcom] void getCaller(
  out JSContextPtr aJSContext,
  out JSObjectPtr aObject
);

Parameters

aJSContext

Missing Description

aObject

Missing Description

Return value

Missing Description

Exceptions thrown

Missing Exception

Missing Description

Wrap a jsval in a chrome object wrapper.

JSVal getCOWForObject(
  in JSContextPtr aJSContext,
  in JSObjectPtr aParent,
  in JSObjectPtr aWrappedObj
);

Parameters

aJSContext

A context to use to create objects.

aParent

The parent to create the wrapper with.

aWrappedObj

The object to wrap.

Return value

Missing Description

Exceptions thrown

Missing Exception

Missing Description

getDefaultSecurityManager()

void getDefaultSecurityManager(
  out nsIXPCSecurityManager aManager,
  out PRUint16 flags
);

Parameters

aManager

Missing Description

flags

Missing Description

Exceptions thrown

Missing Exception

Missing Description

getFunctionThisTranslator()

nsIXPCFunctionThisTranslator getFunctionThisTranslator(
  in nsIIDRef aIID
);

Parameters

aIID

Missing Description

Return value

Missing Description

Exceptions thrown

Missing Exception

Missing Description

getJSObjectOfWrapper()

JSObjectPtr getJSObjectOfWrapper(
  in JSContextPtr aJSContext,
  in JSObjectPtr aJSObj
);

Parameters

aJSContext

Missing Description

aJSObj

Missing Description

Return value

Missing Description

Exceptions thrown

Missing Exception

Missing Description

getNativeOfWrapper()

[noscript, notxpcom] nsISupports getNativeOfWrapper(
  in JSContextPtr aJSContext,
  in JSObjectPtr aJSObj
);

Parameters

aJSContext

Missing Description

aJSObj

Missing Description

Return value

Missing Description

Exceptions thrown

Missing Exception

Missing Description

getSecurityManagerForJSContext()

void getSecurityManagerForJSContext(
  in JSContextPtr aJSContext,
  out nsIXPCSecurityManager aManager,
  out PRUint16 flags
);

Parameters

aJSContext

Missing Description

aManager

Missing Description

flags

Missing Description

Exceptions thrown

Missing Exception

Missing Description

getWrappedNativeOfJSObject()

This only succeeds if the JSObject is a nsIXPConnectWrappedNative. A new wrapper is *never* constructed.

nsIXPConnectWrappedNative getWrappedNativeOfJSObject(
  in JSContextPtr aJSContext,
  in JSObjectPtr aJSObj
);

Parameters

aJSContext

Missing Description

aJSObj

Missing Description

Return value

Missing Description

Exceptions thrown

Missing Exception

Missing Description

getWrappedNativeOfNativeObject()

This only succeeds if the native object is already wrapped by xpconnect. A new wrapper is *never* constructed.

nsIXPConnectWrappedNative getWrappedNativeOfNativeObject(
  in JSContextPtr aJSContext,
  in JSObjectPtr aScope,
  in nsISupports aCOMObj,
  in nsIIDRef aIID
);

Parameters

aJSContext

Missing Description

aScope

Missing Description

aCOMObj

Missing Description

aIID

Missing Description

Return value

Missing Description

Exceptions thrown

Missing Exception

Missing Description

getWrappedNativePrototype()

nsIXPConnectJSObjectHolder getWrappedNativePrototype(
  in JSContextPtr aJSContext,
  in JSObjectPtr aScope,
  in nsIClassInfo aClassInfo
);

Parameters

aJSContext

Missing Description

aScope

Missing Description

aClassInfo

Missing Description

Return value

Missing Description

Exceptions thrown

Missing Exception

Missing Description

Returns an XPCNativeWrapper, XPCSafeJSObjectWrapper, or XPCCrossOriginWrapper for the given object based on the principal, scope, and filename flags that are passed in.

JSVal getWrapperForObject(
  in JSContextPtr aJSContext,
  in JSObjectPtr aObject,
  in JSObjectPtr aScope,
  in nsIPrincipal aPrincipal,
  in unsigned long aFilenameFlags
);

Parameters

aJSContext

A JSContext.

aObject

The object to wrap.

aScope

The scope to be used in the event that we create an XPCCrossOriginWrapper. Can be null.

aPrincipal

The principal that should be used for the wrapper. If this parameter is given then aFilenameFlags will not be calculated and will be assumed to be 0 unless another value is given. If this parameter is null then aFilenameFlags will be calculated and the value of that argument will be ignored.

aFilenameFlags

The filename flags from the script that will use this wrapper. See above (aPrincipal) for details.

Return value

Missing Description

Exceptions thrown

Missing Exception

Missing Description

Wrap a jsval in a cross origin wrapper.

JSVal getXOWForObject(
  in JSContextPtr aJSContext,
  in JSObjectPtr aParent,
  in JSObjectPtr aWrappedObj
);

Parameters

aJSContext

A context to use to create objects.

aParent

The parent to create the wrapper with.

aWrappedObj

The object to wrap.

Return value

Missing Description

Exceptions thrown

Missing Exception

Missing Description

GetXPCWrappedNativeJSClassInfo()

Get the JSEqualityOp pointer to use for identifying JSObjects that hold a pointer to an nsIXPConnectWrappedNative or to the native in their private date. See IS_WRAPPER_CLASS in xpcprivate.h for details.

void GetXPCWrappedNativeJSClassInfo(
  out JSEqualityOp equality
);

Parameters

equality

Missing Description

Exceptions thrown

Missing Exception

Missing Description

holdObject()

Creates a JS object holder around aObject that will hold the object alive for as long as the holder stays alive.

nsIXPConnectJSObjectHolder holdObject(
  in JSContextPtr aJSContext,
  in JSObjectPtr aObject
);

Parameters

aJSContext

Missing Description

aObject

Missing Description

Return value

Missing Description

Exceptions thrown

Missing Exception

Missing Description

initClasses()

Initializes classes on a global object that has already been created.

void initClasses(
  in JSContextPtr aJSContext,
  in JSObjectPtr aGlobalJSObj
);

Parameters

aJSContext

Missing Description

aGlobalJSObj

Missing Description

Exceptions thrown

Missing Exception

Missing Description

initClassesWithNewWrappedGlobal()

Creates a new global object using the given aCOMObj as the global object. The object will be set up according to the flags (defined below). If you do not pass INIT_JS_STANDARD_CLASSES, then aCOMObj must implement nsIXPCScriptable so it can resolve the standard classes when asked by the JS engine.

nsIXPConnectJSObjectHolder initClassesWithNewWrappedGlobal(
  in JSContextPtr aJSContext,
  in nsISupports aCOMObj,
  in nsIIDRef aIID,
  in nsIPrincipal aPrincipal,
  in nsISupports aExtraPtr,
  in PRUint32 aFlags
);

Parameters

aJSContext

The context to use while creating the global object.

aCOMObj

The native object that represents the global object.

aIID

The IID used to wrap the global object.

aPrincipal

The principal of the code that will run in this compartment. Can be null if not on the main thread.

aExtraPtr

Must be passed if aPrincipal is null. Used to separate code from the same principal into different compartments, as for sandboxes.

aFlags

One of the flags below specifying what options this global object wants.

Return value

Missing Description

Exceptions thrown

Missing Exception

Missing Description

JSToVariant()

nsIVariant JSToVariant(
  in JSContextPtr ctx,
  in jsval value
);

Parameters

ctx

Missing Description

value

Missing Description

Return value

Missing Description

Exceptions thrown

Missing Exception

Missing Description

jSValToVariant()

Wraps the given jsval in an nsIVariant and returns the new variant.

nsIVariant jSValToVariant(
  in JSContextPtr cx,
  in JSValPtr aJSVal
);

Parameters

cx

Missing Description

aJSVal

Missing Description

Return value

Missing Description

Exceptions thrown

Missing Exception

Missing Description

moveWrappers()

void moveWrappers(
  in JSContextPtr aJSContext,
  in JSObjectPtr aOldScope,
  in JSObjectPtr aNewScope
);

Parameters

aJSContext

Missing Description

aOldScope

Missing Description

aNewScope

Missing Description

Exceptions thrown

Missing Exception

Missing Description

noteJSContext()

[noscript,notxpcom] void noteJSContext(
  in JSContextPtr aJSContext,
  in nsCCTraversalCallbackRef aCb
);

Parameters

aJSContext

The JSContext to note.

aCb

The cycle collection traversal callback.

Return value

Missing Description

Exceptions thrown

Missing Exception

Missing Description

releaseJSContext()

void releaseJSContext(
  in JSContextPtr aJSContext,
  in PRBool noGC
);

Parameters

aJSContext

Missing Description

noGC

Missing Description

Exceptions thrown

Missing Exception

Missing Description

Stop rooting the JS objects held by aHolder.

void removeJSHolder(
  in voidPtr aHolder
);

Parameters

aHolder

The object that hold the rooted JS objects.

Exceptions thrown

Missing Exception

Missing Description

reparentScopeAwareWrappers()

void reparentScopeAwareWrappers(
  in JSContextPtr aJSContext,
  in JSObjectPtr aOldScope,
  in JSObjectPtr aNewScope
);

Parameters

aJSContext

Missing Description

aOldScope

Missing Description

aNewScope

Missing Description

Exceptions thrown

Missing Exception

Missing Description

reparentWrappedNativeIfFound()

nsIXPConnectJSObjectHolder reparentWrappedNativeIfFound(
  in JSContextPtr aJSContext,
  in JSObjectPtr aScope,
  in JSObjectPtr aNewParent,
  in nsISupports aCOMObj
);

Parameters

aJSContext

Missing Description

aScope

Missing Description

aNewParent

Missing Description

aCOMObj

Missing Description

Return value

Missing Description

Exceptions thrown

Missing Exception

Missing Description

restoreWrappedNativePrototype()

Restore an old prototype for wrapped natives of type aClassInfo. This should be used only when restoring an old scope into a state close to where it was prior to being reinitialized.

void restoreWrappedNativePrototype(
  in JSContextPtr aJSContext,
  in JSObjectPtr aScope,
  in nsIClassInfo aClassInfo,
  in nsIXPConnectJSObjectHolder aPrototype
);

Parameters

aJSContext

Missing Description

aScope

Missing Description

aClassInfo

Missing Description

aPrototype

Missing Description

Exceptions thrown

Missing Exception

Missing Description

When we place the browser in JS debug mode, there can't be any JS on the stack. This is because we currently activate debugMode on all scripts in the JSRuntime when the debugger is activated. This method will turn debug mode on or off when the context stack reaches zero length.

void setDebugModeWhenPossible(
  in PRBool mode
);

Parameters

mode

Missing Description

Exceptions thrown

Missing Exception

Missing Description

setDefaultSecurityManager()

The security manager to use when the current JSContext has no security manager.

void setDefaultSecurityManager(
  in nsIXPCSecurityManager aManager,
  in PRUint16 flags
);

Parameters

aManager

Missing Description

flags

Missing Description

Exceptions thrown

Missing Exception

Missing Description

setFunctionThisTranslator()

nsIXPCFunctionThisTranslator setFunctionThisTranslator(
  in nsIIDRef aIID,
  in nsIXPCFunctionThisTranslator aTranslator
);

Parameters

aIID

Missing Description

aTranslator

Missing Description

Return value

Missing Description

Exceptions thrown

Missing Exception

Missing Description

setReportAllJSExceptions()

Whether or not XPConnect should report all JS exceptions when returning from JS into C++. False by default, although any value set in the MOZ_REPORT_ALL_JS_EXCEPTIONS environment variable will override the value passed here.

void setReportAllJSExceptions(
  in boolean reportAllJSExceptions
);

Parameters

reportAllJSExceptions

Missing Description

Exceptions thrown

Missing Exception

Missing Description

setSafeJSContextForCurrentThread()

Set fallback JSContext to use when xpconnect can't find an appropriate context to use to execute JavaScript.

void setSafeJSContextForCurrentThread(
  in JSContextPtr cx
);

Parameters

cx

Missing Description

Exceptions thrown

Missing Exception

Missing Description

setSecurityManagerForJSContext()

void setSecurityManagerForJSContext(
  in JSContextPtr aJSContext,
  in nsIXPCSecurityManager aManager,
  in PRUint16 flags
);

Parameters

aJSContext

Missing Description

aManager

Missing Description

flags

Missing Description

Exceptions thrown

Missing Exception

Missing Description

syncJSContexts()

Deprecated do-nothing function.

void syncJSContexts();

Parameters

None.

Exceptions thrown

Missing Exception

Missing Description

Performs an operation over all of |object|'s XOWs such as clearing their scopes or updating their concept of the current principal.

void updateXOWs(
  in JSContextPtr aJSContext,
  in nsIXPConnectWrappedNative aObject,
  in PRUint32 aWay
);

Parameters

aJSContext

A context to use to perform JS operations.

aObject

Which XPCWrappedNative we should find the XOWs for.

aWay

What operation to perform.

Exceptions thrown

Missing Exception

Missing Description

variantToJS()

jsval variantToJS(
  in JSContextPtr ctx,
  in JSObjectPtr scope,
  in nsIVariant value
);

Parameters

ctx

Missing Description

scope

Missing Description

value

Missing Description

Return value

Missing Description

Exceptions thrown

Missing Exception

Missing Description

wrapJS()

wrapJS() will yield a new or previously existing xpcom interface pointer to represent the JSObject passed in.

This method now correctly deals with cases where the passed in JSObject already has an associated xpcom interface for the cases: 1) The JSObject has already been wrapped as an nsIXPConnectWrappedJS. 2) The JSObject is in fact an nsIXPConnectWrappedNative and thus already has an underlying xpcom object. 3) The JSObject is of a jsclass which supports getting the nsISupports from the JSObject directly. This is used for idlc style objects (e.g., DOM objects).

It *might* be possible to QueryInterface the resulting interface pointer to nsIXPConnectWrappedJS.

Returns: success: NS_OK failure: NS_ERROR_XPC_BAD_CONVERT_JS NS_ERROR_FAILURE.

void wrapJS(
  in JSContextPtr aJSContext,
  in JSObjectPtr aJSObj,
  in nsIIDRef aIID,
  [iid_is(aIID),retval] out nsQIResult result
);

Parameters

aJSContext

Missing Description

aJSObj

Missing Description

aIID

Missing Description

result

Missing Description

Exceptions thrown

Missing Exception

Missing Description

wrapJSAggregatedToNative()

wrapJSAggregatedToNative() is just like wrapJS() except it is used in cases where the JSObject is also aggregated to some native xpcom Object. At present XBL is the only system that might want to do this.

XXX write more!

Returns: success: NS_OK failure: NS_ERROR_XPC_BAD_CONVERT_JS NS_ERROR_FAILURE.

void wrapJSAggregatedToNative(
  in nsISupports aOuter,
  in JSContextPtr aJSContext,
  in JSObjectPtr aJSObj,
  in nsIIDRef aIID,
  [iid_is(aIID),retval] out nsQIResult result
);

Parameters

aOuter

Missing Description

aJSContext

Missing Description

aJSObj

Missing Description

aIID

Missing Description

result

Missing Description

Exceptions thrown

Missing Exception

Missing Description

wrapNative()

wrapNative() will create a new JSObject or return an existing one.

The JSObject is returned inside a refcounted nsIXPConnectJSObjectHolder. As long as this holder is held the JSObject will be protected from collection by JavaScript's garbage collector. It is a good idea to transfer the JSObject to some equally protected place before releasing the holder (i.e., use JS_SetProperty to make this object a property of some other JSObject).

This method now correctly deals with cases where the passed in xpcom object already has an associated JSObject for the cases: 1) The xpcom object has already been wrapped for use in the same scope as an nsIXPConnectWrappedNative. 2) The xpcom object is in fact an nsIXPConnectWrappedJS and thus already has an underlying JSObject. 3) The xpcom object implements nsIScriptObjectOwner; i.e., is an idlc style DOM object for which we can call GetScriptObject to get the JSObject it uses to represent itself into JavaScript.

It *might* be possible to QueryInterface the nsIXPConnectJSObjectHolder returned by the method into an nsIXPConnectWrappedNative or an nsIXPConnectWrappedJS.

This method will never wrap the JSObject involved in an XPCNativeWrapper before returning.

Returns: success: NS_OK failure: NS_ERROR_XPC_BAD_CONVERT_NATIVE NS_ERROR_XPC_CANT_GET_JSOBJECT_OF_DOM_OBJECT NS_ERROR_FAILURE.

nsIXPConnectJSObjectHolder wrapNative(
  in JSContextPtr aJSContext,
  in JSObjectPtr aScope,
  in nsISupports aCOMObj,
  in nsIIDRef aIID
);

Parameters

aJSContext

Missing Description

aScope

Missing Description

aCOMObj

Missing Description

aIID

Missing Description

Return value

Missing Description

Exceptions thrown

Missing Exception

Missing Description

wrapNativeToJSVal()

Same as wrapNative(), but also returns the JSObject in aVal. C++ callers can pass in null for the aHolder argument, but in that case they must ensure that aVal is rooted. aIID may be null, it means the same as passing in &NS_GET_IID(nsISupports) but when passing in null certain shortcuts can be taken because we know without comparing IIDs that the caller is asking for an nsISupports wrapper. If aAllowWrapper, then the returned value will be wrapped in the proper type of security wrapper on top of the XPCWrappedNative (if needed). This method doesn't push aJSContext on the context stack, so the caller is required to push it if the top of the context stack is not equal to aJSContext.

void wrapNativeToJSVal(
  in JSContextPtr aJSContext,
  in JSObjectPtr aScope,
  in nsISupports aCOMObj,
  in nsWrapperCachePtr aCache,
  in nsIIDPtr aIID,
  in boolean aAllowWrapper,
  out jsval aVal,
  out nsIXPConnectJSObjectHolder aHolder
);

Parameters

aJSContext

Missing Description

aScope

Missing Description

aCOMObj

Missing Description

aCache

Missing Description

aIID

Missing Description

aAllowWrapper

Missing Description

aVal

Missing Description

aHolder

Missing Description