import "nsIXPConnect.idl";

Collaboration diagram for nsIXPConnect:

Public Member Functions
void	initClasses (in JSContextPtr aJSContext, in JSObjectPtr aGlobalJSObj)
	Initializes classes on a global object that has already been created.
nsIXPConnectJSObjectHolder	initClassesWithNewWrappedGlobal (in JSContextPtr aJSContext, in nsISupports aCOMObj, in nsIIDRef aIID, in nsIPrincipal aPrincipal, in nsISupports aExtraPtr, in PRUint32 aFlags)
	Creates a new global object using the given aCOMObj as the global object.
nsIXPConnectJSObjectHolder	wrapNative (in JSContextPtr aJSContext, in JSObjectPtr aScope, in nsISupports aCOMObj, in nsIIDRef aIID)
	wrapNative will create a new JSObject or return an existing one.
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)
	Same as wrapNative, but also returns the JSObject in aVal.
void	wrapJS (in JSContextPtr aJSContext, in JSObjectPtr aJSObj, in nsIIDRef aIID,[iid_is(aIID), retval] out nsQIResult result)
	wrapJS will yield a new or previously existing xpcom interface pointer to represent the JSObject passed in.
nsIVariant	jSValToVariant (in JSContextPtr cx, in JSValPtr aJSVal)
	Wraps the given jsval in a nsIVariant and returns the new variant.
nsIXPConnectWrappedNative	getWrappedNativeOfJSObject (in JSContextPtr aJSContext, in JSObjectPtr aJSObj)
	This only succeeds if the JSObject is a nsIXPConnectWrappedNative.
nsISupports	getNativeOfWrapper (in JSContextPtr aJSContext, in JSObjectPtr aJSObj)
JSObjectPtr	getJSObjectOfWrapper (in JSContextPtr aJSContext, in JSObjectPtr aJSObj)
void	setSecurityManagerForJSContext (in JSContextPtr aJSContext, in nsIXPCSecurityManager aManager, in PRUint16 flags)
void	getSecurityManagerForJSContext (in JSContextPtr aJSContext, out nsIXPCSecurityManager aManager, out PRUint16 flags)
void	setDefaultSecurityManager (in nsIXPCSecurityManager aManager, in PRUint16 flags)
	The security manager to use when the current JSContext has no security manager.
void	getDefaultSecurityManager (out nsIXPCSecurityManager aManager, out PRUint16 flags)
nsIStackFrame	createStackFrameLocation (in PRUint32 aLanguage, in string aFilename, in string aFunctionName, in PRInt32 aLineNumber, in nsIStackFrame aCaller)
void	syncJSContexts ()
	Deprecated do-nothing function.
void	debugDump (in short depth)
void	debugDumpObject (in nsISupports aCOMObj, in short depth)
void	debugDumpJSStack (in PRBool showArgs, in PRBool showLocals, in PRBool showThisProps)
void	debugDumpEvalInJSStackFrame (in PRUint32 aFrameNumber, in string aSourceText)
void	setSafeJSContextForCurrentThread (in JSContextPtr cx)
	Set fallback JSContext to use when xpconnect can't find an appropriate context to use to execute JavaScript.
void	wrapJSAggregatedToNative (in nsISupports aOuter, in JSContextPtr aJSContext, in JSObjectPtr aJSObj, in nsIIDRef aIID,[iid_is(aIID), retval] out nsQIResult result)
	wrapJSAggregatedToNative is just like wrapJS except it is used in cases where the JSObject is also aggregated to some native xpcom Object.
nsIXPConnectWrappedNative	getWrappedNativeOfNativeObject (in JSContextPtr aJSContext, in JSObjectPtr aScope, in nsISupports aCOMObj, in nsIIDRef aIID)
	This only succeeds if the native object is already wrapped by xpconnect.
nsIXPCFunctionThisTranslator	getFunctionThisTranslator (in nsIIDRef aIID)
nsIXPCFunctionThisTranslator	setFunctionThisTranslator (in nsIIDRef aIID, in nsIXPCFunctionThisTranslator aTranslator)
nsIXPConnectJSObjectHolder	reparentWrappedNativeIfFound (in JSContextPtr aJSContext, in JSObjectPtr aScope, in JSObjectPtr aNewParent, in nsISupports aCOMObj)
void	moveWrappers (in JSContextPtr aJSContext, in JSObjectPtr aOldScope, in JSObjectPtr aNewScope)
void	clearAllWrappedNativeSecurityPolicies ()
nsIXPConnectJSObjectHolder	getWrappedNativePrototype (in JSContextPtr aJSContext, in JSObjectPtr aScope, in nsIClassInfo aClassInfo)
void	releaseJSContext (in JSContextPtr aJSContext, in PRBool noGC)
jsval	variantToJS (in JSContextPtr ctx, in JSObjectPtr scope, in nsIVariant value)
nsIVariant	JSToVariant (in JSContextPtr ctx, in jsval value)
void	flagSystemFilenamePrefix (in string aFilenamePrefix, in PRBool aWantNativeWrappers)
	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	restoreWrappedNativePrototype (in JSContextPtr aJSContext, in JSObjectPtr aScope, in nsIClassInfo aClassInfo, in nsIXPConnectJSObjectHolder aPrototype)
	Restore an old prototype for wrapped natives of type aClassInfo.
nsIXPConnectJSObjectHolder	createSandbox (in JSContextPtr cx, in nsIPrincipal principal)
	Create a sandbox for evaluating code in isolation using evalInSandboxObject().
jsval	evalInSandboxObject (in AString source, in JSContextPtr cx, in nsIXPConnectJSObjectHolder sandbox, in PRBool returnStringOnly)
	Evaluate script in a sandbox, completely isolated from all other running scripts.
void	addJSHolder (in voidPtr aHolder, in nsScriptObjectTracerPtr aTracer)
	Root JS objects held by aHolder.
void	removeJSHolder (in voidPtr aHolder)
	Stop rooting the JS objects held by aHolder.
void	noteJSContext (in JSContextPtr aJSContext, in nsCCTraversalCallbackRef aCb)
	Note aJSContext as a child to the cycle collector.
void	GetXPCWrappedNativeJSClassInfo (out JSEqualityOp equality)
	Get the JSEqualityOp pointer to use for identifying JSObjects that hold a pointer to a nsIXPConnectWrappedNative or to the native in their private date.
void	setReportAllJSExceptions (in boolean reportAllJSExceptions)
	Whether or not XPConnect should report all JS exceptions when returning from JS into C++.
void	GarbageCollect ()
	Trigger a JS garbage collection.
PRBool	defineDOMQuickStubs (in JSContextPtr cx, in JSObjectPtr proto, in PRUint32 flags, in PRUint32 interfaceCount,[array, size_is(interfaceCount)] in nsIIDPtr interfaceArray)
	Define quick stubs on the given object, proto.
virtual nsIPrincipal *	GetPrincipal (JSObject *obj, PRBool allowShortCircuit) const =0
	Get the object principal for this wrapper.
virtual char *	DebugPrintJSStack (PRBool showArgs, PRBool showLocals, PRBool showThisProps)=0
nsIXPConnectJSObjectHolder	holdObject (in JSContextPtr aJSContext, in JSObjectPtr aObject)
	Creates a JS object holder around aObject that will hold the object alive for as long as the holder stays alive.
void	getCaller (out JSContextPtr aJSContext, out JSObjectPtr aObject)
	Return the caller object of the current call from JS.
void	setDebugModeWhenPossible (in PRBool mode)
	When we place the browser in JS debug mode, there can't be any JS on the stack.
Public Attributes
const PRUint32	INIT_JS_STANDARD_CLASSES = 1 << 0
const PRUint32	FLAG_SYSTEM_GLOBAL_OBJECT = 1 << 1
const PRUint32	OMIT_COMPONENTS_OBJECT = 1 << 2
readonly attribute nsIStackFrame	CurrentJSStack
readonly attribute nsAXPCNativeCallContextPtr	CurrentNativeCallContext
attribute nsIException	PendingException

Member Function Documentation

void nsIXPConnect::addJSHolder	(	in voidPtr	aHolder,
		in nsScriptObjectTracerPtr	aTracer
	)

Root JS objects held by aHolder.

Parameters:

	aHolder	The object that hold the JS objects that should be rooted.
	aTrace	The tracer for aHolder.

void nsIXPConnect::clearAllWrappedNativeSecurityPolicies ( )

nsIXPConnectJSObjectHolder nsIXPConnect::createSandbox	(	in JSContextPtr	cx,
		in nsIPrincipal	principal
	)

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

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.

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

void nsIXPConnect::debugDump ( in short depth )

void nsIXPConnect::debugDumpEvalInJSStackFrame	(	in PRUint32	aFrameNumber,
		in string	aSourceText
	)

void nsIXPConnect::debugDumpJSStack	(	in PRBool	showArgs,
		in PRBool	showLocals,
		in PRBool	showThisProps
	)

void nsIXPConnect::debugDumpObject	(	in nsISupports	aCOMObj,
		in short	depth
	)

virtual char* nsIXPConnect::DebugPrintJSStack	(	PRBool	showArgs,
		PRBool	showLocals,
		PRBool	showThisProps
	)			`[pure virtual]`

PRBool nsIXPConnect::defineDOMQuickStubs	(	in JSContextPtr	cx,
		in JSObjectPtr	proto,
		in PRUint32	flags,
		in PRUint32	interfaceCount,
		[array, size_is(interfaceCount)] in nsIIDPtr	interfaceArray
	)

Define quick stubs on the given object, proto.

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.

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

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

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.

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

void nsIXPConnect::flagSystemFilenamePrefix	(	in string	aFilenamePrefix,
		in PRBool	aWantNativeWrappers
	)

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.

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

void nsIXPConnect::GarbageCollect ( )

Trigger a JS garbage collection.

void nsIXPConnect::getCaller	(	out JSContextPtr	aJSContext,
		out JSObjectPtr	aObject
	)

Return the caller object of the current call from JS.

void nsIXPConnect::getDefaultSecurityManager	(	out nsIXPCSecurityManager	aManager,
		out PRUint16	flags
	)

nsIXPCFunctionThisTranslator nsIXPConnect::getFunctionThisTranslator ( in nsIIDRef aIID )

JSObjectPtr nsIXPConnect::getJSObjectOfWrapper	(	in JSContextPtr	aJSContext,
		in JSObjectPtr	aJSObj
	)

nsISupports nsIXPConnect::getNativeOfWrapper	(	in JSContextPtr	aJSContext,
		in JSObjectPtr	aJSObj
	)

virtual nsIPrincipal* nsIXPConnect::GetPrincipal	(	JSObject *	obj,
		PRBool	allowShortCircuit
	)			const `[pure virtual]`

Get the object principal for this wrapper.

Note that this may well end up being null; in that case one should seek principals elsewhere. Null here does NOT indicate system principal or no principals at all, just that this wrapper doesn't have an intrinsic one.

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

nsIXPConnectWrappedNative nsIXPConnect::getWrappedNativeOfJSObject	(	in JSContextPtr	aJSContext,
		in JSObjectPtr	aJSObj
	)

This only succeeds if the JSObject is a nsIXPConnectWrappedNative.

A new wrapper is *never* constructed.

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

This only succeeds if the native object is already wrapped by xpconnect.

A new wrapper is *never* constructed.

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

void nsIXPConnect::GetXPCWrappedNativeJSClassInfo ( out JSEqualityOp equality )

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.

nsIXPConnectJSObjectHolder nsIXPConnect::holdObject	(	in JSContextPtr	aJSContext,
		in JSObjectPtr	aObject
	)

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

void nsIXPConnect::initClasses	(	in JSContextPtr	aJSContext,
		in JSObjectPtr	aGlobalJSObj
	)

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

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

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.

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.

nsIVariant nsIXPConnect::JSToVariant	(	in JSContextPtr	ctx,
		in jsval	value
	)

nsIVariant nsIXPConnect::jSValToVariant	(	in JSContextPtr	cx,
		in JSValPtr	aJSVal
	)

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

void nsIXPConnect::moveWrappers	(	in JSContextPtr	aJSContext,
		in JSObjectPtr	aOldScope,
		in JSObjectPtr	aNewScope
	)

void nsIXPConnect::noteJSContext	(	in JSContextPtr	aJSContext,
		in nsCCTraversalCallbackRef	aCb
	)

Note aJSContext as a child to the cycle collector.

Parameters:

	aJSContext	The JSContext to note.
	aCb	The cycle collection traversal callback.

void nsIXPConnect::releaseJSContext	(	in JSContextPtr	aJSContext,
		in PRBool	noGC
	)

void nsIXPConnect::removeJSHolder ( in voidPtr aHolder )

Stop rooting the JS objects held by aHolder.

Parameters:

aHolder

The object that hold the rooted JS objects.

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

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

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 nsIXPConnect::setDebugModeWhenPossible ( in PRBool mode )

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 nsIXPConnect::setDefaultSecurityManager	(	in nsIXPCSecurityManager	aManager,
		in PRUint16	flags
	)

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

nsIXPCFunctionThisTranslator nsIXPConnect::setFunctionThisTranslator	(	in nsIIDRef	aIID,
		in nsIXPCFunctionThisTranslator	aTranslator
	)

void nsIXPConnect::setReportAllJSExceptions ( in boolean reportAllJSExceptions )

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 nsIXPConnect::setSafeJSContextForCurrentThread ( in JSContextPtr cx )

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 nsIXPConnect::setSecurityManagerForJSContext	(	in JSContextPtr	aJSContext,
		in nsIXPCSecurityManager	aManager,
		in PRUint16	flags
	)

void nsIXPConnect::syncJSContexts ( )

Deprecated do-nothing function.

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

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

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 nsIXPConnect::wrapJSAggregatedToNative	(	in nsISupports	aOuter,
		in JSContextPtr	aJSContext,
		in JSObjectPtr	aJSObj,
		in nsIIDRef	aIID,
		[iid_is(aIID), retval] out nsQIResult	result
	)

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

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

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

void nsIXPConnect::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
	)

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.

Member Data Documentation

readonly attribute nsIStackFrame nsIXPConnect::CurrentJSStack

readonly attribute nsAXPCNativeCallContextPtr nsIXPConnect::CurrentNativeCallContext

const PRUint32 nsIXPConnect::FLAG_SYSTEM_GLOBAL_OBJECT = 1 << 1

const PRUint32 nsIXPConnect::INIT_JS_STANDARD_CLASSES = 1 << 0

const PRUint32 nsIXPConnect::OMIT_COMPONENTS_OBJECT = 1 << 2

attribute nsIException nsIXPConnect::PendingException

The documentation for this interface was generated from the following file:

nsIXPConnect.idl

nsIXPConnect Interface Reference

Public Member Functions

Public Attributes

Member Function Documentation

Member Data Documentation