js/xpconnect/src/nsIXPConnect.h

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