nsIXPConnect

This article is in need of an editorial review.

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

Requires Gecko 1.9.1 (Firefox 3.5 / Thunderbird 3.0 / SeaMonkey 2.0)

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

Requires Gecko 1.8 (Firefox 1.5 / Thunderbird 1.5 / SeaMonkey 1.0)

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

Requires Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)

GarbageCollect()

Trigger a JS garbage collection.

void GarbageCollect();
Parameters

None.

Exceptions thrown
Missing Exception
Missing Description

Requires Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)

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

Requires Gecko 1.9.2 (Firefox 3.6 / Thunderbird 3.1 / Fennec 1.0)

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

Requires Gecko 1.9.2 (Firefox 3.6 / Thunderbird 3.1 / Fennec 1.0)

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

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.

Returns a 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 a 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

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

Requires Gecko 1.9 (Firefox 3)

GetXPCWrappedNativeJSClassInfo()

Get the JSEqualityOp pointer to use for identifying JSObjects that hold a pointer to a 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

Requires Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)

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

Requires Gecko 1.8 (Firefox 1.5 / Thunderbird 1.5 / SeaMonkey 1.0)

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

Requires Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)

jSValToVariant()

Wraps the given jsval in a 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

Requires Gecko 1.9.1 (Firefox 3.5 / Thunderbird 3.0 / SeaMonkey 2.0)

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

Requires Gecko 1.9 (Firefox 3)

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

Requires Gecko 1.9 (Firefox 3)

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

Requires Gecko 1.8 (Firefox 1.5 / Thunderbird 1.5 / SeaMonkey 1.0)

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

Requires Gecko 1.9 (Firefox 3)

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

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.

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

Requires Gecko 1.8 (Firefox 1.5 / Thunderbird 1.5 / SeaMonkey 1.0)

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 a nsIXPConnectWrappedJS. 2) The JSObject is in fact a 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 a 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 a nsIXPConnectWrappedNative or a 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

Requires Gecko 1.9.1 (Firefox 3.5 / Thunderbird 3.0 / SeaMonkey 2.0)

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

Document Tags and Contributors

Contributors to this page: Sheppy, fscholz, kscarfone
Last updated by: Sheppy,