gecko/js/src/xpconnect/idl/xpccomponents.idl

/* -*- Mode: C; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*-
 *
 * ***** BEGIN LICENSE BLOCK *****
 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
 *
 * The contents of this file are subject to the Mozilla Public License Version
 * 1.1 (the "License"); you may not use this file except in compliance with
 * the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * The Original Code is Mozilla Communicator client code, released
 * March 31, 1998.
 *
 * The Initial Developer of the Original Code is
 * Netscape Communications Corporation.
 * Portions created by the Initial Developer are Copyright (C) 1998
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 *   John Bandhauer <jband@netscape.com> (original author)
 *
 * Alternatively, the contents of this file may be used under the terms of
 * either of the GNU General Public License Version 2 or later (the "GPL"),
 * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 * in which case the provisions of the GPL or the LGPL are applicable instead
 * of those above. If you wish to allow use of your version of this file only
 * under the terms of either the GPL or the LGPL, and not to allow others to
 * use your version of this file under the terms of the MPL, indicate your
 * decision by deleting the provisions above and replace them with the notice
 * and other provisions required by the GPL or the LGPL. If you do not delete
 * the provisions above, a recipient may use your version of this file under
 * the terms of any one of the MPL, the GPL or the LGPL.
 *
 * ***** END LICENSE BLOCK ***** */

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

interface xpcIJSWeakReference;

/**
* 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 of Components.utils
*/
[scriptable, uuid(da2267f2-d4cc-448f-9d70-1c7fe134d2fe)]
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.
     */
    void reportError();

    /* 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.
     */
    void lookupMethod();

    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);
     */
    void evalInSandbox(in AString source/*, obj */);


    /*
     * 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.
     * After loading, 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.
     * If present, these properties will be installed as properties on
     * targetObj, or, if 'targetObj' is not specified, on the caller's
     * global object.
     *
     * @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 null or is a primitive value, this
     *        method throws an exception.
     * @returns the new global object the module code was loaded into.
     *
     * 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.)
     */
    void /* JSObject */ import(in AUTF8String registryLocation
                               /*, [optional] in JSObject targetObj */);

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

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

/**
* interface of JavaScript's 'Components' object
*/
[scriptable, uuid(155809f1-71f1-47c5-be97-d812ba560405)]
interface nsIXPCComponents : nsISupports
{
    readonly attribute nsIScriptableInterfaces      interfaces;
    readonly attribute nsIScriptableInterfacesByID  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 )
     */
    void lookupMethod();

    /* DEPRECATED: use Components.utils.reportError instead. */
    void reportError();

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