index

Reference: asIScriptContext

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

AddRef

int AddRef();

Description

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.

Returns

The internal reference counter.

Release

int Release();

Description

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.

Returns

The internal reference counter.

GetEngine

asIScriptEngine *GetEngine();

Description

This function is used to retrieve the engine which created this context.

Returns

Returns the pointer to the engine object.

GetState

int GetState();

Description

This method returns the state of a context.

Returns

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.

Prepare

int Prepare(int funcID);

Description

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.

Parameters

funcID 

The id of the function which is to be executed, or asPREPARE_PREVIOUS to use the same function again.

Returns

Returns a negative value if the function cannot be found. Returns 0 or greater if sucessful.

Execute

int Execute();

Description

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

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.

ExecuteStep

int ExecuteStep(asDWORD flag);

Description

Executes one step of the prepared function. One step is normally one complete statement in the scripting code, but may be less.

Parameters

flag 

Can be either asEXEC_STEP_INTO or asEXEC_STEP_OVER.

Returns

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.

Abort

int Abort();

Description

Aborts the current execution of a script.

Returns

Negative value on failure.

Suspend

int Suspend();

Description

Suspends the current execution of a script.

Returns

Negative value on failure.

SetArguments

int SetArguments(int stackPos,
                 asDWORD *data,
                 int count);

Description

This method sets data on the stack space reserved for function arguments.

Parameters

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

Returns a negative value if the function cannot be found. Returns 0 or greater if sucessful.

GetReturnValue

int GetReturnValue(asDWORD *data,
                   int count);

Description

This method gets data from the stack space reserved for the function return value.

Parameters

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

Returns a negative value on failure. Returns 0 or greater if sucessful.

GetCurrentLineNumber

int GetCurrentLineNumber();

Description

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.

Returns

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.

GetCurrentFunction

int GetCurrentFunction();

Description

Use this method to get the id of the function that the context is currently positioned in.

Returns

Returns the id of the function, or a negative value on failure.

SetException

int SetException(const char *string);

Description

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.

Parameters

string 

The exception string.

Returns

Returns a negative number on failure.

GetExceptionLineNumber

int GetExceptionLineNumber();

Description

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

Returns

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.

GetExceptionFunction

int GetExceptionFunction();

Description

Use this method to get the id of the function in which the exception ocurred.

Returns

Returns the id of the function.

Returns -1 if no context was prepared or no exception ocurred.

GetExceptionString

const char *GetExceptionString(int *length = 0);

Description

This function gives the exception string, which describe what happened.

Parameters

length 

Pointer to a variable that will receive the length of the returned string.

Returns

Returns a null-terminated string with the exception description.

top