hippoRENT - The Software Development Kit (SDK)
About the Software Development Kit
Many of our hundreds of users have, in the past, asked for help with bolting functionality onto our rental boxes (e.g. getting a box to communicate with a door, unlocking it for the tenant when the box is rented). Therefore we have providing a simple software development kit (SDK) with this version of the HippoTech Networked Rental System. This allows somebody with scripting expertise to extract data on demand from the box, server or vendor and thus more easily create this kind of functionality that they need.
There are two ways to get data out of the box, server or vendor. You can insert a script of your own *into* them, or you can use the SDK chat channel so a separate object (e.g. a door, security system etc.) can communicate with them. We recommend the script option and the SDK channel method will slowly be phased out in later versions of hippoRENT; the information here is provided for information purposes.
1. Communicating via Chat Using the SDK Channel
1.1 Preparing for Communications
Each of the configuration notecards for the box, server and vendor can have a command like this inserted into it:
SDK CHANNEL: <channel>
e.g. SDK CHANNEL: 123456789
This specifies the chat channel that the SDK will listen for commands on and transmit data back on. If the command is missing from the notecard, or the channel is set to 0, then the SDK will not activate this is to avoid spamming the open channel 0 with meaningless data.
1.2 Extracting Data from a Rental Box
To extract data from the rental box, you will need the scripting skills necessary for working with and parsing strings. Data is sent to you in the form of a string with data items separated by the ^ symbol; thus you can use llParseString2List or llParseStringKeepNulls to extract individual data items.
To extra live rental data from the rental box, send this command on the SDK channel:
And you will get back a string, said on the same channel, that looks something like this:
The format of this string is as follows:
<tenant name>^<key>^<rental time remaining>^<start time of their rental>^<price per week>^<prims>^<name of any person this box is reserved for>^<locked status>
By parsing this string, you can decode many of the box’s key settings. Please note that in future expansion, further data may be added TO THE END of this string, but we will not change the format of these first eight data items. Thus any scripts you write using the SDK should remain compatible with future versions of our system.
You will also find that the rental box repeats a lot of internal script traffic on the SDK channel for you whenever a box “event” occurs. Hence you need to filter channel traffic carefully to pick up what you’re interested in, although other data may be useful too. For example, when a box is rented, you’ll see this transmission:
NEW TENANT^name of tenant^key of tenant
And when a tenant is booted:
... is amongst the transmissions.
In short, by watching and scanning the SDK channel you can pick up a wealth of information about your rental box.
1.3 Extracting Data from a Server
To extract data from the server, use the following commands on the SDK channel:
This command requests the server to send its list of known boxes over the SDK channel. The format is the same as you see in open chat if you use the list boxes menu command:
(1) Windermere Home in Brown | Brown (166, 50, 26) | L$700/week for 606 prims | Pathfinder Linden | 3d, 19h, 28m, 11s | Has picture
The format, as you can see, is like this:
(<box number>) <box name> | <location> | price/<week or day> for <prims> prims | <Tenant name or "No Tenant"> | <remaining time> <Has picture/No picture>
The last data item indicates if the box has a picture in it and thus can have its details served to a vendor.
To get vendor data, use this command
Which produces a result like this:
(1) HippoTech Networked Vendor Unit | Brown (96, 160, 23) | Yes
The format is similar to that above; the final "Yes" or "No" states whether that vendor allows customers to rent by paying it.
As with the box, other occasional internal messages will get output on the SDK channel for you to use. If you come across any of these that look useful, we can explain them to you.
Please note that this method only works with the non-web version of the server; web-enabled servers do not store rental data locally.
1.4 Extracting Data from a Vendor
Finally, this works in much the same way as the above, by issuing a command on the SDK channel or listening to the internal data transmissions that get mirrored on that channel. This is the command you’ll need to use:
This will list the boxes that this vendor knows about, in this format:
(1) Windermere Home in Brown | Brown (166, 50, 26) | L$700/week for 606 prims | Ivor Largeproperty | Yes
You will see that the format is almost identical to the server output above.
2. Listening to Internal Linked Script Messages
The box, server and vendor all use linked messages to transmit messages between the various scripts that run them. In the case of the box, listen to the traffic on linked message with num = 1 to pick up key status changes. You’ll also find that configuration information is transmitted on num >= 7000, so with a bit of practice, you can pick up any settings you need to know.
2.1 Linked Message Numbers Used by a Server
500000 - request the box database to reset itself.
501001 - details of a rental box have been received by the server and are passed to the database. The accompanying text string contains information on the box key, name, location, tenant, time left, free days, price, picture and any refund settings (with ^ separating data items in the string).
502001 - a request to the server’s box database to print out its list of boxes.
503001 - ask the box database to pass back the number of known boxes on linked message number 504.
505001 - tells the box database to contact all of its boxes and ask them to send a status update.
507001 - request the box database to return the details key of the box number held in the string also passed. Info is passed back on link message 508 in the form "box key^box name^tenant name^time left^rental price^free days^refund code.
509001 - send a command to box number held in the string (or "ALL"). Format is "command:" + the command (e.g. "command:boot"). If you wish to use this facility, listen in on this link message number while sending commands from the menus or voice commands to see how it works.
511001 - instruct box database to pass back the location of the box number held in the string. Used by the map function. Details are returned on link message 512.
2.2 Linked Message Numbers Used by a Vendor
50000 - request the vendor’s box database to reset itself.
501001 - details of a rental box have been received by the vendor and are passed to the database. The accompanying text string contains information on the box key, name, location, tenant, time left, free days, price, prims, picture key (with ^ separating data items in the string).
502001 - a request to the vendor’s box database to print out its list of boxes.
503001 - ask the vendor’s box database to pass back the number of known boxes on linked message number 504.
505001 - set the vendor texture to the picture of the box number held in the linked message string. It also passes back on link message number 506 a string with that box’s key, name, location, tenant, price and prims, separated by ^.
591001 - don’t call this yourself; it’s used by the vendor to sort its box database and pass box details from one box database script to another when doing so.