The interface to the virtual machine.

Public Member Functions
Memory management
virtual int	AddRef ()=0
	Increase reference counter. More...

virtual int	Release ()=0
	Decrease reference counter. More...

Miscellaneous
virtual asIScriptEngine *	GetEngine ()=0
	Returns a pointer to the engine. More...

Execution
virtual int	Prepare (int funcId)=0
	Prepares the context for execution of the function identified by funcId. More...

virtual int	Unprepare ()=0
	Frees resources held by the context. More...

virtual int	SetObject (void *obj)=0
	Sets the object for a class method call. 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 ()=0
	Returns the state of the context. 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 *	GetArgPointer (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)=0
	Returns the line number where the exception occurred. More...

virtual int	GetExceptionFunction ()=0
	Returns the function id of 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 int	GetCurrentLineNumber (int *column=0)=0
	Get the current line number that is being executed. More...

virtual int	GetCurrentFunction ()=0
	Get the current function that is being executed. More...

virtual int	GetCallstackSize ()=0
	Returns the size of the callstack, i.e. the number of functions that have yet to complete. More...

virtual int	GetCallstackFunction (int index)=0
	Returns the function id at the specified callstack level. More...

virtual int	GetCallstackLineNumber (int index, int *column=0)=0
	Returns the line number at the specified callstack level. More...

virtual int	GetVarCount (int stackLevel=-1)=0
	Returns the number of local variables at the specified callstack level. More...

virtual const char *	GetVarName (int varIndex, int stackLevel=-1)=0
	Returns the name of local variable at the specified callstack level. More...

virtual const char *	GetVarDeclaration (int varIndex, int stackLevel=-1)=0
	Returns the declaration of a local variable at the specified callstack level. More...

virtual int	GetVarTypeId (int varIndex, int stackLevel=-1)=0
	Returns the type id of a local variable at the specified callstack level. More...

virtual void *	GetAddressOfVar (int varIndex, int stackLevel=-1)=0
	Returns a pointer to a local variable at the specified callstack level. More...

virtual int	GetThisTypeId (int stackLevel=-1)=0
	Returns the type id of the object, if a class method is being executed. More...

virtual void *	GetThisPointer (int stackLevel=-1)=0
	Returns a pointer to the object, if a class method is being executed. More...

User data
virtual void *	SetUserData (void *data)=0
	Register the memory address of some user data. More...

virtual void *	GetUserData ()=0
	Returns the address of the previously registered user data. More...

Deprecated
virtual void *	GetReturnPointer ()=0

virtual void *	GetVarPointer (int varIndex, int stackLevel=-1)=0

Member Function Documentation

virtual int asIScriptContext::Abort ( )

pure virtual

Returns: A negative value on error.

Return values

asERROR Invalid context object.

Aborts the current execution of a script.

virtual int asIScriptContext::AddRef ( )

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

asERROR	Invalid context object, the context is not prepared, or it is not in suspended state.
asEXECUTION_ABORTED	The execution was aborted with a call to Abort.
asEXECUTION_SUSPENDED	The execution was suspended with a call to Suspend.
asEXECUTION_FINISHED	The execution finished successfully.
asEXECUTION_EXCEPTION	The 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.

See Also: Calling a script function

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	(	int	varIndex,
		int	stackLevel = `-1`
	)

pure virtual

Parameters

[in]	varIndex	The index of the variable.
[in]	stackLevel	The 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 void* asIScriptContext::GetArgPointer ( asUINT arg )

pure virtual

Parameters

[in] arg The 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 int asIScriptContext::GetCallstackFunction ( int index )

pure virtual

Parameters

[in] index The index on the call stack.

Returns: The function id on the call stack referred to by the index.

virtual int asIScriptContext::GetCallstackLineNumber	(	int	index,
		int *	column = `0`
	)

pure virtual

Parameters

[in]	index	The index on the call stack.
[out]	column	The variable will receive the column number.

Returns: The line number for the call stack level referred to by the index.

virtual int asIScriptContext::GetCallstackSize ( )

pure virtual

Returns: The number of functions on the call stack.

This methods returns the size of the callstack, i.e. how many parent functions there are above the current functions being called. 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 int asIScriptContext::GetCurrentFunction ( )

pure virtual

Returns: The function id of the current function.

virtual int asIScriptContext::GetCurrentLineNumber ( int * column = 0 )

pure virtual

Parameters

[out] column The variable will receive the column number.

Returns: The current line number.

This method returns the line number where the context is currently located. The line number is relative to the script section where the function was implemented.

virtual asIScriptEngine* asIScriptContext::GetEngine ( )

pure virtual

Returns: A pointer to the engine.

virtual int asIScriptContext::GetExceptionFunction ( )

pure virtual

Returns: The function id where the exception occurred.

virtual int asIScriptContext::GetExceptionLineNumber ( int * column = 0 )

pure virtual

Parameters

[out] column The variable will receive the column number.

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.

virtual const char* asIScriptContext::GetExceptionString ( )

pure virtual

Returns: A null terminated string describing the exception that occurred.

virtual void* asIScriptContext::GetReturnAddress ( )

pure virtual

Returns: The address value returned from the script function, or 0 on error.

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.

virtual void* asIScriptContext::GetReturnPointer ( )

pure virtual

Deprecated:: Since 2.15.0. Use GetAddressOfReturnValue instead.

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 ( )

pure virtual

Returns: The current state of the context.

virtual void* asIScriptContext::GetThisPointer ( int stackLevel = -1 )

pure virtual

Parameters

[in] stackLevel The index on the call stack.

Returns: Returns a pointer to the object if it is a class method.

virtual int asIScriptContext::GetThisTypeId ( int stackLevel = -1 )

pure virtual

Parameters

[in] stackLevel The index on the call stack.

Returns: Returns the type id of the object if it is a class method.

virtual void* asIScriptContext::GetUserData ( )

pure virtual

Returns: The pointer to the user data.

virtual int asIScriptContext::GetVarCount ( int stackLevel = -1 )

pure virtual

Parameters

[in] stackLevel The index on the call stack.

Returns: The number of variables in the function on the call stack level.

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

virtual const char* asIScriptContext::GetVarDeclaration	(	int	varIndex,
		int	stackLevel = `-1`
	)

pure virtual

Parameters

[in]	varIndex	The index of the variable.
[in]	stackLevel	The index on the call stack.

Returns: A null terminated string with the declaration of the variable.

virtual const char* asIScriptContext::GetVarName	(	int	varIndex,
		int	stackLevel = `-1`
	)

pure virtual

Parameters

[in]	varIndex	The index of the variable.
[in]	stackLevel	The index on the call stack.

Returns: A null terminated string with the name of the variable.

virtual void* asIScriptContext::GetVarPointer	(	int	varIndex,
		int	stackLevel = `-1`
	)

pure virtual

Deprecated:: Since 2.15.0. Use GetAddressOfVar instead.

virtual int asIScriptContext::GetVarTypeId	(	int	varIndex,
		int	stackLevel = `-1`
	)

pure virtual

Parameters

[in]	varIndex	The index of the variable.
[in]	stackLevel	The index on the call stack.

Returns: The type id of the variable, or a negative value on error.

Return values

asINVALID_ARG The index or stack level is invalid.

virtual int asIScriptContext::Prepare ( int funcId )

pure virtual

Parameters

[in] funcId The id of the function/method that will be executed.

Returns: A negative value on error.

Return values

asCONTEXT_ACTIVE	The context is still active or suspended.
asNO_FUNCTION	The function id doesn't exist.

This method prepares the context for execution 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::Release ( )

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]	arg	The argument index.
[in]	addr	The address that should be passed in the argument.

Returns: A negative value on error.

Return values

asCONTEXT_NOT_PREPARED	The context is not in prepared state.
asINVALID_ARG	The arg is larger than the number of arguments in the prepared function.
asINVALID_TYPE	The 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]	arg	The argument index.
[in]	value	The value of the argument.

Returns: A negative value on error.

Return values

asCONTEXT_NOT_PREPARED	The context is not in prepared state.
asINVALID_ARG	The arg is larger than the number of arguments in the prepared function.
asINVALID_TYPE	The argument is not an 8-bit value.

Sets a 1 byte argument.

virtual int asIScriptContext::SetArgDouble	(	asUINT	arg,
		double	value
	)

pure virtual

Parameters

[in]	arg	The argument index.
[in]	value	The value of the argument.

Returns: A negative value on error.

Return values

asCONTEXT_NOT_PREPARED	The context is not in prepared state.
asINVALID_ARG	The arg is larger than the number of arguments in the prepared function.
asINVALID_TYPE	The argument is not a 64-bit value.

Sets a double argument.

virtual int asIScriptContext::SetArgDWord	(	asUINT	arg,
		asDWORD	value
	)

pure virtual

Parameters

[in]	arg	The argument index.
[in]	value	The value of the argument.

Returns: A negative value on error.

Return values

asCONTEXT_NOT_PREPARED	The context is not in prepared state.
asINVALID_ARG	The arg is larger than the number of arguments in the prepared function.
asINVALID_TYPE	The argument is not a 32-bit value.

Sets a 4 byte argument.

virtual int asIScriptContext::SetArgFloat	(	asUINT	arg,
		float	value
	)

pure virtual

Parameters

[in]	arg	The argument index.
[in]	value	The value of the argument.

Returns: A negative value on error.

Return values

asCONTEXT_NOT_PREPARED	The context is not in prepared state.
asINVALID_ARG	The arg is larger than the number of arguments in the prepared function.
asINVALID_TYPE	The argument is not a 32-bit value.

Sets a float argument.

virtual int asIScriptContext::SetArgObject	(	asUINT	arg,
		void *	obj
	)

pure virtual

Parameters

[in]	arg	The argument index.
[in]	obj	A pointer to the object.

Returns: A negative value on error.

Return values

asCONTEXT_NOT_PREPARED	The context is not in prepared state.
asINVALID_ARG	The arg is larger than the number of arguments in the prepared function.
asINVALID_TYPE	The 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]	arg	The argument index.
[in]	value	The value of the argument.

Returns: A negative value on error.

Return values

asCONTEXT_NOT_PREPARED	The context is not in prepared state.
asINVALID_ARG	The arg is larger than the number of arguments in the prepared function.
asINVALID_TYPE	The argument is not a 64-bit value.

Sets an 8 byte argument.

virtual int asIScriptContext::SetArgWord	(	asUINT	arg,
		asWORD	value
	)

pure virtual

Parameters

[in]	arg	The argument index.
[in]	value	The value of the argument.

Returns: A negative value on error.

Return values

asCONTEXT_NOT_PREPARED	The context is not in prepared state.
asINVALID_ARG	The arg is larger than the number of arguments in the prepared function.
asINVALID_TYPE	The argument is not a 16-bit value.

Sets a 2 byte argument.

virtual int asIScriptContext::SetException ( const char * string )

pure virtual

Parameters

[in] string A string that describes the exception that occurred.

Returns: A negative value on error.

Return values

asERROR The 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]	callback	The callback function/method that should be called upon an exception.
[in]	obj	The object pointer on which the callback is called.
[in]	callConv	The calling convention of the callback function/method.

Returns: A negative value on error.

Return values

asNOT_SUPPORTED	Calling convention must not be asCALL_GENERIC, or the routine's calling convention is not supported.
asINVALID_ARG	obj must not be null for class methods.
asWRONG_CALLING_CONV	callConv 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]	callback	The callback function/method that should be called for each script line executed.
[in]	obj	The object pointer on which the callback is called.
[in]	callConv	The calling convention of the callback function/method.

Returns: A negative value on error.

Return values

asNOT_SUPPORTED	Calling convention must not be asCALL_GENERIC, or the routine's calling convention is not supported.
asINVALID_ARG	obj must not be null for class methods.
asWRONG_CALLING_CONV	callConv 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] obj A pointer to the object.

Returns: A negative value on error.

Return values

asCONTEXT_NOT_PREPARED	The context is not in prepared state.
asERROR	The prepared function is not a class method.

This method sets object pointer when calling class methods.

virtual void* asIScriptContext::SetUserData ( void * data )

pure virtual

Parameters

[in] data A pointer to the user data.

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.

virtual int asIScriptContext::Suspend ( )

pure virtual

Returns: A negative value on error.

Return values

asERROR Invalid 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_ACTIVE The 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.

Public Member Functions

Member Function Documentation