Scripting:InvokeItem

From STNE Wiki

Ship.InvokeItem is one of those multiplexing calls, comparable to (although completely different invocation wise from) the old dos int 21h or hardware ioctl calls. While at first it may look daunting, it's actually very simply. The caveat is that the sub function calls have to be documented, and as so far I can find only one well documented rendition, gates. So, for a quick tour of InvokeItem, in regards to it's use with a gate.

Firstly, the syntax must be clear. InvokeItem takes up to, and should include, 3 parameters. Firstly, the ID of the item to invoke against. For a gate, this is the portal generator (not a transponder). From the helm view, towards the bottom of the page, is the transponder/generator list. In that list, it's the only one named “Portal Generator”, and the only one not prefixed by “PT-”. To the right of the name is the ID, that's the number you want. This number is unique, so you can't just use the same number on a different gate and expect good results. GIGO (garbage in, garbage out), as always.

Secondly, you need to have a sub function to call. These are free form text fields, and as of the time of this writing, I can find absolutely 0 enumerators for the sub function name (Hint: this would be a GREAT addition to the scripting engine, perhaps an enum of InvokeItemCommands.ItemType.CommandList). The one documented for the gate, broken down by usage, along with known status and caveats are:

User Portal Commands:
• RightsUserList – Fully functioning
• RightsUserCreate – Fully functioning
• RightsUserRemove – Fully functioning
• RightsUserUsed – Does not reset accumulator
• RightsUserLimit – Fully functioning
• RightsUserLevel – Fully functioning
• RightsUserLocked – Fully functioning
• RightsUserShipType – Fully functioning

Alliance Portal Commands:
• RightsAllyList – Fully functioning
• RightsAllyCreate – Fully functioning
• RightsAllyRemove – Fully functioning
• RightsAllyUsed – Does not reset accumulator
• RightsAllyLimit- Does not return current limit
• RightsAllyLevel – Fully functioning
• RightsAllyLocked – Fully functioning
• RightsAllyShipType – Fully functioning

User and Alliance Portal Commands, all fail if the user does not exist on the gate (kinda silly, IMHO. Limits usefulness to require the user exist... Why not just fall back to the alliance calls?):
• DeflectorAvailableMaxUserAndAlly - Probably
• DeflectorAllowedUserAndAlly - Probably
• LevelUserAndAlly - Probably
• ShipTypeAllowedUserAndAlly - Probably
• ShipTypeIsAllowedUserAndAlly - Probably

General Gate Data:
• ReceiveModMax – Fully functioning
• ReceiveModMin – Fully functioning
• DeflectorAvailableMax – Fully functioning
• CreatedItemExists – Fully functioning
• CalcDistanceToTransponder – Not functioning

Thirdly, you need a parameter list. Not just any parameter list, but again matching expected parameter names with expected parameter values. For the user sub functions, the primary is UserID. For alliance sub functions, AllyID. For user and ally sub functions, UserID. For most of the others, ItemID.

And, lastly, you need to know the return type. Getting the data is great, but returning it to be used is the goal. Now, to tie this all together.

Var b As Boolean;
Var ship As New CMyShip(123456);
Var pg As Integer = 789012;
Var uid As Integer = 34567;
CreateUser(uid);

Function CreateUser (user2check As Integer) {
  Var command As String = "RightsUserList";
  Var parameters As New CSortedStringObjectList();
  Var val As CIntegerList = ship.InvokeItem(pg, command, parameters);
  If (NOT val.Contains(user2check)) {
    command = "RightsUserCreate";
    parameters.Add("UserID", user2check);
    b = ship.InvokeItem(pg, command, parameters);
    If (NOT b) {
      WriteLine ("User Creation failed!");
    } Else {
      WriteLine("New gate user ID: " & user2check;
    }
  } Else {
    WriteLine ("User " & user2check & " already exists");
  }
}

This small function checks for a user, and creates them if they don't exist. The next question, at least in my mind, was “How do I know I have the right PG?” You have two options. One is CreatedItemExists, followed by a call to a sub function with a known value or range of values (because a mistaken transponder ID would also exist), the other is just call the sub function. In the case of multiplexing functions, the normal behavior is to return an error condition on fail, not abort. At least InvokeItem for gates follows this protocol.

Function CheckPG(ship As CMyShip, pg As Integer) As Boolean {
  Var parameters As New CSortedStringObjectList();
  Var command As String = "RightsUserList";
  Var val As CIntegerList = ship.InvokeItem(pg, command, parameters);
  // Error condition is 0 entries in the list
  If (val.Count = 0) { 
    Return False;
  }
  Return True;
}

So, there you have it. It's fairly straightforward, with a little practice you can do the majority of your gate configuration via the scripting engine. For the documented passed parameters and return values, from your gate go to Administration->Scripting. They are as of the time of this writing, deemed experimental and subject to change.

--Miltiades (En-1:56599) 07:21, 16 September 2011 (CEST)