AngelScript
asIScriptContext Class Referenceabstract

The interface to the virtual machine. More...

Public Member Functions

Memory management
virtual int AddRef () const =0
 Increase reference counter. More...
 
virtual int Release () const =0
 Decrease reference counter. More...
 
Miscellaneous
virtual asIScriptEngineGetEngine () const =0
 Returns a pointer to the engine. More...
 
Execution
virtual int Prepare (asIScriptFunction *func)=0
 Prepares the context for execution of the function. More...
 
virtual int Unprepare ()=0
 Frees resources held by the context. More...
 
virtual int Execute ()=0
 Executes the prepared function. More...
 
virtual int Abort ()=0
 Aborts the execution. More...
 
virtual int Suspend ()=0
 Suspends the execution, which can then be resumed by calling Execute again. More...
 
virtual asEContextState GetState () const =0
 Returns the state of the context. More...
 
virtual int PushState ()=0
 Backups the current state to prepare the context for a nested call. More...
 
virtual int PopState ()=0
 Restores the state to resume previous script execution. More...
 
virtual bool IsNested (asUINT *nestCount=0) const =0
 Returns true if the context has any nested calls. More...
 
Object pointer for calling class methods
virtual int SetObject (void *obj)=0
 Sets the object for a class method call. More...
 
Arguments
virtual int SetArgByte (asUINT arg, asBYTE value)=0
 Sets an 8-bit argument value. More...
 
virtual int SetArgWord (asUINT arg, asWORD value)=0
 Sets a 16-bit argument value. More...
 
virtual int SetArgDWord (asUINT arg, asDWORD value)=0
 Sets a 32-bit integer argument value. More...
 
virtual int SetArgQWord (asUINT arg, asQWORD value)=0
 Sets a 64-bit integer argument value. More...
 
virtual int SetArgFloat (asUINT arg, float value)=0
 Sets a float argument value. More...
 
virtual int SetArgDouble (asUINT arg, double value)=0
 Sets a double argument value. More...
 
virtual int SetArgAddress (asUINT arg, void *addr)=0
 Sets the address of a reference or handle argument. More...
 
virtual int SetArgObject (asUINT arg, void *obj)=0
 Sets the object argument value. More...
 
virtual void * GetAddressOfArg (asUINT arg)=0
 Returns a pointer to the argument for assignment. More...
 
Return value
virtual asBYTE GetReturnByte ()=0
 Returns the 8-bit return value. More...
 
virtual asWORD GetReturnWord ()=0
 Returns the 16-bit return value. More...
 
virtual asDWORD GetReturnDWord ()=0
 Returns the 32-bit return value. More...
 
virtual asQWORD GetReturnQWord ()=0
 Returns the 64-bit return value. More...
 
virtual float GetReturnFloat ()=0
 Returns the float return value. More...
 
virtual double GetReturnDouble ()=0
 Returns the double return value. More...
 
virtual void * GetReturnAddress ()=0
 Returns the address for a reference or handle return type. More...
 
virtual void * GetReturnObject ()=0
 Return a pointer to the returned object. More...
 
virtual void * GetAddressOfReturnValue ()=0
 Returns the address of the returned value. More...
 
Exception handling
virtual int SetException (const char *string)=0
 Sets an exception, which aborts the execution. More...
 
virtual int GetExceptionLineNumber (int *column=0, const char **sectionName=0)=0
 Returns the line number where the exception occurred. More...
 
virtual asIScriptFunctionGetExceptionFunction ()=0
 Returns the function where the exception occurred. More...
 
virtual const char * GetExceptionString ()=0
 Returns the exception string text. More...
 
virtual int SetExceptionCallback (asSFuncPtr callback, void *obj, int callConv)=0
 Sets an exception callback function. The function will be called if a script exception occurs. More...
 
virtual void ClearExceptionCallback ()=0
 
Debugging
virtual int SetLineCallback (asSFuncPtr callback, void *obj, int callConv)=0
 Sets a line callback function. The function will be called for each executed script statement. More...
 
virtual void ClearLineCallback ()=0
 
virtual asUINT GetCallstackSize () const =0
 Returns the size of the callstack, i.e. the number of functions that have yet to complete. More...
 
virtual asIScriptFunctionGetFunction (asUINT stackLevel=0)=0
 Returns the function at the specified callstack level. More...
 
virtual int GetLineNumber (asUINT stackLevel=0, int *column=0, const char **sectionName=0)=0
 Returns the line number at the specified callstack level. More...
 
virtual int GetVarCount (asUINT stackLevel=0)=0
 Returns the number of local variables at the specified callstack level. More...
 
virtual const char * GetVarName (asUINT varIndex, asUINT stackLevel=0)=0
 Returns the name of local variable at the specified callstack level. More...
 
virtual const char * GetVarDeclaration (asUINT varIndex, asUINT stackLevel=0, bool includeNamespace=false)=0
 Returns the declaration of a local variable at the specified callstack level. More...
 
virtual int GetVarTypeId (asUINT varIndex, asUINT stackLevel=0)=0
 Returns the type id of a local variable at the specified callstack level. More...
 
virtual void * GetAddressOfVar (asUINT varIndex, asUINT stackLevel=0)=0
 Returns a pointer to a local variable at the specified callstack level. More...
 
virtual bool IsVarInScope (asUINT varIndex, asUINT stackLevel=0)=0
 Informs whether the variable is in scope at the current program position. More...
 
virtual int GetThisTypeId (asUINT stackLevel=0)=0
 Returns the type id of the object, if a class method is being executed. More...
 
virtual void * GetThisPointer (asUINT stackLevel=0)=0
 Returns a pointer to the object, if a class method is being executed. More...
 
virtual asIScriptFunctionGetSystemFunction ()=0
 Returns the registered function that is currently being called by the context. More...
 
User data
virtual void * SetUserData (void *data, asPWORD type=0)=0
 Register the memory address of some user data. More...
 
virtual void * GetUserData (asPWORD type=0) const =0
 Returns the address of the previously registered user data. More...
 

Detailed Description

The script context provides the interface for a single script execution. The object stores the call stack where the local variables used by the execution are kept, however it doesn't keep copies of global variables as these are stored in the asIScriptModule, and only referenced by the context.

The value stored in a global variable is shared between all contexts, as they all refer to the same memory. This means that the global variables outlive the execution of a script, and will keep their values between executions.

It is seldom necessary to maintain more than one script context at a time, with the only exceptions being when a script calls an application function that in turn calls another script before returning, and if multiple scripts are running in parallel.

Try to avoid associating a unique context with each object that may need to call scripts. Instead keep a shared pool of contexts that can be requested by the objects on a need-to basis.

Member Function Documentation

virtual int asIScriptContext::Abort ( )
pure virtual
Returns
A negative value on error.
Return values
asERRORInvalid context object.

Aborts the current execution of a script.

virtual int asIScriptContext::AddRef ( ) const
pure virtual
Returns
The number of references to this object.

Call this method when storing an additional reference to the object. Remember that the first reference that is received from asIScriptEngine::CreateContext is already accounted for.

virtual void asIScriptContext::ClearExceptionCallback ( )
pure virtual

Removes a previously registered callback.

virtual void asIScriptContext::ClearLineCallback ( )
pure virtual

Removes a previously registered callback.

virtual int asIScriptContext::Execute ( )
pure virtual
Returns
A negative value on error, or one of asEContextState.
Return values
asCONTEXT_NOT_PREPAREDThe context is not prepared or it is not in suspended state.
asEXECUTION_ABORTEDThe execution was aborted with a call to Abort.
asEXECUTION_SUSPENDEDThe execution was suspended with a call to Suspend.
asEXECUTION_FINISHEDThe execution finished successfully.
asEXECUTION_EXCEPTIONThe execution ended with an exception.

Executes the prepared function until the script returns. If the execution was previously suspended the function resumes where it left of.

Note that if the script freezes, e.g. if trapped in a never ending loop, you may call Abort from another thread to stop execution.

If the function returns asEXECUTION_EXCEPTION, use the GetExceptionString, GetExceptionFunction, and GetExceptionLineNumber to obtain more information on the exception and where it occurred.

See Also
Calling a script function
virtual void* asIScriptContext::GetAddressOfArg ( asUINT  arg)
pure virtual
Parameters
[in]argThe argument index.
Returns
A pointer to the argument on the stack.

This method returns a pointer to the argument on the stack for assignment. For object handles, you should increment the reference counter. For object values, you should pass a pointer to a copy of the object.

virtual void* asIScriptContext::GetAddressOfReturnValue ( )
pure virtual
Returns
A pointer to the return value returned from the script function, or 0 on error.
virtual void* asIScriptContext::GetAddressOfVar ( asUINT  varIndex,
asUINT  stackLevel = 0 
)
pure virtual
Parameters
[in]varIndexThe index of the variable.
[in]stackLevelThe index on the call stack.
Returns
A pointer to the variable.

Returns a pointer to the variable, so that its value can be read and written. The address is valid until the script function returns.

Note that object variables may not be initalized at all moments, thus you must verify if the address returned points to a null pointer, before you try to dereference it.

virtual asUINT asIScriptContext::GetCallstackSize ( ) const
pure virtual
Returns
The number of functions on the call stack, including the current function.

This methods returns the size of the callstack. It can be used to enumerate the callstack in order to generate a detailed report when an exception occurs, or for debugging running scripts.

virtual asIScriptEngine* asIScriptContext::GetEngine ( ) const
pure virtual
Returns
A pointer to the engine.
virtual asIScriptFunction* asIScriptContext::GetExceptionFunction ( )
pure virtual
Returns
The function where the exception occurred.
virtual int asIScriptContext::GetExceptionLineNumber ( int *  column = 0,
const char **  sectionName = 0 
)
pure virtual
Parameters
[out]columnThe variable will receive the column number.
[out]sectionNameThe variable will receive the name of the script section.
Returns
The line number where the exception occurred.

This method returns the line number where the exception ocurred. The line number is relative to the script section where the function was implemented.

Observe that the returned sectionName can be null, e.g. if the function in which the exception occurred was a generated stub function.

virtual const char* asIScriptContext::GetExceptionString ( )
pure virtual
Returns
A null terminated string describing the exception that occurred.
virtual asIScriptFunction* asIScriptContext::GetFunction ( asUINT  stackLevel = 0)
pure virtual
Parameters
[in]stackLevelThe index on the call stack.
Returns
The function descriptor on the call stack referred to by the index.

Index 0 refers to the current function, index 1 to the calling function, and so on. The highest index is the originating function that the application called.

The returned value will be null if the stackLevel is invalid, or if the requested stack level doesn't have a defined function. The latter scenario happens when the engine performs a nested call internally, e.g. to call a constructor for a script object indirectly created.

If the application performs a nested call, then the returned value will give the application registered function that was called by the previous script.

See Also
PushState
virtual int asIScriptContext::GetLineNumber ( asUINT  stackLevel = 0,
int *  column = 0,
const char **  sectionName = 0 
)
pure virtual
Parameters
[in]stackLevelThe index on the call stack.
[out]columnThe variable will receive the column number.
[out]sectionNameThe variable will receive the name of the script section.
Returns
The line number for the call stack level referred to by the index.

This function returns the line number, and optionally the column number and the name of the script section where the program is current at.

The sectionName pointer will point to an internal buffer, so do not deallocate it. If the function doesn't have any debug info sectionName will be set to null.

virtual void* asIScriptContext::GetReturnAddress ( )
pure virtual
Returns
The address value returned from the script function, or 0 on error.

The method doesn't increase the reference counter with this call, so if you store the pointer of a reference counted object you need to increase the reference manually otherwise the object will be released when the context is released or reused.

virtual asBYTE asIScriptContext::GetReturnByte ( )
pure virtual
Returns
The 1 byte value returned from the script function, or 0 on error.
virtual double asIScriptContext::GetReturnDouble ( )
pure virtual
Returns
The double value returned from the script function, or 0 on error.
virtual asDWORD asIScriptContext::GetReturnDWord ( )
pure virtual
Returns
The 4 byte value returned from the script function, or 0 on error.
virtual float asIScriptContext::GetReturnFloat ( )
pure virtual
Returns
The float value returned from the script function, or 0 on error.
virtual void* asIScriptContext::GetReturnObject ( )
pure virtual
Returns
A pointer to the object returned from the script function, or 0 on error.

The method doesn't increase the reference counter with this call, so if you store the pointer of a reference counted object you need to increase the reference manually otherwise the object will be released when the context is released or reused.

virtual asQWORD asIScriptContext::GetReturnQWord ( )
pure virtual
Returns
The 8 byte value returned from the script function, or 0 on error.
virtual asWORD asIScriptContext::GetReturnWord ( )
pure virtual
Returns
The 2 byte value returned from the script function, or 0 on error.
virtual asEContextState asIScriptContext::GetState ( ) const
pure virtual
Returns
The current state of the context.
virtual asIScriptFunction* asIScriptContext::GetSystemFunction ( )
pure virtual
Returns
Returns the registered function that is currently being called, or null if no registered function is being called at the moment.
virtual void* asIScriptContext::GetThisPointer ( asUINT  stackLevel = 0)
pure virtual
Parameters
[in]stackLevelThe index on the call stack.
Returns
Returns a pointer to the object if it is a class method.
virtual int asIScriptContext::GetThisTypeId ( asUINT  stackLevel = 0)
pure virtual
Parameters
[in]stackLevelThe index on the call stack.
Returns
Returns the type id of the object if it is a class method.
virtual void* asIScriptContext::GetUserData ( asPWORD  type = 0) const
pure virtual
Parameters
[in]typeAn identifier specifying the user data to set.
Returns
The pointer to the user data.
virtual int asIScriptContext::GetVarCount ( asUINT  stackLevel = 0)
pure virtual
Parameters
[in]stackLevelThe index on the call stack.
Returns
The number of variables in the function on the call stack level. Or negative value on error.
Return values
asINVALID_ARGThe stackLevel is invalid.

Returns the number of declared variables, including the parameters, in the function on the stack.

virtual const char* asIScriptContext::GetVarDeclaration ( asUINT  varIndex,
asUINT  stackLevel = 0,
bool  includeNamespace = false 
)
pure virtual
Parameters
[in]varIndexThe index of the variable.
[in]stackLevelThe index on the call stack.
[in]includeNamespaceSet to true if the namespace should be included in the declaration.
Returns
A null terminated string with the declaration of the variable.
virtual const char* asIScriptContext::GetVarName ( asUINT  varIndex,
asUINT  stackLevel = 0 
)
pure virtual
Parameters
[in]varIndexThe index of the variable.
[in]stackLevelThe index on the call stack.
Returns
A null terminated string with the name of the variable.
virtual int asIScriptContext::GetVarTypeId ( asUINT  varIndex,
asUINT  stackLevel = 0 
)
pure virtual
Parameters
[in]varIndexThe index of the variable.
[in]stackLevelThe index on the call stack.
Returns
The type id of the variable, or a negative value on error.
Return values
asINVALID_ARGThe index or stack level is invalid.
virtual bool asIScriptContext::IsNested ( asUINT nestCount = 0) const
pure virtual
Parameters
[out]nestCountThis argument receives the nesting level.
Returns
true if there are any nested calls.
virtual bool asIScriptContext::IsVarInScope ( asUINT  varIndex,
asUINT  stackLevel = 0 
)
pure virtual
Parameters
[in]varIndexThe index of the variable.
[in]stackLevelThe index on the call stack.
Returns
True if variable is in scope.

This method can be used to determine if a variable is currently visible from the current program position. This is especially useful if multiple variables with the same name is declared in different scopes.

virtual int asIScriptContext::PopState ( )
pure virtual
Returns
A negative value on error.
Return values
asERRORThe state couldn't be restored.
virtual int asIScriptContext::Prepare ( asIScriptFunction func)
pure virtual
Parameters
[in]funcThe id of the function/method that will be executed.
Returns
A negative value on error.
Return values
asCONTEXT_ACTIVEThe context is still active or suspended.
asNO_FUNCTIONThe function pointer is null.
asINVALID_ARGThe function is from a different engine than the context.
asOUT_OF_MEMORYThe context ran out of memory while allocating call stack.

This method prepares the context for executeion of a script function. It allocates the stack space required and reserves space for return value and parameters. The default value for parameters and return value is 0.

See Also
Calling a script function
virtual int asIScriptContext::PushState ( )
pure virtual
Returns
A negative value on error.
Return values
asERRORThe state couldn't be pushed.

This method can be invoked on an active context in order to reuse the context for a nested call, e.g. when a function called by a script needs to call another script before returning. After the method returns with success the method Prepare() shall be invoked to prepare the new execution.

By reusing an active context the application can avoid creating a temporary context, and thus improve the run time performance.

For each successful call to PushState() the method PopState() must be called to return the state in order to resume the previous script execution.

virtual int asIScriptContext::Release ( ) const
pure virtual
Returns
The number of references to this object.

Call this method when you will no longer use the references that you own.

virtual int asIScriptContext::SetArgAddress ( asUINT  arg,
void *  addr 
)
pure virtual
Parameters
[in]argThe argument index.
[in]addrThe address that should be passed in the argument.
Returns
A negative value on error.
Return values
asCONTEXT_NOT_PREPAREDThe context is not in prepared state.
asINVALID_ARGThe arg is larger than the number of arguments in the prepared function.
asINVALID_TYPEThe argument is not a reference or an object handle.

Sets an address argument, e.g. an object handle or a reference.

virtual int asIScriptContext::SetArgByte ( asUINT  arg,
asBYTE  value 
)
pure virtual
Parameters
[in]argThe argument index.
[in]valueThe value of the argument.
Returns
A negative value on error.
Return values
asCONTEXT_NOT_PREPAREDThe context is not in prepared state.
asINVALID_ARGThe arg is larger than the number of arguments in the prepared function.
asINVALID_TYPEThe argument is not an 8-bit value.

Sets a 1 byte argument.

virtual int asIScriptContext::SetArgDouble ( asUINT  arg,
double  value 
)
pure virtual
Parameters
[in]argThe argument index.
[in]valueThe value of the argument.
Returns
A negative value on error.
Return values
asCONTEXT_NOT_PREPAREDThe context is not in prepared state.
asINVALID_ARGThe arg is larger than the number of arguments in the prepared function.
asINVALID_TYPEThe argument is not a 64-bit value.

Sets a double argument.

virtual int asIScriptContext::SetArgDWord ( asUINT  arg,
asDWORD  value 
)
pure virtual
Parameters
[in]argThe argument index.
[in]valueThe value of the argument.
Returns
A negative value on error.
Return values
asCONTEXT_NOT_PREPAREDThe context is not in prepared state.
asINVALID_ARGThe arg is larger than the number of arguments in the prepared function.
asINVALID_TYPEThe argument is not a 32-bit value.

Sets a 4 byte argument.

virtual int asIScriptContext::SetArgFloat ( asUINT  arg,
float  value 
)
pure virtual
Parameters
[in]argThe argument index.
[in]valueThe value of the argument.
Returns
A negative value on error.
Return values
asCONTEXT_NOT_PREPAREDThe context is not in prepared state.
asINVALID_ARGThe arg is larger than the number of arguments in the prepared function.
asINVALID_TYPEThe argument is not a 32-bit value.

Sets a float argument.

virtual int asIScriptContext::SetArgObject ( asUINT  arg,
void *  obj 
)
pure virtual
Parameters
[in]argThe argument index.
[in]objA pointer to the object.
Returns
A negative value on error.
Return values
asCONTEXT_NOT_PREPAREDThe context is not in prepared state.
asINVALID_ARGThe arg is larger than the number of arguments in the prepared function.
asINVALID_TYPEThe argument is not an object or handle.

Sets an object argument. If the argument is an object handle AngelScript will increment the reference for the object. If the argument is an object value AngelScript will make a copy of the object.

virtual int asIScriptContext::SetArgQWord ( asUINT  arg,
asQWORD  value 
)
pure virtual
Parameters
[in]argThe argument index.
[in]valueThe value of the argument.
Returns
A negative value on error.
Return values
asCONTEXT_NOT_PREPAREDThe context is not in prepared state.
asINVALID_ARGThe arg is larger than the number of arguments in the prepared function.
asINVALID_TYPEThe argument is not a 64-bit value.

Sets an 8 byte argument.

virtual int asIScriptContext::SetArgWord ( asUINT  arg,
asWORD  value 
)
pure virtual
Parameters
[in]argThe argument index.
[in]valueThe value of the argument.
Returns
A negative value on error.
Return values
asCONTEXT_NOT_PREPAREDThe context is not in prepared state.
asINVALID_ARGThe arg is larger than the number of arguments in the prepared function.
asINVALID_TYPEThe argument is not a 16-bit value.

Sets a 2 byte argument.

virtual int asIScriptContext::SetException ( const char *  string)
pure virtual
Parameters
[in]stringA string that describes the exception that occurred.
Returns
A negative value on error.
Return values
asERRORThe context isn't currently calling an application registered function.

This method sets a script exception in the context. This will only work if the context is currently calling a system function, thus this method can only be used for system functions.

Note that if your system function sets an exception, it should not return any object references because the engine will not release the returned reference.

virtual int asIScriptContext::SetExceptionCallback ( asSFuncPtr  callback,
void *  obj,
int  callConv 
)
pure virtual
Parameters
[in]callbackThe callback function/method that should be called upon an exception.
[in]objThe object pointer on which the callback is called.
[in]callConvThe calling convention of the callback function/method.
Returns
A negative value on error.
Return values
asNOT_SUPPORTEDCalling convention must not be asCALL_GENERIC, or the routine's calling convention is not supported.
asINVALID_ARGobj must not be null for class methods.
asWRONG_CALLING_CONVcallConv isn't compatible with the routines' calling convention.

This callback function will be called by the VM when a script exception is raised, which allow the application to examine the callstack and generate a detailed report before the callstack is cleaned up.

See SetLineCallback for details on the calling convention.

virtual int asIScriptContext::SetLineCallback ( asSFuncPtr  callback,
void *  obj,
int  callConv 
)
pure virtual
Parameters
[in]callbackThe callback function/method that should be called for each script line executed.
[in]objThe object pointer on which the callback is called.
[in]callConvThe calling convention of the callback function/method.
Returns
A negative value on error.
Return values
asNOT_SUPPORTEDCalling convention must not be asCALL_GENERIC, or the routine's calling convention is not supported.
asINVALID_ARGobj must not be null for class methods.
asWRONG_CALLING_CONVcallConv isn't compatible with the routines' calling convention.

This function sets a callback function that will be called by the VM each time the SUSPEND instruction is encounted. Generally this instruction is placed before each statement. Thus by setting this callback function it is possible to monitor the execution, and suspend the execution at application defined locations.

The callback function can be either a global function or a class method. For a global function the VM will pass two parameters, first the context pointer and then the object pointer specified by the application. For a class method, the VM will call the method using the object pointer as the owner.

void Callback(asIScriptContext *ctx, void *obj);
void Object::Callback(asIScriptContext *ctx);

The global function can use either asCALL_CDECL or asCALL_STDCALL, and the class method can use either asCALL_THISCALL, asCALL_CDECL_OBJLAST, or asCALL_CDECL_OBJFIRST.

See Also
Debugging scripts
virtual int asIScriptContext::SetObject ( void *  obj)
pure virtual
Parameters
[in]objA pointer to the object.
Returns
A negative value on error.
Return values
asCONTEXT_NOT_PREPAREDThe context is not in prepared state.
asERRORThe prepared function is not a class method.

This method sets object pointer when calling class methods.

virtual void* asIScriptContext::SetUserData ( void *  data,
asPWORD  type = 0 
)
pure virtual
Parameters
[in]dataA pointer to the user data.
[in]typeAn identifier specifying the user data to set.
Returns
The previous pointer stored in the context.

This method allows the application to associate a value, e.g. a pointer, with the context instance.

The type values 1000 through 1999 are reserved for use by the official add-ons.

Optionally, a callback function can be registered to clean up the user data when the context is destroyed. As the callback is registered with the engine, it is only necessary to do it once, even if more than one context is used.

virtual int asIScriptContext::Suspend ( )
pure virtual
Returns
A negative value on error.
Return values
asERRORInvalid context object.

Suspends the current execution of a script. The execution can then be resumed by calling Execute again.

See Also
Calling a script function
virtual int asIScriptContext::Unprepare ( )
pure virtual
Returns
A negative value on error.
Return values
asCONTEXT_ACTIVEThe context is still active or suspended.

This function frees resources held by the context. It's usually not necessary to call this function as the resources are automatically freed when the context is released, or reused when Prepare is called again.


The documentation for this class was generated from the following file: