1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/js/xpconnect/idl/nsIXPConnect.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,613 @@
1.4 +/* -*- Mode: IDL; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*-
1.5 + *
1.6 + * This Source Code Form is subject to the terms of the Mozilla Public
1.7 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.8 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.9 +
1.10 +/* The core XPConnect public interfaces. */
1.11 +
1.12 +#include "nsISupports.idl"
1.13 +
1.14 +%{ C++
1.15 +#include "jspubtd.h"
1.16 +#include "js/TypeDecls.h"
1.17 +
1.18 +struct JSFreeOp;
1.19 +
1.20 +class nsWrapperCache;
1.21 +class nsAXPCNativeCallContext;
1.22 +%}
1.23 +
1.24 +/***************************************************************************/
1.25 +
1.26 +// NB: jsval and jsid are declared in nsrootidl.idl
1.27 +
1.28 +[ptr] native JSContextPtr(JSContext);
1.29 +[ptr] native JSClassPtr(JSClass);
1.30 +[ptr] native JSFreeOpPtr(JSFreeOp);
1.31 +[ptr] native JSObjectPtr(JSObject);
1.32 +[ptr] native JSValConstPtr(const JS::Value);
1.33 + native JSPropertyOp(JSPropertyOp);
1.34 + native JSEqualityOp(JSEqualityOp);
1.35 +[ptr] native JSScriptPtr(JSScript);
1.36 +[ptr] native voidPtrPtr(void*);
1.37 +[ptr] native nsAXPCNativeCallContextPtr(nsAXPCNativeCallContext);
1.38 +[ptr] native nsWrapperCachePtr(nsWrapperCache);
1.39 +[ref] native JSCompartmentOptions(JS::CompartmentOptions);
1.40 +[ref] native JSCallArgsRef(const JS::CallArgs);
1.41 + native JSHandleId(JS::Handle<jsid>);
1.42 +
1.43 +/***************************************************************************/
1.44 +
1.45 +// forward declarations...
1.46 +interface nsIXPCScriptable;
1.47 +interface nsIXPConnect;
1.48 +interface nsIXPConnectWrappedNative;
1.49 +interface nsIInterfaceInfo;
1.50 +interface nsIXPCSecurityManager;
1.51 +interface nsIPrincipal;
1.52 +interface nsIClassInfo;
1.53 +interface nsIVariant;
1.54 +interface nsIStackFrame;
1.55 +interface nsIObjectInputStream;
1.56 +interface nsIObjectOutputStream;
1.57 +
1.58 +/***************************************************************************/
1.59 +[uuid(909e8641-7c54-4dff-9b94-ba631f057b33)]
1.60 +interface nsIXPConnectJSObjectHolder : nsISupports
1.61 +{
1.62 + [notxpcom, nostdcall] JSObjectPtr GetJSObject();
1.63 +};
1.64 +
1.65 +[uuid(675b01ba-397b-472a-9b80-5716376a2ec6)]
1.66 +interface nsIXPConnectWrappedNative : nsIXPConnectJSObjectHolder
1.67 +{
1.68 + /* attribute 'JSObject' inherited from nsIXPConnectJSObjectHolder */
1.69 + readonly attribute nsISupports Native;
1.70 + readonly attribute JSObjectPtr JSObjectPrototype;
1.71 +
1.72 + /**
1.73 + * These are here as an aid to nsIXPCScriptable implementors
1.74 + */
1.75 +
1.76 + nsIInterfaceInfo FindInterfaceWithMember(in JSHandleId nameID);
1.77 + nsIInterfaceInfo FindInterfaceWithName(in JSHandleId nameID);
1.78 + [notxpcom] bool HasNativeMember(in JSHandleId name);
1.79 +
1.80 + void debugDump(in short depth);
1.81 +
1.82 + /*
1.83 + * This finishes initializing a wrapped global, doing the parts that we
1.84 + * couldn't do while the global and window were being simultaneously
1.85 + * bootstrapped. This should be called exactly once, and only for wrapped
1.86 + * globals.
1.87 + */
1.88 + void finishInitForWrappedGlobal();
1.89 +
1.90 + /*
1.91 + * NOTE: Add new IDL methods _before_ the C++ block below if you
1.92 + * add them. Otherwise the vtable won't be what xpidl thinks it
1.93 + * is, since GetObjectPrincipal() is virtual.
1.94 + */
1.95 +
1.96 +%{C++
1.97 + /**
1.98 + * Faster access to the native object from C++. Will never return null.
1.99 + */
1.100 + nsISupports* Native() const { return mIdentity; }
1.101 +
1.102 +protected:
1.103 + nsISupports *mIdentity;
1.104 +public:
1.105 +%}
1.106 +};
1.107 +
1.108 +%{C++
1.109 +#include "nsCOMPtr.h"
1.110 +
1.111 +inline
1.112 +const nsQueryInterface
1.113 +do_QueryWrappedNative(nsIXPConnectWrappedNative *aWrappedNative)
1.114 +{
1.115 + return nsQueryInterface(aWrappedNative->Native());
1.116 +}
1.117 +
1.118 +inline
1.119 +const nsQueryInterfaceWithError
1.120 +do_QueryWrappedNative(nsIXPConnectWrappedNative *aWrappedNative,
1.121 + nsresult *aError)
1.122 +
1.123 +{
1.124 + return nsQueryInterfaceWithError(aWrappedNative->Native(), aError);
1.125 +}
1.126 +
1.127 +%}
1.128 +
1.129 +[uuid(BED52030-BCA6-11d2-BA79-00805F8A5DD7)]
1.130 +interface nsIXPConnectWrappedJS : nsIXPConnectJSObjectHolder
1.131 +{
1.132 + /* attribute 'JSObject' inherited from nsIXPConnectJSObjectHolder */
1.133 + readonly attribute nsIInterfaceInfo InterfaceInfo;
1.134 + readonly attribute nsIIDPtr InterfaceIID;
1.135 +
1.136 + void debugDump(in short depth);
1.137 +
1.138 + void aggregatedQueryInterface(in nsIIDRef uuid,
1.139 + [iid_is(uuid),retval] out nsQIResult result);
1.140 +
1.141 +};
1.142 +
1.143 +/***************************************************************************/
1.144 +
1.145 +/**
1.146 + * This is a sort of a placeholder interface. It is not intended to be
1.147 + * implemented. It exists to give the nsIXPCSecurityManager an iid on
1.148 + * which to gate a specific activity in XPConnect.
1.149 + *
1.150 + * That activity is...
1.151 + *
1.152 + * When JavaScript code uses a component that is itself implemented in
1.153 + * JavaScript then XPConnect will build a wrapper rather than directly
1.154 + * expose the JSObject of the component. This allows components implemented
1.155 + * in JavaScript to 'look' just like any other xpcom component (from the
1.156 + * perspective of the JavaScript caller). This insulates the component from
1.157 + * the caller and hides any properties or methods that are not part of the
1.158 + * interface as declared in xpidl. Usually this is a good thing.
1.159 + *
1.160 + * However, in some cases it is useful to allow the JS caller access to the
1.161 + * JS component's underlying implementation. In order to facilitate this
1.162 + * XPConnect supports the 'wrappedJSObject' property. The caller code can do:
1.163 + *
1.164 + * // 'foo' is some xpcom component (that might be implemented in JS).
1.165 + * try {
1.166 + * var bar = foo.wrappedJSObject;
1.167 + * if(bar) {
1.168 + * // bar is the underlying JSObject. Do stuff with it here.
1.169 + * }
1.170 + * } catch(e) {
1.171 + * // security exception?
1.172 + * }
1.173 + *
1.174 + * Recall that 'foo' above is an XPConnect wrapper, not the underlying JS
1.175 + * object. The property get "foo.wrappedJSObject" will only succeed if three
1.176 + * conditions are met:
1.177 + *
1.178 + * 1) 'foo' really is an XPConnect wrapper around a JSObject.
1.179 + * 2) The underlying JSObject actually implements a "wrappedJSObject"
1.180 + * property that returns a JSObject. This is called by XPConnect. This
1.181 + * restriction allows wrapped objects to only allow access to the underlying
1.182 + * JSObject if they choose to do so. Ususally this just means that 'foo'
1.183 + * would have a property tht looks like:
1.184 + * this.wrappedJSObject = this.
1.185 + * 3) The implemementation of nsIXPCSecurityManager (if installed) allows
1.186 + * a property get on the interface below. Although the JSObject need not
1.187 + * implement 'nsIXPCWrappedJSObjectGetter', XPConnect will ask the
1.188 + * security manager if it is OK for the caller to access the only method
1.189 + * in nsIXPCWrappedJSObjectGetter before allowing the activity. This fits
1.190 + * in with the security manager paradigm and makes control over accessing
1.191 + * the property on this interface the control factor for getting the
1.192 + * underlying wrapped JSObject of a JS component from JS code.
1.193 + *
1.194 + * Notes:
1.195 + *
1.196 + * a) If 'foo' above were the underlying JSObject and not a wrapper at all,
1.197 + * then this all just works and XPConnect is not part of the picture at all.
1.198 + * b) One might ask why 'foo' should not just implement an interface through
1.199 + * which callers might get at the underlying object. There are three reasons:
1.200 + * i) XPConnect would still have to do magic since JSObject is not a
1.201 + * scriptable type.
1.202 + * ii) JS Components might use aggregation (like C++ objects) and have
1.203 + * different JSObjects for different interfaces 'within' an aggregate
1.204 + * object. But, using an additional interface only allows returning one
1.205 + * underlying JSObject. However, this allows for the possibility that
1.206 + * each of the aggregte JSObjects could return something different.
1.207 + * Note that one might do: this.wrappedJSObject = someOtherObject;
1.208 + * iii) Avoiding the explicit interface makes it easier for both the caller
1.209 + * and the component.
1.210 + *
1.211 + * Anyway, some future implementation of nsIXPCSecurityManager might want
1.212 + * do special processing on 'nsIXPCSecurityManager::CanGetProperty' when
1.213 + * the interface id is that of nsIXPCWrappedJSObjectGetter.
1.214 + */
1.215 +
1.216 +[scriptable, uuid(254bb2e0-6439-11d4-8fe0-0010a4e73d9a)]
1.217 +interface nsIXPCWrappedJSObjectGetter : nsISupports
1.218 +{
1.219 + readonly attribute nsISupports neverCalled;
1.220 +};
1.221 +
1.222 +/***************************************************************************/
1.223 +
1.224 +/*
1.225 + * This interface is implemented by outside code and registered with xpconnect
1.226 + * via nsIXPConnect::setFunctionThisTranslator.
1.227 + *
1.228 + * The reason this exists is to support calls to JavaScript event callbacks
1.229 + * needed by the DOM via xpconnect from C++ code.
1.230 + *
1.231 + * We've added support for wrapping JS function objects as xpcom interfaces
1.232 + * by declaring the given interface as a [function] interface. However, to
1.233 + * support the requirements of JS event callbacks we need to call the JS
1.234 + * function with the 'this' set as the JSObject for which the event is being
1.235 + * fired; e.g. a form node.
1.236 + *
1.237 + * We've decided that for all cases we care about the appropriate 'this' object
1.238 + * can be derived from the first param in the call to the callback. In the
1.239 + * event handler case the first param is an event object.
1.240 + *
1.241 + * Though we can't change all the JS code so that it would setup its own 'this',
1.242 + * we can add plugin 'helper' support to xpconnect. And that is what we have
1.243 + * here.
1.244 + *
1.245 + * The idea is that at startup time some code that cares about this issue
1.246 + * (e.g. the DOM helper code) can register a nsIXPCFunctionThisTranslator
1.247 + * object with xpconnect to handle calls to [function] interfaces of a given
1.248 + * iid. When xpconnect goes to invoke a method on a wrapped JSObject for
1.249 + * an interface marked as [function], xpconnect will check if the first param
1.250 + * of the method is an xpcom object pointer and if so it will check to see if a
1.251 + * nsIXPCFunctionThisTranslator has been registered for the given iid of the
1.252 + * interface being called. If so it will call the translator and get an
1.253 + * interface pointer to use as the 'this' for the call. If the translator
1.254 + * returns a non-null interface pointer (which it should then have addref'd
1.255 + * since it is being returned as an out param), xpconnect will attempt to build
1.256 + * a wrapper around the pointer and get a JSObject from that wrapper to use
1.257 + * as the 'this' for the call.
1.258 + *
1.259 + * If a null interface pointer is returned then xpconnect will use the default
1.260 + * 'this' - the same JSObject as the function object it is calling.
1.261 + */
1.262 +
1.263 +[uuid(f5f84b70-92eb-41f1-a1dd-2eaac0ed564c)]
1.264 +interface nsIXPCFunctionThisTranslator : nsISupports
1.265 +{
1.266 + nsISupports TranslateThis(in nsISupports aInitialThis);
1.267 +};
1.268 +
1.269 +/***************************************************************************/
1.270 +
1.271 +
1.272 +%{ C++
1.273 +// For use with the service manager
1.274 +// {CB6593E0-F9B2-11d2-BDD6-000064657374}
1.275 +#define NS_XPCONNECT_CID \
1.276 +{ 0xcb6593e0, 0xf9b2, 0x11d2, \
1.277 + { 0xbd, 0xd6, 0x0, 0x0, 0x64, 0x65, 0x73, 0x74 } }
1.278 +%}
1.279 +
1.280 +[noscript, uuid(3d5a6320-8764-11e3-baa7-0800200c9a66)]
1.281 +interface nsIXPConnect : nsISupports
1.282 +{
1.283 +%{ C++
1.284 + NS_DEFINE_STATIC_CID_ACCESSOR(NS_XPCONNECT_CID)
1.285 +%}
1.286 +
1.287 + /**
1.288 + * Initializes classes on a global object that has already been created.
1.289 + */
1.290 + void
1.291 + initClasses(in JSContextPtr aJSContext,
1.292 + in JSObjectPtr aGlobalJSObj);
1.293 +
1.294 + /**
1.295 + * Creates a new global object using the given aCOMObj as the global
1.296 + * object. The object will be set up according to the flags (defined
1.297 + * below). If you do not pass INIT_JS_STANDARD_CLASSES, then aCOMObj
1.298 + * must implement nsIXPCScriptable so it can resolve the standard
1.299 + * classes when asked by the JS engine.
1.300 + *
1.301 + * @param aJSContext the context to use while creating the global object.
1.302 + * @param aCOMObj the native object that represents the global object.
1.303 + * @param aPrincipal the principal of the code that will run in this
1.304 + * compartment. Can be null if not on the main thread.
1.305 + * @param aFlags one of the flags below specifying what options this
1.306 + * global object wants.
1.307 + * @param aOptions JSAPI-specific options for the new compartment.
1.308 + */
1.309 + nsIXPConnectJSObjectHolder
1.310 + initClassesWithNewWrappedGlobal(
1.311 + in JSContextPtr aJSContext,
1.312 + in nsISupports aCOMObj,
1.313 + in nsIPrincipal aPrincipal,
1.314 + in uint32_t aFlags,
1.315 + in JSCompartmentOptions aOptions);
1.316 +
1.317 + const uint32_t INIT_JS_STANDARD_CLASSES = 1 << 0;
1.318 + const uint32_t DONT_FIRE_ONNEWGLOBALHOOK = 1 << 1;
1.319 + const uint32_t OMIT_COMPONENTS_OBJECT = 1 << 2;
1.320 +
1.321 + /**
1.322 + * wrapNative will create a new JSObject or return an existing one.
1.323 + *
1.324 + * The JSObject is returned inside a refcounted nsIXPConnectJSObjectHolder.
1.325 + * As long as this holder is held the JSObject will be protected from
1.326 + * collection by JavaScript's garbage collector. It is a good idea to
1.327 + * transfer the JSObject to some equally protected place before releasing
1.328 + * the holder (i.e. use JS_SetProperty to make this object a property of
1.329 + * some other JSObject).
1.330 + *
1.331 + * This method now correctly deals with cases where the passed in xpcom
1.332 + * object already has an associated JSObject for the cases:
1.333 + * 1) The xpcom object has already been wrapped for use in the same scope
1.334 + * as an nsIXPConnectWrappedNative.
1.335 + * 2) The xpcom object is in fact a nsIXPConnectWrappedJS and thus already
1.336 + * has an underlying JSObject.
1.337 + *
1.338 + * It *might* be possible to QueryInterface the nsIXPConnectJSObjectHolder
1.339 + * returned by the method into a nsIXPConnectWrappedNative or a
1.340 + * nsIXPConnectWrappedJS.
1.341 + *
1.342 + * This method will never wrap the JSObject involved in an
1.343 + * XPCNativeWrapper before returning.
1.344 + *
1.345 + * Returns:
1.346 + * success:
1.347 + * NS_OK
1.348 + * failure:
1.349 + * NS_ERROR_XPC_BAD_CONVERT_NATIVE
1.350 + * NS_ERROR_XPC_CANT_GET_JSOBJECT_OF_DOM_OBJECT
1.351 + * NS_ERROR_FAILURE
1.352 + */
1.353 + nsIXPConnectJSObjectHolder
1.354 + wrapNative(in JSContextPtr aJSContext,
1.355 + in JSObjectPtr aScope,
1.356 + in nsISupports aCOMObj,
1.357 + in nsIIDRef aIID);
1.358 +
1.359 + /**
1.360 + * Same as wrapNative, but it returns the JSObject in aVal. C++ callers
1.361 + * must ensure that aVal is rooted.
1.362 + * aIID may be null, it means the same as passing in
1.363 + * &NS_GET_IID(nsISupports) but when passing in null certain shortcuts
1.364 + * can be taken because we know without comparing IIDs that the caller is
1.365 + * asking for an nsISupports wrapper.
1.366 + * If aAllowWrapper, then the returned value will be wrapped in the proper
1.367 + * type of security wrapper on top of the XPCWrappedNative (if needed).
1.368 + * This method doesn't push aJSContext on the context stack, so the caller
1.369 + * is required to push it if the top of the context stack is not equal to
1.370 + * aJSContext.
1.371 + */
1.372 + void
1.373 + wrapNativeToJSVal(in JSContextPtr aJSContext,
1.374 + in JSObjectPtr aScope,
1.375 + in nsISupports aCOMObj,
1.376 + in nsWrapperCachePtr aCache,
1.377 + in nsIIDPtr aIID,
1.378 + in boolean aAllowWrapper,
1.379 + out jsval aVal);
1.380 +
1.381 + /**
1.382 + * wrapJS will yield a new or previously existing xpcom interface pointer
1.383 + * to represent the JSObject passed in.
1.384 + *
1.385 + * This method now correctly deals with cases where the passed in JSObject
1.386 + * already has an associated xpcom interface for the cases:
1.387 + * 1) The JSObject has already been wrapped as a nsIXPConnectWrappedJS.
1.388 + * 2) The JSObject is in fact a nsIXPConnectWrappedNative and thus already
1.389 + * has an underlying xpcom object.
1.390 + * 3) The JSObject is of a jsclass which supports getting the nsISupports
1.391 + * from the JSObject directly. This is used for idlc style objects
1.392 + * (e.g. DOM objects).
1.393 + *
1.394 + * It *might* be possible to QueryInterface the resulting interface pointer
1.395 + * to nsIXPConnectWrappedJS.
1.396 + *
1.397 + * Returns:
1.398 + * success:
1.399 + * NS_OK
1.400 + * failure:
1.401 + * NS_ERROR_XPC_BAD_CONVERT_JS
1.402 + * NS_ERROR_FAILURE
1.403 + */
1.404 + void
1.405 + wrapJS(in JSContextPtr aJSContext,
1.406 + in JSObjectPtr aJSObj,
1.407 + in nsIIDRef aIID,
1.408 + [iid_is(aIID),retval] out nsQIResult result);
1.409 +
1.410 + /**
1.411 + * Wraps the given jsval in a nsIVariant and returns the new variant.
1.412 + */
1.413 + nsIVariant
1.414 + jSValToVariant(in JSContextPtr cx, in jsval aJSVal);
1.415 +
1.416 + /**
1.417 + * This only succeeds if the JSObject is a nsIXPConnectWrappedNative.
1.418 + * A new wrapper is *never* constructed.
1.419 + */
1.420 + nsIXPConnectWrappedNative
1.421 + getWrappedNativeOfJSObject(in JSContextPtr aJSContext,
1.422 + in JSObjectPtr aJSObj);
1.423 +
1.424 + [noscript, notxpcom] nsISupports
1.425 + getNativeOfWrapper(in JSContextPtr aJSContext,
1.426 + in JSObjectPtr aJSObj);
1.427 +
1.428 + /**
1.429 + * The security manager to use when the current JSContext has no security
1.430 + * manager.
1.431 + */
1.432 + void setDefaultSecurityManager(in nsIXPCSecurityManager aManager);
1.433 +
1.434 + nsIStackFrame
1.435 + createStackFrameLocation(in uint32_t aLanguage,
1.436 + in string aFilename,
1.437 + in string aFunctionName,
1.438 + in int32_t aLineNumber,
1.439 + in nsIStackFrame aCaller);
1.440 +
1.441 +
1.442 + [noscript,notxpcom,nostdcall] JSContextPtr getCurrentJSContext();
1.443 + [noscript,notxpcom,nostdcall] JSContextPtr initSafeJSContext();
1.444 + [noscript,notxpcom,nostdcall] JSContextPtr getSafeJSContext();
1.445 +
1.446 + readonly attribute nsIStackFrame CurrentJSStack;
1.447 + readonly attribute nsAXPCNativeCallContextPtr CurrentNativeCallContext;
1.448 +
1.449 + void debugDump(in short depth);
1.450 + void debugDumpObject(in nsISupports aCOMObj, in short depth);
1.451 + void debugDumpJSStack(in boolean showArgs,
1.452 + in boolean showLocals,
1.453 + in boolean showThisProps);
1.454 + void debugDumpEvalInJSStackFrame(in uint32_t aFrameNumber,
1.455 + in string aSourceText);
1.456 +
1.457 + /**
1.458 + * wrapJSAggregatedToNative is just like wrapJS except it is used in cases
1.459 + * where the JSObject is also aggregated to some native xpcom Object.
1.460 + * At present XBL is the only system that might want to do this.
1.461 + *
1.462 + * XXX write more!
1.463 + *
1.464 + * Returns:
1.465 + * success:
1.466 + * NS_OK
1.467 + * failure:
1.468 + * NS_ERROR_XPC_BAD_CONVERT_JS
1.469 + * NS_ERROR_FAILURE
1.470 + */
1.471 + void
1.472 + wrapJSAggregatedToNative(in nsISupports aOuter,
1.473 + in JSContextPtr aJSContext,
1.474 + in JSObjectPtr aJSObj,
1.475 + in nsIIDRef aIID,
1.476 + [iid_is(aIID),retval] out nsQIResult result);
1.477 +
1.478 + // Methods added since mozilla 0.6....
1.479 +
1.480 + /**
1.481 + * This only succeeds if the native object is already wrapped by xpconnect.
1.482 + * A new wrapper is *never* constructed.
1.483 + */
1.484 + nsIXPConnectWrappedNative
1.485 + getWrappedNativeOfNativeObject(in JSContextPtr aJSContext,
1.486 + in JSObjectPtr aScope,
1.487 + in nsISupports aCOMObj,
1.488 + in nsIIDRef aIID);
1.489 +
1.490 + void
1.491 + setFunctionThisTranslator(in nsIIDRef aIID,
1.492 + in nsIXPCFunctionThisTranslator aTranslator);
1.493 +
1.494 + void
1.495 + reparentWrappedNativeIfFound(in JSContextPtr aJSContext,
1.496 + in JSObjectPtr aScope,
1.497 + in JSObjectPtr aNewParent,
1.498 + in nsISupports aCOMObj);
1.499 + void
1.500 + rescueOrphansInScope(in JSContextPtr aJSContext, in JSObjectPtr aScope);
1.501 +
1.502 + nsIXPConnectJSObjectHolder
1.503 + getWrappedNativePrototype(in JSContextPtr aJSContext,
1.504 + in JSObjectPtr aScope,
1.505 + in nsIClassInfo aClassInfo);
1.506 +
1.507 + jsval variantToJS(in JSContextPtr ctx, in JSObjectPtr scope, in nsIVariant value);
1.508 + nsIVariant JSToVariant(in JSContextPtr ctx, in jsval value);
1.509 +
1.510 + /**
1.511 + * Create a sandbox for evaluating code in isolation using
1.512 + * evalInSandboxObject().
1.513 + *
1.514 + * @param cx A context to use when creating the sandbox object.
1.515 + * @param principal The principal (or NULL to use the null principal)
1.516 + * to use when evaluating code in this sandbox.
1.517 + */
1.518 + [noscript] nsIXPConnectJSObjectHolder createSandbox(in JSContextPtr cx,
1.519 + in nsIPrincipal principal);
1.520 +
1.521 + /**
1.522 + * Evaluate script in a sandbox, completely isolated from all
1.523 + * other running scripts.
1.524 + *
1.525 + * @param source The source of the script to evaluate.
1.526 + * @param filename The filename of the script. May be null.
1.527 + * @param cx The context to use when setting up the evaluation of
1.528 + * the script. The actual evaluation will happen on a new
1.529 + * temporary context.
1.530 + * @param sandbox The sandbox object to evaluate the script in.
1.531 + * @param returnStringOnly The only results to come out of the
1.532 + * computation (including exceptions) will
1.533 + * be coerced into strings created in the
1.534 + * sandbox.
1.535 + * @return The result of the evaluation as a jsval. If the caller
1.536 + * intends to use the return value from this call the caller
1.537 + * is responsible for rooting the jsval before making a call
1.538 + * to this method.
1.539 + */
1.540 + [noscript] jsval evalInSandboxObject(in AString source, in string filename,
1.541 + in JSContextPtr cx,
1.542 + in JSObjectPtr sandbox,
1.543 + in boolean returnStringOnly);
1.544 +
1.545 + /**
1.546 + * Whether or not XPConnect should report all JS exceptions when returning
1.547 + * from JS into C++. False by default, although any value set in the
1.548 + * MOZ_REPORT_ALL_JS_EXCEPTIONS environment variable will override the value
1.549 + * passed here.
1.550 + */
1.551 + void setReportAllJSExceptions(in boolean reportAllJSExceptions);
1.552 +
1.553 + /**
1.554 + * Trigger a JS garbage collection.
1.555 + * Use a js::gcreason::Reason from jsfriendapi.h for the kind.
1.556 + */
1.557 + void GarbageCollect(in uint32_t reason);
1.558 +
1.559 + /**
1.560 + * Signals a good place to do an incremental GC slice, because the
1.561 + * browser is drawing a frame.
1.562 + */
1.563 + void NotifyDidPaint();
1.564 +
1.565 +%{C++
1.566 + /**
1.567 + * Get the object principal for this wrapper. Note that this may well end
1.568 + * up being null; in that case one should seek principals elsewhere. Null
1.569 + * here does NOT indicate system principal or no principals at all, just
1.570 + * that this wrapper doesn't have an intrinsic one.
1.571 + */
1.572 + virtual nsIPrincipal* GetPrincipal(JSObject* obj,
1.573 + bool allowShortCircuit) const = 0;
1.574 + virtual char* DebugPrintJSStack(bool showArgs,
1.575 + bool showLocals,
1.576 + bool showThisProps) = 0;
1.577 +%}
1.578 +
1.579 + /**
1.580 + * Creates a JS object holder around aObject that will hold the object
1.581 + * alive for as long as the holder stays alive.
1.582 + */
1.583 + nsIXPConnectJSObjectHolder holdObject(in JSContextPtr aJSContext,
1.584 + in JSObjectPtr aObject);
1.585 +
1.586 + /**
1.587 + * When we place the browser in JS debug mode, there can't be any
1.588 + * JS on the stack. This is because we currently activate debugMode
1.589 + * on all scripts in the JSRuntime when the debugger is activated.
1.590 + * This method will turn debug mode on or off when the context
1.591 + * stack reaches zero length.
1.592 + */
1.593 + [noscript] void setDebugModeWhenPossible(in boolean mode,
1.594 + in boolean allowSyncDisable);
1.595 +
1.596 + [noscript] void writeScript(in nsIObjectOutputStream aStream,
1.597 + in JSContextPtr aJSContext,
1.598 + in JSScriptPtr aJSScript);
1.599 +
1.600 + [noscript] JSScriptPtr readScript(in nsIObjectInputStream aStream,
1.601 + in JSContextPtr aJSContext);
1.602 +
1.603 + [noscript] void writeFunction(in nsIObjectOutputStream aStream,
1.604 + in JSContextPtr aJSContext,
1.605 + in JSObjectPtr aJSObject);
1.606 +
1.607 + [noscript] JSObjectPtr readFunction(in nsIObjectInputStream aStream,
1.608 + in JSContextPtr aJSContext);
1.609 +
1.610 + /**
1.611 + * This function should be called in JavaScript error reporters
1.612 + * to signal that they are ignoring the error. In this case,
1.613 + * XPConnect can print a warning to the console.
1.614 + */
1.615 + [noscript] void markErrorUnreported(in JSContextPtr aJSContext);
1.616 +};
