1/* -*- Mode: IDL; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*- 2 * 3 * This Source Code Form is subject to the terms of the Mozilla Public 4 * License, v. 2.0. If a copy of the MPL was not distributed with this 5 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ 6 7/* The core XPConnect public interfaces. */ 8 9#include "nsISupports.idl" 10 11%{ C++ 12#include "jspubtd.h" 13#include "js/TypeDecls.h" 14#include "mozilla/Attributes.h" 15#include "xptinfo.h" 16#include "nsCOMPtr.h" 17 18class nsWrapperCache; 19%} 20 21/***************************************************************************/ 22 23// NB: jsval and jsid are declared in nsrootidl.idl 24 25[ptr] native JSContextPtr(JSContext); 26[ptr] native JSObjectPtr(JSObject); 27[ptr] native JSScriptPtr(JSScript); 28[ptr] native nsWrapperCachePtr(nsWrapperCache); 29 native JSHandleId(JS::Handle<jsid>); 30 31/***************************************************************************/ 32 33// forward declarations... 34interface nsIPrincipal; 35interface nsIClassInfo; 36interface nsIVariant; 37interface nsIObjectInputStream; 38interface nsIObjectOutputStream; 39 40/***************************************************************************/ 41[builtinclass, uuid(73e6ff4a-ab99-4d99-ac00-ba39ccb8e4d7)] 42interface nsIXPConnectJSObjectHolder : nsISupports 43{ 44 [notxpcom, nostdcall] JSObjectPtr GetJSObject(); 45}; 46 47[builtinclass, uuid(e787be29-db5d-4a45-a3d6-1de1d6b85c30)] 48interface nsIXPConnectWrappedNative : nsIXPConnectJSObjectHolder 49{ 50 /* attribute 'JSObject' inherited from nsIXPConnectJSObjectHolder */ 51 52 void debugDump(in short depth); 53 54%{C++ 55 /** 56 * Faster access to the native object from C++. Will never return null. 57 */ 58 nsISupports* Native() const { return mIdentity; } 59 60protected: 61 nsCOMPtr<nsISupports> mIdentity; 62public: 63%} 64}; 65 66[builtinclass, uuid(3a01b0d6-074b-49ed-bac3-08c76366cae4)] 67interface nsIXPConnectWrappedJS : nsIXPConnectJSObjectHolder 68{ 69 /* attribute 'JSObject' inherited from nsIXPConnectJSObjectHolder */ 70 readonly attribute nsIIDPtr InterfaceIID; 71 72 // Returns the global object for our JS object. If this object is a 73 // cross-compartment wrapper, returns the compartment's first global. 74 // The global we return is guaranteed to be same-compartment with the 75 // object. 76 // Note: this matches the GetJSObject() signature. 77 [notxpcom, nostdcall] JSObjectPtr GetJSObjectGlobal(); 78 79 void debugDump(in short depth); 80 81 void aggregatedQueryInterface(in nsIIDRef uuid, 82 [iid_is(uuid),retval] out nsQIResult result); 83 84}; 85 86// Special interface to unmark the internal JSObject. 87// QIing to nsIXPConnectWrappedJSUnmarkGray does *not* addref, it only unmarks, 88// and QIing to nsIXPConnectWrappedJSUnmarkGray is always supposed to fail. 89[builtinclass, uuid(c02a0ce6-275f-4ea1-9c23-08494898b070)] 90interface nsIXPConnectWrappedJSUnmarkGray : nsIXPConnectWrappedJS 91{ 92}; 93 94/***************************************************************************/ 95 96 97[noscript, builtinclass, uuid(768507b5-b981-40c7-8276-f6a1da502a24)] 98interface nsIXPConnect : nsISupports 99{ 100%{ C++ 101 // This gets a non-addref'd pointer. 102 static nsIXPConnect* XPConnect(); 103%} 104 105 /** 106 * wrapNative will create a new JSObject or return an existing one. 107 * 108 * This method now correctly deals with cases where the passed in xpcom 109 * object already has an associated JSObject for the cases: 110 * 1) The xpcom object has already been wrapped for use in the same scope 111 * as an nsIXPConnectWrappedNative. 112 * 2) The xpcom object is in fact a nsIXPConnectWrappedJS and thus already 113 * has an underlying JSObject. 114 * 115 * It *might* be possible to QueryInterface the nsIXPConnectJSObjectHolder 116 * returned by the method into a nsIXPConnectWrappedNative or a 117 * nsIXPConnectWrappedJS. 118 * 119 * This method will never wrap the JSObject involved in an 120 * XPCNativeWrapper before returning. 121 * 122 * Returns: 123 * success: 124 * NS_OK 125 * failure: 126 * NS_ERROR_XPC_BAD_CONVERT_NATIVE 127 * NS_ERROR_XPC_CANT_GET_JSOBJECT_OF_DOM_OBJECT 128 * NS_ERROR_FAILURE 129 */ 130 JSObjectPtr 131 wrapNative(in JSContextPtr aJSContext, 132 in JSObjectPtr aScope, 133 in nsISupports aCOMObj, 134 in nsIIDRef aIID); 135 136 /** 137 * Same as wrapNative, but it returns the JSObject in aVal. C++ callers 138 * must ensure that aVal is rooted. 139 * aIID may be null, it means the same as passing in 140 * &NS_GET_IID(nsISupports) but when passing in null certain shortcuts 141 * can be taken because we know without comparing IIDs that the caller is 142 * asking for an nsISupports wrapper. 143 * If aAllowWrapper, then the returned value will be wrapped in the proper 144 * type of security wrapper on top of the XPCWrappedNative (if needed). 145 * This method doesn't push aJSContext on the context stack, so the caller 146 * is required to push it if the top of the context stack is not equal to 147 * aJSContext. 148 */ 149 void 150 wrapNativeToJSVal(in JSContextPtr aJSContext, 151 in JSObjectPtr aScope, 152 in nsISupports aCOMObj, 153 in nsWrapperCachePtr aCache, 154 in nsIIDPtr aIID, 155 in boolean aAllowWrapper, 156 out jsval aVal); 157 158 /** 159 * wrapJS will yield a new or previously existing xpcom interface pointer 160 * to represent the JSObject passed in. 161 * 162 * This method now correctly deals with cases where the passed in JSObject 163 * already has an associated xpcom interface for the cases: 164 * 1) The JSObject has already been wrapped as a nsIXPConnectWrappedJS. 165 * 2) The JSObject is in fact a nsIXPConnectWrappedNative and thus already 166 * has an underlying xpcom object. 167 * 3) The JSObject is of a jsclass which supports getting the nsISupports 168 * from the JSObject directly. This is used for idlc style objects 169 * (e.g. DOM objects). 170 * 171 * It *might* be possible to QueryInterface the resulting interface pointer 172 * to nsIXPConnectWrappedJS. 173 * 174 * Returns: 175 * success: 176 * NS_OK 177 * failure: 178 * NS_ERROR_XPC_BAD_CONVERT_JS 179 * NS_ERROR_FAILURE 180 */ 181 void 182 wrapJS(in JSContextPtr aJSContext, 183 in JSObjectPtr aJSObj, 184 in nsIIDRef aIID, 185 [iid_is(aIID),retval] out nsQIResult result); 186 187 /** 188 * Wraps the given jsval in a nsIVariant and returns the new variant. 189 */ 190 nsIVariant 191 jSValToVariant(in JSContextPtr cx, in jsval aJSVal); 192 193 /** 194 * This only succeeds if the JSObject is a nsIXPConnectWrappedNative. 195 * A new wrapper is *never* constructed. 196 */ 197 nsIXPConnectWrappedNative 198 getWrappedNativeOfJSObject(in JSContextPtr aJSContext, 199 in JSObjectPtr aJSObj); 200 201 void debugDump(in short depth); 202 void debugDumpObject(in nsISupports aCOMObj, in short depth); 203 void debugDumpJSStack(in boolean showArgs, 204 in boolean showLocals, 205 in boolean showThisProps); 206 207 /** 208 * wrapJSAggregatedToNative is just like wrapJS except it is used in cases 209 * where the JSObject is also aggregated to some native xpcom Object. 210 * At present XBL is the only system that might want to do this. 211 * 212 * XXX write more! 213 * 214 * Returns: 215 * success: 216 * NS_OK 217 * failure: 218 * NS_ERROR_XPC_BAD_CONVERT_JS 219 * NS_ERROR_FAILURE 220 */ 221 void 222 wrapJSAggregatedToNative(in nsISupports aOuter, 223 in JSContextPtr aJSContext, 224 in JSObjectPtr aJSObj, 225 in nsIIDRef aIID, 226 [iid_is(aIID),retval] out nsQIResult result); 227 228 // Methods added since mozilla 0.6.... 229 230 jsval variantToJS(in JSContextPtr ctx, in JSObjectPtr scope, in nsIVariant value); 231 nsIVariant JSToVariant(in JSContextPtr ctx, in jsval value); 232 233 /** 234 * Create a sandbox for evaluating code in isolation using 235 * evalInSandboxObject(). 236 * 237 * @param cx A context to use when creating the sandbox object. 238 * @param principal The principal (or NULL to use the null principal) 239 * to use when evaluating code in this sandbox. 240 */ 241 [noscript] JSObjectPtr createSandbox(in JSContextPtr cx, in nsIPrincipal principal); 242 243 /** 244 * Evaluate script in a sandbox, completely isolated from all 245 * other running scripts. 246 * 247 * @param source The source of the script to evaluate. 248 * @param filename The filename of the script. May be null. 249 * @param cx The context to use when setting up the evaluation of 250 * the script. The actual evaluation will happen on a new 251 * temporary context. 252 * @param sandbox The sandbox object to evaluate the script in. 253 * @return The result of the evaluation as a jsval. If the caller 254 * intends to use the return value from this call the caller 255 * is responsible for rooting the jsval before making a call 256 * to this method. 257 */ 258 [noscript] jsval evalInSandboxObject(in AString source, in string filename, 259 in JSContextPtr cx, 260 in JSObjectPtr sandbox); 261 262 [noscript] void writeScript(in nsIObjectOutputStream aStream, 263 in JSContextPtr aJSContext, 264 in JSScriptPtr aJSScript); 265 266 [noscript] JSScriptPtr readScript(in nsIObjectInputStream aStream, 267 in JSContextPtr aJSContext); 268 269 [infallible] readonly attribute boolean isShuttingDown; 270}; 271