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