The interface to the virtual machine. More...

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

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

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

Execution
virtual int	Prepare (asIScriptFunction *func)=0
	Prepares the context for execution of the function.

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

virtual int	Execute ()=0
	Executes the prepared function.

virtual int	Abort ()=0
	Aborts the execution.

virtual int	Suspend ()=0
	Suspends the execution, which can then be resumed by calling Execute again.

virtual asEContextState	GetState () const =0
	Returns the state of the context.

virtual int	PushState ()=0
	Backups the current state to prepare the context for a nested call.

virtual int	PopState ()=0
	Restores the state to resume previous script execution.

virtual bool	IsNested (asUINT *nestCount=0) const =0
	Returns true if the context has any nested calls.

Object pointer for calling class methods
virtual int	SetObject (void *obj)=0
	Sets the object for a class method call.

Arguments
virtual int	SetArgByte (asUINT arg, asBYTE value)=0
	Sets an 8-bit argument value.

virtual int	SetArgWord (asUINT arg, asWORD value)=0
	Sets a 16-bit argument value.

virtual int	SetArgDWord (asUINT arg, asDWORD value)=0
	Sets a 32-bit integer argument value.

virtual int	SetArgQWord (asUINT arg, asQWORD value)=0
	Sets a 64-bit integer argument value.

virtual int	SetArgFloat (asUINT arg, float value)=0
	Sets a float argument value.

virtual int	SetArgDouble (asUINT arg, double value)=0
	Sets a double argument value.

virtual int	SetArgAddress (asUINT arg, void *addr)=0
	Sets the address of a reference or handle argument.

virtual int	SetArgObject (asUINT arg, void *obj)=0
	Sets the object argument value.

virtual int	SetArgVarType (asUINT arg, void *ptr, int typeId)=0
	Sets the variable argument value and type.

virtual void *	GetAddressOfArg (asUINT arg)=0
	Returns a pointer to the argument for assignment.

Return value
virtual asBYTE	GetReturnByte ()=0
	Returns the 8-bit return value.

virtual asWORD	GetReturnWord ()=0
	Returns the 16-bit return value.

virtual asDWORD	GetReturnDWord ()=0
	Returns the 32-bit return value.

virtual asQWORD	GetReturnQWord ()=0
	Returns the 64-bit return value.

virtual float	GetReturnFloat ()=0
	Returns the float return value.

virtual double	GetReturnDouble ()=0
	Returns the double return value.

virtual void *	GetReturnAddress ()=0
	Returns the address for a reference or handle return type.

virtual void *	GetReturnObject ()=0
	Return a pointer to the returned object.

virtual void *	GetAddressOfReturnValue ()=0
	Returns the address of the returned value.

Exception handling
virtual int	SetException (const char *info, bool allowCatch=true)=0
	Sets an exception, which aborts the execution.

virtual int	GetExceptionLineNumber (int column=0, const char *sectionName=0)=0
	Returns the line number where the exception occurred.

virtual asIScriptFunction *	GetExceptionFunction ()=0
	Returns the function where the exception occurred.

virtual const char *	GetExceptionString ()=0
	Returns the exception string text.

virtual bool	WillExceptionBeCaught ()=0
	Determine if the current exception will be caught by the script.

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.

virtual void	ClearExceptionCallback ()=0
	Removes the registered callback.

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.

virtual void	ClearLineCallback ()=0
	Removes the registered callback.

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

virtual asIScriptFunction *	GetFunction (asUINT stackLevel=0)=0
	Returns the function at the specified callstack level.

virtual int	GetLineNumber (asUINT stackLevel=0, int column=0, const char *sectionName=0)=0
	Returns the line number at the specified callstack level.

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

virtual int	GetVar (asUINT varIndex, asUINT stackLevel, const char *name, int typeId=0, asETypeModifiers typeModifiers=0, bool isVarOnHeap=0, int *stackOffset=0)=0
	Returns information on a local variable at the specified callstack level.

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

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.

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

virtual void *	GetAddressOfVar (asUINT varIndex, asUINT stackLevel=0, bool dontDereference=false, bool returnAddressOfUnitializedObjects=false)=0
	Returns a pointer to a local variable at the specified callstack level.

virtual bool	IsVarInScope (asUINT varIndex, asUINT stackLevel=0)=0
	Informs whether the variable is in scope at the current program position.

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

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

virtual asIScriptFunction *	GetSystemFunction ()=0
	Returns the registered function that is currently being called by the context.

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

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

Serialization
virtual int	StartDeserialization ()=0
	Start a deserialization of a context.

virtual int	FinishDeserialization ()=0
	Finish a deserialization of a context.

virtual int	PushFunction (asIScriptFunction func, void object)=0
	Push a function call onto the context stack for deserialization.

virtual int	GetStateRegisters (asUINT stackLevel, asIScriptFunction callingSystemFunction, asIScriptFunction initialFunction, asDWORD origStackPointer, asDWORD argumentsSize, asQWORD valueRegister, void objectRegister, asITypeInfo *objectTypeRegister)=0
	Get the state registers for serialization.

virtual int	GetCallStateRegisters (asUINT stackLevel, asDWORD stackFramePointer, asIScriptFunction currentFunction, asDWORD programPointer, asDWORD stackPointer, asDWORD stackIndex)=0
	Get the call state registers for serialization.

virtual int	SetStateRegisters (asUINT stackLevel, asIScriptFunction callingSystemFunction, asIScriptFunction initialFunction, asDWORD origStackPointer, asDWORD argumentsSize, asQWORD valueRegister, void objectRegister, asITypeInfo objectTypeRegister)=0
	Set the state registers for deserialization.

virtual int	SetCallStateRegisters (asUINT stackLevel, asDWORD stackFramePointer, asIScriptFunction *currentFunction, asDWORD programPointer, asDWORD stackPointer, asDWORD stackIndex)=0
	Set the call state registers for deserialization.

virtual int	GetArgsOnStackCount (asUINT stackLevel)=0
	Get the number of args pushed on the stack for serialization.

virtual int	GetArgOnStack (asUINT stackLevel, asUINT arg, int typeId, asUINT flags, void **address)=0
	Get the argument pushed on the stack for serialization and deserialization.

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

◆ Abort()

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.

If the call to Abort is done from within a function called by the script, it will only take effect after that function returns.

◆ AddRef()

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.

◆ ClearExceptionCallback()

virtual void asIScriptContext::ClearExceptionCallback ( )

pure virtual

Removes a previously registered callback.

◆ ClearLineCallback()

virtual void asIScriptContext::ClearLineCallback ( )

pure virtual

Removes a previously registered callback.

◆ Execute()

virtual int asIScriptContext::Execute ( )

pure virtual

Returns: A negative value on error, or one of asEContextState.

Return values

asCONTEXT_NOT_PREPARED	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.

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

◆ FinishDeserialization()

virtual int asIScriptContext::FinishDeserialization ( )

pure virtual

Returns: A negative value to indicate an error.

Return values

asCONTEXT_NOT_PREPARED The deserialization was not initiated, or the context was not successfully deserialized.

Call this method to finish the deserialization previously initiated with StartDeserialization.

◆ GetAddressOfArg()

virtual void * asIScriptContext::GetAddressOfArg ( 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.

◆ GetAddressOfReturnValue()

virtual void * asIScriptContext::GetAddressOfReturnValue ( )

pure virtual

Returns: A pointer to the return value returned from the script function, or 0 on error.

◆ GetAddressOfVar()

virtual void * asIScriptContext::GetAddressOfVar	(	asUINT	varIndex,
		asUINT	stackLevel = `0`,
		bool	dontDereference = `false`,
		bool	returnAddressOfUnitializedObjects = `false`
	)

pure virtual

Parameters

[in]	varIndex	The index of the variable.
[in]	stackLevel	The index on the call stack.
[in]	dontDereference	Do not dereference the variable, i.e. get the location where the address to the memory is stored.
[in]	returnAddressOfUnitializedObjects	Return the address even if the variable is not initialized yet.

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.

When deserializing a context, it may be necessary to set dontDereference and/or returnAddressOfUnitializedObjects in order to allocate and initialize memory for local variables.

◆ GetArgOnStack()

virtual int asIScriptContext::GetArgOnStack	(	asUINT	stackLevel,
		asUINT	arg,
		int *	typeId,
		asUINT *	flags,
		void **	address
	)

pure virtual

Parameters

[in]	stackLevel	The index on the call stack.
[in]	arg	The argument to retrieve.
[out]	typeId	Set to the typeId of the argument.
[out]	flags	A combination of asETypeModifiers.
[out]	address	Set to the address of the argument.

Returns: A negative value to indicate an error.

Return values

asERROR	The programPointer is not set
asINVALID_ARG	The stackLevel is out of range

This method should be used to retrieve the typeId and type modifiers as well as the address of the argument pushed on the stack for serialization. It should also be used during deserialization to restore the argument on the stack.

If the typeId indicate that the argument is an object type, or the flags indicate that it is a reference, then the address may be either an address to the value, or an integer place holder refering to the local variable holding the actual value. The latter is often used to avoid storing unsafe references on the stack until just before the function call. The method GetVar can be used to determine the stackOffset of local variables to match the value in address if it is an integer place holder.

◆ GetArgsOnStackCount()

virtual int asIScriptContext::GetArgsOnStackCount ( asUINT stackLevel )

pure virtual

Parameters

[in] stackLevel The index on the call stack.

Returns: The number of args currently pushed on the stack or a negative value on error.

Return values

asERROR	The programPointer is not set for this function, e.g. Execute has not been called yet.
asINVALID_ARG	The stackLevel is out of range.

This method will determine the number of arguments currently pushed on the stack in preparation for a function call. Use this during serialization of the context, followed by calls to GetArgOnStack to serialize the arguments.

◆ GetCallstackSize()

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.

◆ GetCallStateRegisters()

virtual int asIScriptContext::GetCallStateRegisters	(	asUINT	stackLevel,
		asDWORD *	stackFramePointer,
		asIScriptFunction **	currentFunction,
		asDWORD *	programPointer,
		asDWORD *	stackPointer,
		asDWORD *	stackIndex
	)

pure virtual

Parameters

[in]	stackLevel	The index on the call stack.
[out]	stackFramePointer	Will be set to a DWORD representing the stack frame pointer.
[out]	currentFunction	Will be set to the current function.
[out]	programPointer	Will be set to the offset from the start of the bytecode representing the current program position.
[out]	stackPointer	Will be set to a DWORD representing the stack pointer.
[out]	stackIndex	Will be set to the index of the stack memory block.

Returns: A negative value to indicate an error.

Return values

asINVALID_ARG	The stackLevel is out of bounds.
asERROR	The stackLevel represent a pushed state for nested calls.

Use this method to get the call state registers for serialization. Each function on the call stack must be stored during serialization. The number of functions on the call stack can be obtained with GetCallstackSize.

If the context has been used for nested calls, this will return asERROR on the stack levels representing pushed states. In this case use GetStateRegisters to obtain the pushed state.

See also: PushState

◆ GetEngine()

virtual asIScriptEngine * asIScriptContext::GetEngine ( ) const

pure virtual

Returns: A pointer to the engine.

◆ GetExceptionFunction()

virtual asIScriptFunction * asIScriptContext::GetExceptionFunction ( )

pure virtual

Returns: The function where the exception occurred.

◆ GetExceptionLineNumber()

virtual int asIScriptContext::GetExceptionLineNumber	(	int *	column = `0`,
		const char **	sectionName = `0`
	)

pure virtual

Parameters

[out]	column	The variable will receive the column number.
[out]	sectionName	The 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.

◆ GetExceptionString()

virtual const char * asIScriptContext::GetExceptionString ( )

pure virtual

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

◆ GetFunction()

virtual asIScriptFunction * asIScriptContext::GetFunction ( asUINT stackLevel = 0 )

pure virtual

Parameters

[in] stackLevel The 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

◆ GetLineNumber()

virtual int asIScriptContext::GetLineNumber	(	asUINT	stackLevel = `0`,
		int *	column = `0`,
		const char **	sectionName = `0`
	)

pure virtual

Parameters

[in]	stackLevel	The index on the call stack.
[out]	column	The variable will receive the column number.
[out]	sectionName	The 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.

◆ GetReturnAddress()

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.

◆ GetReturnByte()

virtual asBYTE asIScriptContext::GetReturnByte ( )

pure virtual

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

◆ GetReturnDouble()

virtual double asIScriptContext::GetReturnDouble ( )

pure virtual

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

◆ GetReturnDWord()

virtual asDWORD asIScriptContext::GetReturnDWord ( )

pure virtual

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

◆ GetReturnFloat()

virtual float asIScriptContext::GetReturnFloat ( )

pure virtual

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

◆ GetReturnObject()

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.

◆ GetReturnQWord()

virtual asQWORD asIScriptContext::GetReturnQWord ( )

pure virtual

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

◆ GetReturnWord()

virtual asWORD asIScriptContext::GetReturnWord ( )

pure virtual

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

◆ GetState()

virtual asEContextState asIScriptContext::GetState ( ) const

pure virtual

Returns: The current state of the context.

◆ GetStateRegisters()

virtual int asIScriptContext::GetStateRegisters	(	asUINT	stackLevel,
		asIScriptFunction **	callingSystemFunction,
		asIScriptFunction **	initialFunction,
		asDWORD *	origStackPointer,
		asDWORD *	argumentsSize,
		asQWORD *	valueRegister,
		void **	objectRegister,
		asITypeInfo **	objectTypeRegister
	)

pure virtual

Parameters

[in]	stackLevel	The index on the call stack.
[out]	callingSystemFunction	Will be set to the system function that is being called, or null if no system function is being called.
[out]	initialFunction	Will be set to the initial function with which the context was prepared.
[out]	origStackPointer	Will be set to a DWORD representing the original stack pointer.
[out]	argumentsSize	Will be set to the size reserved on the stack for the arguments in the initial function with which the context was prepared.
[out]	valueRegister	Will be set to the content of the value register.
[out]	objectRegister	Will be set to the address of the object held in the object register, or null if no object is currently held.
[out]	objectTypeRegister	Will be set to the object type of the object held in the object register, or null if no object is currently held.

Returns: A negative value to indicate an error.

Return values

asERROR	The stackLevel is not 0 or doesn't represent a pushed state for nested calls.
asINVALID_ARG	The stackLevel is out of bounds.

Call this to get the context state registers for serialization. During serialization the current state registers must be stored. If the context has been used for nested calls, then this method must also be used to retrieve any pushed states by passing the stackLevel representing the push state.

During deserialization use these values to restore the state with SetStateRegisters.

See also: PushState

◆ GetSystemFunction()

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.

◆ GetThisPointer()

virtual void * asIScriptContext::GetThisPointer ( asUINT stackLevel = 0 )

pure virtual

Parameters

[in] stackLevel The index on the call stack.

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

◆ GetThisTypeId()

virtual int asIScriptContext::GetThisTypeId ( asUINT stackLevel = 0 )

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.

◆ GetUserData()

virtual void * asIScriptContext::GetUserData ( asPWORD type = 0 ) const

pure virtual

Parameters

[in] type An identifier specifying the user data to set.

Returns: The pointer to the user data.

◆ GetVar()

virtual int asIScriptContext::GetVar	(	asUINT	varIndex,
		asUINT	stackLevel,
		const char **	name,
		int *	typeId = `0`,
		asETypeModifiers *	typeModifiers = `0`,
		bool *	isVarOnHeap = `0`,
		int *	stackOffset = `0`
	)

pure virtual

Parameters

[in]	varIndex	The index of the variable.
[in]	stackLevel	The index on the call stack.
[out]	name	This will be set to the name of the variable or null if the variable is unnamed.
[out]	typeId	This will be set to the type id of the variable.
[out]	typeModifiers	This will be set with the type modifiers of the variable.
[out]	isVarOnHeap	This will be set to true if the variable memory is allocated on the heap.
[out]	stackOffset	This will be set to the offset on the stack where the variable is allocated.

Returns: Returns a negative value on error.

Return values

asINVALID_ARG	The index or stack level is invalid.
asNOT_SUPPORTED	The function is not a script function.

◆ GetVarCount()

virtual int asIScriptContext::GetVarCount ( asUINT stackLevel = 0 )

pure virtual

Parameters

[in] stackLevel The 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_ARG The stackLevel is invalid.

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

◆ GetVarDeclaration()

virtual const char * asIScriptContext::GetVarDeclaration	(	asUINT	varIndex,
		asUINT	stackLevel = `0`,
		bool	includeNamespace = `false`
	)

pure virtual

Parameters

[in]	varIndex	The index of the variable.
[in]	stackLevel	The index on the call stack.
[in]	includeNamespace	Set to true if the namespace should be included in the declaration.

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

◆ GetVarName()

virtual const char * asIScriptContext::GetVarName	(	asUINT	varIndex,
		asUINT	stackLevel = `0`
	)

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.

Deprecated:: Since 2.36.0. Use asIScriptContext::GetVar instead

◆ GetVarTypeId()

virtual int asIScriptContext::GetVarTypeId	(	asUINT	varIndex,
		asUINT	stackLevel = `0`
	)

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.

Deprecated:: Since 2.36.0. Use asIScriptContext::GetVar instead

◆ IsNested()

virtual bool asIScriptContext::IsNested ( asUINT * nestCount = 0 ) const

pure virtual

Parameters

[out] nestCount This argument receives the nesting level.

Returns: true if there are any nested calls.

◆ IsVarInScope()

virtual bool asIScriptContext::IsVarInScope	(	asUINT	varIndex,
		asUINT	stackLevel = `0`
	)

pure virtual

Parameters

[in]	varIndex	The index of the variable.
[in]	stackLevel	The 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.

◆ PopState()

virtual int asIScriptContext::PopState ( )

pure virtual

Returns: A negative value on error.

Return values

asERROR The state couldn't be restored.

◆ Prepare()

virtual int asIScriptContext::Prepare ( asIScriptFunction * func )

pure virtual

Parameters

[in] func 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 pointer is null.
asINVALID_ARG	The function is from a different engine than the context.
asOUT_OF_MEMORY	The 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

◆ PushFunction()

virtual int asIScriptContext::PushFunction	(	asIScriptFunction *	func,
		void *	object
	)

pure virtual

Parameters

[in]	func	The function that should be pushed on the call stack.
[in]	object	The object pointer, if the function is a class method.

Returns: A negative value to indicate an error.

Return values

asINVALID_ARG	func is null
asCONTEXT_NOT_PREPARED	The context is not in deserialization mode

Use this after calling StartDeserialization to push functions on the call stack. This will prepare the stack frame so that call state registers can be restored with SetCallStateRegisters, the local variables with GetAddressOfVar, and arguments on the stack with GetArgOnStack.

◆ PushState()

virtual int asIScriptContext::PushState ( )

pure virtual

Returns: A negative value on error.

Return values

asERROR	The current context is not active.
asOUT_OF_MEMORY	Couldn't allocate memory to store state.

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.

If PushState() fails, the context was not modified, so the application can just create a different context instead, and when it is done with it the original context can be resumed normally.

◆ Release()

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.

◆ SetArgAddress()

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.

◆ SetArgByte()

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.

◆ SetArgDouble()

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.

◆ SetArgDWord()

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.

◆ SetArgFloat()

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.

◆ SetArgObject()

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.

◆ SetArgQWord()

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.

◆ SetArgVarType()

virtual int asIScriptContext::SetArgVarType	(	asUINT	arg,
		void *	ptr,
		int	typeId
	)

pure virtual

Parameters

[in]	arg	The argument index.
[in]	ptr	A pointer to the value.
[in]	typeId	The type id of the value.

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 variable type.

This method should be used when setting the argument for functions with variable parameter types.

◆ SetArgWord()

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.

◆ SetCallStateRegisters()

virtual int asIScriptContext::SetCallStateRegisters	(	asUINT	stackLevel,
		asDWORD	stackFramePointer,
		asIScriptFunction *	currentFunction,
		asDWORD	programPointer,
		asDWORD	stackPointer,
		asDWORD	stackIndex
	)

pure virtual

Parameters

[in]	stackLevel	The index on the call stack.
[out]	stackFramePointer	Give the DWORD representing the stack frame pointer for the serialized context.
[out]	currentFunction	Give the current function for the serialized context.
[out]	programPointer	Give the offset from the start of the bytecode representing the current program position for the serialized context.
[out]	stackPointer	Give the DWORD representing the stack pointer for the serialized context.
[out]	stackIndex	Give the index of the stack memory block for the serialized context.

Returns: A negative value to indicate an error.

Return values

asCONTEXT_ACTIVE	The context is not currently in deserialization mode.
asINVALID_ARG	The stackLevel is out of bounds.

Use this method to restore the context call state registers for each function on the call stack during deserialization. Call PushFunction before each call to allocate the memory for the callstack entry that will be restored.

See also: StartDeserialization

◆ SetException()

virtual int asIScriptContext::SetException	(	const char *	info,
		bool	allowCatch = `true`
	)

pure virtual

Parameters

[in]	info	A string that describes the exception that occurred.
[in]	allowCatch	Set to false if the script shouldn't be allowed to catch the exception.

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.

◆ SetExceptionCallback()

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.

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

asIScriptContext

The interface to the virtual machine.

Definition: angelscript.h:2764

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: Exception handling

◆ SetLineCallback()

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

◆ SetObject()

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.

◆ SetStateRegisters()

virtual int asIScriptContext::SetStateRegisters	(	asUINT	stackLevel,
		asIScriptFunction *	callingSystemFunction,
		asIScriptFunction *	initialFunction,
		asDWORD	origStackPointer,
		asDWORD	argumentsSize,
		asQWORD	valueRegister,
		void *	objectRegister,
		asITypeInfo *	objectTypeRegister
	)

pure virtual

Parameters

[in]	stackLevel	The index on the call stack.
[in]	callingSystemFunction	Give the system function that was called when serializing the context, or null if none.
[in]	initialFunction	Give the initial function with which the serialized context was originally prepared.
[in]	origStackPointer	Give the DWORD representing the original stack pointer for the serialized context.
[in]	argumentsSize	Give the size reserved for the arguments in the initial function in the serialized context.
[in]	valueRegister	Give the content of the value register from the serialized context.
[in]	objectRegister	Give the address of the object that was held in the register by the serialized context, or null if no object was held.
[in]	objectTypeRegister	Give the object type of the object held in the object register by serialized context, or null if no object was held.

Returns: A negative value to indicate an error.

Return values

asCONTEXT_ACTIVE	The context is not currently in deserialization mode.
asINVALID_ARG	The stackLevel is out of bounds.
asERROR	The stackLevel is not 0 or doesn't represent a pushed state for nested calls.

Use this method to restore the context state registers during deserialization with the values obtained by GetStateRegisters.

To restore a nested call, first call PushState to allocate the memory for the callstack entry that will be restored.

See also: StartDeserialization

◆ SetUserData()

virtual void * asIScriptContext::SetUserData	(	void *	data,
		asPWORD	type = `0`
	)

pure virtual

Parameters

[in]	data	A pointer to the user data.
[in]	type	An 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.

◆ StartDeserialization()

virtual int asIScriptContext::StartDeserialization ( )

pure virtual

Returns: A negative value to indicate an error.

Return values

asCONTEXT_ACTIVE The context is currently active or suspended.

Call this method to initiate a deserialization of a previously serialized context. After deserializing the call stack call FinishDeserialization.

See also: Serialization of contexts

◆ Suspend()

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.

If the call to Suspend is done from within a function called by the script, it will only take effect after that function returns.

See also: Calling a script function

◆ Unprepare()

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.

◆ WillExceptionBeCaught()

virtual bool asIScriptContext::WillExceptionBeCaught ( )

pure virtual

Returns: True if the exception will be caught by the script.

This method is intended to be used from the exception callback, where the application can potentially make a different decision depending on whether the script will catch the exception or not.

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

angelscript.h

Public Member Functions

Detailed Description

Member Function Documentation

◆ Abort()

◆ AddRef()

◆ ClearExceptionCallback()

◆ ClearLineCallback()

◆ Execute()

◆ FinishDeserialization()

◆ GetAddressOfArg()

◆ GetAddressOfReturnValue()

◆ GetAddressOfVar()

◆ GetArgOnStack()

◆ GetArgsOnStackCount()

◆ GetCallstackSize()

◆ GetCallStateRegisters()

◆ GetEngine()

◆ GetExceptionFunction()

◆ GetExceptionLineNumber()

◆ GetExceptionString()

◆ GetFunction()

◆ GetLineNumber()

◆ GetReturnAddress()

◆ GetReturnByte()

◆ GetReturnDouble()

◆ GetReturnDWord()

◆ GetReturnFloat()

◆ GetReturnObject()

◆ GetReturnQWord()

◆ GetReturnWord()

◆ GetState()

◆ GetStateRegisters()

◆ GetSystemFunction()

◆ GetThisPointer()

◆ GetThisTypeId()

◆ GetUserData()

◆ GetVar()

◆ GetVarCount()

◆ GetVarDeclaration()

◆ GetVarName()

◆ GetVarTypeId()

◆ IsNested()

◆ IsVarInScope()

◆ PopState()

◆ Prepare()

◆ PushFunction()

◆ PushState()

◆ Release()

◆ SetArgAddress()

◆ SetArgByte()

◆ SetArgDouble()

◆ SetArgDWord()

◆ SetArgFloat()

◆ SetArgObject()

◆ SetArgQWord()

◆ SetArgVarType()

◆ SetArgWord()

◆ SetCallStateRegisters()

◆ SetException()

◆ SetExceptionCallback()

◆ SetLineCallback()

◆ SetObject()

◆ SetStateRegisters()

◆ SetUserData()

◆ StartDeserialization()

◆ Suspend()

◆ Unprepare()

◆ WillExceptionBeCaught()