Regular API function

simCallScriptFunction (DEPRECATED) (remote API equivalent: simxCallScriptFunction)

Description This function is deprecated. Use instead simCallScriptFunctionEx.

Calls a script function (from a plugin, the main client application, or from another script). This represents a callback inside of a script. Call this only:
a) from the main thread, or:
b) from a thread that originated from a threaded child script. In that case, you cannot call non-threaded child scripts.
When calling simulation scripts, then simulation must be running. See also simCallScriptFunctionEx and simSetScriptVariable.
C synopsis simInt simCallScriptFunction(simInt scriptHandleOrType,const simChar* functionNameAtScriptName,SLuaCallBack* data,const simChar* reservedSetToNull)
C parameters
scriptHandleOrType: the handle of the script, otherwise the type of the script:
sim_scripttype_mainscript (0): the main script will be called.
sim_scripttype_childscript (1): a child script will be called. In that case, functionNameAtScriptName should also contain the name of the object associated with the script.
sim_scripttype_jointctrlcallback (4): a joint control callback script will be called. In that case, functionNameAtScriptName should also contain the name of the object associated with the script.
sim_scripttype_contactcallback (5): the contact callback script will be called.
sim_scripttype_customizationscript (6): a customization script will be called. In that case, functionNameAtScriptName should also contain the name of the object associated with the script.
sim_scripttype_generalcallback (7): the general callback script will be called.
functionNameAtScriptName: the name of the Lua function to call in the specified script. If scriptHandleOrType is sim_scripttype_childscript, sim_scripttype_jointctrlcallback or sim_scripttype_customizationscript, then functionNameAtScriptName should also contain the name of the object associated with the script: "functionName@objectName".
data: a pointer to a SLuaCallback structure. The structure needs to be properly initialized. See further down.
reservedSetToNull: reserved for future extensions. Set to NULL.


SLuaCallBack structure (see further down for a helper call that makes reading/writing to that structure easier):
simChar* inputBool: pointer to all Boolean input arguments. The user is in charge of allocating/releasing this buffer with simCreateBuffer/simReleaseBuffer if he intends to use it.
simInt* inputInt: pointer to all integer input arguments. The user is in charge of allocating/releasing this buffer with simCreateBuffer/simReleaseBuffer if he intends to use it.
simFloat* inputFloat: pointer to all single precision floating point input arguments. The user is in charge of allocating/releasing this buffer with simCreateBuffer/simReleaseBuffer if he intends to use it.
simDouble* inputDouble: pointer to all double precision floating point input arguments. The user is in charge of allocating/releasing this buffer with simCreateBuffer/simReleaseBuffer if he intends to use it.
simChar* inputChar: pointer to all string input arguments. Strings are separated by the "zero-char". The user is in charge of allocating/releasing this buffer with simCreateBuffer/simReleaseBuffer if he intends to use it.
simChar* inputCharBuff: pointer to all char buffer input arguments. The user is in charge of allocating/releasing this buffer with simCreateBuffer/simReleaseBuffer if he intends to use it.
simInt inputArgCount: number of input arguments.
simInt* inputArgTypeAndSize: pointer to input argument's type and size (e.g. with "inputArgCount==2" we could have "inputArgTypeAndSize[0]==sim_lua_arg_int|sim_lua_arg_table", "inputArgTypeAndSize[1]==3", "inputArgTypeAndSize[2]==sim_lua_arg_char", "inputArgTypeAndSize[3]==1". This would mean that we have two input arguments: (1) an integer table of size 3 and (2) a string). The user is in charge of allocating/releasing this buffer with simCreateBuffer/simReleaseBuffer.
simChar* outputBool: similar to inputBool, but for output values. V-REP will allocate this buffer, and the user should always release it, even if the function call was not successful.
simInt* outputInt: similar to inputInt, but for output values. V-REP will allocate this buffer, and the user should always release it, even if the function call was not successful.
simFloat* outputFloat: similar to inputFloat, but for output values. V-REP will allocate this buffer, and the user should always release it, even if the function call was not successful.
simFloat* outputDouble: similar to inputDouble, but for output values. V-REP will allocate this buffer, and the user should always release it, even if the function call was not successful.
simChar* outputChar: similar to inputChar, but for output values. V-REP will allocate this buffer, and the user should always release it, even if the function call was not successful. If two strings "ab" and "cde" are returned, the buffer will look like: "ab@cde@" (@ being the zero char).
simChar* outputCharBuff: similar to inputCharBuff, but for output values. V-REP will allocate this buffer, and the user should always release it, even if the function call was not successful. If two char buffers are returned, they should lay appended to each other in this buffer.
simInt outputArgCount: similar to inputArgCount, but for output values. Indicates how many arguments are expected to be returned. This value will be overwritten with the effective number of return arguments.
simInt* outputArgTypeAndSize: similar to inputArgTypeAndSize, but for output values. This represents the return data the user expects. This buffer will be used to perform correct type conversions, but in the end, the buffer will be reallocated and overwritten with the effective return arguments' type and sizes. The user is in charge of allocating/releasing the buffer with simCreateBuffer/simReleaseBuffer.

Values are stored in input or output arrays in the order they appear as arguments or return values e.g. with input arguments: number_int 1,table_2_float {2.0,3.0},string 'hello',number_int 4,string 'bye' we would have following input arrays:

inputInt=={1,4}
inputFloat=={2.0,3.0}
inputChar=="hello@bye@"
inputArgCount==5
inputArgTypeAndSize=={sim_lua_arg_int,1,sim_lua_arg_float|sim_lua_arg_table,
            2,sim_lua_arg_string,1, sim_lua_arg_int,1, sim_lua_arg_string,1}

Reading and writing arguments from/to the SLuaCallBack structure can be quite complicated and is error prone. Use instead the helper classes located in programming/common/stack and programming/include/stack: they will greatly simplify the task. Have a look at the example plugin programming/v_repExtSkeletonPlugin.
C return value
-1 in case of an error
Lua synopsis ...=simCallScriptFunction(string functionNameAtScriptName,number scriptHandleOrType,...)
Lua parameters
functionNameAtScriptName: a string representing the function name and script name, e.g. myFunctionName@theScriptName. When the script is not associated with an object, then just specify the function name.
scriptHandleOrType: the handle of the script, otherwise the type of the script:
sim_scripttype_mainscript (0): the main script will be called.
sim_scripttype_childscript (1): a child script will be called.
sim_scripttype_jointctrlcallback (4): a joint control callback script will be called.
sim_scripttype_contactcallback (5): the contact callback script will be called.
sim_scripttype_customizationscript (6): a customization script will be called.
sim_scripttype_generalcallback (7): the general callback script will be called.
...: any number of arguments that will be handed over to the called function.
Lua return values
...: any number of return values from the called function.

All regular API functions on one page