gecko-dev/js/xpconnect/idl/xpccomponents.idl

387 lines
13 KiB
Plaintext

/* -*- Mode: IDL; 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"
%{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(b032a8f1-9149-4cbe-bee6-4ac5dfe7c80a)]
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.
*/
[implicit_jscontext]
void forceGC();
/*
* Schedule a garbage collection cycle for a point in the future when no JS
* is running. Call the provided function once this has occurred.
*/
[implicit_jscontext]
void schedulePreciseGC(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);
/*
* 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.
*
* Ensures that all functions come from vobj's scope (and aren't cross
* compartment wrappers).
*/
[implicit_jscontext]
void makeObjectPropsNormal(in jsval vobj);
/*
* 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]
void setGCZeal(in long zeal);
};
/**
* interface of JavaScript's 'Components' object
*/
[scriptable, uuid(4676e9cf-2c07-423b-b161-26bb9d8067d3)]
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 */
};