AngelScript
asIScriptEngine Class Referenceabstract

The engine interface. More...

Public Member Functions

Memory management
virtual int AddRef () const =0
 Increase reference counter. More...
 
virtual int Release () const =0
 Decrease reference counter. More...
 
Engine properties
virtual int SetEngineProperty (asEEngineProp property, asPWORD value)=0
 Dynamically change some engine properties. More...
 
virtual asPWORD GetEngineProperty (asEEngineProp property) const =0
 Retrieve current engine property settings. More...
 
Compiler messages
virtual int SetMessageCallback (const asSFuncPtr &callback, void *obj, asDWORD callConv)=0
 Sets a message callback that will receive compiler messages. More...
 
virtual int ClearMessageCallback ()=0
 Clears the registered message callback routine. More...
 
virtual int WriteMessage (const char *section, int row, int col, asEMsgType type, const char *message)=0
 Writes a message to the message callback. More...
 
JIT compiler
virtual int SetJITCompiler (asIJITCompiler *compiler)=0
 Sets the JIT compiler.
 
virtual asIJITCompilerGetJITCompiler () const =0
 Returns the JIT compiler.
 
Global functions
virtual int RegisterGlobalFunction (const char *declaration, const asSFuncPtr &funcPointer, asDWORD callConv, void *objForThiscall=0)=0
 Registers a global function. More...
 
virtual asUINT GetGlobalFunctionCount () const =0
 Returns the number of registered functions. More...
 
virtual asIScriptFunctionGetGlobalFunctionByIndex (asUINT index) const =0
 Returns the registered function. More...
 
virtual asIScriptFunctionGetGlobalFunctionByDecl (const char *declaration) const =0
 Returns the registered function. More...
 
Global properties
virtual int RegisterGlobalProperty (const char *declaration, void *pointer)=0
 Registers a global property. More...
 
virtual asUINT GetGlobalPropertyCount () const =0
 Returns the number of registered global properties. More...
 
virtual int GetGlobalPropertyByIndex (asUINT index, const char **name, const char **nameSpace=0, int *typeId=0, bool *isConst=0, const char **configGroup=0, void **pointer=0, asDWORD *accessMask=0) const =0
 Returns the detail on the registered global property. More...
 
virtual int GetGlobalPropertyIndexByName (const char *name) const =0
 Returns the index of the property. More...
 
virtual int GetGlobalPropertyIndexByDecl (const char *decl) const =0
 Returns the index of the property. More...
 
Object types
virtual int RegisterObjectType (const char *obj, int byteSize, asDWORD flags)=0
 Registers a new object type. More...
 
virtual int RegisterObjectProperty (const char *obj, const char *declaration, int byteOffset)=0
 Registers a property for the object type. More...
 
virtual int RegisterObjectMethod (const char *obj, const char *declaration, const asSFuncPtr &funcPointer, asDWORD callConv, void *objForThiscall=0)=0
 Registers a method for the object type. More...
 
virtual int RegisterObjectBehaviour (const char *obj, asEBehaviours behaviour, const char *declaration, const asSFuncPtr &funcPointer, asDWORD callConv, void *objForThiscall=0)=0
 Registers a behaviour for the object type. More...
 
virtual int RegisterInterface (const char *name)=0
 Registers a script interface. More...
 
virtual int RegisterInterfaceMethod (const char *intf, const char *declaration)=0
 Registers a script interface method. More...
 
virtual asUINT GetObjectTypeCount () const =0
 Returns the number of registered 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 a matching object type by name. More...
 
virtual asIObjectTypeGetObjectTypeByDecl (const char *decl) const =0
 Returns an object type by declaration. More...
 
String factory
virtual int RegisterStringFactory (const char *datatype, const asSFuncPtr &factoryFunc, asDWORD callConv, void *objForThiscall=0)=0
 Registers the string factory. More...
 
virtual int GetStringFactoryReturnTypeId (asDWORD *flags=0) const =0
 Returns the type id of the type that the string factory returns. More...
 
Default array type
virtual int RegisterDefaultArrayType (const char *type)=0
 Registers the type that should be used as the default array. More...
 
virtual int GetDefaultArrayTypeId () const =0
 Returns the type id of the registered type. More...
 
Enums
virtual int RegisterEnum (const char *type)=0
 Registers an enum type. More...
 
virtual int RegisterEnumValue (const char *type, const char *name, int value)=0
 Registers an enum value. More...
 
virtual asUINT GetEnumCount () const =0
 Returns the number of registered enum types. More...
 
virtual const char * GetEnumByIndex (asUINT index, int *enumTypeId, const char **nameSpace=0, const char **configGroup=0, asDWORD *accessMask=0) const =0
 Returns the registered enum type. More...
 
virtual int GetEnumValueCount (int enumTypeId) const =0
 Returns the number of enum values 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 for the enum type. More...
 
Funcdefs
virtual int RegisterFuncdef (const char *decl)=0
 Registers a function definition. More...
 
virtual asUINT GetFuncdefCount () const =0
 Returns the number of registered function definitions. More...
 
virtual asIScriptFunctionGetFuncdefByIndex (asUINT index) const =0
 Returns a registered function definition. More...
 
Typedefs
virtual int RegisterTypedef (const char *type, const char *decl)=0
 Registers a typedef. More...
 
virtual asUINT GetTypedefCount () const =0
 Returns the number of registered typedefs. More...
 
virtual const char * GetTypedefByIndex (asUINT index, int *typeId, const char **nameSpace=0, const char **configGroup=0, asDWORD *accessMask=0) const =0
 Returns a registered typedef. More...
 
Configuration groups
virtual int BeginConfigGroup (const char *groupName)=0
 Starts a new dynamic configuration group. More...
 
virtual int EndConfigGroup ()=0
 Ends the configuration group. More...
 
virtual int RemoveConfigGroup (const char *groupName)=0
 Removes a previously registered configuration group. More...
 
virtual asDWORD SetDefaultAccessMask (asDWORD defaultMask)=0
 Sets the access mask that should be used for subsequent registered entities. More...
 
virtual int SetDefaultNamespace (const char *nameSpace)=0
 Sets the current default namespace for registrations and searches. More...
 
virtual const char * GetDefaultNamespace () const =0
 Returns the current default namespace. More...
 
Script modules
virtual asIScriptModuleGetModule (const char *module, asEGMFlags flag=asGM_ONLY_IF_EXISTS)=0
 Return an interface pointer to the module. More...
 
virtual int DiscardModule (const char *module)=0
 Discard a module. More...
 
virtual asUINT GetModuleCount () const =0
 Get the number of modules. More...
 
virtual asIScriptModuleGetModuleByIndex (asUINT index) const =0
 Get a module by index. More...
 
Script functions
virtual asIScriptFunctionGetFunctionById (int funcId) const =0
 Returns the function by its id. More...
 
virtual asIScriptFunctionGetFuncDefFromTypeId (int typeId) const =0
 Returns the function description for the funcdef. More...
 
Type identification
virtual asIObjectTypeGetObjectTypeById (int typeId) const =0
 Returns the object type interface for type. More...
 
virtual int GetTypeIdByDecl (const char *decl) const =0
 Returns a type id by declaration. More...
 
virtual const char * GetTypeDeclaration (int typeId, bool includeNamespace=false) const =0
 Returns a type declaration. More...
 
virtual int GetSizeOfPrimitiveType (int typeId) const =0
 Returns the size of a primitive type. More...
 
Script execution
virtual asIScriptContextCreateContext ()=0
 Creates a new script context. More...
 
virtual void * CreateScriptObject (const asIObjectType *type)=0
 Creates an object defined by its type. More...
 
virtual void * CreateScriptObjectCopy (void *obj, const asIObjectType *type)=0
 Creates a copy of a script object. More...
 
virtual void * CreateUninitializedScriptObject (const asIObjectType *type)=0
 Creates an uninitialized script object defined by its type. More...
 
virtual asIScriptFunctionCreateDelegate (asIScriptFunction *func, void *obj)=0
 Create a delegate for an object and method. More...
 
virtual void AssignScriptObject (void *dstObj, void *srcObj, const asIObjectType *type)=0
 Copy one script object to another. More...
 
virtual void ReleaseScriptObject (void *obj, const asIObjectType *type)=0
 Release the object pointer. More...
 
virtual void AddRefScriptObject (void *obj, const asIObjectType *type)=0
 Increase the reference counter for the script object. More...
 
virtual bool IsHandleCompatibleWithObject (void *obj, int objTypeId, int handleTypeId) const =0
 Returns true if the object referenced by a handle compatible with the specified type. More...
 
virtual asILockableSharedBoolGetWeakRefFlagOfScriptObject (void *obj, const asIObjectType *type) const =0
 Returns the weak ref flag from the object. More...
 
Context pooling
virtual asIScriptContextRequestContext ()=0
 Request a context. More...
 
virtual void ReturnContext (asIScriptContext *ctx)=0
 Return a context when it won't be used anymore. More...
 
virtual int SetContextCallbacks (asREQUESTCONTEXTFUNC_t requestCtx, asRETURNCONTEXTFUNC_t returnCtx, void *param=0)=0
 Register context callbacks for pooling. More...
 
String interpretation
virtual asETokenClass ParseToken (const char *string, size_t stringLength=0, int *tokenLength=0) const =0
 Returns the class and length of the first token in the string. More...
 
Garbage collection
virtual int GarbageCollect (asDWORD flags=asGC_FULL_CYCLE, asUINT numIterations=1)=0
 Perform garbage collection. More...
 
virtual void GetGCStatistics (asUINT *currentSize, asUINT *totalDestroyed=0, asUINT *totalDetected=0, asUINT *newObjects=0, asUINT *totalNewDestroyed=0) const =0
 Obtain statistics from the garbage collector. More...
 
virtual int NotifyGarbageCollectorOfNewObject (void *obj, asIObjectType *type)=0
 Notify the garbage collector of a new object that needs to be managed. More...
 
virtual int GetObjectInGC (asUINT idx, asUINT *seqNbr=0, void **obj=0, asIObjectType **type=0)=0
 Gets an object in the garbage collector. More...
 
virtual void GCEnumCallback (void *reference)=0
 Used by the garbage collector to enumerate all references held by an object. More...
 
User data
virtual void * SetUserData (void *data, asPWORD type=0)=0
 Register the memory address of some user data. More...
 
virtual void * GetUserData (asPWORD type=0) const =0
 Returns the address of the previously registered user data. More...
 
virtual void SetEngineUserDataCleanupCallback (asCLEANENGINEFUNC_t callback, asPWORD type=0)=0
 Set the function that should be called when the engine is destroyed. More...
 
virtual void SetModuleUserDataCleanupCallback (asCLEANMODULEFUNC_t callback, asPWORD type=0)=0
 Set the function that should be called when the module is destroyed. More...
 
virtual void SetContextUserDataCleanupCallback (asCLEANCONTEXTFUNC_t callback, asPWORD type=0)=0
 Set the function that should be called when a context is destroyed. More...
 
virtual void SetFunctionUserDataCleanupCallback (asCLEANFUNCTIONFUNC_t callback, asPWORD type=0)=0
 Set the function that should be called when a function is destroyed. More...
 
virtual void SetObjectTypeUserDataCleanupCallback (asCLEANOBJECTTYPEFUNC_t callback, asPWORD type=0)=0
 Set the function that should be called when an object type is destroyed. More...
 

Detailed Description

The engine is the central object. It is where the application registers the application interface that the scripts should be able to use, and it is where the application can request modules to build scripts and contexts to execute them.

The engine instance is created with a call to asCreateScriptEngine.

It is allowed to have multiple instances of script engines, but there is rarely a need for it. Even if the application needs to expose different interfaces to different types of scripts this can usually be accomplished through the use of configuration groups and access profiles.

Member Function Documentation

virtual int asIScriptEngine::AddRef ( ) const
pure virtual
Returns
The number of references to this object.

Call this method when storing an additional reference to the object. Remember that the first reference that is received from asCreateScriptEngine is already accounted for.

virtual void asIScriptEngine::AddRefScriptObject ( void *  obj,
const asIObjectType type 
)
pure virtual
Parameters
[in]objA pointer to the object.
[in]typeThe type of the object.

This calls the add ref method of the object to increase the reference count.

virtual void asIScriptEngine::AssignScriptObject ( void *  dstObj,
void *  srcObj,
const asIObjectType type 
)
pure virtual
Parameters
[in]dstObjA pointer to the destination object.
[in]srcObjA pointer to the source object.
[in]typeThe type of the objects.

This calls the assignment operator to copy the object from one to the other.

This only works for objects.

virtual int asIScriptEngine::BeginConfigGroup ( const char *  groupName)
pure virtual
Parameters
[in]groupNameThe name of the configuration group
Returns
A negative value on error
Return values
asNAME_TAKENAnother group with the same name already exists.
asNOT_SUPPORTEDNesting configuration groups is not supported.

Starts a new dynamic configuration group. This group can be setup so that it is only visible to specific modules, and it can also be removed when it is no longer used.

See Also
Dynamic configurations
virtual int asIScriptEngine::ClearMessageCallback ( )
pure virtual
Returns
A negative value on error.

Call this method to remove the message callback.

virtual asIScriptContext* asIScriptEngine::CreateContext ( )
pure virtual
Returns
A pointer to the new script context.

This method creates a context that will be used to execute the script functions. The context interface created will have its reference counter already increased.

See Also
RequestContext
virtual asIScriptFunction* asIScriptEngine::CreateDelegate ( asIScriptFunction func,
void *  obj 
)
pure virtual
Parameters
[in]funcThe object method
[in]objThe object pointer
Returns
The new delegate instance
virtual void* asIScriptEngine::CreateScriptObject ( const asIObjectType type)
pure virtual
Parameters
[in]typeThe type of the object to create.
Returns
A pointer to the new object if successful, or null if not.

This method is used to create an object based on it's type. The method will call the object type's default factory. If the object type doesn't have a default factory the call will fail and no object will be created.

Created objects will have their reference counter set to 1 so the application needs to release the pointer when it will no longer use it.

If the type is a registered value type, then the memory for the object will be allocated using the default memory routine. To destroy and and deallocate the object it is best to use ReleaseScriptObject.

The method only works for objects, for primitive types and object handles the method doesn't do anything and returns a null pointer.

virtual void* asIScriptEngine::CreateScriptObjectCopy ( void *  obj,
const asIObjectType type 
)
pure virtual
Parameters
[in]objA pointer to the source object.
[in]typeThe type of the object.
Returns
A pointer to the new object if successful, or null if not.

This method is used to create a copy of an existing object.

This only works for objects, for primitive types and object handles the method doesn't do anything and returns a null pointer.

virtual void* asIScriptEngine::CreateUninitializedScriptObject ( const asIObjectType type)
pure virtual
Parameters
[in]typeThe type of the object to create.
Returns
A pointer to the new object if successful, or null if not.

This method can only be used to create instances of script classes.

The returned object will only be initialized so far that there are no invalid pointers or references. The constructor of the script class will not be invoked.

If the script class has any registered types as members, the default constructor for those members will be executed.

This method is meant for objects that will be initialized manually by the application, e.g. when restoring a serialized object.

virtual int asIScriptEngine::DiscardModule ( const char *  module)
pure virtual
Parameters
[in]moduleThe name of the module
Returns
A negative value on error
Return values
asNO_MODULEThe module was not found.

Discards a module and frees its memory. Any pointers that the application holds to this module will be invalid after this call.

virtual int asIScriptEngine::EndConfigGroup ( )
pure virtual
Returns
A negative value on error
Return values
asERRORCan't end a group that hasn't been begun.

Ends the current configuration group. Once finished a config group cannot be changed, but it can be removed when it is no longer used.

See Also
Dynamic configurations
virtual int asIScriptEngine::GarbageCollect ( asDWORD  flags = asGC_FULL_CYCLE,
asUINT  numIterations = 1 
)
pure virtual
Parameters
[in]flagsSet to a combination of the asEGCFlags.
[in]numIterationsThe number of iterations to perform when not doing a full cycle
Returns
1 if the cycle wasn't completed, 0 if it was.

This method will free script objects that can no longer be reached. When the engine is released the garbage collector will automatically do a full cycle to release all objects still alive. If the engine is long living it is important to call this method every once in a while to free up memory allocated by the scripts. If a script does a lot of allocations before returning it may be necessary to implement a line callback function that calls the garbage collector during execution of the script.

It is not necessary to do a full cycle with every call. This makes it possible to spread out the garbage collection time over a large period, thus not impacting the responsiveness of the application.

See Also
Garbage collection
virtual void asIScriptEngine::GCEnumCallback ( void *  reference)
pure virtual
Parameters
[in]referenceA pointer to the referenced object.

When processing the EnumReferences call the called object should call GCEnumCallback for each of the references it holds to other objects.

See Also
Garbage collected objects
virtual int asIScriptEngine::GetDefaultArrayTypeId ( ) const
pure virtual
Returns
The type id, or a negative value on error.
Return values
asINVALID_TYPEThe default array type hasn't been registered.
virtual const char* asIScriptEngine::GetDefaultNamespace ( ) const
pure virtual
Returns
The current default namespace
virtual asPWORD asIScriptEngine::GetEngineProperty ( asEEngineProp  property) const
pure virtual
Parameters
[in]propertyOne of the asEEngineProp values.
Returns
The value of the property, or 0 if it is an invalid property.

Calling this method lets you determine the current value of the engine properties.

virtual const char* asIScriptEngine::GetEnumByIndex ( asUINT  index,
int *  enumTypeId,
const char **  nameSpace = 0,
const char **  configGroup = 0,
asDWORD accessMask = 0 
) const
pure virtual
Parameters
[in]indexThe index of the enum type.
[out]enumTypeIdReceives the type if of the enum type.
[out]nameSpaceReceives the namespace of the enum.
[out]configGroupReceives the config group in which the enum was registered.
[out]accessMaskReceives the access mask of the enum.
Returns
The name of the registered enum type, or null on error.
virtual asUINT asIScriptEngine::GetEnumCount ( ) const
pure virtual
Returns
The number of registered enum types.
virtual const char* asIScriptEngine::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 value of the enum value.
Returns
The name of the enum value.
virtual int asIScriptEngine::GetEnumValueCount ( int  enumTypeId) const
pure virtual
Parameters
[in]enumTypeIdThe type id of the enum type.
Returns
The number of enum values for the enum type.
virtual asIScriptFunction* asIScriptEngine::GetFuncdefByIndex ( asUINT  index) const
pure virtual
Parameters
[in]indexThe index of the funcdef.
Returns
The funcdef.

This function does not increase the reference count of the return function definition.

virtual asUINT asIScriptEngine::GetFuncdefCount ( ) const
pure virtual
Returns
The number of registered funcdefs.
virtual asIScriptFunction* asIScriptEngine::GetFuncDefFromTypeId ( int  typeId) const
pure virtual
Parameters
[in]typeIdThe type id for the funcdef.
Returns
A pointer to the function description interface, or null if not found.

This does not increment the reference count of the returned function interface.

virtual asIScriptFunction* asIScriptEngine::GetFunctionById ( int  funcId) const
pure virtual
Parameters
[in]funcIdThe id of the function or method.
Returns
A pointer to the function description interface, or null if not found.

This does not increment the reference count of the returned function interface.

virtual void asIScriptEngine::GetGCStatistics ( asUINT currentSize,
asUINT totalDestroyed = 0,
asUINT totalDetected = 0,
asUINT newObjects = 0,
asUINT totalNewDestroyed = 0 
) const
pure virtual
Parameters
[out]currentSizeThe current number of objects known to the garbage collector.
[out]totalDestroyedThe total number of objects destroyed by the garbage collector.
[out]totalDetectedThe total number of objects detected as garbage with circular references.
[out]newObjectsThe current number of objects in the new generation.
[out]totalNewDestroyedThe total number of objects destroyed while still in the new generation.

This method can be used to query the number of objects that the garbage collector is keeping track of. If the number is very large then it is probably time to call the GarbageCollect method so that some of the objects ca be freed.

See Also
Garbage collection
virtual asIScriptFunction* asIScriptEngine::GetGlobalFunctionByDecl ( const char *  declaration) const
pure virtual
Parameters
[in]declarationThe signature of the function.
Returns
The function object, or null on error.
virtual asIScriptFunction* asIScriptEngine::GetGlobalFunctionByIndex ( asUINT  index) const
pure virtual
Parameters
[in]indexThe index of the registered global function.
Returns
The function object, or null on error.
virtual asUINT asIScriptEngine::GetGlobalFunctionCount ( ) const
pure virtual
Returns
The number of registered functions.
virtual int asIScriptEngine::GetGlobalPropertyByIndex ( asUINT  index,
const char **  name,
const char **  nameSpace = 0,
int *  typeId = 0,
bool *  isConst = 0,
const char **  configGroup = 0,
void **  pointer = 0,
asDWORD accessMask = 0 
) const
pure virtual
Parameters
[in]indexThe index of the global variable.
[out]nameReceives the name of the property.
[out]nameSpaceReceives the namespace of the property.
[out]typeIdReceives the typeId of the property.
[out]isConstReceives the constness indicator of the property.
[out]configGroupReceives the config group in which the property was registered.
[out]pointerReceives the pointer of the property.
[out]accessMaskReceives the access mask of the property.
Returns
A negative value on error.
Return values
asINVALID_ARGindex is too large.
virtual asUINT asIScriptEngine::GetGlobalPropertyCount ( ) const
pure virtual
Returns
The number of registered global properties.
virtual int asIScriptEngine::GetGlobalPropertyIndexByDecl ( const char *  decl) const
pure virtual
Parameters
[in]declThe declaration of the property to search for.
Returns
The index of the matching property or negative on error.
Return values
asNO_GLOBAL_VARNo matching property was found.
asINVALID_DECLARATIONThe given declaration is invalid.
virtual int asIScriptEngine::GetGlobalPropertyIndexByName ( const char *  name) const
pure virtual
Parameters
[in]nameThe name of the property.
Returns
The index of the matching property or negative on error.
Return values
asNO_GLOBAL_VARNo matching property was found.
virtual asIScriptModule* asIScriptEngine::GetModule ( const char *  module,
asEGMFlags  flag = asGM_ONLY_IF_EXISTS 
)
pure virtual
Parameters
[in]moduleThe name of the module
[in]flagOne of the asEGMFlags flags
Returns
A pointer to the module interface

Use this method to get access to the module interface, which will let you build new scripts, and enumerate functions and types in existing modules.

If asGM_ALWAYS_CREATE is informed as the flag the previous module with the same name will be discarded, thus any pointers that the engine holds to it will be invalid after the call.

virtual asIScriptModule* asIScriptEngine::GetModuleByIndex ( asUINT  index) const
pure virtual
Parameters
[in]indexThe index of the module.
Returns
A pointer to the module or null on error.
virtual asUINT asIScriptEngine::GetModuleCount ( ) const
pure virtual
Returns
The number of modules.
virtual int asIScriptEngine::GetObjectInGC ( asUINT  idx,
asUINT seqNbr = 0,
void **  obj = 0,
asIObjectType **  type = 0 
)
pure virtual
Parameters
[in]idxThe index of the desired object
[out]seqNbrThe sequence number of the obtained object
[out]objThe object pointer
[out]typeThe type of the obtained object
Returns
A negative value on error
Return values
asINVALID_ARGThe index is not valid
virtual asIObjectType* asIScriptEngine::GetObjectTypeByDecl ( const char *  decl) const
pure virtual
Parameters
[in]declThe declaration of the type.
Returns
The object type or null on error.

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

virtual asIObjectType* asIScriptEngine::GetObjectTypeById ( int  typeId) const
pure virtual
Parameters
[in]typeIdThe type id of the type.
Returns
The object type interface for the type, or null if not found.

This does not increment the reference count of the returned object type.

virtual asIObjectType* asIScriptEngine::GetObjectTypeByIndex ( asUINT  index) const
pure virtual
Parameters
[in]indexThe index of the type.
Returns
The registered object type interface for the type, or null if not found.
virtual asIObjectType* asIScriptEngine::GetObjectTypeByName ( const char *  name) const
pure virtual
Parameters
[in]nameThe name of the type.
Returns
The object type or null if no match is found.
virtual asUINT asIScriptEngine::GetObjectTypeCount ( ) const
pure virtual
Returns
The number of object types registered by the application.
virtual int asIScriptEngine::GetSizeOfPrimitiveType ( int  typeId) const
pure virtual
Parameters
[in]typeIdThe type id of the type.
Returns
The size of the type in bytes, or zero if it is not a primitive type.

This method can be used to return the size of any built-in primitive type, and also for script declared or application registered enums.

virtual int asIScriptEngine::GetStringFactoryReturnTypeId ( asDWORD flags = 0) const
pure virtual
Returns
The type id of the type that the string type returns, or a negative value on error.
Parameters
[out]flagsThe type modifiers for the return type
Return values
asNO_FUNCTIONThe string factory has not been registered.
virtual const char* asIScriptEngine::GetTypeDeclaration ( int  typeId,
bool  includeNamespace = false 
) const
pure virtual
Parameters
[in]typeIdThe type id of the type.
[in]includeNamespaceSet to true if the namespace should be included in the formatted declaration.
Returns
A null terminated string with the type declaration, or null if not found.
virtual const char* asIScriptEngine::GetTypedefByIndex ( asUINT  index,
int *  typeId,
const char **  nameSpace = 0,
const char **  configGroup = 0,
asDWORD accessMask = 0 
) const
pure virtual
Parameters
[in]indexThe index of the typedef.
[out]typeIdThe type that the typedef aliases.
[out]nameSpaceThe namespace in which the typedef was registered.
[out]configGroupReceives the config group in which the type def was registered.
[out]accessMaskThe access mask for the typedef.
Returns
The name of the typedef.
virtual asUINT asIScriptEngine::GetTypedefCount ( ) const
pure virtual
Returns
The number of registered typedefs.
virtual int asIScriptEngine::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.

This method is only able to return the type id that are not specific for a script module, i.e. built-in types and application registered types. Type ids for script declared types should be obtained through the script module's GetTypeIdByDecl.

virtual void* asIScriptEngine::GetUserData ( asPWORD  type = 0) const
pure virtual
Parameters
[in]typeAn identifier specifying the user data to get.
Returns
The pointer to the user data.
virtual asILockableSharedBool* asIScriptEngine::GetWeakRefFlagOfScriptObject ( void *  obj,
const asIObjectType type 
) const
pure virtual
Parameters
[in]objThe object
[in]typeThe object type
Returns
The weak ref flag, if the object supports weak references.

The method doesn't increase the reference to the returned shared boolean.

virtual bool asIScriptEngine::IsHandleCompatibleWithObject ( void *  obj,
int  objTypeId,
int  handleTypeId 
) const
pure virtual
Parameters
[in]objA pointer to the object.
[in]objTypeIdThe type id of the object.
[in]handleTypeIdThe type id of the handle.
Returns
Returns true if the handle type is compatible with the object type.

This method can be used to determine if a handle of a certain type is compatible with an object of another type. This is useful if you have a pointer to a object, but only knows that it implements a certain interface and now you want to determine if it implements another interface.

virtual int asIScriptEngine::NotifyGarbageCollectorOfNewObject ( void *  obj,
asIObjectType type 
)
pure virtual
Parameters
[in]objA pointer to the newly created object.
[in]typeThe type of the object.
Returns
The sequence number of the added object, or a negative value on error.
Return values
asINVALID_ARGEither the object or the type is null

This method should be called when a new garbage collected object is created. The GC will then store a reference to the object so that it can automatically detect whether the object is involved in any circular references that should be released.

See Also
Garbage collected objects
virtual asETokenClass asIScriptEngine::ParseToken ( const char *  string,
size_t  stringLength = 0,
int *  tokenLength = 0 
) const
pure virtual
Parameters
[in]stringThe string to parse.
[in]stringLengthThe length of the string. Can be 0 if the string is null terminated.
[out]tokenLengthGives the length of the identified token.
Returns
One of the asETokenClass values.

This function is useful for those applications that want to tokenize strings into tokens that the script language uses, e.g. IDEs providing syntax highlighting, or intellisense. It can also be used to parse the meta data strings that may be declared for script entities.

virtual int asIScriptEngine::RegisterDefaultArrayType ( const char *  type)
pure virtual
Parameters
[in]typeThe name of the template type, e.g. array<T>
Returns
A negative value on error.
Return values
asINVALID_TYPEThe type is not a template type
virtual int asIScriptEngine::RegisterEnum ( const char *  type)
pure virtual
Parameters
[in]typeThe name of the enum type.
Returns
A negative value on error.
Return values
asINVALID_NAMEtype is null.
asALREADY_REGISTEREDAnother type with this name already exists.
asERRORThe type couldn't be parsed.
asINVALID_NAMEThe type is not an identifier, or it is a reserved keyword.
asNAME_TAKENThe type name is already taken.

This method registers an enum type in the engine. The enum values should then be registered with RegisterEnumValue.

virtual int asIScriptEngine::RegisterEnumValue ( const char *  type,
const char *  name,
int  value 
)
pure virtual
Parameters
[in]typeThe name of the enum type.
[in]nameThe name of the enum value.
[in]valueThe integer value of the enum value.
Returns
A negative value on error.
Return values
asWRONG_CONFIG_GROUPThe enum type was registered in a different configuration group.
asINVALID_TYPEThe type is invalid.
asALREADY_REGISTEREDThe name is already registered for this enum.

This method registers an enum value for a previously registered enum type.

virtual int asIScriptEngine::RegisterFuncdef ( const char *  decl)
pure virtual
Parameters
[in]declThe declaration of the function definition.
Returns
A negative value on error.
Return values
asINVALID_ARGThe decl parameter is not given.
asINVALID_DECLARATIONdecl is not a valid function definition.
asNAME_TAKENThe name of the funcdef conflicts with another name.

Funcdefs are used to define the signature of function pointers. If the application is going to receive function pointers from scripts, it is necessary to first register the funcdef before registering the function or property that will be used to receive it.

virtual int asIScriptEngine::RegisterGlobalFunction ( const char *  declaration,
const asSFuncPtr funcPointer,
asDWORD  callConv,
void *  objForThiscall = 0 
)
pure virtual
Parameters
[in]declarationThe declaration of the global function in script syntax.
[in]funcPointerThe function pointer.
[in]callConvThe calling convention for the function.
[in]objForThiscallAn object pointer for use with asCALL_THISCALL_ASGLOBAL.
Returns
A negative value on error, or the function id if successful.
Return values
asNOT_SUPPORTEDThe calling convention is not supported.
asWRONG_CALLING_CONVThe function's calling convention doesn't match callConv.
asINVALID_DECLARATIONThe function declaration is invalid.
asNAME_TAKENThe function name is already used elsewhere.
asALREADY_REGISTEREDThe function has already been registered with the same parameter list.
asINVALID_ARGThe objForThiscall pointer wasn't set according to calling convention.

This method registers system functions that the scripts may use to communicate with the host application.

See Also
Registering a function
virtual int asIScriptEngine::RegisterGlobalProperty ( const char *  declaration,
void *  pointer 
)
pure virtual
Parameters
[in]declarationThe declaration of the global property in script syntax.
[in]pointerThe address of the property that will be used to access the property value.
Returns
A negative value on error.
Return values
asINVALID_DECLARATIONThe declaration has invalid syntax.
asINVALID_TYPEThe declaration is a reference.
asINVALID_ARGThe pointer is null.
asNAME_TAKENThe name is already taken.

Use this method to register a global property that the scripts will be able to access as global variables. The property may optionally be registered as const, if the scripts shouldn't be allowed to modify it.

When registering the property, the application must pass the address to the actual value. The application must also make sure that this address remains valid throughout the life time of this registration, i.e. until the engine is released or the dynamic configuration group is removed.

virtual int asIScriptEngine::RegisterInterface ( const char *  name)
pure virtual
Parameters
[in]nameThe name of the interface.
Returns
A negative value on error.
Return values
asINVALID_NAMEThe name is null, or a reserved keyword.
asALREADY_REGISTEREDAn object type with this name already exists.
asERRORThe name is not a proper identifier.
asNAME_TAKENThe name is already used elsewhere.

This registers an interface that script classes can implement. By doing this the application can register functions and methods that receives an asIScriptObject and still be sure that the class implements certain methods needed by the application.

See Also
Receiving script classes
virtual int asIScriptEngine::RegisterInterfaceMethod ( const char *  intf,
const char *  declaration 
)
pure virtual
Parameters
[in]intfThe name of the interface.
[in]declarationThe method declaration.
Returns
A negative value on error.
Return values
asWRONG_CONFIG_GROUPThe interface was registered in another configuration group.
asINVALID_TYPEintf is not an interface type.
asINVALID_DECLARATIONThe declaration is invalid.
asNAME_TAKENThe method name is already taken.

This registers a method that the class that implements the script interface must have.

virtual int asIScriptEngine::RegisterObjectBehaviour ( const char *  obj,
asEBehaviours  behaviour,
const char *  declaration,
const asSFuncPtr funcPointer,
asDWORD  callConv,
void *  objForThiscall = 0 
)
pure virtual
Parameters
[in]objThe name of the type.
[in]behaviourOne of the object behaviours from asEBehaviours.
[in]declarationThe declaration of the method in script syntax.
[in]funcPointerThe method or function pointer.
[in]callConvThe calling convention for the method or function.
[in]objForThiscallThe object pointer used for asCALL_THISCALL_ASGLOBAL, asCALL_THISCALL_OBJFIRST, and asCALL_THISCALL_OBJLAST
Returns
A negative value on error, or the function id is successful.
Return values
asWRONG_CONFIG_GROUPThe object type was registered in a different configuration group.
asINVALID_ARGobj is not set, or a global behaviour is given in behaviour.
asWRONG_CALLING_CONVThe function's calling convention isn't compatible with callConv.
asNOT_SUPPORTEDThe calling convention or the behaviour signature is not supported.
asINVALID_TYPEThe obj parameter is not a valid object name.
asINVALID_DECLARATIONThe declaration is invalid.
asILLEGAL_BEHAVIOUR_FOR_TYPEThe behaviour is not allowed for this type.
asALREADY_REGISTEREDThe behaviour is already registered with the same signature.
asINVALID_ARGThe objForThiscall pointer wasn't set according to calling convention.

Use this method to register behaviour functions that will be called by the virtual machine to perform certain operations, such as memory management, math operations, comparisons, etc.

The declaration must form a valid function signature, but the give function name will not be used or stored in the application so there is no need to provide a meaningful function name.

See Also
Registering a function, Registering operator behaviours
virtual int asIScriptEngine::RegisterObjectMethod ( const char *  obj,
const char *  declaration,
const asSFuncPtr funcPointer,
asDWORD  callConv,
void *  objForThiscall = 0 
)
pure virtual
Parameters
[in]objThe name of the type.
[in]declarationThe declaration of the method in script syntax.
[in]funcPointerThe method or function pointer.
[in]callConvThe calling convention for the method or function.
[in]objForThiscallA pointer to the functor object for use with asCALL_THISCALL_OBJFIRST and asCALL_THISCALL_OBJLAST
Returns
A negative value on error, or the function id if successful.
Return values
asWRONG_CONFIG_GROUPThe object type was registered in a different configuration group.
asNOT_SUPPORTEDThe calling convention is not supported.
asINVALID_TYPEThe obj parameter is not a valid object name.
asINVALID_DECLARATIONThe declaration is invalid.
asNAME_TAKENThe name conflicts with other members.
asWRONG_CALLING_CONVThe function's calling convention isn't compatible with callConv.
asALREADY_REGISTEREDThe method has already been registered with the same parameter list.
asINVALID_ARGThe objForThiscall pointer wasn't set according to calling convention.

Use this method to register a member method for the type. The method that is registered may be an actual class method, or a global function that takes the object pointer as either the first or last parameter. Or it may be a global function implemented with the generic calling convention.

See Also
Registering a function
virtual int asIScriptEngine::RegisterObjectProperty ( const char *  obj,
const char *  declaration,
int  byteOffset 
)
pure virtual
Parameters
[in]objThe name of the type.
[in]declarationThe property declaration in script syntax.
[in]byteOffsetThe offset into the memory block where this property is found.
Returns
A negative value on error.
Return values
asWRONG_CONFIG_GROUPThe object type was registered in a different configuration group.
asINVALID_OBJECTThe obj does not specify an object type.
asINVALID_TYPEThe obj parameter has invalid syntax.
asINVALID_DECLARATIONThe declaration is invalid.
asNAME_TAKENThe name conflicts with other members.

Use this method to register a member property of a class. The property must be local to the object, i.e. not a global variable or a static member. The easiest way to get the offset of the property is to use the asOFFSET macro.

struct MyType {float prop;};
r = engine->RegisterObjectProperty("MyType", "float prop", asOFFSET(MyType, prop)));
virtual int asIScriptEngine::RegisterObjectType ( const char *  obj,
int  byteSize,
asDWORD  flags 
)
pure virtual
Parameters
[in]objThe name of the type.
[in]byteSizeThe size of the type in bytes. Only necessary for value types.
[in]flagsOne or more of the asEObjTypeFlags.
Returns
The type id on success or a negative value on error.
Return values
asINVALID_ARGThe flags are invalid.
asINVALID_NAMEThe name is invalid.
asALREADY_REGISTEREDAnother type of the same name already exists.
asNAME_TAKENThe name conflicts with other symbol names.
asLOWER_ARRAY_DIMENSION_NOT_REGISTEREDWhen registering an array type the array element must be a primitive or a registered type.
asINVALID_TYPEThe array type was not properly formed.
asNOT_SUPPORTEDThe array type is not supported, or already in use preventing it from being overloaded.

Use this method to register new types that should be available to the scripts. Reference types, which have their memory managed by the application, should be registered with asOBJ_REF. Value types, which have their memory managed by the engine, should be registered with asOBJ_VALUE.

See Also
Registering an object type
virtual int asIScriptEngine::RegisterStringFactory ( const char *  datatype,
const asSFuncPtr factoryFunc,
asDWORD  callConv,
void *  objForThiscall = 0 
)
pure virtual
Parameters
[in]datatypeThe datatype that the string factory returns
[in]factoryFuncThe pointer to the factory function
[in]callConvThe calling convention of the factory function
[in]objForThiscallThe object pointer used for asCALL_THISCALL_ASGLOBAL.
Returns
A negative value on error, or the function id if successful.
Return values
asNOT_SUPPORTEDThe calling convention is not supported.
asWRONG_CALLING_CONVThe function's calling convention doesn't match callConv.
asINVALID_TYPEThe datatype is not a valid type.

Use this function to register a string factory that will be called when the virtual machine finds a string constant in an expression. The string factory function will receive two parameters, the length of the string constant in bytes and a pointer to the character data. The factory should return a value to a previously registered type that will represent the string. Example:

// Our string factory implementation
std::string StringFactory(unsigned int byteLength, const char *s)
{
return std::string(s, byteLength);
}
// Registering the string factory
int r = engine->RegisterStringFactory("string", asFUNCTION(StringFactory), asCALL_CDECL); assert( r >= 0 );

The example assumes that the std::string type has been registered as the string type, with RegisterObjectType.

virtual int asIScriptEngine::RegisterTypedef ( const char *  type,
const char *  decl 
)
pure virtual
Parameters
[in]typeThe name of the new typedef
[in]declThe datatype that the typedef represents
Returns
A negative value on error.
Return values
asINVALID_NAMEThe type is null.
asALREADY_REGISTEREDA type with the same name already exists.
asINVALID_TYPEThe decl is not a primitive type.
asINVALID_NAMEThe type is not an identifier, or it is a reserved keyword.
asNAME_TAKENThe name is already used elsewhere.

This method registers an alias for a data type.

Currently typedefs can only be registered for built-in primitive types.

virtual int asIScriptEngine::Release ( ) const
pure virtual
Returns
The number of references to this object.

Call this method when you will no longer use the references that you own.

The application is responsible for releasing references to all other script objects before releasing its last reference to the engine. If this is not done, it is possible that memory leaks occur as the engine cannot free objects kept alive by the application.

virtual void asIScriptEngine::ReleaseScriptObject ( void *  obj,
const asIObjectType type 
)
pure virtual
Parameters
[in]objA pointer to the object.
[in]typeThe type of the object.

This calls the release method of the object to release the reference.

If the type is a value type, the method will destroy the object and deallocate the memory using the default memory routine.

virtual int asIScriptEngine::RemoveConfigGroup ( const char *  groupName)
pure virtual
Parameters
[in]groupNameThe name of the configuration group
Returns
A negative value on error
Return values
asCONFIG_GROUP_IS_IN_USEThe group is in use and cannot be removed.

Remove the configuration group. If something in the configuration group is currently in use, the function will return with an error code. Examples of uses are compiled modules that have function calls to functions in the group and global variables of types registered in the group.

See Also
Dynamic configurations
virtual asIScriptContext* asIScriptEngine::RequestContext ( )
pure virtual
Returns
An unprepared context

This method will invoke the registered request context callback and return an available context in an unprepared state.

Contexts obtained through this method shouldn't be released, instead they should be returned to the origin with a call to ReturnContext.

See Also
CreateContext
virtual void asIScriptEngine::ReturnContext ( asIScriptContext ctx)
pure virtual
Parameters
[in]ctxThe context that should be returned to the origin
virtual int asIScriptEngine::SetContextCallbacks ( asREQUESTCONTEXTFUNC_t  requestCtx,
asRETURNCONTEXTFUNC_t  returnCtx,
void *  param = 0 
)
pure virtual
Parameters
[in]requestCtxThe request context callback function
[in]returnCtxThe return context callback function
[in]paramAn optional parameter that will be passed to the callback
Returns
A negative value on error
Return values
asINVALID_ARGOnly one of the context functions is informed

This method can be used by the application to implement a context pool, or to perform custom configuration on the contexts that the engine uses internally.

This can for example be used to debug calls to initialize global variables when building modules, or to detect script exceptions that may occur in script class destructors when called from the garbage collector.

virtual void asIScriptEngine::SetContextUserDataCleanupCallback ( asCLEANCONTEXTFUNC_t  callback,
asPWORD  type = 0 
)
pure virtual
Parameters
[in]callbackA pointer to the function
[in]typeAn identifier specifying which user data the callback is to be used with.

The function given with this call will be invoked when a context is destroyed if any user data has been registered with the context.

The function is called from within the context destructor, so the callback should not be used for anything but cleaning up the user data itself.

virtual asDWORD asIScriptEngine::SetDefaultAccessMask ( asDWORD  defaultMask)
pure virtual
Parameters
[in]defaultMaskThe default access bit mask.
Returns
The previous default mask.
See Also
Access masks and exposing different interfaces
virtual int asIScriptEngine::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 invalid

Call this method to set the default namespace for which the following calls should assume. This applies to registration of the application interface and also to the functions that searches for registered entities.

Nested namespaces can be informed by separating them with the scope token, i.e. ::

virtual int asIScriptEngine::SetEngineProperty ( asEEngineProp  property,
asPWORD  value 
)
pure virtual
Parameters
[in]propertyOne of the asEEngineProp values.
[in]valueThe new value of the property.
Returns
Negative value on error.
Return values
asINVALID_ARGInvalid property.

With this method you can change the way the script engine works in some regards.

virtual void asIScriptEngine::SetEngineUserDataCleanupCallback ( asCLEANENGINEFUNC_t  callback,
asPWORD  type = 0 
)
pure virtual
Parameters
[in]callbackA pointer to the function
[in]typeAn identifier specifying which user data the callback is to be used with.

The function given with this call will be invoked when the engine is destroyed if any user data has been registered with the engine.

The function is called from within the engine destructor, so the callback should not be used for anything but cleaning up the user data itself.

virtual void asIScriptEngine::SetFunctionUserDataCleanupCallback ( asCLEANFUNCTIONFUNC_t  callback,
asPWORD  type = 0 
)
pure virtual
Parameters
[in]callbackA pointer to the function
[in]typeAn identifier specifying which user data the callback is to be used with.

The function given with this call will be invoked when a function is destroyed if any user data has been registered with the function.

The function is called from within the function destructor, so the callback should not be used for anything but cleaning up the user data itself.

virtual int asIScriptEngine::SetMessageCallback ( const asSFuncPtr callback,
void *  obj,
asDWORD  callConv 
)
pure virtual
Parameters
[in]callbackA function or class method pointer.
[in]objThe object for methods, or an optional parameter for functions.
[in]callConvThe calling convention.
Returns
A negative value for an error.
Return values
asINVALID_ARGOne of the arguments is incorrect, e.g. obj is null for a class method.
asNOT_SUPPORTEDThe arguments are not supported, e.g. asCALL_GENERIC.

This method sets the callback routine that will receive compiler messages. The callback routine can be either a class method, e.g:

void MyClass::MessageCallback(const asSMessageInfo *msg);
r = engine->SetMessageCallback(asMETHOD(MyClass,MessageCallback), &obj, asCALL_THISCALL);

or a global function, e.g:

void MessageCallback(const asSMessageInfo *msg, void *param);
r = engine->SetMessageCallback(asFUNCTION(MessageCallback), param, asCALL_CDECL);

It is recommended to register the message callback routine right after creating the engine, as some of the registration functions can provide useful information to better explain errors.

virtual void asIScriptEngine::SetModuleUserDataCleanupCallback ( asCLEANMODULEFUNC_t  callback,
asPWORD  type = 0 
)
pure virtual
Parameters
[in]callbackA pointer to the function
[in]typeAn identifier specifying which user data the callback is to be used with.

The function given with this call will be invoked when the module is destroyed if any user data has been registered with the module.

The function is called from within the module destructor, so the callback should not be used for anything but cleaning up the user data itself.

virtual void asIScriptEngine::SetObjectTypeUserDataCleanupCallback ( asCLEANOBJECTTYPEFUNC_t  callback,
asPWORD  type = 0 
)
pure virtual
Parameters
[in]callbackA pointer to the function
[in]typeAn identifier specifying which user data the callback is to be used with.

The function given with this call will be invoked when an object type is destroyed if any user data has been registered with the type.

The function is called from within the object type destructor, so the callback should not be used for anything but cleaning up the user data itself.

virtual void* asIScriptEngine::SetUserData ( void *  data,
asPWORD  type = 0 
)
pure virtual
Parameters
[in]dataA pointer to the user data.
[in]typeAn identifier specifying the user data to set.
Returns
The previous pointer stored in the engine.

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

The type values 1000 through 1999 are reserved for use by the official add-ons.

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

virtual int asIScriptEngine::WriteMessage ( const char *  section,
int  row,
int  col,
asEMsgType  type,
const char *  message 
)
pure virtual
Parameters
[in]sectionThe name of the script section.
[in]rowThe row number.
[in]colThe column number.
[in]typeThe message type.
[in]messageThe message text.
Returns
A negative value on error.
Return values
asINVALID_ARGThe section or message is null.

This method can be used by the application to write messages to the same message callback that the script compiler uses. This is useful for example if a preprocessor is used.


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