Extension Reference - TheCodeNugget/Arma3-PiShock GitHub Wiki
Preamble
If you're planning to use Arma 3 PiShock as a basis/dependency to what you're planning to do, I'd highly recommend avoiding calling the extension direcly and using the functions found in Functions Reference, if you can't find a solution there, consider Requesting New Functions.
However, if you're planning to take the binaries and use them in your own mod, go right ahead.
Introduction
Before writing extensions BI requests that you to ask yourself the question is SQF unable to fulfill your needs?
Unfortunately, you can not make API calls over SQF and even if you were able to, you still need to create threads to ensure that the game doesn't freeze while waiting. While most of the logic of the mod is handled in game with SQF, the final transmit/receive stage is handled by the extension.
OPS:SHOCK
Sends a shock command to the PiShock API
"arma3_pishock" callExtension ["ops:shock", [Username, Sharecode, APIKEY, Intensity, Duration]];`
See Extension Call Arguments For further info
Sample Return
["Shock command sent successfully!,""Steam(00000000000000000),Pbo(\""new.sqf\""),None,Singleplayer""",0,0]
See Execution Return For further info
Sample Callback
["arma3_pishock", "Shock", "Operation Succeeded."]
See Callback Return For further info
OPS:VIBRATE
Sends a shock command to the PiShock API
"arma3_pishock" callExtension ["ops:vibrate", [Username, Sharecode, APIKEY, Intensity, Duration]];`
See Extension Call Arguments For further info
Sample Return
["Vibration command sent successfully!,""Steam(00000000000000000),Pbo(\""new.sqf\""),None,Singleplayer""",0,0]
See Execution Return For further info
Sample Callback
["arma3_pishock", "Vibrate", "Operation Succeeded."]
See Callback Return For further info
OPS:BEEP
Sends a shock command to the PiShock API
"arma3_pishock" callExtension ["ops:beep", [Username, Sharecode, APIKEY, Duration]];`
See Extension Call Arguments For further info
Sample Return
["Beep command sent successfully!,""Steam(00000000000000000),Pbo(\""new.sqf\""),None,Singleplayer""",0,0]
See Execution Return For further info
Sample Callback
["arma3_pishock", "Beep", "Operation Succeeded."]
See Callback Return For further info
Extension Call Arguments
Argument | Description |
---|---|
Username | PiShock Username. |
Sharecode | Sharecode for the shocker. |
APIKEY | API Key generated from pishock.com. |
Intensity | Intensity of the shock (1-100 : Integer). |
Duration | Duration of the shock (1-15 : Integer). |
Returns
The extension calls have 2 returns, a execution return and a callback
Execution Return
Upon being called the extension performs a sanity check on the Intensity and Duration values. Upon passing these checks it creates a thread for the API call and returns a result string along with return and error numbers in an array.
Return | Description |
---|---|
Command sent successfully! | Status message (see below) |
Steam(00000000000000000) | steamID of the client calling extension getPlayerUID or "0". |
Pbo(""new.sqf"") | fileSource from which the extension was executed or "" if done on the fly. |
None | missionName missionNameSource. |
Singleplayer | serverName serverName. |
0 | Extension return code (Not Used) |
0 | Error code in case of command error (see below). 0 means no errors. |
Status Message | Description |
---|---|
Command sent successfully! | API Request was sent successfully |
Intensity out of range! | Intensity value outside of permitted range (1-100) |
Duration out of range! | Duration value outside of permitted range (1-15) |
Error Code | Description |
---|---|
101 | SYNTAX_ERROR_WRONG_PARAMS_SIZE |
102 | SYNTAX_ERROR_WRONG_PARAMS_TYPE |
201 | PARAMS_ERROR_TOO_MANY_ARGS |
301 | EXECUTION_WARNING_TAKES_TOO_LONG |
Callback Return
Callback returns only occur when a command is successfully sent to the PiShock API. As the response from the API takes an undetermined amount of time to arrive and process the extension fires off a callback return whenever the process is done. An active Mission Event Handler set to ExtensionCallBack to catch these returns.
Paramater | Type | Description |
---|---|---|
Extension Name | String | Used to differentiate between extensions |
Function Name | String | Name of the function that return originates from |
API Response | String | Response message from the API (see below for values) |
Response Message | Meaning |
---|---|
Operation Succeeded. | The command was sent successfully. |
This code doesn’t exist. | The specified share code could not be found. Make sure you create and copy an active share code from the PiShock website. |
Not Authorized. | The specified username or apikey is not correct (or your account has not been activated). |
Shocker is Paused, unable to send command. | The shocker is paused (from the PiShock.com web panel). |
Device currently not connected. | The PiShock is offline. |
This share code has already been used by somebody else. | Someone (or something) else is using the specified share code. Generate a new one. |
Unknown Op, use 0 for shock, 1 for vibrate and 2 for beep. | Invalid Op code specified. Must be 0, 1, or 2. |
Intensity must be between 0 and {maxint} | The specified intensity was outside the range set for the sharecode. |
Duration must be between 1 and {maxdur} | The specified duration was outside the range set for the sharecode. |