class asIScriptContext { public: // Memory management int AddRef(); int Release(); // Engine asIScriptEngine *GetEngine(); // Script context int GetState(); int Prepare(int funcID); int SetArgDWord(asUINT arg, asDWORD value); int SetArgQWord(asUINT arg, asQWORD value); int SetArgFloat(asUINT arg, float value); int SetArgDouble(asUINT arg, double value); int SetArgAddress(asUINT arg, void *address); int SetArgObject(asUINT arg, void *object); int SetObject(void *object); asDWORD GetReturnDWord(); asQWORD GetReturnQWord(); float GetReturnFloat(); double GetReturnDouble(); void *GetReturnAddress(); void *GetReturnObject(); int Execute(); int Abort(); int Suspend(); int GetCurrentLineNumber(int *column = 0); int GetCurrentFunction(); // Exception handling int SetException(const char *string); int GetExceptionLineNumber(int *column = 0); int GetExceptionFunction(); const char *GetExceptionString(int *length = 0); int SetLineCallback(asUPtr callback, void *obj, int callConv); void ClearLineCallback(); int SetExceptionCallback(asUPtr callback, void *obj, int callConv); void ClearExceptionCallback(); int GetCallstackSize(); int GetCallstackFunction(int index); int GetCallstackLineNumber(int index, int *column = 0); int GetVarCount(int stackLevel = -1); const char *GetVarName(int varIndex, int *length = 0, int stackLevel = -1); const char *GetVarDeclaration(int varIndex, int *length = 0, int stackLevel = -1); int GetVarTypeId(int varIndex, int stackLevel = -1); void *GetVarPointer(int varIndex, int stackLevel = -1); };
int AddRef();
This method increases the internal reference counter of the object and returns the count. The returned value shouldn't be used for anything else but debugging.
Call AddRef() each time you assign a reference to a new variable.
The internal reference counter.
int Release();
Decreases the internal reference counter and returns the count. If the counter reaches 0 the object is deleted and the memory is freed.
After calling Release() don't forget to set your reference to 0 so that you don't mistakenly try to use the reference again.
The internal reference counter.
asIScriptEngine *GetEngine();
This function is used to retrieve the engine which created this context.
Returns the pointer to the engine object.
int GetState();
This method returns the state of a context.
Returns a negative value on failure. And one of asEXECUTION_FINISHED, asEXECUTION_SUSPENDED, asEXECUTION_ABORTED, asEXECUTION_EXCEPTION, asEXECUTION_PREPARED, asEXECUTION_UNINITIALIZED, or asEXECUTION_ACTIVE on success.
int Prepare(int funcID);
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.
funcID |
The id of the function which is to be executed, or asPREPARE_PREVIOUS to use the same function again. |
Returns a negative value if the function cannot be found. Returns 0 or greater if sucessful.
int Execute();
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 engine freezes, e.g. if trapped in a never ending loop, you may call Abort() from another thread to stop execution.
Returns a negative value on an unexpected error. On success it returns one of the following values to show the state of the context asEXECUTION_FINISHED, asEXECUTION_SUSPENDED, asEXECUTION_ABORTED, or asEXECUTION_EXCEPTION.
int Abort();
Aborts the current execution of a script.
Negative value on failure.
int Suspend();
Suspends the current execution of a script.
Negative value on failure.
int SetArgDWord(asUINT arg, asDWORD value); int SetArgQWord(asUINT arg, asQWORD value); int SetArgFloat(asUINT arg, float value); int SetArgDouble(asUINT arg, double value); int SetArgAddress(asUINT arg, void *address); int SetArgObject(asUINT arg, void *object);
These method sets function arguments when calling script functions.
arg |
This is the argument number starting from 0, i.e. the first argument is on 0, the second on 1, and so on. |
value |
This is the value of the argument. This should be used for passing primitive data to the function. |
address |
This is the address of a value. This should be used for passing values by reference to the function. |
object |
When the function expects an object, either by value or by reference, you should use SetArgObject(). Pass a pointer to the object. If the function expects an object by value the library will automatically make a copy of the object. |
Returns a negative value if the function cannot be found. Returns 0 or greater if sucessful.
int SetObject(void *object);
This method sets object pointer when calling class methods.
object |
The object pointer. |
Returns a negative value if the function cannot be found. Returns 0 or greater if sucessful.
asDWORD GetReturnDWord(); asQWORD GetReturnQWord(); float GetReturnFloat(); double GetReturnDouble(); void *GetReturnAddress(); void *GetReturnObject();
This method gets the return value from the script function. The value returned is only valid if the script function has finished successfully, i.e. if the state of the context is asEXECUTION_FINISHED.
The functions return the value that the script function returned. If the function returns an object, either by value or by reference you should use GetReturnObject(), which will return a pointer to the object. If the object is returned by value you need to make a copy of it, as the library will release the object when the context is released or reused.
int GetCurrentLineNumber(int *column);
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 found.
column |
An optional pointer to an integer that will receive the column number. |
The line number, where the first line is 1. May also return 0, if the line number counter has been disabled.
Returns negative value on failure.
int GetCurrentFunction();
Use this method to get the id of the function that the context is currently positioned in.
Returns the id of the function, or a negative value on failure.
int SetException(const char *string);
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.
string |
The exception string. |
Returns a negative number on failure.
int GetExceptionLineNumber(int *column);
This method returns the line number where the exception ocurred. The line number is relative to the script section where the function was found.
column |
An optional pointer to an integer that will receive the column number. |
The line number, where the first line is 1. May also return 0, if the line number counter has been disabled.
Returns -1 if no context was prepared or no exception ocurred.
int GetExceptionFunction();
Use this method to get the id of the function in which the exception ocurred.
Returns the id of the function.
Returns -1 if no context was prepared or no exception ocurred.
const char *GetExceptionString(int *length = 0);
This function gives the exception string, which describe what happened.
length |
Pointer to a variable that will receive the length of the returned string. |
Returns a null-terminated string with the exception description.
int SetLineCallback(asUPtr callback, void *obj, int callConv);
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 CDECL or STDCALL, and the class method can use either THISCALL, CDECL_OBJLAST, or CDECL_OBJFIRST.
callback |
Pointer to a the function or method. |
obj |
Pointer to the object or parameter for the function. |
callConv |
The calling convention for the function. |
Returns a negative value on failure.
void ClearLineCallback();
This method removes the line callback function.
int SetExceptionCallback(asUPtr callback, void *obj, int callConv);
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.
callback |
Pointer to a the function or method. |
obj |
Pointer to the object or parameter for the function. |
callConv |
The calling convention for the function. |
Returns a negative value on failure.
void ClearExceptionCallback();
This method removes the exception callback function.
int GetCallstackSize();
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.
The size of the callstack.
int GetCallstackFunction(int index);
Returns the function id of a function on the determined level in the callstack.
index |
The index into the callstack. |
The function id.
int GetCallstackLineNumber(int index, int *column);
Returns the line number for the function at the callstack index.
index |
The index into the callstack. |
column |
An optional pointer to an integer that will receive the column number. |
The line number.
int GetVarCount(int stackLevel);
Returns the number of declared variables, including the parameters, in the function on the stack.
stackLevel |
The stack level. 0 is the first called function on the stack, the greater the number the younger the function. -1 (default) is the current function. |
The number of variables in the function.
const char *GetVarName(int varIndex, int *length, int stackLevel);
Returns the name of the variable in the function.
varIndex |
The index of the variable. |
length |
This argument will receive the length of the returned string. Can be 0. |
stackLevel |
The stack level in which the variables are enumerated. -1 is the default, and means the current function. |
Returns the pointer to a temporary string with the name of the variable.
const char *GetVarDeclaration(int varIndex, int *length, int stackLevel);
Returns the declaration of the variable in the function.
varIndex |
The index of the variable. |
length |
This argument will receive the length of the returned string. Can be 0. |
stackLevel |
The stack level in which the variables are enumerated. -1 is the default, and means the current function. |
Returns the pointer to a temporary string with the declaration of the variable.
int GetVarTypeId(int varIndex, int stackLevel);
Returns the type id of the variable in the function.
varIndex |
The index of the variable. |
stackLevel |
The stack level in which the variables are enumerated. -1 is the default, and means the current function. |
Returns the type id of the variable.
const char *GetVarPointer(int varIndex, int stackLevel);
Returns a pointer to the variable, so that its value can be read and written. The address is valid until the script function returns.
The address points to the position in the stack where the variable is stored. As primitives are stored directly on the stack, the value of primitive types is gotten by dereferencing the pointer. Object variables are not stored directly on the stack, instead the stack holds a pointer to the object. Thus for object types the object is gotten by dereferencing the pointer twice.
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.
varIndex |
The index of the variable. |
length |
This argument will receive the length of the returned string. Can be 0. |
stackLevel |
The stack level in which the variables are enumerated. -1 is the default, and means the current function. |
Returns the pointer to the variable.