michael@0: /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #include "nsISupports.idl"
michael@0: 
michael@0: [ptr] native nsAXPCNativeCallContextPtr(nsAXPCNativeCallContext);
michael@0: 
michael@0: %{C++
michael@0: #include "js/TypeDecls.h"
michael@0: 
michael@0: class nsAXPCNativeCallContext;
michael@0: %}
michael@0: 
michael@0: [ptr] native JSObjectPtr(JSObject);
michael@0: 
michael@0: [scriptable, uuid(243d1a31-db9f-47a1-9922-55a1ad5515fb)]
michael@0: interface xpcIJSModuleLoader : nsISupports
michael@0: {
michael@0:   /**
michael@0:    * To be called from JavaScript only.
michael@0:    *
michael@0:    * Synchronously loads and evaluates the js file located at
michael@0:    * aResourceURI with a new, fully privileged global object.
michael@0:    *
michael@0:    * If 'targetObj' is specified and equal to null, returns the
michael@0:    * module's global object. Otherwise (if 'targetObj' is not
michael@0:    * specified, or 'targetObj' is != null) looks for a property
michael@0:    * 'EXPORTED_SYMBOLS' on the new global object. 'EXPORTED_SYMBOLS'
michael@0:    * is expected to be an array of strings identifying properties on
michael@0:    * the global object.  These properties will be installed as
michael@0:    * properties on 'targetObj', or, if 'targetObj' is not specified,
michael@0:    * on the caller's global object. If 'EXPORTED_SYMBOLS' is not
michael@0:    * found, an error is thrown.
michael@0:    *
michael@0:    * @param resourceURI A resource:// URI string to load the module from.
michael@0:    * @param targetObj  the object to install the exported properties on.
michael@0:    *        If this parameter is a primitive value, this method throws
michael@0:    *        an exception.
michael@0:    * @returns the module code's global object.
michael@0:    *
michael@0:    * The implementation maintains a hash of registryLocation->global obj.
michael@0:    * Subsequent invocations of importModule with 'registryLocation'
michael@0:    * pointing to the same file will not cause the module to be re-evaluated,
michael@0:    * but the symbols in EXPORTED_SYMBOLS will be exported into the
michael@0:    * specified target object and the global object returned as above.
michael@0:    *
michael@0:    * (This comment is duplicated to nsIXPCComponents_Utils.)
michael@0:    */
michael@0:   [implicit_jscontext,optional_argc]
michael@0:   jsval import(in AUTF8String aResourceURI, [optional] in jsval targetObj);
michael@0: 
michael@0:   /**
michael@0:    * Imports the JS module at aResourceURI to the JS object
michael@0:    * 'targetObj' (if != null) as described for importModule() and
michael@0:    * returns the module's global object.
michael@0:    */
michael@0:   [noscript] JSObjectPtr importInto(in AUTF8String aResourceURI,
michael@0:                                     in JSObjectPtr targetObj,
michael@0:                                     in nsAXPCNativeCallContextPtr cc);
michael@0: 
michael@0:   /**
michael@0:    * Unloads the JS module at aResourceURI. Existing references to the module
michael@0:    * will continue to work but any subsequent import of the module will
michael@0:    * reload it and give new reference. If the JS module hasn't yet been imported
michael@0:    * then this method will do nothing.
michael@0:    */
michael@0:   void unload(in AUTF8String aResourceURI);
michael@0: };