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.