index

Reference: asIScriptContext

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 SetArgObject(asUINT arg, void *object);

  asDWORD GetReturnDWord();
  asQWORD GetReturnQWord();
  float   GetReturnFloat();
  double  GetReturnDouble();
  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);
  void *GetVarPointer(int varIndex, int stackLevel = -1);
};

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.

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.

SetArg

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 SetArgObject(asUINT arg, void *object);

Description

These method sets function arguments when calling script functions.

Parameters

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. Use DWord when passing a reference to a primitive variable.

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

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

GetReturn

asDWORD GetReturnDWord();
asQWORD GetReturnQWord();
float   GetReturnFloat();
double  GetReturnDouble();
void   *GetReturnObject();

Description

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.

Returns

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.

GetCurrentLineNumber

int GetCurrentLineNumber(int *column);

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.

Parameters

column 

An optional pointer to an integer that will receive the column number.

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(int *column);

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.

Parameters

column 

An optional pointer to an integer that will receive the column number.

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.

SetLineCallback

int SetLineCallback(asUPtr callback, void *obj, int callConv);

Description

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.

Parameters

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

Returns a negative value on failure.

ClearLineCallback

void ClearLineCallback();

Description

This method removes the line callback function.

SetExceptionCallback

int SetExceptionCallback(asUPtr callback, void *obj, int callConv);

Description

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.

Parameters

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

Returns a negative value on failure.

ClearExceptionCallback

void ClearExceptionCallback();

Description

This method removes the exception callback function.

GetCallstackSize

int GetCallstackSize();

Description

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.

Returns

The size of the callstack.

GetCallstackFunction

int GetCallstackFunction(int index);

Description

Returns the function id of a function on the determined level in the callstack.

Parameters

index 

The index into the callstack.

Returns

The function id.

GetCallstackLineNumber

int GetCallstackLineNumber(int index, int *column);

Description

Returns the line number for the function at the callstack index.

Parameters

index 

The index into the callstack.

column 

An optional pointer to an integer that will receive the column number.

Returns

The line number.

GetVarCount

int GetVarCount(int stackLevel);

Description

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

Parameters

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.

Returns

The number of variables in the function.

GetVarName

const char *GetVarName(int varIndex, int *length, int stackLevel);

Description

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

Returns the pointer to a temporary string with the name of the variable.

GetVarDeclaration

const char *GetVarDeclaration(int varIndex, int *length, int stackLevel);

Description

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

Returns the pointer to a temporary string with the declaration of the variable.

GetVarPointer

const char *GetVarPointer(int varIndex, int stackLevel);

Description

Returns a pointer to the variable, so that its value can be read and written. The address is valid until the script function returns.

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

Returns the pointer to the variable.

top