AngelScript
asIScriptModule Class Referenceabstract

The interface to the script modules. More...

Public Member Functions

Miscellaneous
virtual asIScriptEngineGetEngine () const =0
 Returns a pointer to the engine. More...
 
virtual void SetName (const char *name)=0
 Sets the name of the module. More...
 
virtual const char * GetName () const =0
 Gets the name of the module. More...
 
virtual void Discard ()=0
 Discards the module. More...
 
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. More...
 
virtual int Build ()=0
 Build the previously added script sections. More...
 
virtual int CompileFunction (const char *sectionName, const char *code, int lineOffset, asDWORD compileFlags, asIScriptFunction **outFunc)=0
 Compile a single function. More...
 
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. More...
 
virtual asDWORD SetAccessMask (asDWORD accessMask)=0
 Sets the access mask that should be used during the compilation. More...
 
virtual int SetDefaultNamespace (const char *nameSpace)=0
 Sets the default namespace that should be used in the following calls. More...
 
virtual const char * GetDefaultNamespace () const =0
 Returns the current default namespace. More...
 
Functions
virtual asUINT GetFunctionCount () const =0
 Returns the number of global functions in the module. More...
 
virtual asIScriptFunctionGetFunctionByIndex (asUINT index) const =0
 Returns the function by index. More...
 
virtual asIScriptFunctionGetFunctionByDecl (const char *decl) const =0
 Returns the function by its declaration. More...
 
virtual asIScriptFunctionGetFunctionByName (const char *name) const =0
 Returns the function by its name. More...
 
virtual int RemoveFunction (asIScriptFunction *func)=0
 Remove a single function from the scope of the module. More...
 
Global variables
virtual int ResetGlobalVars (asIScriptContext *ctx=0)=0
 Reset the global variables of the module. More...
 
virtual asUINT GetGlobalVarCount () const =0
 Returns the number of global variables in the module. More...
 
virtual int GetGlobalVarIndexByName (const char *name) const =0
 Returns the global variable index by name. More...
 
virtual int GetGlobalVarIndexByDecl (const char *decl) const =0
 Returns the global variable index by declaration. More...
 
virtual const char * GetGlobalVarDeclaration (asUINT index, bool includeNamespace=false) const =0
 Returns the global variable declaration. More...
 
virtual int GetGlobalVar (asUINT index, const char **name, const char **nameSpace=0, int *typeId=0, bool *isConst=0) const =0
 Returns the global variable properties. More...
 
virtual void * GetAddressOfGlobalVar (asUINT index)=0
 Returns the pointer to the global variable. More...
 
virtual int RemoveGlobalVar (asUINT index)=0
 Remove the global variable from the scope of the module. More...
 
Type identification
virtual asUINT GetObjectTypeCount () const =0
 Returns the number of object types. More...
 
virtual asIObjectTypeGetObjectTypeByIndex (asUINT index) const =0
 Returns the object type interface by index. More...
 
virtual asIObjectTypeGetObjectTypeByName (const char *name) const =0
 Returns the object type interface by name. More...
 
virtual int GetTypeIdByDecl (const char *decl) const =0
 Returns a type id by declaration. More...
 
Enums
virtual asUINT GetEnumCount () const =0
 Returns the number of enum types declared in the module. More...
 
virtual const char * GetEnumByIndex (asUINT index, int *enumTypeId, const char **nameSpace=0) const =0
 Returns the enum type. More...
 
virtual int GetEnumValueCount (int enumTypeId) const =0
 Returns the number of values defined for the enum type. More...
 
virtual const char * GetEnumValueByIndex (int enumTypeId, asUINT index, int *outValue) const =0
 Returns the name and value of the enum value. More...
 
Typedefs
virtual asUINT GetTypedefCount () const =0
 Returns the number of typedefs in the module. More...
 
virtual const char * GetTypedefByIndex (asUINT index, int *typeId, const char **nameSpace=0) const =0
 Returns the typedef. More...
 
Dynamic binding between modules
virtual asUINT GetImportedFunctionCount () const =0
 Returns the number of functions declared for import. More...
 
virtual int GetImportedFunctionIndexByDecl (const char *decl) const =0
 Returns the imported function index by declaration. More...
 
virtual const char * GetImportedFunctionDeclaration (asUINT importIndex) const =0
 Returns the imported function declaration. More...
 
virtual const char * GetImportedFunctionSourceModule (asUINT importIndex) const =0
 Returns the declared imported function source module. More...
 
virtual int BindImportedFunction (asUINT importIndex, asIScriptFunction *func)=0
 Binds an imported function to the function from another module. More...
 
virtual int UnbindImportedFunction (asUINT importIndex)=0
 Unbinds an imported function. More...
 
virtual int BindAllImportedFunctions ()=0
 Binds all imported functions in a module, by searching their equivalents in the declared source modules. More...
 
virtual int UnbindAllImportedFunctions ()=0
 Unbinds all imported functions. More...
 
Bytecode saving and loading
virtual int SaveByteCode (asIBinaryStream *out, bool stripDebugInfo=false) const =0
 Save compiled bytecode to a binary stream. More...
 
virtual int LoadByteCode (asIBinaryStream *in, bool *wasDebugInfoStripped=0)=0
 Load pre-compiled bytecode from a binary stream. More...
 
User data
virtual void * SetUserData (void *data)=0
 Register the memory address of some user data. More...
 
virtual void * GetUserData () const =0
 Returns the address of the previously registered user data. More...
 

Detailed Description

A script module can be thought of a library of script functions, classes, and global variables.

A pointer to the module interface is obtained by calling asIScriptEngine::GetModule. The module can then be built from a single or multiple script files, also known as script sections. Alternatively pre-built bytecode can be loaded, if it has been saved from a previous build.

See Also
Script modules

Member Function Documentation

virtual int asIScriptModule::AddScriptSection ( const char *  name,
const char *  code,
size_t  codeLength = 0,
int  lineOffset = 0 
)
pure virtual
Parameters
[in]nameThe name of the script section
[in]codeThe script code buffer
[in]codeLengthThe length of the script code
[in]lineOffsetAn offset that will be added to compiler message line numbers
Returns
A negative value on error.
Return values
asMODULE_IS_IN_USEThe module is currently in use.
asINVALID_ARGThe code argument is null.
asNOT_SUPPORTEDCompiler support is disabled in the engine.

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
asERRORAn error occurred.
asCANT_BIND_ALL_FUNCTIONSNot 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 ( asUINT  importIndex,
asIScriptFunction func 
)
pure virtual
Parameters
[in]importIndexThe index of the imported function.
[in]funcThe true function that will be bound to the imported function.
Returns
A negative value on error.
Return values
asNO_FUNCTIONimportIndex or func is incorrect.
asINVALID_INTERFACEThe 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_CONFIGURATIONThe engine configuration is invalid.
asERRORThe script failed to build.
asBUILD_IN_PROGRESSAnother thread is currently building.
asINIT_GLOBAL_VARS_FAILEDIt was not possible to initialize at least one of the global variables.
asNOT_SUPPORTEDCompiler support is disabled in the engine.

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. If you get the error asINIT_GLOBAL_VARS_FAILED, then it is probable that one of the global variables during the initialization is trying to access another global variable before it has been initialized.

virtual int asIScriptModule::CompileFunction ( const char *  sectionName,
const char *  code,
int  lineOffset,
asDWORD  compileFlags,
asIScriptFunction **  outFunc 
)
pure virtual
Parameters
[in]sectionNameThe name of the script section
[in]codeThe script code buffer
[in]lineOffsetAn offset that will be added to compiler message line numbers
[in]compileFlagsOne of asECompileFlags values
[out]outFuncOptional parameter to receive the compiled function descriptor
Returns
A negative value on error
Return values
asINVALID_ARGOne or more arguments have invalid values.
asINVALID_CONFIGURATIONThe engine configuration is invalid.
asBUILD_IN_PROGRESSAnother build is in progress.
asERRORThe compilation failed.
asNOT_SUPPORTEDCompiler support is disabled in the engine.

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]sectionNameThe name of the script section
[in]codeThe script code buffer
[in]lineOffsetAn offset that will be added to compiler message line numbers
Returns
A negative value on error
Return values
asINVALID_ARGOne or more arguments have invalid values.
asINVALID_CONFIGURATIONThe engine configuration is invalid.
asBUILD_IN_PROGRESSAnother build is in progress.
asERRORThe compilation failed.
asNOT_SUPPORTEDCompiler support is disabled in the engine.

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::Discard ( )
pure virtual

This method is used to discard the module and any compiled bytecode it has. After calling this method the module pointer is no longer valid and shouldn't be used by the application.

virtual void* asIScriptModule::GetAddressOfGlobalVar ( asUINT  index)
pure virtual
Parameters
[in]indexThe 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 const char* asIScriptModule::GetDefaultNamespace ( ) const
pure virtual
Returns
The current default namespace
virtual asIScriptEngine* asIScriptModule::GetEngine ( ) const
pure virtual
Returns
A pointer to the engine.
virtual const char* asIScriptModule::GetEnumByIndex ( asUINT  index,
int *  enumTypeId,
const char **  nameSpace = 0 
) const
pure virtual
Parameters
[in]indexThe index of the enum type.
[out]enumTypeIdReceives the type id of the enum type.
[out]nameSpaceReceives the namespace of the enum.
Returns
The name of the enum type, or null on error.
virtual asUINT asIScriptModule::GetEnumCount ( ) const
pure virtual
Returns
The number of enum types in the module.
virtual const char* asIScriptModule::GetEnumValueByIndex ( int  enumTypeId,
asUINT  index,
int *  outValue 
) const
pure virtual
Parameters
[in]enumTypeIdThe type id of the enum type.
[in]indexThe index of the enum value.
[out]outValueReceives the numeric value.
Returns
The name of the enum value.
virtual int asIScriptModule::GetEnumValueCount ( int  enumTypeId) const
pure virtual
Parameters
[in]enumTypeIdThe type id of the enum type.
Returns
The number of enum values or a negative value on error.
Return values
asINVALID_ARGenumTypeId is not an enum type.
virtual asIScriptFunction* asIScriptModule::GetFunctionByDecl ( const char *  decl) const
pure virtual
Parameters
[in]declThe function declaration.
Returns
The function or null in case of error.
virtual asIScriptFunction* asIScriptModule::GetFunctionByIndex ( asUINT  index) const
pure virtual
Parameters
[in]indexThe index of the function
Returns
The function or null in case of error.
virtual asIScriptFunction* asIScriptModule::GetFunctionByName ( const char *  name) const
pure virtual
Parameters
[in]nameThe function name
Returns
The function or null if not found or there are multiple matches.
virtual asUINT asIScriptModule::GetFunctionCount ( ) const
pure virtual
Returns
The number of global functions in this module.

This method retrieves the number of compiled script functions.

virtual int asIScriptModule::GetGlobalVar ( asUINT  index,
const char **  name,
const char **  nameSpace = 0,
int *  typeId = 0,
bool *  isConst = 0 
) const
pure virtual
Parameters
[in]indexThe index of the global variable.
[out]nameThe name of the variable.
[out]nameSpaceThe namespace of the variable.
[out]typeIdThe type of the variable.
[out]isConstWhether or not the variable is const.
Returns
A negative value on error.
Return values
asINVALID_ARGThe index is out of range.
virtual asUINT asIScriptModule::GetGlobalVarCount ( ) const
pure virtual
Returns
The number of global variables in the module.
virtual const char* asIScriptModule::GetGlobalVarDeclaration ( asUINT  index,
bool  includeNamespace = false 
) const
pure virtual
Parameters
[in]indexThe index of the global variable.
[in]includeNamespaceSet to true if the namespace should be included in the declaration.
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) const
pure virtual
Parameters
[in]declThe global variable declaration.
Returns
A negative value on error, or the global variable index.
Return values
asERRORThe module was not built successfully.
asNO_GLOBAL_VARNo matching global variable was found.
asINVALID_DECLARATIONThe given declaration is invalid.

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) const
pure virtual
Parameters
[in]nameThe name of the global variable.
Returns
A negative value on error, or the global variable index.
Return values
asERRORThe module was not built successfully.
asNO_GLOBAL_VARThe matching global variable was found.

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

virtual asUINT asIScriptModule::GetImportedFunctionCount ( ) const
pure virtual
Returns
The number of imported functions.

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 ( asUINT  importIndex) const
pure virtual
Parameters
[in]importIndexThe 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) const
pure virtual
Parameters
[in]declThe function declaration of the imported function.
Returns
A negative value on error, or the index of the imported function.
Return values
asERRORThe module was not built successfully.
asMULTIPLE_FUNCTIONSFound multiple matching functions.
asNO_FUNCTIONDidn't find any matching function.

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

virtual const char* asIScriptModule::GetImportedFunctionSourceModule ( asUINT  importIndex) const
pure virtual
Parameters
[in]importIndexThe 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 ( ) const
pure virtual
Returns
The name of the module.
virtual asIObjectType* asIScriptModule::GetObjectTypeByIndex ( asUINT  index) const
pure virtual
Parameters
[in]indexThe index of the type.
Returns
The object type interface for the type, or null if not found.

This does not increase the reference count of the returned object.

virtual asIObjectType* asIScriptModule::GetObjectTypeByName ( const char *  name) const
pure virtual
Parameters
[in]nameThe name of the type.
Returns
The object type interface for the type, or null if not found.

This does not increase the reference count of the returned object.

virtual asUINT asIScriptModule::GetObjectTypeCount ( ) const
pure virtual
Returns
The number of object types declared in the module.
virtual const char* asIScriptModule::GetTypedefByIndex ( asUINT  index,
int *  typeId,
const char **  nameSpace = 0 
) const
pure virtual
Parameters
[in]indexThe index of the typedef.
[out]typeIdThe type that the typedef aliases.
[out]nameSpaceReceives the namespace of the typedef.
Returns
The name of the typedef.
virtual asUINT asIScriptModule::GetTypedefCount ( ) const
pure virtual
Returns
The number of typedefs in the module.
virtual int asIScriptModule::GetTypeIdByDecl ( const char *  decl) const
pure virtual
Parameters
[in]declThe declaration of the type.
Returns
A negative value on error, or the type id of the type.
Return values
asINVALID_TYPEdecl 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 void* asIScriptModule::GetUserData ( ) const
pure virtual
Returns
The pointer to the user data.
virtual int asIScriptModule::LoadByteCode ( asIBinaryStream in,
bool *  wasDebugInfoStripped = 0 
)
pure virtual
Parameters
[in]inThe input stream.
[out]wasDebugInfoStrippedSet to true if the bytecode was saved without debug information.
Returns
A negative value on error.
Return values
asINVALID_ARGThe stream object wasn't specified.
asBUILD_IN_PROGRESSAnother 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.

See Also
Pre-compiled byte code
virtual int asIScriptModule::RemoveFunction ( asIScriptFunction func)
pure virtual
Parameters
[in]funcThe pointer to the function that should be removed.
Returns
A negative value on error.
Return values
asNO_FUNCTIONThe 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 ( asUINT  index)
pure virtual
Parameters
[in]indexThe index of the global variable.
Returns
A negative value on error.
Return values
asINVALID_ARGThe 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 ( asIScriptContext ctx = 0)
pure virtual
Parameters
[in]ctxOptional script context.
Returns
A negative value on error.
Return values
asERRORThe module was not compiled successfully.
asINIT_GLOBAL_VARS_FAILEDThe initialization of the global variables failed.

Resets the global variables declared in this module to their initial value. The context should be informed if the application needs to have extra control over how the initialization is done, for example for debugging, or for catching exceptions.

virtual int asIScriptModule::SaveByteCode ( asIBinaryStream out,
bool  stripDebugInfo = false 
) const
pure virtual
Parameters
[in]outThe output stream.
[in]stripDebugInfoSet to true to skip saving the debug information.
Returns
A negative value on error.
Return values
asINVALID_ARGThe stream object wasn't specified.
asNOT_SUPPORTEDCompiler support is disabled in the engine.
asERRORNothing has been compiled in the module.

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.

See Also
Pre-compiled byte code
virtual asDWORD asIScriptModule::SetAccessMask ( asDWORD  accessMask)
pure virtual
Parameters
[in]accessMaskThe access bit mask
Returns
The previous access mask.

The module's access mask with be bitwise and-ed with the registered entity's access mask in order to determine if the module is allowed to access the entity. If the result is zero then the script in the module will not be able to use the entity.

This can be used to provide different interfaces to scripts that serve different purposes in the application.

See Also
Access masks and exposing different interfaces
virtual int asIScriptModule::SetDefaultNamespace ( const char *  nameSpace)
pure virtual
Parameters
[in]nameSpaceThe namespace that should be used.
Returns
A negative value on error.
Return values
asINVALID_ARGThe namespace is null.
asINVALID_DECLARATIONThe namespace is invalid.

Set the default namespace that should be used in the following calls for searching for declared entities, or when compiling new individual entities.

virtual void asIScriptModule::SetName ( const char *  name)
pure virtual
Parameters
[in]nameThe new name.

Sets the name of the script module.

virtual void* asIScriptModule::SetUserData ( void *  data)
pure virtual
Parameters
[in]dataA pointer to the user data.
Returns
The previous pointer stored in the module

This method allows the application to associate a value, e.g. a pointer, with the module instance.

Optionally, a callback function can be registered to clean up the user data when the module is destroyed.

virtual int asIScriptModule::UnbindAllImportedFunctions ( )
pure virtual
Returns
A negative value on error.

Unbinds all imported functions in the module.

virtual int asIScriptModule::UnbindImportedFunction ( asUINT  importIndex)
pure virtual
Parameters
[in]importIndexThe index of the imported function.
Returns
A negative value on error.
Return values
asINVALID_ARGThe index is not valid.

Unbinds the imported function.


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