EngineFunctionInfo
Engine/source/console/engineFunctions.h
A function exported by the engine for interfacing with the control layer.
Protected Attributes
void *
Address of either the function implementation or the variable taking the address of a call-out.
const char *
Name of the DLL symbol denoting the address of the exported entity.
Default values for the function arguments.
A combination of EngineFunctionFlags.
The type of the function.
Next function in the global link chain of engine functions.
const char *
Full function prototype string.
Protected Static Attributes
First function in the global link chain of engine functions.
Public Functions
EngineFunctionInfo(const char * name, EngineExportScope * scope, const char * docString, const char * protoypeString, const char * bindingName, const EngineTypeInfo * functionType, const EngineFunctionDefaultArguments * defaultArgs, void * address, U32 flags)
getArgumentType(U32 index)
const char *
Return the DLL export symbol name.
Return the vector storing the default argument values.
const char *
Return the name of the function.
Return the type of this function.
Return the number of arguments that this function takes.
const char *
Return the function's full prototype string including the return type, function name, and argument list.
Return the return type of the function.
bool
Test whether this is a callout function.
bool
Test whether the function is variadic, i.e. takes a variable number of arguments.
Public Static Functions
Reset all callout function pointers back to NULL. This deactivates all callbacks.
Detailed Description
A function exported by the engine for interfacing with the control layer.
A function can either be a call-in, transfering control flow from the control layer to the engine, or a call-out, transfering control flow from the engine to the control layer.
All engine API functions use the native C (
cdecl) calling convention.
Be aware that there a no implicit parameters to functions. This, for example, means that methods will simply list an object type parameter as their first argument but otherwise be indistinguishable from other functions.
Variadic functions are supported.
String Arguments and Return Values
Strings passed through the API are assumed to be owned by the caller. They must persist for the entire duration of a call.
Strings returned by a function are assumed to be in transient storage that will be overwritten by subsequent API calls. If the caller wants to preserve a string, it is responsible to copying strings to its own memory. This will happen with most higher-level control layers anyway.
Default Arguments
As the engine API export system is set up to not require hand-written code in generated wrappers per se, the export system seeks to include a maximum possible amount of information in the export structures. To this end, where applicable, information about suggested default values for arguments to the engine API functions is stored in the export structures. It is up to the wrapper generator if and how it makes use of this information.
Default arguments are represented by capturing raw stack frame vectors of the arguments to functions. These frames could be used as default images for passing arguments in stack frames, though wrapper generators may actually want to read out individual argument values and include them in function prototypes within the generated code.
Call-ins
Call-ins are exposed as native entry points. The control layer must be able to natively marshall arguments and call DLL function exports using C calling conventions.
Call-outs
Call-outs are exposed as pointer-sized memory locations into which the control layer needs to install addresses of functions that receive the call from the engine back into the control layer. The function has to follow C calling conventions and
A call-out will initially be set to NULL and while being NULL, will simply cause the engine to skip and ignore the call-out. This allows the control layer to only install call-outs it is actually interested in.
Protected Attributes
void * mAddress
Address of either the function implementation or the variable taking the address of a call-out.
const char * mBindingName
Name of the DLL symbol denoting the address of the exported entity.
const EngineFunctionDefaultArguments * mDefaultArgumentValues
Default values for the function arguments.
BitSet32 mFunctionFlags
A combination of EngineFunctionFlags.
const EngineTypeInfo * mFunctionType
The type of the function.
EngineFunctionInfo * mNextFunction
Next function in the global link chain of engine functions.
const char * mPrototypeString
Full function prototype string.
Useful for quick printing and most importantly, this will be the only place containing information about the argument names.
Protected Static Attributes
EngineFunctionInfo * smFirstFunction
First function in the global link chain of engine functions.
Public Functions
EngineFunctionInfo(const char * name, EngineExportScope * scope, const char * docString, const char * protoypeString, const char * bindingName, const EngineTypeInfo * functionType, const EngineFunctionDefaultArguments * defaultArgs, void * address, U32 flags)
DECLARE_CLASS(EngineFunctionInfo , EngineExport )
getArgumentType(U32 index)
getBindingName()
Return the DLL export symbol name.
getDefaultArguments()
Return the vector storing the default argument values.
getFunctionName()
Return the name of the function.
getFunctionType()
Return the type of this function.
getNumArguments()
Return the number of arguments that this function takes.
If the function is variadic, this is the number of fixed arguments.
getPrototypeString()
Return the function's full prototype string including the return type, function name, and argument list.
getReturnType()
Return the return type of the function.
isCallout()
Test whether this is a callout function.
isVariadic()
Test whether the function is variadic, i.e. takes a variable number of arguments.
Public Static Functions
resetAllCallouts()
Reset all callout function pointers back to NULL. This deactivates all callbacks.