nsIXPConnect.h (9581B)
1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ 2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */ 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 #ifndef nsIXPConnect_h 8 #define nsIXPConnect_h 9 10 /* The core XPConnect public interfaces. */ 11 12 #include "nsISupports.h" 13 14 #include "jspubtd.h" 15 #include "js/CompileOptions.h" 16 #include "js/TypeDecls.h" 17 #include "xptinfo.h" 18 #include "nsCOMPtr.h" 19 20 class XPCWrappedNative; 21 class nsXPCWrappedJS; 22 class nsWrapperCache; 23 24 // forward declarations... 25 class nsIPrincipal; 26 class nsIVariant; 27 28 /***************************************************************************/ 29 #define NS_IXPCONNECTJSOBJECTHOLDER_IID_STR \ 30 "73e6ff4a-ab99-4d99-ac00-ba39ccb8e4d7" 31 #define NS_IXPCONNECTJSOBJECTHOLDER_IID \ 32 {0x73e6ff4a, 0xab99, 0x4d99, {0xac, 0x00, 0xba, 0x39, 0xcc, 0xb8, 0xe4, 0xd7}} 33 34 class NS_NO_VTABLE nsIXPConnectJSObjectHolder : public nsISupports { 35 public: 36 NS_INLINE_DECL_STATIC_IID(NS_IXPCONNECTJSOBJECTHOLDER_IID) 37 38 virtual JSObject* GetJSObject() = 0; 39 }; 40 41 #define NS_IXPCONNECTWRAPPEDNATIVE_IID_STR \ 42 "e787be29-db5d-4a45-a3d6-1de1d6b85c30" 43 #define NS_IXPCONNECTWRAPPEDNATIVE_IID \ 44 {0xe787be29, 0xdb5d, 0x4a45, {0xa3, 0xd6, 0x1d, 0xe1, 0xd6, 0xb8, 0x5c, 0x30}} 45 46 class nsIXPConnectWrappedNative : public nsIXPConnectJSObjectHolder { 47 public: 48 NS_INLINE_DECL_STATIC_IID(NS_IXPCONNECTWRAPPEDNATIVE_IID) 49 50 nsresult DebugDump(int16_t depth); 51 52 nsISupports* Native() const { return mIdentity; } 53 54 protected: 55 nsCOMPtr<nsISupports> mIdentity; 56 57 private: 58 XPCWrappedNative* AsXPCWrappedNative(); 59 }; 60 61 #define NS_IXPCONNECTWRAPPEDJS_IID_STR "3a01b0d6-074b-49ed-bac3-08c76366cae4" 62 #define NS_IXPCONNECTWRAPPEDJS_IID \ 63 {0x3a01b0d6, 0x074b, 0x49ed, {0xba, 0xc3, 0x08, 0xc7, 0x63, 0x66, 0xca, 0xe4}} 64 65 class nsIXPConnectWrappedJS : public nsIXPConnectJSObjectHolder { 66 public: 67 NS_INLINE_DECL_STATIC_IID(NS_IXPCONNECTWRAPPEDJS_IID) 68 69 nsresult GetInterfaceIID(nsIID** aInterfaceIID); 70 71 // Returns the global object for our JS object. If this object is a 72 // cross-compartment wrapper, returns the compartment's first global. 73 // The global we return is guaranteed to be same-compartment with the 74 // object. 75 // Note: this matches the GetJSObject() signature. 76 JSObject* GetJSObjectGlobal(); 77 78 nsresult DebugDump(int16_t depth); 79 80 nsresult AggregatedQueryInterface(const nsIID& aIID, void** aInstancePtr); 81 82 private: 83 nsXPCWrappedJS* AsXPCWrappedJS(); 84 }; 85 86 #define NS_IXPCONNECTWRAPPEDJSUNMARKGRAY_IID_STR \ 87 "c02a0ce6-275f-4ea1-9c23-08494898b070" 88 #define NS_IXPCONNECTWRAPPEDJSUNMARKGRAY_IID \ 89 {0xc02a0ce6, 0x275f, 0x4ea1, {0x9c, 0x23, 0x08, 0x49, 0x48, 0x98, 0xb0, 0x70}} 90 91 // Special interface to unmark the internal JSObject. 92 // QIing to nsIXPConnectWrappedJSUnmarkGray does *not* addref, it only unmarks, 93 // and QIing to nsIXPConnectWrappedJSUnmarkGray is always supposed to fail. 94 class NS_NO_VTABLE nsIXPConnectWrappedJSUnmarkGray 95 : public nsIXPConnectWrappedJS { 96 public: 97 NS_INLINE_DECL_STATIC_IID(NS_IXPCONNECTWRAPPEDJSUNMARKGRAY_IID) 98 }; 99 100 /***************************************************************************/ 101 102 #define NS_IXPCONNECT_IID_STR "768507b5-b981-40c7-8276-f6a1da502a24" 103 #define NS_IXPCONNECT_IID \ 104 {0x768507b5, 0xb981, 0x40c7, {0x82, 0x76, 0xf6, 0xa1, 0xda, 0x50, 0x2a, 0x24}} 105 106 class nsIXPConnect : public nsISupports { 107 public: 108 NS_INLINE_DECL_STATIC_IID(NS_IXPCONNECT_IID) 109 // This gets a non-addref'd pointer. 110 static nsIXPConnect* XPConnect(); 111 112 /** 113 * wrapNative will create a new JSObject or return an existing one. 114 * 115 * This method now correctly deals with cases where the passed in xpcom 116 * object already has an associated JSObject for the cases: 117 * 1) The xpcom object has already been wrapped for use in the same scope 118 * as an nsIXPConnectWrappedNative. 119 * 2) The xpcom object is in fact a nsIXPConnectWrappedJS and thus already 120 * has an underlying JSObject. 121 * 122 * It *might* be possible to QueryInterface the nsIXPConnectJSObjectHolder 123 * returned by the method into a nsIXPConnectWrappedNative or a 124 * nsIXPConnectWrappedJS. 125 * 126 * This method will never wrap the JSObject involved in an 127 * XPCNativeWrapper before returning. 128 * 129 * Returns: 130 * success: 131 * NS_OK 132 * failure: 133 * NS_ERROR_XPC_BAD_CONVERT_NATIVE 134 * NS_ERROR_FAILURE 135 */ 136 nsresult WrapNative(JSContext* aJSContext, JSObject* aScopeArg, 137 nsISupports* aCOMObj, const nsIID& aIID, 138 JSObject** aRetVal); 139 140 /** 141 * Same as wrapNative, but it returns the JSObject in aVal. C++ callers 142 * must ensure that aVal is rooted. 143 * aIID may be null, it means the same as passing in 144 * &NS_GET_IID(nsISupports) but when passing in null certain shortcuts 145 * can be taken because we know without comparing IIDs that the caller is 146 * asking for an nsISupports wrapper. 147 * If aAllowWrapper, then the returned value will be wrapped in the proper 148 * type of security wrapper on top of the XPCWrappedNative (if needed). 149 * This method doesn't push aJSContext on the context stack, so the caller 150 * is required to push it if the top of the context stack is not equal to 151 * aJSContext. 152 */ 153 nsresult WrapNativeToJSVal(JSContext* aJSContext, JSObject* aScopeArg, 154 nsISupports* aCOMObj, nsWrapperCache* aCache, 155 const nsIID* aIID, bool aAllowWrapping, 156 JS::MutableHandle<JS::Value> 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 nsresult WrapJS(JSContext* aJSContext, JSObject* aJSObj, const nsIID& aIID, 182 void** result); 183 184 /** 185 * Wraps the given jsval in a nsIVariant and returns the new variant. 186 */ 187 nsresult JSValToVariant(JSContext* cx, JS::Handle<JS::Value> aJSVal, 188 nsIVariant** aResult); 189 190 /** 191 * This only succeeds if the JSObject is a nsIXPConnectWrappedNative. 192 * A new wrapper is *never* constructed. 193 */ 194 nsresult GetWrappedNativeOfJSObject(JSContext* aJSContext, JSObject* aJSObj, 195 nsIXPConnectWrappedNative** _retval); 196 197 nsresult DebugDump(int16_t depth); 198 nsresult DebugDumpObject(nsISupports* aCOMObj, int16_t depth); 199 nsresult DebugDumpJSStack(bool showArgs, bool showLocals, bool showThisProps); 200 201 /** 202 * wrapJSAggregatedToNative is just like wrapJS except it is used in cases 203 * where the JSObject is also aggregated to some native xpcom Object. 204 * At present XBL is the only system that might want to do this. 205 * 206 * XXX write more! 207 * 208 * Returns: 209 * success: 210 * NS_OK 211 * failure: 212 * NS_ERROR_XPC_BAD_CONVERT_JS 213 * NS_ERROR_FAILURE 214 */ 215 nsresult WrapJSAggregatedToNative(nsISupports* aOuter, JSContext* aJSContext, 216 JSObject* aJSObj, const nsIID& aIID, 217 void** result); 218 219 // Methods added since mozilla 0.6.... 220 221 nsresult VariantToJS(JSContext* ctx, JSObject* scope, nsIVariant* value, 222 JS::MutableHandle<JS::Value> _retval); 223 nsresult JSToVariant(JSContext* ctx, JS::Handle<JS::Value> value, 224 nsIVariant** _retval); 225 226 /** 227 * Create a sandbox for evaluating code in isolation using 228 * evalInSandboxObject(). 229 * 230 * @param cx A context to use when creating the sandbox object. 231 * @param principal The principal (or NULL to use the null principal) 232 * to use when evaluating code in this sandbox. 233 */ 234 nsresult CreateSandbox(JSContext* cx, nsIPrincipal* principal, 235 JSObject** _retval); 236 237 /** 238 * Evaluate script in a sandbox, completely isolated from all 239 * other running scripts. 240 * 241 * @param source The source of the script to evaluate. 242 * @param filename The filename of the script. May be null. 243 * @param cx The context to use when setting up the evaluation of 244 * the script. The actual evaluation will happen on a new 245 * temporary context. 246 * @param sandbox The sandbox object to evaluate the script in. 247 * @return The result of the evaluation as a jsval. If the caller 248 * intends to use the return value from this call the caller 249 * is responsible for rooting the jsval before making a call 250 * to this method. 251 */ 252 nsresult EvalInSandboxObject(const nsAString& source, const char* filename, 253 JSContext* cx, JSObject* sandboxArg, 254 JS::MutableHandle<JS::Value> rval); 255 }; 256 257 #endif // defined nsIXPConnect_h