The Tor Browser: comparison js/xpconnect/idl/nsIXPConnect.idl

--1:000000000000
+:72c4e6d1361d
+/* -*- Mode: IDL; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*-
+*
+* This Source Code Form is subject to the terms of the Mozilla Public
+* License, v. 2.0. If a copy of the MPL was not distributed with this
+* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+/* The core XPConnect public interfaces. */
+#include "nsISupports.idl"
+%{ C++
+#include "jspubtd.h"
+#include "js/TypeDecls.h"
+struct JSFreeOp;
+class nsWrapperCache;
+class nsAXPCNativeCallContext;
+%}
+/***************************************************************************/
+// NB: jsval and jsid are declared in nsrootidl.idl
+[ptr] native JSContextPtr(JSContext);
+[ptr] native JSClassPtr(JSClass);
+[ptr] native JSFreeOpPtr(JSFreeOp);
+[ptr] native JSObjectPtr(JSObject);
+[ptr] native JSValConstPtr(const JS::Value);
+native JSPropertyOp(JSPropertyOp);
+native JSEqualityOp(JSEqualityOp);
+[ptr] native JSScriptPtr(JSScript);
+[ptr] native voidPtrPtr(void*);
+[ptr] native nsAXPCNativeCallContextPtr(nsAXPCNativeCallContext);
+[ptr] native nsWrapperCachePtr(nsWrapperCache);
+[ref] native JSCompartmentOptions(JS::CompartmentOptions);
+[ref] native JSCallArgsRef(const JS::CallArgs);
+native JSHandleId(JS::Handle<jsid>);
+/***************************************************************************/
+// forward declarations...
+interface nsIXPCScriptable;
+interface nsIXPConnect;
+interface nsIXPConnectWrappedNative;
+interface nsIInterfaceInfo;
+interface nsIXPCSecurityManager;
+interface nsIPrincipal;
+interface nsIClassInfo;
+interface nsIVariant;
+interface nsIStackFrame;
+interface nsIObjectInputStream;
+interface nsIObjectOutputStream;
+/***************************************************************************/
+[uuid(909e8641-7c54-4dff-9b94-ba631f057b33)]
+interface nsIXPConnectJSObjectHolder : nsISupports
+{
+[notxpcom, nostdcall] JSObjectPtr GetJSObject();
+};
+[uuid(675b01ba-397b-472a-9b80-5716376a2ec6)]
+interface nsIXPConnectWrappedNative : nsIXPConnectJSObjectHolder
+{
+/* attribute 'JSObject' inherited from nsIXPConnectJSObjectHolder */
+readonly attribute nsISupports      Native;
+readonly attribute JSObjectPtr      JSObjectPrototype;
+/**
+* These are here as an aid to nsIXPCScriptable implementors
+*/
+nsIInterfaceInfo FindInterfaceWithMember(in JSHandleId nameID);
+nsIInterfaceInfo FindInterfaceWithName(in JSHandleId nameID);
+[notxpcom] bool HasNativeMember(in JSHandleId name);
+void debugDump(in short depth);
+/*
+* This finishes initializing a wrapped global, doing the parts that we
+* couldn't do while the global and window were being simultaneously
+* bootstrapped. This should be called exactly once, and only for wrapped
+* globals.
+*/
+void finishInitForWrappedGlobal();
+/*
+* NOTE: Add new IDL methods _before_ the C++ block below if you
+* add them.  Otherwise the vtable won't be what xpidl thinks it
+* is, since GetObjectPrincipal() is virtual.
+*/
+%{C++
+/**
+* Faster access to the native object from C++.  Will never return null.
+*/
+nsISupports* Native() const { return mIdentity; }
+protected:
+nsISupports *mIdentity;
+public:
+%}
+};
+%{C++
+#include "nsCOMPtr.h"
+inline
+const nsQueryInterface
+do_QueryWrappedNative(nsIXPConnectWrappedNative *aWrappedNative)
+{
+return nsQueryInterface(aWrappedNative->Native());
+}
+inline
+const nsQueryInterfaceWithError
+do_QueryWrappedNative(nsIXPConnectWrappedNative *aWrappedNative,
+nsresult *aError)
+{
+return nsQueryInterfaceWithError(aWrappedNative->Native(), aError);
+}
+%}
+[uuid(BED52030-BCA6-11d2-BA79-00805F8A5DD7)]
+interface nsIXPConnectWrappedJS : nsIXPConnectJSObjectHolder
+{
+/* attribute 'JSObject' inherited from nsIXPConnectJSObjectHolder */
+readonly attribute nsIInterfaceInfo InterfaceInfo;
+readonly attribute nsIIDPtr         InterfaceIID;
+void debugDump(in short depth);
+void aggregatedQueryInterface(in nsIIDRef uuid,
+[iid_is(uuid),retval] out nsQIResult result);
+};
+/***************************************************************************/
+/**
+* This is a sort of a placeholder interface. It is not intended to be
+* implemented. It exists to give the nsIXPCSecurityManager an iid on
+* which to gate a specific activity in XPConnect.
+*
+* That activity is...
+*
+* When JavaScript code uses a component that is itself implemented in
+* JavaScript then XPConnect will build a wrapper rather than directly
+* expose the JSObject of the component. This allows components implemented
+* in JavaScript to 'look' just like any other xpcom component (from the
+* perspective of the JavaScript caller). This insulates the component from
+* the caller and hides any properties or methods that are not part of the
+* interface as declared in xpidl. Usually this is a good thing.
+*
+* However, in some cases it is useful to allow the JS caller access to the
+* JS component's underlying implementation. In order to facilitate this
+* XPConnect supports the 'wrappedJSObject' property. The caller code can do:
+*
+* // 'foo' is some xpcom component (that might be implemented in JS).
+* try {
+*   var bar = foo.wrappedJSObject;
+*   if(bar) {
+*      // bar is the underlying JSObject. Do stuff with it here.
+*   }
+* } catch(e) {
+*   // security exception?
+* }
+*
+* Recall that 'foo' above is an XPConnect wrapper, not the underlying JS
+* object. The property get "foo.wrappedJSObject" will only succeed if three
+* conditions are met:
+*
+* 1) 'foo' really is an XPConnect wrapper around a JSObject.
+* 2) The underlying JSObject actually implements a "wrappedJSObject"
+*    property that returns a JSObject. This is called by XPConnect. This
+*    restriction allows wrapped objects to only allow access to the underlying
+*    JSObject if they choose to do so. Ususally this just means that 'foo'
+*    would have a property tht looks like:
+*       this.wrappedJSObject = this.
+* 3) The implemementation of nsIXPCSecurityManager (if installed) allows
+*    a property get on the interface below. Although the JSObject need not
+*    implement 'nsIXPCWrappedJSObjectGetter', XPConnect will ask the
+*    security manager if it is OK for the caller to access the only method
+*    in nsIXPCWrappedJSObjectGetter before allowing the activity. This fits
+*    in with the security manager paradigm and makes control over accessing
+*    the property on this interface the control factor for getting the
+*    underlying wrapped JSObject of a JS component from JS code.
+*
+* Notes:
+*
+* a) If 'foo' above were the underlying JSObject and not a wrapper at all,
+*    then this all just works and XPConnect is not part of the picture at all.
+* b) One might ask why 'foo' should not just implement an interface through
+*    which callers might get at the underlying object. There are three reasons:
+*   i)   XPConnect would still have to do magic since JSObject is not a
+*        scriptable type.
+*   ii)  JS Components might use aggregation (like C++ objects) and have
+*        different JSObjects for different interfaces 'within' an aggregate
+*        object. But, using an additional interface only allows returning one
+*        underlying JSObject. However, this allows for the possibility that
+*        each of the aggregte JSObjects could return something different.
+*        Note that one might do: this.wrappedJSObject = someOtherObject;
+*   iii) Avoiding the explicit interface makes it easier for both the caller
+*        and the component.
+*
+*  Anyway, some future implementation of nsIXPCSecurityManager might want
+*  do special processing on 'nsIXPCSecurityManager::CanGetProperty' when
+*  the interface id is that of nsIXPCWrappedJSObjectGetter.
+*/
+[scriptable, uuid(254bb2e0-6439-11d4-8fe0-0010a4e73d9a)]
+interface nsIXPCWrappedJSObjectGetter : nsISupports
+{
+readonly attribute nsISupports neverCalled;
+};
+/***************************************************************************/
+/*
+* This interface is implemented by outside code and registered with xpconnect
+* via nsIXPConnect::setFunctionThisTranslator.
+*
+* The reason this exists is to support calls to JavaScript event callbacks
+* needed by the DOM via xpconnect from C++ code.
+*
+* We've added support for wrapping JS function objects as xpcom interfaces
+* by declaring the given interface as a [function] interface. However, to
+* support the requirements of JS event callbacks we need to call the JS
+* function with the 'this' set as the JSObject for which the event is being
+* fired; e.g. a form node.
+*
+* We've decided that for all cases we care about the appropriate 'this' object
+* can be derived from the first param in the call to the callback. In the
+* event handler case the first param is an event object.
+*
+* Though we can't change all the JS code so that it would setup its own 'this',
+* we can add plugin 'helper' support to xpconnect. And that is what we have
+* here.
+*
+* The idea is that at startup time some code that cares about this issue
+* (e.g. the DOM helper code) can register a nsIXPCFunctionThisTranslator
+* object with xpconnect to handle calls to [function] interfaces of a given
+* iid. When xpconnect goes to invoke a method on a wrapped JSObject for
+* an interface marked as [function], xpconnect will check if the first param
+* of the method is an xpcom object pointer and if so it will check to see if a
+* nsIXPCFunctionThisTranslator has been registered for the given iid of the
+* interface being called. If so it will call the translator and get an
+* interface pointer to use as the 'this' for the call. If the translator
+* returns a non-null interface pointer (which it should then have addref'd
+* since it is being returned as an out param), xpconnect will attempt to build
+* a wrapper around the pointer and get a JSObject from that wrapper to use
+* as the 'this' for the call.
+*
+* If a null interface pointer is returned then xpconnect will use the default
+* 'this' - the same JSObject as the function object it is calling.
+*/
+[uuid(f5f84b70-92eb-41f1-a1dd-2eaac0ed564c)]
+interface nsIXPCFunctionThisTranslator : nsISupports
+{
+nsISupports TranslateThis(in nsISupports aInitialThis);
+};
+/***************************************************************************/
+%{ C++
+// For use with the service manager
+// {CB6593E0-F9B2-11d2-BDD6-000064657374}
+#define NS_XPCONNECT_CID \
+{ 0xcb6593e0, 0xf9b2, 0x11d2, \
+{ 0xbd, 0xd6, 0x0, 0x0, 0x64, 0x65, 0x73, 0x74 } }
+%}
+[noscript, uuid(3d5a6320-8764-11e3-baa7-0800200c9a66)]
+interface nsIXPConnect : nsISupports
+{
+%{ C++
+NS_DEFINE_STATIC_CID_ACCESSOR(NS_XPCONNECT_CID)
+%}
+/**
+* Initializes classes on a global object that has already been created.
+*/
+void
+initClasses(in JSContextPtr aJSContext,
+in JSObjectPtr  aGlobalJSObj);
+/**
+* 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.
+*
+* @param aJSContext the context to use while creating the global object.
+* @param aCOMObj the native object that represents the global object.
+* @param aPrincipal the principal of the code that will run in this
+*                   compartment. Can be null if not on the main thread.
+* @param aFlags one of the flags below specifying what options this
+*               global object wants.
+* @param aOptions JSAPI-specific options for the new compartment.
+*/
+nsIXPConnectJSObjectHolder
+initClassesWithNewWrappedGlobal(
+in JSContextPtr         aJSContext,
+in nsISupports          aCOMObj,
+in nsIPrincipal         aPrincipal,
+in uint32_t             aFlags,
+in JSCompartmentOptions aOptions);
+const uint32_t INIT_JS_STANDARD_CLASSES  = 1 << 0;
+const uint32_t DONT_FIRE_ONNEWGLOBALHOOK = 1 << 1;
+const uint32_t OMIT_COMPONENTS_OBJECT    = 1 << 2;
+/**
+* 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.
+*
+* 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);
+/**
+* Same as wrapNative, but it returns the JSObject in aVal. C++ callers
+* 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);
+/**
+* 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);
+/**
+* Wraps the given jsval in a nsIVariant and returns the new variant.
+*/
+nsIVariant
+jSValToVariant(in JSContextPtr cx, in jsval aJSVal);
+/**
+* This only succeeds if the JSObject is a nsIXPConnectWrappedNative.
+* A new wrapper is *never* constructed.
+*/
+nsIXPConnectWrappedNative
+getWrappedNativeOfJSObject(in JSContextPtr aJSContext,
+in JSObjectPtr  aJSObj);
+[noscript, notxpcom] nsISupports
+getNativeOfWrapper(in JSContextPtr aJSContext,
+in JSObjectPtr  aJSObj);
+/**
+* The security manager to use when the current JSContext has no security
+* manager.
+*/
+void setDefaultSecurityManager(in nsIXPCSecurityManager aManager);
+nsIStackFrame
+createStackFrameLocation(in uint32_t       aLanguage,
+in string         aFilename,
+in string         aFunctionName,
+in int32_t        aLineNumber,
+in nsIStackFrame  aCaller);
+[noscript,notxpcom,nostdcall] JSContextPtr getCurrentJSContext();
+[noscript,notxpcom,nostdcall] JSContextPtr initSafeJSContext();
+[noscript,notxpcom,nostdcall] JSContextPtr getSafeJSContext();
+readonly attribute nsIStackFrame                CurrentJSStack;
+readonly attribute nsAXPCNativeCallContextPtr   CurrentNativeCallContext;
+void debugDump(in short depth);
+void debugDumpObject(in nsISupports aCOMObj, in short depth);
+void debugDumpJSStack(in boolean showArgs,
+in boolean showLocals,
+in boolean showThisProps);
+void debugDumpEvalInJSStackFrame(in uint32_t aFrameNumber,
+in string aSourceText);
+/**
+* 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);
+// Methods added since mozilla 0.6....
+/**
+* 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);
+void
+setFunctionThisTranslator(in nsIIDRef aIID,
+in nsIXPCFunctionThisTranslator aTranslator);
+void
+reparentWrappedNativeIfFound(in JSContextPtr aJSContext,
+in JSObjectPtr  aScope,
+in JSObjectPtr  aNewParent,
+in nsISupports  aCOMObj);
+void
+rescueOrphansInScope(in JSContextPtr aJSContext, in JSObjectPtr  aScope);
+nsIXPConnectJSObjectHolder
+getWrappedNativePrototype(in JSContextPtr aJSContext,
+in JSObjectPtr  aScope,
+in nsIClassInfo aClassInfo);
+jsval variantToJS(in JSContextPtr ctx, in JSObjectPtr scope, in nsIVariant value);
+nsIVariant JSToVariant(in JSContextPtr ctx, in jsval value);
+/**
+* Create a sandbox for evaluating code in isolation using
+* evalInSandboxObject().
+*
+* @param cx A context to use when creating the sandbox object.
+* @param principal The principal (or NULL to use the null principal)
+*                  to use when evaluating code in this sandbox.
+*/
+[noscript] nsIXPConnectJSObjectHolder createSandbox(in JSContextPtr cx,
+in nsIPrincipal principal);
+/**
+* Evaluate script in a sandbox, completely isolated from all
+* other running scripts.
+*
+* @param source The source of the script to evaluate.
+* @param filename The filename of the script. May be null.
+* @param cx The context to use when setting up the evaluation of
+*           the script. The actual evaluation will happen on a new
+*           temporary context.
+* @param sandbox The sandbox object to evaluate the script in.
+* @param returnStringOnly The only results to come out of the
+*                         computation (including exceptions) will
+*                         be coerced into strings created in the
+*                         sandbox.
+* @return 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.
+*/
+[noscript] jsval evalInSandboxObject(in AString source, in string filename,
+in JSContextPtr cx,
+in JSObjectPtr sandbox,
+in boolean returnStringOnly);
+/**
+* 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);
+/**
+* Trigger a JS garbage collection.
+* Use a js::gcreason::Reason from jsfriendapi.h for the kind.
+*/
+void GarbageCollect(in uint32_t reason);
+/**
+* Signals a good place to do an incremental GC slice, because the
+* browser is drawing a frame.
+*/
+void NotifyDidPaint();
+%{C++
+/**
+* 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.
+*/
+virtual nsIPrincipal* GetPrincipal(JSObject* obj,
+bool allowShortCircuit) const = 0;
+virtual char* DebugPrintJSStack(bool showArgs,
+bool showLocals,
+bool showThisProps) = 0;
+%}
+/**
+* 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);
+/**
+* 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.
+*/
+[noscript] void setDebugModeWhenPossible(in boolean mode,
+in boolean allowSyncDisable);
+[noscript] void writeScript(in nsIObjectOutputStream aStream,
+in JSContextPtr aJSContext,
+in JSScriptPtr aJSScript);
+[noscript] JSScriptPtr readScript(in nsIObjectInputStream aStream,
+in JSContextPtr aJSContext);
+[noscript] void writeFunction(in nsIObjectOutputStream aStream,
+in JSContextPtr aJSContext,
+in JSObjectPtr aJSObject);
+[noscript] JSObjectPtr readFunction(in nsIObjectInputStream aStream,
+in JSContextPtr aJSContext);
+/**
+* This function should be called in JavaScript error reporters
+* to signal that they are ignoring the error. In this case,
+* XPConnect can print a warning to the console.
+*/
+[noscript] void markErrorUnreported(in JSContextPtr aJSContext);
+};

The Tor Browser / file comparison

comparison: js/xpconnect/idl/nsIXPConnect.idl

js/xpconnect/idl/nsIXPConnect.idl