AngelScript: asIScriptModule Class Reference

# asIScriptModule Class Reference

The interface to the script modules.

List of all members.

## Public Member Functions
Miscellaneous
virtual asIScriptEngine * | GetEngine ()=0
| Returns a pointer to the engine.
virtual void | SetName (const char *name)=0
| Sets the name of the module.
virtual const char * | GetName ()=0
| Gets the name of the module.
Compilation
virtual int | AddScriptSection (const char *name, const char *code, size_t codeLength=0, int lineOffset=0)=0
| Add a script section for the next build.
virtual int | Build ()=0
| Build the previously added script sections.
virtual int | CompileFunction (const char *sectionName, const char *code, int lineOffset, asDWORD compileFlags, asIScriptFunction **outFunc)=0
| Compile a single function.
virtual int | CompileGlobalVar (const char *sectionName, const char *code, int lineOffset)=0
| Compile a single global variable and add it to the scope of the module.
Functions
virtual int | GetFunctionCount ()=0
| Returns the number of global functions in the module.
virtual int | GetFunctionIdByIndex (int index)=0
| Returns the function id by index.
virtual int | GetFunctionIdByName (const char *name)=0
| Returns the function id by name.
virtual int | GetFunctionIdByDecl (const char *decl)=0
| Returns the function id by declaration.
virtual asIScriptFunction * | GetFunctionDescriptorByIndex (int index)=0
| Returns the function descriptor for the script function.
virtual asIScriptFunction * | GetFunctionDescriptorById (int funcId)=0
| Returns the function descriptor for the script function.
virtual int | RemoveFunction (int funcId)=0
| Remove a single function from the scope of the module.
Global variables
virtual int | ResetGlobalVars ()=0
| Reset the global variables of the module.
virtual int | GetGlobalVarCount ()=0
| Returns the number of global variables in the module.
virtual int | GetGlobalVarIndexByName (const char *name)=0
| Returns the global variable index by name.
virtual int | GetGlobalVarIndexByDecl (const char *decl)=0
| Returns the global variable index by declaration.
virtual const char * | GetGlobalVarDeclaration (int index)=0
| Returns the global variable declaration.
virtual const char * | GetGlobalVarName (int index)=0
| Returns the global variable name.
virtual int | GetGlobalVarTypeId (int index, bool *isConst=0)=0
| Returns the type id for the global variable.
virtual void * | GetAddressOfGlobalVar (int index)=0
| Returns the pointer to the global variable.
virtual int | RemoveGlobalVar (int index)=0
| Remove the global variable from the scope of the module.
Type identification
virtual int | GetObjectTypeCount ()=0
| Returns the number of object types.
virtual asIObjectType * | GetObjectTypeByIndex (asUINT index)=0
| Returns the object type interface by index.
virtual int | GetTypeIdByDecl (const char *decl)=0
| Returns a type id by declaration.
Enums
virtual int | GetEnumCount ()=0
| Returns the number of enum types declared in the module.
virtual const char * | GetEnumByIndex (asUINT index, int *enumTypeId)=0
| Returns the enum type.
virtual int | GetEnumValueCount (int enumTypeId)=0
| Returns the number of values defined for the enum type.
virtual const char * | GetEnumValueByIndex (int enumTypeId, asUINT index, int *outValue)=0
| Returns the name and value of the enum value.
Typedefs
virtual int | GetTypedefCount ()=0
| Returns the number of typedefs in the module.
virtual const char * | GetTypedefByIndex (asUINT index, int *typeId)=0
| Returns the typedef.
Dynamic binding between modules
virtual int | GetImportedFunctionCount ()=0
| Returns the number of functions declared for import.
virtual int | GetImportedFunctionIndexByDecl (const char *decl)=0
| Returns the imported function index by declaration.
virtual const char * | GetImportedFunctionDeclaration (int importIndex)=0
| Returns the imported function declaration.
virtual const char * | GetImportedFunctionSourceModule (int importIndex)=0
| Returns the declared imported function source module.
virtual int | BindImportedFunction (int importIndex, int funcId)=0
| Binds an imported function to the function from another module.
virtual int | UnbindImportedFunction (int importIndex)=0
| Unbinds an imported function.
virtual int | BindAllImportedFunctions ()=0
| Binds all imported functions in a module, by searching their equivalents in the declared source modules.
virtual int | UnbindAllImportedFunctions ()=0
| Unbinds all imported functions.
Bytecode saving and loading
virtual int | SaveByteCode (asIBinaryStream *out)=0
| Save compiled bytecode to a binary stream.
virtual int | LoadByteCode (asIBinaryStream *in)=0
| Load pre-compiled bytecode from a binary stream.

## Member Function Documentation

virtual int asIScriptModule::AddScriptSection | ( | const char * | name,
|  | const char * | code,
|  | size_t | codeLength = `0`,
|  | int | lineOffset = `0` |
| ) |  |  | `[pure virtual]`

Parameters:

  `[in]` | name | The name of the script section
  `[in]` | code | The script code buffer
  `[in]` | codeLength | The length of the script code
  `[in]` | lineOffset | An offset that will be added to compiler message line numbers

Returns:
  A negative value on error.

Return values:

  | asMODULE_IS_IN_USE | The module is currently in use.

This adds a script section to the module. All sections added will be treated as if one large script. Errors reported will give the name of the corresponding section.

The code added is copied by the engine, so there is no need to keep the original buffer after the call. Note that this can be changed by setting the engine property asEP_COPY_SCRIPT_SECTIONS with asIScriptEngine::SetEngineProperty.

virtual int asIScriptModule::BindAllImportedFunctions | ( |  | ) | `[pure virtual]`

Returns:
  A negative value on error.

Return values:

  | asERROR | An error occurred.
  | asCANT_BIND_ALL_FUNCTIONS | Not all functions where bound.

This functions tries to bind all imported functions in the module by searching for matching functions in the suggested modules. If a function cannot be bound the function will give an error asCANT_BIND_ALL_FUNCTIONS, but it will continue binding the rest of the functions.

virtual int asIScriptModule::BindImportedFunction | ( | int | importIndex,
|  | int | funcId |
| ) |  |  | `[pure virtual]`

Parameters:

  `[in]` | importIndex | The index of the imported function.
  `[in]` | funcId | The function id of the function that will be bound to the imported function.

Returns:
  A negative value on error.

Return values:

  | asNO_FUNCTION | importIndex or fundId is incorrect.
  | asINVALID_INTERFACE | The signature of function doesn't match the import statement.

The imported function is only bound if the functions have the exact same signature, i.e the same return type, and parameters.

virtual int asIScriptModule::Build | ( |  | ) | `[pure virtual]`

Returns:
  A negative value on error

Return values:

  | asINVALID_CONFIGURATION | The engine configuration is invalid.
  | asERROR | The script failed to build.
  | asBUILD_IN_PROGRESS | Another thread is currently building.

Builds the script based on the added sections, and registered types and functions. After the build is complete the script sections are removed to free memory. If the script module needs to be rebuilt all of the script sections needs to be added again.

Compiler messages are sent to the message callback function set with asIScriptEngine::SetMessageCallback. If there are no errors or warnings, no messages will be sent to the callback function.

Any global variables found in the script will be initialized by the compiler if the engine property asEP_INIT_GLOBAL_VARS_AFTER_BUILD is set.

virtual int asIScriptModule::CompileFunction | ( | const char * | sectionName,
|  | const char * | code,
|  | int | lineOffset,
|  | asDWORD | compileFlags,
|  | asIScriptFunction ** | outFunc |
| ) |  |  | `[pure virtual]`

Parameters:

  `[in]` | sectionName | The name of the script section
  `[in]` | code | The script code buffer
  `[in]` | lineOffset | An offset that will be added to compiler message line numbers
  `[in]` | compileFlags | One of asECompileFlags values
  `[out]` | outFunc | Optional parameter to receive the compiled function descriptor

Returns:
  A negative value on error

Return values:

  | asINVALID_ARG | One or more arguments have invalid values.
  | asINVALID_CONFIGURATION | The engine configuration is invalid.
  | asBUILD_IN_PROGRESS | Another build is in progress.
  | asERROR | The compilation failed.

Use this to compile a single function. The function can be optionally added to the scope of the module, in which case it will be available for subsequent compilations. If not added to the module, the function can still be returned in the output parameter, which will allow the application to execute it, and then discard it when it is no longer needed.

If the output function parameter is set, remember to release the function object when you're done with it.

virtual int asIScriptModule::CompileGlobalVar | ( | const char * | sectionName,
|  | const char * | code,
|  | int | lineOffset |
| ) |  |  | `[pure virtual]`

Parameters:

  `[in]` | sectionName | The name of the script section
  `[in]` | code | The script code buffer
  `[in]` | lineOffset | An offset that will be added to compiler message line numbers

Returns:
  A negative value on error

Return values:

  | asINVALID_ARG | One or more arguments have invalid values.
  | asINVALID_CONFIGURATION | The engine configuration is invalid.
  | asBUILD_IN_PROGRESS | Another build is in progress.
  | asERROR | The compilation failed.

Use this to add a single global variable to the scope of a module. The variable can then be referred to by the application and subsequent compilations.

The script code may contain an initialization expression, which will be executed by the compiler if the engine property asEP_INIT_GLOBAL_VARS_AFTER_BUILD is set.

virtual void* asIScriptModule::GetAddressOfGlobalVar | ( | int | index | ) | `[pure virtual]`

Parameters:

  `[in]` | index | The index of the global variable.

Returns:
  A pointer to the global variable, or null if not found.

This method should be used to retrieve the pointer of a variable that you wish to access.

virtual asIScriptEngine* asIScriptModule::GetEngine | ( |  | ) | `[pure virtual]`

Returns:
  A pointer to the engine.

virtual const char* asIScriptModule::GetEnumByIndex | ( | asUINT | index,
|  | int * | enumTypeId |
| ) |  |  | `[pure virtual]`

Parameters:

  `[in]` | index | The index of the enum type.
  `[out]` | enumTypeId | Receives the type id of the enum type.

Returns:
  The name of the enum type, or null on error.

virtual int asIScriptModule::GetEnumCount | ( |  | ) | `[pure virtual]`

Returns:
  The number of enum types in the module.

virtual const char* asIScriptModule::GetEnumValueByIndex | ( | int | enumTypeId,
|  | asUINT | index,
|  | int * | outValue |
| ) |  |  | `[pure virtual]`

Parameters:

  `[in]` | enumTypeId | The type id of the enum type.
  `[in]` | index | The index of the enum value.
  `[out]` | outValue | Receives the numeric value.

Returns:
  The name of the enum value.

virtual int asIScriptModule::GetEnumValueCount | ( | int | enumTypeId | ) | `[pure virtual]`

Parameters:

  `[in]` | enumTypeId | The type id of the enum type.

Returns:
  The number of enum values or a negative value on error.

Return values:

  | asINVALID_ARG | enumTypeId is not an enum type.

virtual int asIScriptModule::GetFunctionCount | ( |  | ) | `[pure virtual]`

Returns:
  A negative value on error, or the number of global functions in this module.

Return values:

  | asERROR | The module was not compiled successfully.

This method retrieves the number of compiled script functions.

virtual asIScriptFunction* asIScriptModule::GetFunctionDescriptorById | ( | int | funcId | ) | `[pure virtual]`

Parameters:

  `[in]` | funcId | The id of the function or method.

Returns:
  A pointer to the function description interface, or null if not found.

virtual asIScriptFunction* asIScriptModule::GetFunctionDescriptorByIndex | ( | int | index | ) | `[pure virtual]`

Parameters:

  `[in]` | index | The index of the function.

Returns:
  A pointer to the function description interface, or null if not found.

virtual int asIScriptModule::GetFunctionIdByDecl | ( | const char * | decl | ) | `[pure virtual]`

Parameters:

  `[in]` | decl | The function signature.

Returns:
  A negative value on error, or the function id.

Return values:

  | asERROR | The module was not compiled successfully.
  | asINVALID_DECLARATION | The decl is invalid.
  | asMULTIPLE_FUNCTIONS | Found multiple matching functions.
  | asNO_FUNCTION | Didn't find any matching functions.

This method should be used to retrieve the id of the script function that you wish to execute. The id is then sent to the context's Prepare method.

The method will find the script function with the exact same declaration.

virtual int asIScriptModule::GetFunctionIdByIndex | ( | int | index | ) | `[pure virtual]`

Parameters:

  `[in]` | index | The index of the function.

Returns:
  A negative value on error, or the function id.

Return values:

  | asNO_FUNCTION | There is no function with that index.

This method should be used to retrieve the id of the script function that you wish to execute. The id is then sent to the context's Prepare method.

virtual int asIScriptModule::GetFunctionIdByName | ( | const char * | name | ) | `[pure virtual]`

Parameters:

  `[in]` | name | The name of the function.

Returns:
  A negative value on error, or the function id.

Return values:

  | asERROR | The module was not compiled successfully.
  | asMULTIPLE_FUNCTIONS | Found multiple matching functions.
  | asNO_FUNCTION | Didn't find any matching functions.

This method should be used to retrieve the id of the script function that you wish to execute. The id is then sent to the context's Prepare method.

virtual int asIScriptModule::GetGlobalVarCount | ( |  | ) | `[pure virtual]`

Returns:
  A negative value on error, or the number of global variables in the module.

Return values:

  | asERROR | The module was not compiled successfully.
  | asINIT_GLOBAL_VARS_FAILED | The initialization of the global variables failed.

virtual const char* asIScriptModule::GetGlobalVarDeclaration | ( | int | index | ) | `[pure virtual]`

Parameters:

  `[in]` | index | The index of the global variable.

Returns:
  A null terminated string with the variable declaration, or null if not found.

This method can be used to retrieve the variable declaration of the script variables that the host application will access. Verifying the declaration is important because, even though the script may compile correctly the user may not have used the variable types as intended.

virtual int asIScriptModule::GetGlobalVarIndexByDecl | ( | const char * | decl | ) | `[pure virtual]`

Parameters:

  `[in]` | decl | The global variable declaration.

Returns:
  A negative value on error, or the global variable index.

Return values:

  | asERROR | The module was not built successfully.
  | asNO_GLOBAL_VAR | The matching global variable was found.

This method should be used to retrieve the index of the script variable that you wish to access.

The method will find the script variable with the exact same declaration.

virtual int asIScriptModule::GetGlobalVarIndexByName | ( | const char * | name | ) | `[pure virtual]`

Parameters:

  `[in]` | name | The name of the global variable.

Returns:
  A negative value on error, or the global variable index.

Return values:

  | asERROR | The module was not built successfully.
  | asNO_GLOBAL_VAR | The matching global variable was found.

This method should be used to retrieve the index of the script variable that you wish to access.

virtual const char* asIScriptModule::GetGlobalVarName | ( | int | index | ) | `[pure virtual]`

Parameters:

  `[in]` | index | The index of the global variable.

Returns:
  A null terminated string with the variable name, or null if not found.

virtual int asIScriptModule::GetGlobalVarTypeId | ( | int | index,
|  | bool * | isConst = `0` |
| ) |  |  | `[pure virtual]`

Parameters:

  `[in]` | index | The index of the global variable.
  `[out]` | isConst | Receives the constness indicator of the variable.

Returns:
  The type id of the global variable, or a negative value on error.

Return values:

  | asINVALID_ARG | The index is out of range.

virtual int asIScriptModule::GetImportedFunctionCount | ( |  | ) | `[pure virtual]`

Returns:
  A negative value on error, or the number of imported functions.

Return values:

  | asERROR | The module was not built successfully.

This function returns the number of functions that are imported in a module. These functions need to be bound before they can be used, or a script exception will be thrown.

virtual const char* asIScriptModule::GetImportedFunctionDeclaration | ( | int | importIndex | ) | `[pure virtual]`

Parameters:

  `[in]` | importIndex | The index of the imported function.

Returns:
  A null terminated string with the function declaration, or null if not found.

Use this function to get the declaration of the imported function. The returned declaration can be used to find a matching function in another module that can be bound to the imported function.

virtual int asIScriptModule::GetImportedFunctionIndexByDecl | ( | const char * | decl | ) | `[pure virtual]`

Parameters:

  `[in]` | decl | The function declaration of the imported function.

Returns:
  A negative value on error, or the index of the imported function.

Return values:

  | asERROR | The module was not built successfully.
  | asMULTIPLE_FUNCTIONS | Found multiple matching functions.
  | asNO_FUNCTION | Didn't find any matching function.

This function is used to find a specific imported function by its declaration.

virtual const char* asIScriptModule::GetImportedFunctionSourceModule | ( | int | importIndex | ) | `[pure virtual]`

Parameters:

  `[in]` | importIndex | The index of the imported function.

Returns:
  A null terminated string with the name of the source module, or null if not found.

Use this function to get the name of the suggested module to import the function from.

virtual const char* asIScriptModule::GetName | ( |  | ) | `[pure virtual]`

Returns:
  The name of the module.

virtual asIObjectType* asIScriptModule::GetObjectTypeByIndex | ( | asUINT | index | ) | `[pure virtual]`

Parameters:

  `[in]` | index | The index of the type.

Returns:
  The object type interface for the type, or null if not found.

virtual int asIScriptModule::GetObjectTypeCount | ( |  | ) | `[pure virtual]`

Returns:
  The number of object types declared in the module.

virtual const char* asIScriptModule::GetTypedefByIndex | ( | asUINT | index,
|  | int * | typeId |
| ) |  |  | `[pure virtual]`

Parameters:

  `[in]` | index | The index of the typedef.
  `[out]` | typeId | The type that the typedef aliases.

Returns:
  The name of the typedef.

virtual int asIScriptModule::GetTypedefCount | ( |  | ) | `[pure virtual]`

Returns:
  The number of typedefs in the module.

virtual int asIScriptModule::GetTypeIdByDecl | ( | const char * | decl | ) | `[pure virtual]`

Parameters:

  `[in]` | decl | The declaration of the type.

Returns:
  A negative value on error, or the type id of the type.

Return values:

  | asINVALID_TYPE | decl is not a valid type.

Translates a type declaration into a type id. The returned type id is valid for as long as the type is valid, so you can safely store it for later use to avoid potential overhead by calling this function each time. Just remember to update the type id, any time the type is changed within the engine, e.g. when recompiling script declared classes, or changing the engine configuration.

The type id is based on a sequence number and depends on the order in which the type ids are queried, thus is not guaranteed to always be the same for each execution of the application. The asETypeIdFlags can be used to obtain some information about the type directly from the id.

A base type yields the same type id whether the declaration is const or not, however if the const is for the subtype then the type id is different, e.g. string@ isn't the same as const string@ but string is the same as const string.

virtual int asIScriptModule::LoadByteCode | ( | asIBinaryStream * | in | ) | `[pure virtual]`

Parameters:

  `[in]` | in | The input stream.

Returns:
  A negative value on error.

Return values:

  | asINVALID_ARG | The stream object wasn't specified.
  | asBUILD_IN_PROGRESS | Another thread is currently building.

This method is used to load pre-compiled byte code from disk or memory. The application must implement an object that inherits from asIBinaryStream to provide the necessary stream operations.

It is expected that the application performs the necessary validations to make sure the pre-compiled byte code is from a trusted source. The application should also make sure the pre-compiled byte code is compatible with the current engine configuration, i.e. that the engine has been configured in the same way as when the byte code was first compiled.

virtual int asIScriptModule::RemoveFunction | ( | int | funcId | ) | `[pure virtual]`

Parameters:

  `[in]` | funcId | The id of the function to remove.

Returns:
  A negative value on error.

Return values:

  | asNO_FUNCTION | The function is not part of the scope.

This method allows the application to remove a single function from the scope of the module. The function is not destroyed immediately though, only when no more references point to it.

virtual int asIScriptModule::RemoveGlobalVar | ( | int | index | ) | `[pure virtual]`

Parameters:

  `[in]` | index | The index of the global variable.

Returns:
  A negative value on error.

Return values:

  | asINVALID_ARG | The index is out of range.

The global variable is removed from the scope of the module, but it is not destroyed until all functions that access it are freed.

virtual int asIScriptModule::ResetGlobalVars | ( |  | ) | `[pure virtual]`

Returns:
  A negative value on error.

Return values:

  | asERROR | The module was not compiled successfully.

Resets the global variables declared in this module to their initial value.

virtual int asIScriptModule::SaveByteCode | ( | asIBinaryStream * | out | ) | `[pure virtual]`

Parameters:

  `[in]` | out | The output stream.

Returns:
  A negative value on error.

Return values:

  | asINVALID_ARG | The stream object wasn't specified.

This method is used to save pre-compiled byte code to disk or memory, for a later restoral. The application must implement an object that inherits from asIBinaryStream to provide the necessary stream operations.

The pre-compiled byte code is currently not platform independent, so you need to make sure the byte code is compiled on a platform that is compatible with the one that will load it.

virtual void asIScriptModule::SetName | ( | const char * | name | ) | `[pure virtual]`

Parameters:

  `[in]` | name | The new name.

Sets the name of the script module.

virtual int asIScriptModule::UnbindAllImportedFunctions | ( |  | ) | `[pure virtual]`

Returns:
  A negative value on error.

Unbinds all imported functions in the module.

virtual int asIScriptModule::UnbindImportedFunction | ( | int | importIndex | ) | `[pure virtual]`

Parameters:

  `[in]` | importIndex | The index of the imported function.

Returns:
  A negative value on error.

Return values:

  | asINVALID_ARG | The index is not valid. Unbinds the imported function.

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

- angelscript.h