callExtension
Description
- Description:
- Calls custom .dll also known as Extension. The name of the extension is the name of the extension .dll without ".dll" part (or without "_x64.dll" part on 64-bit Arma). For example if the file is 'myExtension.dll' the name of the extension will be "myExtension". For 64-bit extensions, the name of the extension doesn't need to change and is still "myExtension". The game will automatically look for 'myExtension_x64.dll' when you use 64-bit Arma exe.
This command is blocking, meaning that the game will wait for the extension to return before continuing. This may cause FPS drop if extension is not optimised. If extension takes too long, consider making asynchronous extension, where the result of the work of the extension is collected in a separate call.
Currently there is no limit how much data you can send to the extension. However there is a limit on how much data you can return from extension in one call. The limit is known to the extension and is passed in int outputSize. The limit may or may not change in the future and is currently 10240 bytes. It is up to extension designer to handle multipart results if returned data exceeds output limit.
Since Arma 3 v1.67 it is possible to pass array of arguments to extensions. The array of arguments could be anything and all elements will be converted to strings, however you might want to only send simple types like Booleans, Strings, Numbers and Arrays of all of the above. There is currently a limit on how many arguments can be sent and it is 2048 (since Arma 3 v1.92; previous limit: 1024). However an argument could be an Array itself, in this case extension maker will have to provide additional methods for parsing such arguments.
Possible error codes:- 101: SYNTAX_ERROR_WRONG_PARAMS_SIZE
- 102: SYNTAX_ERROR_WRONG_PARAMS_TYPE
- 201: PARAMS_ERROR_TOO_MANY_ARGS
- 301: EXECUTION_WARNING_TAKES_TOO_LONG
The extension execution timeout, after which 301: EXECUTION_WARNING_TAKES_TOO_LONG warning is issued, is hardcoded on clients and is 1000.0 milliseconds (1 second). On the server the default limit is also 1 second, however it is possible to set custom limit with callExtReportLimit param (see Server Options).
If an extension with the given name can't be found (or it is found but doesn't implement the required interface properly / at all) the following error will be written into the RPT (In this example the given dll-name was "MyExtension"):
If an extension is not whitelisted with BattlEye (see Extensions for more info) it will be blocked on clients running with enabled BattlEye protection. RPT message outputted however is a little obscure:
Since Arma 3 v1.69, RVExtensionVersion interface (see source code example below) has been added, which is called by the engine on extension load and expects extension version. This interface is designed to work with both, Linux and Windows. The max buffer size is 32 bytes. The version information will then appear in .rpt file like so:19:06:36 CallExtension loaded: test_extension (.\test_extension.dll) [1.0.0.1]
For more information see Extensions.
Linux specific
While on Windows the extension name is case-insensitive, on Linux the extension name is case-sensitive and should match the name of the .so file exactly (minus ".so" part).
Extension Callback
Since Arma 3 v1.95 it is possible to call the game directly from the extension via function pointer provided when extension is called for the first time (assuming the extension implements at least one of the RVExtension or RVExtensionArgs methods). The function pointer passed over to RVExtensionRegisterCallback method is of the following signature (see Example 4):
int(*callbackProc)(char const *name, char const *function, char const *data)
Calling this function pointer from extension will trigger "ExtensionCallback" mission event handler with 3 user supplied params. The params are
- name - make it unique name, for example the extension name, so that other modders can quickly filter out calls from own extensions
- function - make it name of the function the extension sends the result to. (Note: The returned function is just a STRING! So compile is needed, before using call or spawn, to execute it)
- data - make it the actual result. You can also format it as an array so it could be parsed by parseSimpleArray
- Groups:
- System
Syntax
- Syntax:
- extension callExtension function
- Parameters:
- extension: String - extension name
- function: String - data sent to the extension
- Return Value:
- String - data sent back from extension; If the extensiion was not found an empty String will be returned
Alternative Syntax
- Syntax:
- extension callExtension [function, arguments]
- Parameters:
- extension: String - extension name
- function: String - extension function identifier
- arguments: Array - function arguments. Could be array of Anything, each element will be converted to String automatically. Current allowed max length of this array is 2048 (since Arma 3 v1.92; previous limit: 1024)
- Return Value:
- Array - in format [result, returnCode, errorCode], where:
Examples
- Example 1:
- Example 2:
- Example 3:
- _result = "test_extension" callExtension ["fnc1", [1, "two", true, [4, "five", false]]]; parseSimpleArray (_result select 0) params ["_number","_string","_boolean","_array"]; systemChat str [_number,_string,_boolean,_array];
Source Code (Download .dll)This is an example of an extension compatible with both syntaxes. When using 1st syntax, the data is just copied from input to output. When using alt syntax, the arguments are parsed and then assembled back into string array in 2 ways: fnc1 and fnc2. fnc1 is a fraction faster.
↑ Back to spoiler's top#include <string> #include <vector> #include <iterator> #include <sstream> #define CURRENT_VERSION "1.0.0.1" extern "C" { //--- Engine called on extension load __declspec (dllexport) void __stdcall RVExtensionVersion(char *output, int outputSize); //--- STRING callExtension STRING __declspec (dllexport) void __stdcall RVExtension(char *output, int outputSize, const char *function); //--- STRING callExtension ARRAY __declspec (dllexport) int __stdcall RVExtensionArgs(char *output, int outputSize, const char *function, const char **args, int argsCnt); } //--- Extension version information shown in .rpt file void __stdcall RVExtensionVersion(char *output, int outputSize) { //--- max outputSize is 32 bytes strncpy_s(output, outputSize, CURRENT_VERSION, _TRUNCATE); } //--- name callExtension function void __stdcall RVExtension(char *output, int outputSize, const char *function) { std::string str = function; strncpy_s(output, outputSize, ("Input Was: " + str).c_str(), _TRUNCATE); } //--- name callExtension [function, args] int __stdcall RVExtensionArgs(char *output, int outputSize, const char *function, const char **args, int argsCnt) { if (strcmp(function, "fnc1") == 0) { //--- Manually assemble output array int i = 0; std::string str = "["; //--- Each argument can be accessed via args[n] if (argsCnt > 0) str += args[i++]; while (i < argsCnt) { str += ","; str += args[i++]; } str += "]"; //--- Extension result strncpy_s(output, outputSize, str.c_str(), _TRUNCATE); //--- Extension return code return 100; } else if (strcmp(function, "fnc2") == 0) { //--- Parse args into vector std::vector<std::string> vec(args, std::next(args, argsCnt)); std::ostringstream oss; if (!vec.empty()) { //--- Assemble output array std::copy(vec.begin(), vec.end() - 1, std::ostream_iterator<std::string>(oss, ",")); oss << vec.back(); } //--- Extension result strncpy_s(output, outputSize, ("[" + oss.str() + "]").c_str(), _TRUNCATE); //--- Extension return code return 200; } else { strncpy_s(output, outputSize, "Avaliable Functions: fnc1, fnc2", outputSize - 1); return -1; } }
- Example 4:
- fncToExecute_1 = { hint format ["Extension Result 1: %1", _this] }; fncToExecute_2 = { hint format ["Extension Result 2: %1", _this] }; fncToExecute_3 = { hint format ["Extension Result 3: %1", _this] }; addMissionEventHandler ["ExtensionCallback", { params ["_name", "_function", "_data"]; if (_name isEqualTo "test_callback") then { parseSimpleArray _data call (missionNamespace getVariable [_function, { hint "Function does not exist!" }]); }; }]; "test_callback" callExtension str "test data";
Here is a minimal example of an extension utilising extension callback (don't actually do it like this). fncToExecute_X function is called from "ExtensionCallback" event handler when it is triggered after 2 seconds of the extension call.↑ Back to spoiler's top#include <thread> #include <string> #include <chrono> extern "C" { __declspec (dllexport) void __stdcall RVExtensionRegisterCallback(int(*callbackProc)(char const *name, char const *function, char const *data)); __declspec (dllexport) void __stdcall RVExtension(char *output, int outputSize, const char *function); } int(*callbackPtr)(char const *name, char const *function, char const *data) = nullptr; void __stdcall RVExtensionRegisterCallback(int(*callbackProc)(char const *name, char const *function, char const *data)) { callbackPtr = callbackProc; } void __stdcall RVExtension(char *output, int outputSize, const char *function) { if (!callbackPtr) return; std::thread ([](std::string fnc) { using namespace std::chrono_literals; fnc = "[1,2,3," + fnc + "]"; for (int i = 1; i < 4; ++i) // run 3 times { std::this_thread::sleep_for(2s); // sleep for 2 seconds callbackPtr("test_callback", ("fncToExecute_" + std::to_string(i)).c_str(), fnc.c_str()); } }, function).detach(); }
Additional Information
- See also:
- call compile parseSimpleArray Extensions
Notes
-
Report bugs on the Feedback Tracker and/or discuss them on the Arma Discord or on the Forums.
Only post proven facts here! Add Note