LCOV - code coverage report
Current view: directory - dom/base - nsIScriptContext.h (source / functions) Found Hit Coverage
Test: app.info Lines: 2 0 0.0 %
Date: 2012-06-02 Functions: 2 0 0.0 %

       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                 : #include "jsfriendapi.h"
      47                 : #include "jspubtd.h"
      48                 : 
      49                 : class nsIScriptGlobalObject;
      50                 : class nsIScriptSecurityManager;
      51                 : class nsIPrincipal;
      52                 : class nsIAtom;
      53                 : class nsIArray;
      54                 : class nsIVariant;
      55                 : class nsIObjectInputStream;
      56                 : class nsIObjectOutputStream;
      57                 : template<class> class nsScriptObjectHolder;
      58                 : class nsIScriptObjectPrincipal;
      59                 : class nsIDOMWindow;
      60                 : 
      61                 : typedef void (*nsScriptTerminationFunc)(nsISupports* aRef);
      62                 : 
      63                 : #define NS_ISCRIPTCONTEXTPRINCIPAL_IID \
      64                 :   { 0xd012cdb3, 0x8f1e, 0x4440, \
      65                 :     { 0x8c, 0xbd, 0x32, 0x7f, 0x98, 0x1d, 0x37, 0xb4 } }
      66                 : 
      67                 : class nsIScriptContextPrincipal : public nsISupports
      68               0 : {
      69                 : public:
      70                 :   NS_DECLARE_STATIC_IID_ACCESSOR(NS_ISCRIPTCONTEXTPRINCIPAL_IID)
      71                 : 
      72                 :   virtual nsIScriptObjectPrincipal* GetObjectPrincipal() = 0;
      73                 : };
      74                 : 
      75                 : NS_DEFINE_STATIC_IID_ACCESSOR(nsIScriptContextPrincipal,
      76                 :                               NS_ISCRIPTCONTEXTPRINCIPAL_IID)
      77                 : 
      78                 : #define NS_ISCRIPTCONTEXT_IID \
      79                 : { 0xdfaea249, 0xaaad, 0x48bd, \
      80                 :   { 0xb8, 0x04, 0x92, 0xad, 0x30, 0x88, 0xd0, 0xc6 } }
      81                 : 
      82                 : /* This MUST match JSVERSION_DEFAULT.  This version stuff if we don't
      83                 :    know what language we have is a little silly... */
      84                 : #define SCRIPTVERSION_DEFAULT JSVERSION_DEFAULT
      85                 : 
      86                 : /**
      87                 :  * It is used by the application to initialize a runtime and run scripts.
      88                 :  * A script runtime would implement this interface.
      89                 :  */
      90                 : class nsIScriptContext : public nsIScriptContextPrincipal
      91               0 : {
      92                 : public:
      93                 :   NS_DECLARE_STATIC_IID_ACCESSOR(NS_ISCRIPTCONTEXT_IID)
      94                 : 
      95                 :   /* Get the ID of this language. */
      96                 :   virtual PRUint32 GetScriptTypeID() = 0;
      97                 : 
      98                 :   /**
      99                 :    * Compile and execute a script.
     100                 :    *
     101                 :    * @param aScript a string representing the script to be executed
     102                 :    * @param aScopeObject a script object for the scope to execute in, or
     103                 :    *                     nsnull to use a default scope
     104                 :    * @param aPrincipal the principal the script should be evaluated with
     105                 :    * @param aOriginPrincipal the principal the script originates from.  If null,
     106                 :    *                         aPrincipal is used.
     107                 :    * @param aURL the URL or filename for error messages
     108                 :    * @param aLineNo the starting line number of the script for error messages
     109                 :    * @param aVersion the script language version to use when executing
     110                 :    * @param aRetValue the result of executing the script, or null for no result.
     111                 :    *        If this is a JS context, it's the caller's responsibility to
     112                 :    *        preserve aRetValue from GC across this call
     113                 :    * @param aIsUndefined true if the result of executing the script is the
     114                 :    *                     undefined value
     115                 :    *
     116                 :    * @return NS_OK if the script was valid and got executed
     117                 :    *
     118                 :    **/
     119                 :   virtual nsresult EvaluateString(const nsAString& aScript,
     120                 :                                   JSObject* aScopeObject,
     121                 :                                   nsIPrincipal *aPrincipal,
     122                 :                                   nsIPrincipal *aOriginPrincipal,
     123                 :                                   const char *aURL,
     124                 :                                   PRUint32 aLineNo,
     125                 :                                   PRUint32 aVersion,
     126                 :                                   nsAString *aRetValue,
     127                 :                                   bool* aIsUndefined) = 0;
     128                 : 
     129                 :   virtual nsresult EvaluateStringWithValue(const nsAString& aScript,
     130                 :                                            JSObject* aScopeObject,
     131                 :                                            nsIPrincipal *aPrincipal,
     132                 :                                            const char *aURL,
     133                 :                                            PRUint32 aLineNo,
     134                 :                                            PRUint32 aVersion,
     135                 :                                            JS::Value* aRetValue,
     136                 :                                            bool* 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 aPrincipal the principal that produced the script
     144                 :    * @param aURL the URL or filename for error messages
     145                 :    * @param aLineNo the starting line number of the script for error messages
     146                 :    * @param aVersion the script language version to use when executing
     147                 :    * @param aScriptObject an executable object that's the result of compiling
     148                 :    *                      the script.
     149                 :    *
     150                 :    * @return NS_OK if the script source was valid and got compiled.
     151                 :    *
     152                 :    **/
     153                 :   virtual nsresult CompileScript(const PRUnichar* aText,
     154                 :                                  PRInt32 aTextLength,
     155                 :                                  nsIPrincipal* aPrincipal,
     156                 :                                  const char* aURL,
     157                 :                                  PRUint32 aLineNo,
     158                 :                                  PRUint32 aVersion,
     159                 :                                  nsScriptObjectHolder<JSScript>& aScriptObject) = 0;
     160                 : 
     161                 :   /**
     162                 :    * Execute a precompiled script object.
     163                 :    *
     164                 :    * @param aScriptObject an object representing the script to be executed
     165                 :    * @param aScopeObject an object telling the scope in which to execute,
     166                 :    *                     or nsnull to use a default scope
     167                 :    * @param aRetValue the result of executing the script, may be null in
     168                 :    *                  which case no result string is computed
     169                 :    * @param aIsUndefined true if the result of executing the script is the
     170                 :    *                     undefined value, may be null for "don't care"
     171                 :    *
     172                 :    * @return NS_OK if the script was valid and got executed
     173                 :    *
     174                 :    */
     175                 :   virtual nsresult ExecuteScript(JSScript* aScriptObject,
     176                 :                                  JSObject* aScopeObject,
     177                 :                                  nsAString* aRetValue,
     178                 :                                  bool* aIsUndefined) = 0;
     179                 : 
     180                 :   /**
     181                 :    * Compile the event handler named by atom aName, with function body aBody
     182                 :    * into a function object returned if ok via aHandler.  Does NOT bind the
     183                 :    * function to anything - BindCompiledEventHandler() should be used for that
     184                 :    * purpose.  Note that this event handler is always considered 'shared' and
     185                 :    * hence is compiled without principals.  Never call the returned object
     186                 :    * directly - it must be bound (and thereby cloned, and therefore have the 
     187                 :    * correct principals) before use!
     188                 :    *
     189                 :    * If the compilation sets a pending exception on the native context, it is
     190                 :    * this method's responsibility to report said exception immediately, without
     191                 :    * relying on callers to do so.
     192                 :    *
     193                 :    *
     194                 :    * @param aName an nsIAtom pointer naming the function; it must be lowercase
     195                 :    *        and ASCII, and should not be longer than 63 chars.  This bound on
     196                 :    *        length is enforced only by assertions, so caveat caller!
     197                 :    * @param aEventName the name that the event object should be bound to
     198                 :    * @param aBody the event handler function's body
     199                 :    * @param aURL the URL or filename for error messages
     200                 :    * @param aLineNo the starting line number of the script for error messages
     201                 :    * @param aVersion the script language version to use when executing
     202                 :    * @param aHandler the out parameter in which a void pointer to the compiled
     203                 :    *        function object is stored on success
     204                 :    *
     205                 :    * @return NS_OK if the function body was valid and got compiled
     206                 :    */
     207                 :   virtual nsresult CompileEventHandler(nsIAtom* aName,
     208                 :                                        PRUint32 aArgCount,
     209                 :                                        const char** aArgNames,
     210                 :                                        const nsAString& aBody,
     211                 :                                        const char* aURL,
     212                 :                                        PRUint32 aLineNo,
     213                 :                                        PRUint32 aVersion,
     214                 :                                        nsScriptObjectHolder<JSObject>& aHandler) = 0;
     215                 : 
     216                 :   /**
     217                 :    * Call the function object with given args and return its boolean result,
     218                 :    * or true if the result isn't boolean.
     219                 :    *
     220                 :    * @param aTarget the event target
     221                 :    * @param aScript an object telling the scope in which to call the compiled
     222                 :    *        event handler function.
     223                 :    * @param aHandler function object (function and static scope) to invoke.
     224                 :    * @param argv array of arguments.  Note each element is assumed to
     225                 :    *        be an nsIVariant.
     226                 :    * @param rval out parameter returning result
     227                 :    **/
     228                 :   virtual nsresult CallEventHandler(nsISupports* aTarget,
     229                 :                                     JSObject* aScope, JSObject* aHandler,
     230                 :                                     nsIArray *argv, nsIVariant **rval) = 0;
     231                 : 
     232                 :   /**
     233                 :    * Bind an already-compiled event handler function to the given
     234                 :    * target.  Scripting languages with static scoping must re-bind the
     235                 :    * scope chain for aHandler to begin (after the activation scope for
     236                 :    * aHandler itself, typically) with aTarget's scope.
     237                 :    *
     238                 :    * The result of the bind operation is a new handler object, with
     239                 :    * principals now set and scope set as above.  This is returned in
     240                 :    * aBoundHandler.  When this function is called, aBoundHandler is
     241                 :    * expected to not be holding an object.
     242                 :    *
     243                 :    * @param aTarget an object telling the scope in which to bind the compiled
     244                 :    *        event handler function.  The context will presumably associate
     245                 :    *        this nsISupports with a native script object.
     246                 :    * @param aScope the scope in which the script object for aTarget should be
     247                 :    *        looked for.
     248                 :    * @param aHandler the function object to bind, created by an earlier call to
     249                 :    *        CompileEventHandler
     250                 :    * @param aBoundHandler [out] the result of the bind operation.
     251                 :    * @return NS_OK if the function was successfully bound
     252                 :    */
     253                 :   virtual nsresult BindCompiledEventHandler(nsISupports* aTarget,
     254                 :                                             JSObject* aScope,
     255                 :                                             JSObject* aHandler,
     256                 :                                             nsScriptObjectHolder<JSObject>& aBoundHandler) = 0;
     257                 : 
     258                 :   /**
     259                 :    * Compile a function that isn't used as an event handler.
     260                 :    *
     261                 :    * NOTE: Not yet language agnostic (main problem is XBL - not yet agnostic)
     262                 :    * Caller must make sure aFunctionObject is a JS GC root.
     263                 :    *
     264                 :    **/
     265                 :   virtual nsresult CompileFunction(JSObject* aTarget,
     266                 :                                    const nsACString& aName,
     267                 :                                    PRUint32 aArgCount,
     268                 :                                    const char** aArgArray,
     269                 :                                    const nsAString& aBody,
     270                 :                                    const char* aURL,
     271                 :                                    PRUint32 aLineNo,
     272                 :                                    PRUint32 aVersion,
     273                 :                                    bool aShared,
     274                 :                                    JSObject** aFunctionObject) = 0;
     275                 : 
     276                 :   /**
     277                 :    * Return the global object.
     278                 :    *
     279                 :    **/
     280                 :   virtual nsIScriptGlobalObject *GetGlobalObject() = 0;
     281                 : 
     282                 :   /**
     283                 :    * Return the native script context
     284                 :    *
     285                 :    **/
     286                 :   virtual JSContext* GetNativeContext() = 0;
     287                 : 
     288                 :   /**
     289                 :    * Return the native global object for this context.
     290                 :    *
     291                 :    **/
     292                 :   virtual JSObject* GetNativeGlobal() = 0;
     293                 : 
     294                 :   /**
     295                 :    * Create a new global object that will be used for an inner window.
     296                 :    * Return the native global and an nsISupports 'holder' that can be used
     297                 :    * to manage the lifetime of it.
     298                 :    */
     299                 :   virtual nsresult CreateNativeGlobalForInner(
     300                 :                                       nsIScriptGlobalObject *aNewInner,
     301                 :                                       bool aIsChrome,
     302                 :                                       nsIPrincipal *aPrincipal,
     303                 :                                       JSObject** aNativeGlobal,
     304                 :                                       nsISupports **aHolder) = 0;
     305                 : 
     306                 :   /**
     307                 :    * Connect this context to a new inner window, to allow "prototype"
     308                 :    * chaining from the inner to the outer.
     309                 :    * Called after both the the inner and outer windows are initialized
     310                 :    **/
     311                 :   virtual nsresult ConnectToInner(nsIScriptGlobalObject *aNewInner,
     312                 :                                   JSObject *aOuterGlobal) = 0;
     313                 : 
     314                 : 
     315                 :   /**
     316                 :    * Initialize the context generally. Does not create a global object.
     317                 :    **/
     318                 :   virtual nsresult InitContext() = 0;
     319                 : 
     320                 :   /**
     321                 :    * Creates the outer window for this context.
     322                 :    *
     323                 :    * @param aGlobalObject The script global object to use as our global.
     324                 :    */
     325                 :   virtual nsresult CreateOuterObject(nsIScriptGlobalObject *aGlobalObject,
     326                 :                                      nsIScriptGlobalObject *aCurrentInner) = 0;
     327                 : 
     328                 :   /**
     329                 :    * Given an outer object, updates this context with that outer object.
     330                 :    */
     331                 :   virtual nsresult SetOuterObject(JSObject* aOuterObject) = 0;
     332                 : 
     333                 :   /**
     334                 :    * Prepares this context for use with the current inner window for the
     335                 :    * context's global object. This must be called after CreateOuterObject.
     336                 :    */
     337                 :   virtual nsresult InitOuterWindow() = 0;
     338                 : 
     339                 :   /**
     340                 :    * Check to see if context is as yet intialized. Used to prevent
     341                 :    * reentrancy issues during the initialization process.
     342                 :    *
     343                 :    * @return true if initialized, false if not
     344                 :    *
     345                 :    */
     346                 :   virtual bool IsContextInitialized() = 0;
     347                 : 
     348                 :   /**
     349                 :    * For garbage collected systems, do a synchronous collection pass.
     350                 :    * May be a no-op on other systems
     351                 :    *
     352                 :    * @return NS_OK if the method is successful
     353                 :    */
     354                 :   virtual void GC(js::gcreason::Reason aReason) = 0;
     355                 : 
     356                 :   /**
     357                 :    * Inform the context that a script was evaluated.
     358                 :    * A GC may be done if "necessary."
     359                 :    * This call is necessary if script evaluation is done
     360                 :    * without using the EvaluateScript method.
     361                 :    * @param aTerminated If true then call termination function if it was 
     362                 :    *    previously set. Within DOM this will always be true, but outside 
     363                 :    *    callers (such as xpconnect) who may do script evaluations nested
     364                 :    *    inside DOM script evaluations can pass false to avoid premature
     365                 :    *    calls to the termination function.
     366                 :    * @return NS_OK if the method is successful
     367                 :    */
     368                 :   virtual void ScriptEvaluated(bool aTerminated) = 0;
     369                 : 
     370                 :   virtual nsresult Serialize(nsIObjectOutputStream* aStream,
     371                 :                              JSScript* aScriptObject) = 0;
     372                 :   
     373                 :   /* Deserialize a script from a stream.
     374                 :    */
     375                 :   virtual nsresult Deserialize(nsIObjectInputStream* aStream,
     376                 :                                nsScriptObjectHolder<JSScript>& aResult) = 0;
     377                 : 
     378                 :   /**
     379                 :    * JS only - this function need not be implemented by languages other
     380                 :    * than JS (ie, this should be moved to a private interface!)
     381                 :    * Called to specify a function that should be called when the current
     382                 :    * script (if there is one) terminates. Generally used if breakdown
     383                 :    * of script state needs to happen, but should be deferred till
     384                 :    * the end of script evaluation.
     385                 :    *
     386                 :    * @throws NS_ERROR_OUT_OF_MEMORY if that happens
     387                 :    */
     388                 :   virtual void SetTerminationFunction(nsScriptTerminationFunc aFunc,
     389                 :                                       nsIDOMWindow* aRef) = 0;
     390                 : 
     391                 :   /**
     392                 :    * Called to disable/enable script execution in this context.
     393                 :    */
     394                 :   virtual bool GetScriptsEnabled() = 0;
     395                 :   virtual void SetScriptsEnabled(bool aEnabled, bool aFireTimeouts) = 0;
     396                 : 
     397                 :   // SetProperty is suspect and jst believes should not be needed.  Currenly
     398                 :   // used only for "arguments".
     399                 :   virtual nsresult SetProperty(JSObject* aTarget, const char* aPropName, nsISupports* aVal) = 0;
     400                 :   /** 
     401                 :    * Called to set/get information if the script context is
     402                 :    * currently processing a script tag
     403                 :    */
     404                 :   virtual bool GetProcessingScriptTag() = 0;
     405                 :   virtual void SetProcessingScriptTag(bool aResult) = 0;
     406                 : 
     407                 :   /**
     408                 :    * Called to find out if this script context might be executing script.
     409                 :    */
     410                 :   virtual bool GetExecutingScript() = 0;
     411                 : 
     412                 :   /**
     413                 :    * Tell the context whether or not to GC when destroyed.  An optimization
     414                 :    * used when the window is a [i]frame, so GC will happen anyway.
     415                 :    */
     416                 :   virtual void SetGCOnDestruction(bool aGCOnDestruction) = 0;
     417                 : 
     418                 :   /**
     419                 :    * Initialize DOM classes on aGlobalObj, always call
     420                 :    * WillInitializeContext() before calling InitContext(), and always
     421                 :    * call DidInitializeContext() when a context is fully
     422                 :    * (successfully) initialized.
     423                 :    */
     424                 :   virtual nsresult InitClasses(JSObject* aGlobalObj) = 0;
     425                 : 
     426                 :   /**
     427                 :    * Tell the context we're about to be reinitialize it.
     428                 :    */
     429                 :   virtual void WillInitializeContext() = 0;
     430                 : 
     431                 :   /**
     432                 :    * Tell the context we're done reinitializing it.
     433                 :    */
     434                 :   virtual void DidInitializeContext() = 0;
     435                 : 
     436                 :   /* Memory managment for script objects.  Used by the implementation of
     437                 :    * nsScriptObjectHolder to manage the lifetimes of the held script objects.
     438                 :    *
     439                 :    * See also nsIScriptRuntime, which has identical methods and is useful
     440                 :    * in situations when you do not have an nsIScriptContext.
     441                 :    * 
     442                 :    */
     443                 :   virtual nsresult DropScriptObject(void *object) = 0;
     444                 :   virtual nsresult HoldScriptObject(void *object) = 0;
     445                 : 
     446                 :   virtual void EnterModalState() = 0;
     447                 :   virtual void LeaveModalState() = 0;
     448                 : };
     449                 : 
     450                 : NS_DEFINE_STATIC_IID_ACCESSOR(nsIScriptContext, NS_ISCRIPTCONTEXT_IID)
     451                 : 
     452                 : #endif // nsIScriptContext_h__
     453                 : 

Generated by: LCOV version 1.7