The Tor Browser / file comparison

comparison: js/xpconnect/idl/xpccomponents.idl

js/xpconnect/idl/xpccomponents.idl

branch
TOR_BUG_3246
changeset 7
129ffea94266
equal deleted inserted replaced
-1:000000000000 0:4a2c3e48cb56
1 /* -*- Mode: IDL; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 /* This Source Code Form is subject to the terms of the Mozilla Public
3 * License, v. 2.0. If a copy of the MPL was not distributed with this
4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
5
6 #include "nsISupports.idl"
7
8 %{C++
9 #include "jspubtd.h"
10 %}
11
12 interface xpcIJSWeakReference;
13 interface nsIClassInfo;
14 interface nsIComponentManager;
15 interface nsIJSCID;
16 interface nsIJSIID;
17 interface nsIPrincipal;
18 interface nsIStackFrame;
19
20 /**
21 * interface of Components.interfacesByID
22 * (interesting stuff only reflected into JavaScript)
23 */
24 [scriptable, uuid(c99cffac-5aed-4267-ad2f-f4a4c9d4a081)]
25 interface nsIXPCComponents_InterfacesByID : nsISupports
26 {
27 };
28
29 /**
30 * interface of Components.interfaces
31 * (interesting stuff only reflected into JavaScript)
32 */
33 [scriptable, uuid(b8c31bba-79db-4a1d-930d-4cdd68713f9e)]
34 interface nsIXPCComponents_Interfaces : nsISupports
35 {
36 };
37
38 /**
39 * interface of Components.classes
40 * (interesting stuff only reflected into JavaScript)
41 */
42 [scriptable, uuid(978ff520-d26c-11d2-9842-006008962422)]
43 interface nsIXPCComponents_Classes : nsISupports
44 {
45 };
46
47 /**
48 * interface of Components.classesByID
49 * (interesting stuff only reflected into JavaScript)
50 */
51 [scriptable, uuid(336a9590-4d19-11d3-9893-006008962422)]
52 interface nsIXPCComponents_ClassesByID : nsISupports
53 {
54 };
55
56 /**
57 * interface of Components.results
58 * (interesting stuff only reflected into JavaScript)
59 */
60 [scriptable, uuid(2fc229a0-5860-11d3-9899-006008962422)]
61 interface nsIXPCComponents_Results : nsISupports
62 {
63 };
64
65 /**
66 * interface of Components.ID
67 * (interesting stuff only reflected into JavaScript)
68 */
69 [scriptable, uuid(7994a6e0-e028-11d3-8f5d-0010a4e73d9a)]
70 interface nsIXPCComponents_ID : nsISupports
71 {
72 };
73
74 /**
75 * interface of Components.Exception
76 * (interesting stuff only reflected into JavaScript)
77 */
78 [scriptable, uuid(5bf039c0-e028-11d3-8f5d-0010a4e73d9a)]
79 interface nsIXPCComponents_Exception : nsISupports
80 {
81 };
82
83 /**
84 * interface of Components.Constructor
85 * (interesting stuff only reflected into JavaScript)
86 */
87 [scriptable, uuid(88655640-e028-11d3-8f5d-0010a4e73d9a)]
88 interface nsIXPCComponents_Constructor : nsISupports
89 {
90 };
91
92 /**
93 * interface of object returned by Components.Constructor
94 * (additional interesting stuff only reflected into JavaScript)
95 */
96 [scriptable, uuid(c814ca20-e0dc-11d3-8f5f-0010a4e73d9a)]
97 interface nsIXPCConstructor : nsISupports
98 {
99 readonly attribute nsIJSCID classID;
100 readonly attribute nsIJSIID interfaceID;
101 readonly attribute string initializer;
102 };
103
104 /**
105 * interface of object returned by Components.utils.Sandbox.
106 */
107 [scriptable, uuid(4f8ae0dc-d266-4a32-875b-6a9de71a8ce9)]
108 interface nsIXPCComponents_utils_Sandbox : nsISupports
109 {
110 };
111
112 /**
113 * interface for callback to be passed to Cu.schedulePreciseGC
114 */
115 [scriptable, function, uuid(71000535-b0fd-44d1-8ce0-909760e3953c)]
116 interface ScheduledGCCallback : nsISupports
117 {
118 void callback();
119 };
120
121 /**
122 * interface of Components.utils
123 */
124 [scriptable, uuid(45b80e00-fb0d-439e-b7bf-54f24af0c4a6)]
125 interface nsIXPCComponents_Utils : nsISupports
126 {
127
128 /* reportError is designed to be called from JavaScript only.
129 *
130 * It will report a JS Error object to the JS console, and return. It
131 * is meant for use in exception handler blocks which want to "eat"
132 * an exception, but still want to report it to the console.
133 *
134 * It must be called with one param, usually an object which was caught by
135 * an exception handler. If it is not a JS error object, the parameter
136 * is converted to a string and reported as a new error.
137 */
138 [implicit_jscontext] void reportError(in jsval error);
139
140 readonly attribute nsIXPCComponents_utils_Sandbox Sandbox;
141
142 /*
143 * evalInSandbox is designed to be called from JavaScript only.
144 *
145 * evalInSandbox evaluates the provided source string in the given sandbox.
146 * It returns the result of the evaluation to the caller.
147 *
148 * var s = new C.u.Sandbox("http://www.mozilla.org");
149 * var res = C.u.evalInSandbox("var five = 5; 2 + five", s);
150 * var outerFive = s.five;
151 * s.seven = res;
152 * var thirtyFive = C.u.evalInSandbox("five * seven", s);
153 */
154 [implicit_jscontext,optional_argc]
155 jsval evalInSandbox(in AString source, in jsval sandbox,
156 [optional] in jsval version,
157 [optional] in AUTF8String filename,
158 [optional] in long lineNo);
159
160 /*
161 * getSandboxMetadata is designed to be called from JavaScript only.
162 *
163 * getSandboxMetadata retrieves the metadata associated with
164 * a sandbox object. It will return undefined if there
165 * is no metadata attached to the sandbox.
166 *
167 * var s = C.u.Sandbox(..., { metadata: "metadata" });
168 * var metadata = C.u.getSandboxMetadata(s);
169 */
170 [implicit_jscontext]
171 jsval getSandboxMetadata(in jsval sandbox);
172
173 /*
174 * setSandboxMetadata is designed to be called from JavaScript only.
175 *
176 * setSandboxMetadata sets the metadata associated with
177 * a sandbox object.
178 *
179 * Note that the metadata object will be copied before being used.
180 * The copy will be performed using the structured clone algorithm.
181 * Note that this algorithm does not support reflectors and
182 * it will throw if it encounters them.
183 */
184 [implicit_jscontext]
185 void setSandboxMetadata(in jsval sandbox, in jsval metadata);
186
187 /*
188 * import is designed to be called from JavaScript only.
189 *
190 * Synchronously loads and evaluates the js file located at
191 * 'registryLocation' with a new, fully privileged global object.
192 *
193 * If 'targetObj' is specified and equal to null, returns the
194 * module's global object. Otherwise (if 'targetObj' is not
195 * specified, or 'targetObj' is != null) looks for a property
196 * 'EXPORTED_SYMBOLS' on the new global object. 'EXPORTED_SYMBOLS'
197 * is expected to be an array of strings identifying properties on
198 * the global object. These properties will be installed as
199 * properties on 'targetObj', or, if 'targetObj' is not specified,
200 * on the caller's global object. If 'EXPORTED_SYMBOLS' is not
201 * found, an error is thrown.
202 *
203 * @param resourceURI A resource:// URI string to load the module from.
204 * @param targetObj the object to install the exported properties on.
205 * If this parameter is a primitive value, this method throws
206 * an exception.
207 * @returns the module code's global object.
208 *
209 * The implementation maintains a hash of registryLocation->global obj.
210 * Subsequent invocations of importModule with 'registryLocation'
211 * pointing to the same file will not cause the module to be re-evaluated,
212 * but the symbols in EXPORTED_SYMBOLS will be exported into the
213 * specified target object and the global object returned as above.
214 *
215 * (This comment is duplicated from xpcIJSModuleLoader.)
216 */
217 [implicit_jscontext,optional_argc]
218 jsval import(in AUTF8String aResourceURI, [optional] in jsval targetObj);
219
220 /*
221 * Unloads the JS module at 'registryLocation'. Existing references to the
222 * module will continue to work but any subsequent import of the module will
223 * reload it and give new reference. If the JS module hasn't yet been
224 * imported then this method will do nothing.
225 *
226 * @param resourceURI A resource:// URI string to unload the module from.
227 */
228 void unload(in AUTF8String registryLocation);
229
230 /*
231 * Imports global properties (like DOM constructors) into the scope, defining
232 * them on the caller's global. aPropertyList should be an array of property
233 * names.
234 *
235 * See xpc::GlobalProperties::Parse for the current list of supported
236 * properties.
237 */
238 [implicit_jscontext]
239 void importGlobalProperties(in jsval aPropertyList);
240
241 /*
242 * To be called from JS only.
243 *
244 * Return a weak reference for the given JS object.
245 */
246 [implicit_jscontext]
247 xpcIJSWeakReference getWeakReference(in jsval obj);
248
249 /*
250 * To be called from JS only.
251 *
252 * Force an immediate garbage collection cycle.
253 */
254 void forceGC();
255
256 /*
257 * To be called from JS only.
258 *
259 * Force an immediate cycle collection cycle.
260 */
261 void forceCC();
262
263 /*
264 * To be called from JS only.
265 *
266 * Force an immediate shrinking garbage collection cycle.
267 */
268 void forceShrinkingGC();
269
270 /*
271 * Schedule a garbage collection cycle for a point in the future when no JS
272 * is running. Call the provided function once this has occurred.
273 */
274 void schedulePreciseGC(in ScheduledGCCallback callback);
275
276 /*
277 * Schedule a shrinking garbage collection cycle for a point in the future
278 * when no JS is running. Call the provided function once this has occured.
279 */
280 void schedulePreciseShrinkingGC(in ScheduledGCCallback callback);
281
282 /*
283 * In a debug build, unlink any ghost windows. This is only for debugging
284 * leaks, and can cause bad things to happen if called.
285 */
286 void unlinkGhostWindows();
287
288 /**
289 * Return the keys in a weak map. This operation is
290 * non-deterministic because it is affected by the scheduling of the
291 * garbage collector and the cycle collector.
292 *
293 * This should only be used to write tests of the interaction of
294 * the GC and CC with weak maps.
295 *
296 * @param aMap weak map or other JavaScript value
297 * @returns If aMap is a weak map object, return the keys of the weak
298 map as an array. Otherwise, return undefined.
299 */
300 [implicit_jscontext]
301 jsval nondeterministicGetWeakMapKeys(in jsval aMap);
302
303 [implicit_jscontext]
304 jsval getJSTestingFunctions();
305
306 /*
307 * To be called from JS only.
308 *
309 * Returns the global object with which the given object is associated.
310 *
311 * @param obj The JavaScript object whose global is to be gotten.
312 * @return the corresponding global.
313 */
314 [implicit_jscontext]
315 jsval getGlobalForObject(in jsval obj);
316
317 /*
318 * To be called from JS only.
319 *
320 * Returns the true if the object is a (scripted) proxy.
321 * NOTE: Security wrappers are unwrapped first before the check.
322 */
323 [implicit_jscontext]
324 boolean isProxy(in jsval vobject);
325
326 /*
327 * Similar to evalInSandbox except this one is used to eval a script in the
328 * scope of a window. Also note, that the return value and the possible exceptions
329 * in the script are structured cloned, unless they are natives (then they are just
330 * wrapped).
331 * Principal of the caller must subsume the target's.
332 */
333 [implicit_jscontext]
334 jsval evalInWindow(in AString source, in jsval window);
335
336 /*
337 * To be called from JS only.
338 *
339 * Instead of simply wrapping a function into another compartment,
340 * this helper function creates a native function in the target
341 * compartment and forwards the call to the original function.
342 * That call will be different than a regular JS function call in
343 * that, the |this| is left unbound, and all the non-native JS
344 * object arguments will be cloned using the structured clone
345 * algorithm.
346 * The return value is the new forwarder function, wrapped into
347 * the caller's compartment.
348 * The 3rd argument is an optional options object:
349 * - defineAs: the name of the property that will
350 * be set on the target scope, with
351 * the forwarder function as the value.
352 */
353 [implicit_jscontext]
354 jsval exportFunction(in jsval vfunction, in jsval vscope, [optional] in jsval voptions);
355
356 /*
357 * To be called from JS only.
358 *
359 * Returns an object created in |vobj|'s compartment.
360 * If defineAs property on the options object is a non-null ID,
361 * the new object will be added to vobj as a property. Also, the
362 * returned new object is always automatically waived (see waiveXrays).
363 */
364 [implicit_jscontext]
365 jsval createObjectIn(in jsval vobj, [optional] in jsval voptions);
366
367 /*
368 * To be called from JS only.
369 *
370 * Ensures that all functions come from vobj's scope (and aren't cross
371 * compartment wrappers).
372 */
373 [implicit_jscontext]
374 void makeObjectPropsNormal(in jsval vobj);
375
376 /**
377 * Determines whether this object is backed by a DeadObjectProxy.
378 *
379 * Dead-wrapper objects hold no other objects alive (they have no outgoing
380 * reference edges) and will throw if you touch them (e.g. by
381 * reading/writing a property).
382 */
383 bool isDeadWrapper(in jsval obj);
384
385 /*
386 * To be called from JS only. This is for Gecko internal use only, and may
387 * disappear at any moment.
388 *
389 * Forces a recomputation of all wrappers in and out of the compartment
390 * containing |vobj|. If |vobj| is not an object, all wrappers system-wide
391 * are recomputed.
392 */
393 [implicit_jscontext]
394 void recomputeWrappers([optional] in jsval vobj);
395
396 /*
397 * To be called from JS only. This is for Gecko internal use only, and may
398 * disappear at any moment.
399 *
400 * Enables Xray vision for same-compartment access for the compartment
401 * indicated by |vscope|. All outgoing wrappers are recomputed.
402 */
403 [implicit_jscontext]
404 void setWantXrays(in jsval vscope);
405
406 /*
407 * Forces the usage of a privileged |Components| object for a potentially-
408 * unprivileged scope. This will crash if used outside of automation.
409 */
410 [implicit_jscontext]
411 void forcePrivilegedComponentsForScope(in jsval vscope);
412
413 /*
414 * This seemingly-paradoxical API allows privileged code to explicitly give
415 * unprivileged code a reference to its own Components object (whereas it's
416 * normally hidden away on a scope chain visible only to XBL methods). See
417 * also SpecialPowers.getComponents.
418 */
419 [implicit_jscontext]
420 jsval getComponentsForScope(in jsval vscope);
421
422 /*
423 * Dispatches a runnable to the current/main thread. If |scope| is passed,
424 * the runnable will be dispatch in the compartment of |scope|, which
425 * affects which error reporter gets called.
426 */
427 [implicit_jscontext]
428 void dispatch(in jsval runnable, [optional] in jsval scope);
429
430 /*
431 * To be called from JS only.
432 *
433 * These are the set of JSContext options that privileged script
434 * is allowed to control for the purposes of testing. These
435 * options should be kept in sync with what's controllable in the
436 * jsshell and by setting prefs in nsJSEnvironment.
437 *
438 * NB: Assume that getting any of these attributes is relatively
439 * cheap, but setting any of them is relatively expensive.
440 */
441 [implicit_jscontext]
442 attribute boolean strict;
443
444 [implicit_jscontext]
445 attribute boolean werror;
446
447 [implicit_jscontext]
448 attribute boolean strict_mode;
449
450 [implicit_jscontext]
451 attribute boolean ion;
452
453 [implicit_jscontext]
454 void setGCZeal(in long zeal);
455
456 [implicit_jscontext]
457 void nukeSandbox(in jsval obj);
458
459 /*
460 * API to dynamically block script for a given global. This takes effect
461 * immediately, unlike other APIs that only affect newly-created globals.
462 *
463 * The machinery here maintains a counter, and allows script only if each
464 * call to blockScriptForGlobal() has been matched with a call to
465 * unblockScriptForGlobal(). The caller _must_ make sure never to call
466 * unblock() more times than it calls block(), since that could potentially
467 * interfere with another consumer's script blocking.
468 */
469
470 [implicit_jscontext]
471 void blockScriptForGlobal(in jsval global);
472
473 [implicit_jscontext]
474 void unblockScriptForGlobal(in jsval global);
475
476 /**
477 * Check whether the given object is an XrayWrapper.
478 */
479 bool isXrayWrapper(in jsval obj);
480
481 /**
482 * Waive Xray on a given value. Identity op for primitives.
483 */
484 [implicit_jscontext]
485 jsval waiveXrays(in jsval aVal);
486
487 /**
488 * Strip off Xray waivers on a given value. Identity op for primitives.
489 */
490 [implicit_jscontext]
491 jsval unwaiveXrays(in jsval aVal);
492
493 /**
494 * Gets the name of the JSClass of the object.
495 *
496 * if |aUnwrap| is true, all wrappers are unwrapped first. Unless you're
497 * specifically trying to detect whether the object is a proxy, this is
498 * probably what you want.
499 */
500 [implicit_jscontext]
501 string getClassName(in jsval aObj, in bool aUnwrap);
502
503 /**
504 * Get a DOM classinfo for the given classname. Only some class
505 * names are supported.
506 */
507 nsIClassInfo getDOMClassInfo(in AString aClassName);
508
509 /**
510 * Gets the incument global for the execution of this function. For internal
511 * and testing use only.
512 *
513 * If |callback| is passed, it is invoked with the incumbent global as its
514 * sole argument. This allows the incumbent global to be measured in callback
515 * environments with no scripted frames on the stack.
516 */
517 [implicit_jscontext]
518 jsval getIncumbentGlobal([optional] in jsval callback);
519
520 /**
521 * Forces the generation of an XPCWrappedJS for a given object. For internal
522 * and testing use only. This is only useful to set up wrapper map conditions
523 * for a testcase. The return value is not an XPCWrappedJS itself, but an
524 * opaque nsISupports holder that keeps the underlying XPCWrappedJS alive.
525 *
526 * if |scope| is passed, the XPCWrappedJS is generated in the scope of that object.
527 */
528 [implicit_jscontext]
529 nsISupports generateXPCWrappedJS(in jsval obj, [optional] in jsval scope);
530
531 /**
532 * Retrieve the last time, in microseconds since epoch, that a given
533 * watchdog-related event occured.
534 *
535 * Valid categories:
536 * "RuntimeStateChange" - Runtime switching between active and inactive states
537 * "WatchdogWakeup" - Watchdog waking up from sleeping
538 * "WatchdogHibernateStart" - Watchdog begins hibernating
539 * "WatchdogHibernateStop" - Watchdog stops hibernating
540 */
541 PRTime getWatchdogTimestamp(in AString aCategory);
542
543 [implicit_jscontext]
544 jsval getJSEngineTelemetryValue();
545
546 /*
547 * Clone an object into a scope.
548 * The 3rd argument is an optional options object:
549 * - cloneFunction: boolean. If true, any function in the value is are
550 * wrapped in a function forwarder that appears to be a native function in
551 * the content scope.
552 */
553 [implicit_jscontext]
554 jsval cloneInto(in jsval value, in jsval scope, [optional] in jsval options);
555
556 /*
557 * When C++-Implemented code does security checks, it can generally query
558 * the subject principal (i.e. the principal of the most-recently-executed
559 * script) in order to determine the responsible party. However, when an API
560 * is implemented in JS, this doesn't work - the most-recently-executed
561 * script is always the System-Principaled API implementation. So we need
562 * another mechanism.
563 *
564 * Hence the notion of the "WebIDL Caller". If the current Entry Script on
565 * the Script Settings Stack represents the invocation of JS-implemented
566 * WebIDL, this API returns the principal of the caller at the time
567 * of invocation. Otherwise (i.e. outside of JS-implemented WebIDL), this
568 * function throws. If it throws, you probably shouldn't be using it.
569 */
570 nsIPrincipal getWebIDLCallerPrincipal();
571
572 /*
573 * Gets the principal of a script object, after unwrapping any cross-
574 * compartment wrappers.
575 */
576 [implicit_jscontext]
577 nsIPrincipal getObjectPrincipal(in jsval obj);
578 };
579
580 /**
581 * Interface for the 'Components' object.
582 *
583 * The first interface contains things that are available to non-chrome XBL code
584 * that runs in a scope with an nsExpandedPrincipal. The second interface
585 * includes members that are only exposed to chrome.
586 */
587
588 [scriptable, uuid(eeeada2f-86c0-4609-b2bf-4bf2351b1ce6)]
589 interface nsIXPCComponentsBase : nsISupports
590 {
591 readonly attribute nsIXPCComponents_Interfaces interfaces;
592 readonly attribute nsIXPCComponents_InterfacesByID interfacesByID;
593 readonly attribute nsIXPCComponents_Results results;
594
595 boolean isSuccessCode(in nsresult result);
596
597 };
598
599 [scriptable, uuid(aa28aaf6-70ce-4b03-9514-afe43c7dfda8)]
600 interface nsIXPCComponents : nsIXPCComponentsBase
601 {
602 readonly attribute nsIXPCComponents_Classes classes;
603 readonly attribute nsIXPCComponents_ClassesByID classesByID;
604 readonly attribute nsIStackFrame stack;
605 readonly attribute nsIComponentManager manager;
606 readonly attribute nsIXPCComponents_Utils utils;
607
608 readonly attribute nsIXPCComponents_ID ID;
609 readonly attribute nsIXPCComponents_Exception Exception;
610 readonly attribute nsIXPCComponents_Constructor Constructor;
611
612 [implicit_jscontext]
613 readonly attribute jsval lastResult;
614 [implicit_jscontext]
615 attribute jsval returnCode;
616
617 /* @deprecated Use Components.utils.reportError instead. */
618 [deprecated, implicit_jscontext] void reportError(in jsval error);
619 };

Mercurial Repository: The Tor Browser

Europalab SCM Repository Server

mercurial