nsIXPConnect

js/src/xpconnect/idl/nsIXPConnect.idlNot scriptable

Provides the XPConnect service.

Inherits from: nsISupports Last changed in Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)

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

void addJSHolder(in voidPtr aHolder, in nsScriptObjectTracerPtr aTracer); Native code only!

void clearAllWrappedNativeSecurityPolicies();

nsIXPConnectJSObjectHolder createSandbox(in JSContextPtr cx, in nsIPrincipal principal); Native code only!

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

void debugDump(in short depth);

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

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

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

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

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

Native code only!

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

void GarbageCollect();

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

JSVal getCOWForObject(in JSContextPtr aJSContext, in JSObjectPtr aParent, in JSObjectPtr aWrappedObj); Native code only! Obsolete since Gecko 2.0

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

nsIXPCFunctionThisTranslator getFunctionThisTranslator(in nsIIDRef aIID);

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

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

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

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

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

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

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

Native code only! Obsolete since Gecko 2.0

JSVal getXOWForObject(in JSContextPtr aJSContext, in JSObjectPtr aParent, in JSObjectPtr aWrappedObj); Native code only! Obsolete since Gecko 2.0

void GetXPCWrappedNativeJSClassInfo(out JSEqualityOp equality);

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

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

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

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

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

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

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

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

void removeJSHolder(in voidPtr aHolder); Native code only!

void reparentScopeAwareWrappers(in JSContextPtr aJSContext, in JSObjectPtr aOldScope, in JSObjectPtr aNewScope); Obsolete since Gecko 1.9.1

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

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

void setDebugModeWhenPossible(in PRBool mode); Native code only!

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

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

void setReportAllJSExceptions(in boolean reportAllJSExceptions);

void setSafeJSContextForCurrentThread(in JSContextPtr cx);

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

void syncJSContexts();

void updateXOWs(in JSContextPtr aJSContext, in nsIXPConnectWrappedNative aObject, in PRUint32 aWay); Native code only! Obsolete since Gecko 2.0

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

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

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

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

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);

Attributes

Attribute	Type	Description
`collectGarbageOnMainThreadOnly`	`PRBool`	Obsolete since Gecko 1.9
`CurrentJSStack`	`nsIStackFrame`	Read only.
`CurrentNativeCallContext`	`nsAXPCNativeCallContextPtr`	Read only.
`deferReleasesUntilAfterGarbageCollection`	`PRBool`	Obsolete since Gecko 1.9
`PendingException`	`nsIException`

Constants

Constant	Value	Description
`INIT_JS_STANDARD_CLASSES`	`1 << 0`
`FLAG_SYSTEM_GLOBAL_OBJECT`	`1 << 1`
`OMIT_COMPONENTS_OBJECT`	`1 << 2`
`XPC_XOW_CLEARSCOPE`	`1`	Tells `updateXOWs()` to clear the scope of all of the XOWs it finds. Obsolete since Gecko 2.0

Methods

Native code only!

addJSHolder

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

Native code only!

createSandbox

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

Native code only!

evalInSandboxObject

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

Native code only!

getCOWForObject

Obsolete since Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)
This feature is obsolete. Although it may still work in some browsers, its use is discouraged since it could be removed at any time. Try to avoid using it.

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

Native code only!

getWrapperForObject

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

Note: In C++, the out jsval parameter must already be a strong GC root.

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

Native code only!

getXOWForObject

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()

Note: AJSContext as a child to the cycle collector.

[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

Native code only!

removeJSHolder

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()

Obsolete since Gecko 1.9.1 (Firefox 3.5 / Thunderbird 3.0 / SeaMonkey 2.0)
This feature is obsolete. Although it may still work in some browsers, its use is discouraged since it could be removed at any time. Try to avoid using it.

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

Native code only!

setDebugModeWhenPossible

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.

Note: This method is DEPRECATED. Use nsIThreadJSContextStack::safeJSContext instead.

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

Native code only!

updateXOWs

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