/* -*- Mode: IDL; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"
#include "xpcexception.idl"
#include "xpcjsid.idl"
#include "nsIComponentManager.idl"

%{C++
#include "jspubtd.h"
%}

interface xpcIJSWeakReference;

/**
* interface of Components.interfacesByID
* (interesting stuff only reflected into JavaScript)
*/
[scriptable, uuid(c99cffac-5aed-4267-ad2f-f4a4c9d4a081)]
interface nsIXPCComponents_InterfacesByID : nsISupports
{
};

/**
* interface of Components.interfaces
* (interesting stuff only reflected into JavaScript)
*/
[scriptable, uuid(b8c31bba-79db-4a1d-930d-4cdd68713f9e)]
interface nsIXPCComponents_Interfaces : nsISupports
{
};

/**
* interface of Components.classes
* (interesting stuff only reflected into JavaScript)
*/
[scriptable, uuid(978ff520-d26c-11d2-9842-006008962422)]
interface nsIXPCComponents_Classes : nsISupports
{
};

/**
* interface of Components.classesByID
* (interesting stuff only reflected into JavaScript)
*/
[scriptable, uuid(336a9590-4d19-11d3-9893-006008962422)]
interface nsIXPCComponents_ClassesByID : nsISupports
{
};

/**
* interface of Components.results
* (interesting stuff only reflected into JavaScript)
*/
[scriptable, uuid(2fc229a0-5860-11d3-9899-006008962422)]
interface nsIXPCComponents_Results : nsISupports
{
};

/**
* interface of Components.ID
* (interesting stuff only reflected into JavaScript)
*/
[scriptable, uuid(7994a6e0-e028-11d3-8f5d-0010a4e73d9a)]
interface nsIXPCComponents_ID : nsISupports
{
};

/**
* interface of Components.Exception
* (interesting stuff only reflected into JavaScript)
*/
[scriptable, uuid(5bf039c0-e028-11d3-8f5d-0010a4e73d9a)]
interface nsIXPCComponents_Exception : nsISupports
{
};

/**
* interface of Components.Constructor
* (interesting stuff only reflected into JavaScript)
*/
[scriptable, uuid(88655640-e028-11d3-8f5d-0010a4e73d9a)]
interface nsIXPCComponents_Constructor : nsISupports
{
};

/**
* interface of object returned by Components.Constructor
* (additional interesting stuff only reflected into JavaScript)
*/
[scriptable, uuid(c814ca20-e0dc-11d3-8f5f-0010a4e73d9a)]
interface nsIXPCConstructor : nsISupports
{
    readonly attribute nsIJSCID classID;
    readonly attribute nsIJSIID interfaceID;
    readonly attribute string   initializer;
};

/**
* interface of object returned by Components.utils.Sandbox.
*/
[scriptable, uuid(4f8ae0dc-d266-4a32-875b-6a9de71a8ce9)]
interface nsIXPCComponents_utils_Sandbox : nsISupports
{
};

/**
 * interface for callback to be passed to Cu.schedulePreciseGC
 */
[scriptable, function, uuid(71000535-b0fd-44d1-8ce0-909760e3953c)]
interface ScheduledGCCallback : nsISupports
{
    void callback();
};

/**
* interface of Components.utils
*/
[scriptable, uuid(25442383-a1f5-440c-9e18-a2a1cdb8a638)]
interface nsIXPCComponents_Utils : nsISupports
{

    /* reportError is designed to be called from JavaScript only.
     *
     * It will report a JS Error object to the JS console, and return. It
     * is meant for use in exception handler blocks which want to "eat"
     * an exception, but still want to report it to the console.
     *
     * It must be called with one param, usually an object which was caught by
     * an exception handler.  If it is not a JS error object, the parameter
     * is converted to a string and reported as a new error.
     */
    [implicit_jscontext] void reportError(in jsval error);

    /* lookupMethod is designed to be called from JavaScript only.
     *
     * It returns a method looking only at the idl interfaces and
     * ignores any overrides or resolvers that might be in place for
     * a given scriptable wrapped native.
     * It must be called with two params: an object and a method name.
     * It returns a function object or throws an exception on error.
     * This method exists only to solve mozilla browser problems
     * when chrome attempts to lookup and call methods in content
     * and *must* not get confused by method properties that have been
     * replaced in the content JS code. This method is not recommended for
     * any other use.
     */
    [implicit_jscontext]
    jsval lookupMethod(in jsval obj, in jsval name);

    readonly attribute nsIXPCComponents_utils_Sandbox Sandbox;

    /*
     * evalInSandbox is designed to be called from JavaScript only.
     *
     * evalInSandbox evaluates the provided source string in the given sandbox.
     * It returns the result of the evaluation to the caller.
     *
     * var s = new C.u.Sandbox("http://www.mozilla.org");
     * var res = C.u.evalInSandbox("var five = 5; 2 + five", s);
     * var outerFive = s.five;
     * s.seven = res;
     * var thirtyFive = C.u.evalInSandbox("five * seven", s);
     */
    [implicit_jscontext,optional_argc]
    jsval evalInSandbox(in AString source, in jsval sandbox,
                        [optional] in jsval version,
                        [optional] in jsval filename,
                        [optional] in long lineNo);


    /*
     * import is designed to be called from JavaScript only.
     *
     * Synchronously loads and evaluates the js file located at
     * 'registryLocation' with a new, fully privileged global object.
     *
     * If 'targetObj' is specified and equal to null, returns the
     * module's global object. Otherwise (if 'targetObj' is not
     * specified, or 'targetObj' is != null) looks for a property
     * 'EXPORTED_SYMBOLS' on the new global object. 'EXPORTED_SYMBOLS'
     * is expected to be an array of strings identifying properties on
     * the global object.  These properties will be installed as
     * properties on 'targetObj', or, if 'targetObj' is not specified,
     * on the caller's global object. If 'EXPORTED_SYMBOLS' is not
     * found, an error is thrown.
     *
     * @param resourceURI A resource:// URI string to load the module from.
     * @param targetObj  the object to install the exported properties on.
     *        If this parameter is a primitive value, this method throws
     *        an exception.
     * @returns the module code's global object.
     *
     * The implementation maintains a hash of registryLocation->global obj.
     * Subsequent invocations of importModule with 'registryLocation'
     * pointing to the same file will not cause the module to be re-evaluated,
     * but the symbols in EXPORTED_SYMBOLS will be exported into the
     * specified target object and the global object returned as above.
     *
     * (This comment is duplicated from xpcIJSModuleLoader.)
     */
    [implicit_jscontext,optional_argc]
    jsval import(in AUTF8String aResourceURI, [optional] in jsval targetObj);

    /*
     * Unloads the JS module at 'registryLocation'. Existing references to the
     * module will continue to work but any subsequent import of the module will
     * reload it and give new reference. If the JS module hasn't yet been
     * imported then this method will do nothing.
     *
     * @param resourceURI A resource:// URI string to unload the module from.
     */
    void unload(in AUTF8String registryLocation);

    /*
     * To be called from JS only.
     *
     * Return a weak reference for the given JS object.
     */
    [implicit_jscontext]
    xpcIJSWeakReference getWeakReference(in jsval obj);

    /*
     * To be called from JS only.
     *
     * Force an immediate garbage collection cycle.
     */
    void forceGC();

    /*
     * To be called from JS only.
     *
     * Force an immediate cycle collection cycle.
     */
    void forceCC();
    
    /*
     * To be called from JS only.
     *
     * Force an immediate shrinking garbage collection cycle.
     */
    void forceShrinkingGC();

    /*
     * Schedule a garbage collection cycle for a point in the future when no JS
     * is running. Call the provided function once this has occurred.
     */
    void schedulePreciseGC(in ScheduledGCCallback callback);
    
    /*
     * Schedule a shrinking garbage collection cycle for a point in the future
     * when no JS is running. Call the provided function once this has occured.
     */
    void schedulePreciseShrinkingGC(in ScheduledGCCallback callback);

    /**
     * Return the keys in a weak map.  This operation is
     * non-deterministic because it is affected by the scheduling of the
     * garbage collector and the cycle collector.
     *
     * This should only be used to write tests of the interaction of
     * the GC and CC with weak maps.
     *
     * @param aMap weak map or other JavaScript value
     * @returns If aMap is a weak map object, return the keys of the weak
                map as an array.  Otherwise, return undefined.
     */
    [implicit_jscontext]
    jsval nondeterministicGetWeakMapKeys(in jsval aMap);

    [implicit_jscontext]
    jsval getJSTestingFunctions();

    /*
     * To be called from JS only.
     *
     * Returns the global object with which the given object is associated.
     *
     * @param obj The JavaScript object whose global is to be gotten.
     * @return the corresponding global.
     */
    [implicit_jscontext]
    jsval getGlobalForObject(in jsval obj);

    /*
     * To be called from JS only.
     *
     * Returns an object created in |vobj|'s compartment.
     */
    [implicit_jscontext]
    jsval createObjectIn(in jsval vobj);

    /*
     * To be called from JS only.
     *
     * Returns an array created in |vobj|'s compartment.
     */
    [implicit_jscontext]
    jsval createArrayIn(in jsval vobj);

    /*
     * To be called from JS only.
     *
     * Ensures that all functions come from vobj's scope (and aren't cross
     * compartment wrappers).
     */
    [implicit_jscontext]
    void makeObjectPropsNormal(in jsval vobj);

    /**
     * Determines whether this object is backed by a DeadObjectProxy.
     *
     * Dead-wrapper objects hold no other objects alive (they have no outgoing
     * reference edges) and will throw if you touch them (e.g. by
     * reading/writing a property).
     */
    bool isDeadWrapper(in jsval obj);

    /*
     * To be called from JS only. This is for Gecko internal use only, and may
     * disappear at any moment.
     *
     * Forces a recomputation of all wrappers in and out of the compartment
     * containing |obj|. If |obj| is not an object, all wrappers system-wide
     * are recomputed.
     */
    [implicit_jscontext]
    void recomputeWrappers([optional] in jsval vobj);

    /*
     * Dispatches a runnable to the current/main thread. If |scope| is passed,
     * the runnable will be dispatch in the compartment of |scope|, which
     * affects which error reporter gets called.
     */
    [implicit_jscontext]
    void dispatch(in jsval runnable, [optional] in jsval scope);

    /*
     * To be called from JS only.
     *
     * These are the set of JSContext options that privileged script
     * is allowed to control for the purposes of testing.  These
     * options should be kept in sync with what's controllable in the
     * jsshell and by setting prefs in nsJSEnvironment.
     *
     * NB: Assume that getting any of these attributes is relatively
     * cheap, but setting any of them is relatively expensive.
     */
    [implicit_jscontext]
    attribute boolean strict;

    [implicit_jscontext]
    attribute boolean werror;

    [implicit_jscontext]
    attribute boolean atline;

    [implicit_jscontext]
    attribute boolean xml;

    [implicit_jscontext]
    attribute boolean relimit;

    [implicit_jscontext]
    attribute boolean methodjit;

    [implicit_jscontext]
    attribute boolean methodjit_always;

    [implicit_jscontext]
    attribute boolean strict_mode;

    [implicit_jscontext]
    void setGCZeal(in long zeal);

    [implicit_jscontext]
    void nukeSandbox(in jsval obj);
};

/**
* interface of JavaScript's 'Components' object
*/
[scriptable, uuid(8406dedb-23cc-42db-9f69-1f18785091b5)]
interface nsIXPCComponents : nsISupports
{
    readonly attribute nsIXPCComponents_Interfaces      interfaces;
    readonly attribute nsIXPCComponents_InterfacesByID  interfacesByID;
    readonly attribute nsIXPCComponents_Classes         classes;
    readonly attribute nsIXPCComponents_ClassesByID     classesByID;
    readonly attribute nsIStackFrame                    stack;
    readonly attribute nsIXPCComponents_Results         results;
    readonly attribute nsIComponentManager              manager;
    readonly attribute nsIXPCComponents_Utils           utils;

    readonly attribute nsIXPCComponents_ID              ID;
    readonly attribute nsIXPCComponents_Exception       Exception;
    readonly attribute nsIXPCComponents_Constructor     Constructor;

    boolean isSuccessCode(in nsresult result);

    /* @deprecated Use Components.utils.lookupMethod instead.
     * (But are you sure you really want this method any more?
     *  See http://developer-test.mozilla.org/en/docs/XPCNativeWrapper )
     */
    [deprecated,implicit_jscontext]
    jsval lookupMethod(in jsval obj, in jsval name);

    /* @deprecated Use Components.utils.reportError instead. */
    [deprecated, implicit_jscontext] void reportError(in jsval error);

    /* 'lastResult' is accessible via JavaScript only */
    /* 'returnCode' is accessible via JavaScript only */
};