class asIScriptContext { public: // Memory management virtual int AddRef() = 0; virtual int Release() = 0; // Engine virtual asIScriptEngine *GetEngine() = 0; // Script context virtual int GetState() = 0; virtual int Prepare(int funcID) = 0; virtual int SetArguments(int stackPos, asDWORD *data, int count) = 0; virtual int GetReturnValue(asDWORD *data, int count) = 0; virtual int Execute() = 0; virtual int ExecuteStep(asDWORD flag) = 0; virtual int Abort() = 0; virtual int Suspend() = 0; virtual int GetCurrentLineNumber() = 0; virtual int GetCurrentFunction() = 0; // Exception handling virtual int SetException(const char *string) = 0; virtual int GetExceptionLineNumber() = 0; virtual int GetExceptionFunction() = 0; virtual const char *GetExceptionString(int *length = 0) = 0; };
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 ExecuteStep(asDWORD flag);
Executes one step of the prepared function. One step is normally one complete statement in the scripting code, but may be less.
flag |
Can be either asEXEC_STEP_INTO or asEXEC_STEP_OVER. |
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 SetArguments(int stackPos, asDWORD *data, int count);
This method sets data on the stack space reserved for function arguments.
stackPos |
The position in the stack to set, relative to the function's stack frame. The argument data should be placed on positions starting with 0 and increasing, i.e the first argument on 0, the second on 1, etc. Note that some types take up more than one position, e.g. double take 2 dwords. |
data |
A pointer to the data to be set. You should verify the function interface before setting parameters, so that the function really takes the parameters that you are sending. |
count |
The number of dwords to copy from the data pointer. |
Returns a negative value if the function cannot be found. Returns 0 or greater if sucessful.
int GetReturnValue(asDWORD *data, int count);
This method gets data from the stack space reserved for the function return value.
data |
A pointer to a buffer that receives the data. You should verify the function interface before getting the return value, so that the function really returns what you are expecting. |
count |
The number of dwords to copy. |
Returns a negative value on failure. Returns 0 or greater if sucessful.
int GetCurrentLineNumber();
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.
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();
This method returns the line number where the exception ocurred. The line number is relative to the script section where the function was found.
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.