dom/base/nsIScriptContext.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License Version
   6  * 1.1 (the "License"); you may not use this file except in compliance with
   7  * the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is mozilla.org code.
  16  *
  17  * The Initial Developer of the Original Code is
  18  * Netscape Communications Corporation.
  19  * Portions created by the Initial Developer are Copyright (C) 1998-1999
  20  * the Initial Developer. All Rights Reserved.
  21  *
  22  * Contributor(s):
  23  *
  24  * Alternatively, the contents of this file may be used under the terms of
  25  * either of the GNU General Public License Version 2 or later (the "GPL"),
  26  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27  * in which case the provisions of the GPL or the LGPL are applicable instead
  28  * of those above. If you wish to allow use of your version of this file only
  29  * under the terms of either the GPL or the LGPL, and not to allow others to
  30  * use your version of this file under the terms of the MPL, indicate your
  31  * decision by deleting the provisions above and replace them with the notice
  32  * and other provisions required by the GPL or the LGPL. If you do not delete
  33  * the provisions above, a recipient may use your version of this file under
  34  * the terms of any one of the MPL, the GPL or the LGPL.
  35  *
  36  * ***** END LICENSE BLOCK ***** */
  37
  38 #ifndef nsIScriptContext_h__
  39 #define nsIScriptContext_h__
  40
  41 #include "nscore.h"
  42 #include "nsStringGlue.h"
  43 #include "nsISupports.h"
  44 #include "nsCOMPtr.h"
  45 #include "nsIProgrammingLanguage.h"
  46
  47 class nsIScriptGlobalObject;
  48 class nsIScriptSecurityManager;
  49 class nsIPrincipal;
  50 class nsIAtom;
  51 class nsIArray;
  52 class nsIVariant;
  53 class nsIObjectInputStream;
  54 class nsIObjectOutputStream;
  55 class nsScriptObjectHolder;
  56 class nsIScriptObjectPrincipal;
  57
  58 typedef void (*nsScriptTerminationFunc)(nsISupports* aRef);
  59
  60 #define NS_ISCRIPTCONTEXTPRINCIPAL_IID \
  61   { 0xd012cdb3, 0x8f1e, 0x4440, \
  62     { 0x8c, 0xbd, 0x32, 0x7f, 0x98, 0x1d, 0x37, 0xb4 } }
  63
  64 class nsIScriptContextPrincipal : public nsISupports
  65 {
  66 public:
  67   NS_DECLARE_STATIC_IID_ACCESSOR(NS_ISCRIPTCONTEXTPRINCIPAL_IID)
  68
  69   virtual nsIScriptObjectPrincipal* GetObjectPrincipal() = 0;
  70 };
  71
  72 NS_DEFINE_STATIC_IID_ACCESSOR(nsIScriptContextPrincipal,
  73                               NS_ISCRIPTCONTEXTPRINCIPAL_IID)
  74
  75 // a7139c0e-962c-44b6-bec3-e4166bfe84eb
  76 #define NS_ISCRIPTCONTEXT_IID \
  77 { 0xa7139c0e, 0x962c, 0x44b6, \
  78   { 0xbe, 0xc3, 0xe4, 0x16, 0x6b, 0xfe, 0x84, 0xeb } }
  79
  80 /* This MUST match JSVERSION_DEFAULT.  This version stuff if we don't
  81    know what language we have is a little silly... */
  82 #define SCRIPTVERSION_DEFAULT JSVERSION_DEFAULT
  83
  84 /**
  85  * It is used by the application to initialize a runtime and run scripts.
  86  * A script runtime would implement this interface.
  87  * <P><I>It does have a bit too much java script information now, that
  88  * should be removed in a short time. Ideally this interface will be
  89  * language neutral</I>
  90  */
  91 class nsIScriptContext : public nsIScriptContextPrincipal
  92 {
  93 public:
  94   NS_DECLARE_STATIC_IID_ACCESSOR(NS_ISCRIPTCONTEXT_IID)
  95
  96   /* Get the ID of this language. */
  97   virtual PRUint32 GetScriptTypeID() = 0;
  98
  99   /**
 100    * Compile and execute a script.
 101    *
 102    * @param aScript a string representing the script to be executed
 103    * @param aScopeObject a script object for the scope to execute in, or
 104    *                     nsnull to use a default scope
 105    * @param aPrincipal the principal that produced the script
 106    * @param aURL the URL or filename for error messages
 107    * @param aLineNo the starting line number of the script for error messages
 108    * @param aVersion the script language version to use when executing
 109    * @param aRetValue the result of executing the script, or null for no result.
 110    *        If this is a JS context, it's the caller's responsibility to
 111    *        preserve aRetValue from GC across this call
 112    * @param aIsUndefined true if the result of executing the script is the
 113    *                     undefined value
 114    *
 115    * @return NS_OK if the script was valid and got executed
 116    *
 117    **/
 118   virtual nsresult EvaluateString(const nsAString& aScript,
 119                                   void *aScopeObject,
 120                                   nsIPrincipal *aPrincipal,
 121                                   const char *aURL,
 122                                   PRUint32 aLineNo,
 123                                   PRUint32 aVersion,
 124                                   nsAString *aRetValue,
 125                                   PRBool* aIsUndefined) = 0;
 126
 127   // Note JS bigotry remains here - 'void *aRetValue' is assumed to be a
 128   // jsval.  This must move to JSObject before it can be made agnostic.
 129   virtual nsresult EvaluateStringWithValue(const nsAString& aScript,
 130                                            void *aScopeObject,
 131                                            nsIPrincipal *aPrincipal,
 132                                            const char *aURL,
 133                                            PRUint32 aLineNo,
 134                                            PRUint32 aVersion,
 135                                            void* aRetValue,
 136                                            PRBool* aIsUndefined) = 0;
 137
 138   /**
 139    * Compile a script.
 140    *
 141    * @param aText a PRUnichar buffer containing script source
 142    * @param aTextLength number of characters in aText
 143    * @param aScopeObject an object telling the scope in which to execute,
 144    *                     or nsnull to use a default scope
 145    * @param aPrincipal the principal that produced the script
 146    * @param aURL the URL or filename for error messages
 147    * @param aLineNo the starting line number of the script for error messages
 148    * @param aVersion the script language version to use when executing
 149    * @param aScriptObject an executable object that's the result of compiling
 150    *                      the script.
 151    *
 152    * @return NS_OK if the script source was valid and got compiled.
 153    *
 154    **/
 155   virtual nsresult CompileScript(const PRUnichar* aText,
 156                                  PRInt32 aTextLength,
 157                                  void* aScopeObject,
 158                                  nsIPrincipal* aPrincipal,
 159                                  const char* aURL,
 160                                  PRUint32 aLineNo,
 161                                  PRUint32 aVersion,
 162                                  nsScriptObjectHolder &aScriptObject) = 0;
 163
 164   /**
 165    * Execute a precompiled script object.
 166    *
 167    * @param aScriptObject an object representing the script to be executed
 168    * @param aScopeObject an object telling the scope in which to execute,
 169    *                     or nsnull to use a default scope
 170    * @param aRetValue the result of executing the script, may be null in
 171    *                  which case no result string is computed
 172    * @param aIsUndefined true if the result of executing the script is the
 173    *                     undefined value, may be null for "don't care"
 174    *
 175    * @return NS_OK if the script was valid and got executed
 176    *
 177    */
 178   virtual nsresult ExecuteScript(void* aScriptObject,
 179                                  void* aScopeObject,
 180                                  nsAString* aRetValue,
 181                                  PRBool* aIsUndefined) = 0;
 182
 183   /**
 184    * Compile the event handler named by atom aName, with function body aBody
 185    * into a function object returned if ok via aHandler.  Does NOT bind the
 186    * function to anything - BindCompiledEventHandler() should be used for that
 187    * purpose.  Note that this event handler is always considered 'shared' and
 188    * hence is compiled without principals.  Never call the returned object
 189    * directly - it must be bound (and thereby cloned, and therefore have the
 190    * correct principals) before use!
 191    *
 192    * If the compilation sets a pending exception on the native context, it is
 193    * this method's responsibility to report said exception immediately, without
 194    * relying on callers to do so.
 195    *
 196    *
 197    * @param aName an nsIAtom pointer naming the function; it must be lowercase
 198    *        and ASCII, and should not be longer than 63 chars.  This bound on
 199    *        length is enforced only by assertions, so caveat caller!
 200    * @param aEventName the name that the event object should be bound to
 201    * @param aBody the event handler function's body
 202    * @param aURL the URL or filename for error messages
 203    * @param aLineNo the starting line number of the script for error messages
 204    * @param aVersion the script language version to use when executing
 205    * @param aHandler the out parameter in which a void pointer to the compiled
 206    *        function object is stored on success
 207    *
 208    * @return NS_OK if the function body was valid and got compiled
 209    */
 210   virtual nsresult CompileEventHandler(nsIAtom* aName,
 211                                        PRUint32 aArgCount,
 212                                        const char** aArgNames,
 213                                        const nsAString& aBody,
 214                                        const char* aURL,
 215                                        PRUint32 aLineNo,
 216                                        PRUint32 aVersion,
 217                                        nsScriptObjectHolder &aHandler) = 0;
 218
 219   /**
 220    * Call the function object with given args and return its boolean result,
 221    * or true if the result isn't boolean.
 222    *
 223    * @param aTarget the event target
 224    * @param aScript an object telling the scope in which to call the compiled
 225    *        event handler function.
 226    * @param aHandler function object (function and static scope) to invoke.
 227    * @param argv array of arguments.  Note each element is assumed to
 228    *        be an nsIVariant.
 229    * @param rval out parameter returning result
 230    **/
 231   virtual nsresult CallEventHandler(nsISupports* aTarget,
 232                                     void *aScope, void* aHandler,
 233                                     nsIArray *argv, nsIVariant **rval) = 0;
 234
 235   /**
 236    * Bind an already-compiled event handler function to a name in the given
 237    * scope object.  The same restrictions on aName (lowercase ASCII, not too
 238    * long) applies here as for CompileEventHandler.  Scripting languages with
 239    * static scoping must re-bind the scope chain for aHandler to begin (after
 240    * the activation scope for aHandler itself, typically) with aTarget's scope.
 241    *
 242    * Logically, this 'bind' operation is more of a 'copy' - it simply
 243    * stashes/associates the event handler function with the event target, so
 244    * it can be fetched later with GetBoundEventHandler().
 245    *
 246    * @param aTarget an object telling the scope in which to bind the compiled
 247    *        event handler function.  The context will presumably associate
 248    *        this nsISupports with a native script object.
 249    * @param aName an nsIAtom pointer naming the function; it must be lowercase
 250    *        and ASCII, and should not be longer than 63 chars.  This bound on
 251    *        length is enforced only by assertions, so caveat caller!
 252    * @param aHandler the function object to name, created by an earlier call to
 253    *        CompileEventHandler
 254    * @return NS_OK if the function was successfully bound to the name
 255    *
 256    * XXXmarkh - fold this in with SetProperty?  Exactly the same concept!
 257    */
 258   virtual nsresult BindCompiledEventHandler(nsISupports* aTarget, void *aScope,
 259                                             nsIAtom* aName,
 260                                             void* aHandler) = 0;
 261
 262   /**
 263    * Lookup a previously bound event handler for the specified target.  This
 264    * will return an object equivilent to the one passed to
 265    * BindCompiledEventHandler (although the pointer may not be the same).
 266    *
 267    */
 268   virtual nsresult GetBoundEventHandler(nsISupports* aTarget, void *aScope,
 269                                         nsIAtom* aName,
 270                                         nsScriptObjectHolder &aHandler) = 0;
 271
 272   /**
 273    * Compile a function that isn't used as an event handler.
 274    *
 275    * NOTE: Not yet language agnostic (main problem is XBL - not yet agnostic)
 276    * Caller must make sure aFunctionObject is a JS GC root.
 277    *
 278    **/
 279   virtual nsresult CompileFunction(void* aTarget,
 280                                    const nsACString& aName,
 281                                    PRUint32 aArgCount,
 282                                    const char** aArgArray,
 283                                    const nsAString& aBody,
 284                                    const char* aURL,
 285                                    PRUint32 aLineNo,
 286                                    PRUint32 aVersion,
 287                                    PRBool aShared,
 288                                    void **aFunctionObject) = 0;
 289
 290   /**
 291    * Set the default scripting language version for this context, which must
 292    * be a context specific to a particular scripting language.
 293    *
 294    **/
 295   virtual void SetDefaultLanguageVersion(PRUint32 aVersion) = 0;
 296
 297   /**
 298    * Return the global object.
 299    *
 300    **/
 301   virtual nsIScriptGlobalObject *GetGlobalObject() = 0;
 302
 303   /**
 304    * Return the native script context
 305    *
 306    **/
 307   virtual void *GetNativeContext() = 0;
 308
 309   /**
 310    * Return the native global object for this context.
 311    *
 312    **/
 313   virtual void *GetNativeGlobal() = 0;
 314
 315   /**
 316    * Create a new global object that will be used for an inner window.
 317    * Return the native global and an nsISupports 'holder' that can be used
 318    * to manage the lifetime of it.
 319    */
 320   virtual nsresult CreateNativeGlobalForInner(
 321                                       nsIScriptGlobalObject *aNewInner,
 322                                       PRBool aIsChrome,
 323                                       nsIPrincipal *aPrincipal,
 324                                       void **aNativeGlobal,
 325                                       nsISupports **aHolder) = 0;
 326
 327   /**
 328    * Connect this context to a new inner window, to allow "prototype"
 329    * chaining from the inner to the outer.
 330    * Called after both the the inner and outer windows are initialized
 331    **/
 332   virtual nsresult ConnectToInner(nsIScriptGlobalObject *aNewInner,
 333                                   void *aOuterGlobal) = 0;
 334
 335
 336   /**
 337    * Initialize the context generally. Does not create a global object.
 338    **/
 339   virtual nsresult InitContext() = 0;
 340
 341   /**
 342    * Creates the outer window for this context.
 343    *
 344    * @param aGlobalObject The script global object to use as our global.
 345    */
 346   virtual nsresult CreateOuterObject(nsIScriptGlobalObject *aGlobalObject,
 347                                      nsIScriptGlobalObject *aCurrentInner) = 0;
 348
 349   /**
 350    * Given an outer object, updates this context with that outer object.
 351    */
 352   virtual nsresult SetOuterObject(void *aOuterObject) = 0;
 353
 354   /**
 355    * Prepares this context for use with the current inner window for the
 356    * context's global object. This must be called after CreateOuterObject.
 357    */
 358   virtual nsresult InitOuterWindow() = 0;
 359
 360   /**
 361    * Check to see if context is as yet intialized. Used to prevent
 362    * reentrancy issues during the initialization process.
 363    *
 364    * @return PR_TRUE if initialized, PR_FALSE if not
 365    *
 366    */
 367   virtual PRBool IsContextInitialized() = 0;
 368
 369   /**
 370    * Called as the global object discards its reference to the context.
 371    */
 372   virtual void FinalizeContext() = 0;
 373
 374   /**
 375    * For garbage collected systems, do a synchronous collection pass.
 376    * May be a no-op on other systems
 377    *
 378    * @return NS_OK if the method is successful
 379    */
 380   virtual void GC() = 0;
 381
 382   /**
 383    * Inform the context that a script was evaluated.
 384    * A GC may be done if "necessary."
 385    * This call is necessary if script evaluation is done
 386    * without using the EvaluateScript method.
 387    * @param aTerminated If true then call termination function if it was
 388    *    previously set. Within DOM this will always be true, but outside
 389    *    callers (such as xpconnect) who may do script evaluations nested
 390    *    inside DOM script evaluations can pass false to avoid premature
 391    *    calls to the termination function.
 392    * @return NS_OK if the method is successful
 393    */
 394   virtual void ScriptEvaluated(PRBool aTerminated) = 0;
 395
 396   virtual nsresult Serialize(nsIObjectOutputStream* aStream,
 397                              void *aScriptObject) = 0;
 398
 399   /* Deserialize a script from a stream.
 400    */
 401   virtual nsresult Deserialize(nsIObjectInputStream* aStream,
 402                                nsScriptObjectHolder &aResult) = 0;
 403
 404   /**
 405    * JS only - this function need not be implemented by languages other
 406    * than JS (ie, this should be moved to a private interface!)
 407    * Called to specify a function that should be called when the current
 408    * script (if there is one) terminates. Generally used if breakdown
 409    * of script state needs to happen, but should be deferred till
 410    * the end of script evaluation.
 411    *
 412    * @throws NS_ERROR_OUT_OF_MEMORY if that happens
 413    */
 414   virtual nsresult SetTerminationFunction(nsScriptTerminationFunc aFunc,
 415                                           nsISupports* aRef) = 0;
 416
 417   /**
 418    * Called to disable/enable script execution in this context.
 419    */
 420   virtual PRBool GetScriptsEnabled() = 0;
 421   virtual void SetScriptsEnabled(PRBool aEnabled, PRBool aFireTimeouts) = 0;
 422
 423   // SetProperty is suspect and jst believes should not be needed.  Currenly
 424   // used only for "arguments".
 425   virtual nsresult SetProperty(void *aTarget, const char *aPropName, nsISupports *aVal) = 0;
 426   /**
 427    * Called to set/get information if the script context is
 428    * currently processing a script tag
 429    */
 430   virtual PRBool GetProcessingScriptTag() = 0;
 431   virtual void SetProcessingScriptTag(PRBool aResult) = 0;
 432
 433   /**
 434    * Called to find out if this script context might be executing script.
 435    */
 436   virtual PRBool GetExecutingScript() = 0;
 437
 438   /**
 439    * Tell the context whether or not to GC when destroyed.  An optimization
 440    * used when the window is a [i]frame, so GC will happen anyway.
 441    */
 442   virtual void SetGCOnDestruction(PRBool aGCOnDestruction) = 0;
 443
 444   /**
 445    * Initialize DOM classes on aGlobalObj, always call
 446    * WillInitializeContext() before calling InitContext(), and always
 447    * call DidInitializeContext() when a context is fully
 448    * (successfully) initialized.
 449    */
 450   virtual nsresult InitClasses(void *aGlobalObj) = 0;
 451
 452   /**
 453    * Clear the scope object - may be called either as we are being torn down,
 454    * or before we are attached to a different document.
 455    *
 456    * aClearFromProtoChain is probably somewhat JavaScript specific.  It
 457    * indicates that the global scope polluter should be removed from the
 458    * prototype chain and that the objects in the prototype chain should
 459    * also have their scopes cleared.  We don't do this all the time
 460    * because the prototype chain is shared between inner and outer
 461    * windows, and needs to stay with inner windows that we're keeping
 462    * around.
 463    */
 464   virtual void ClearScope(void* aGlobalObj, PRBool aClearFromProtoChain) = 0;
 465
 466   /**
 467    * Tell the context we're about to be reinitialize it.
 468    */
 469   virtual void WillInitializeContext() = 0;
 470
 471   /**
 472    * Tell the context we're done reinitializing it.
 473    */
 474   virtual void DidInitializeContext() = 0;
 475
 476   /**
 477    * Tell the context our global has a new document, and the scope
 478    * used by it.  Use nsISupports to avoid dependency issues - but expect
 479    * a QI for nsIDOMDocument and/or nsIDocument.
 480    */
 481   virtual void DidSetDocument(nsISupports *aDoc, void *aGlobal) = 0;
 482
 483   /* Memory managment for script objects.  Used by the implementation of
 484    * nsScriptObjectHolder to manage the lifetimes of the held script objects.
 485    *
 486    * See also nsIScriptRuntime, which has identical methods and is useful
 487    * in situations when you do not have an nsIScriptContext.
 488    *
 489    */
 490   virtual nsresult DropScriptObject(void *object) = 0;
 491   virtual nsresult HoldScriptObject(void *object) = 0;
 492
 493   virtual void EnterModalState() = 0;
 494   virtual void LeaveModalState() = 0;
 495 };
 496
 497 NS_DEFINE_STATIC_IID_ACCESSOR(nsIScriptContext, NS_ISCRIPTCONTEXT_IID)
 498
 499 #endif // nsIScriptContext_h__
 500