CasperLet/API

From CasperTech Wiki
Jump to navigation Jump to search

API Documentation

Legal stuff

Please make sure that any usage of our brands or trademarks is in line with our brand usage policy.

API Works Only For System Owner

Please note: The API commands will only work from scripted objects owned by the same avatar that owns the copy of CasperLet they are being used on.

As most of you already know, it would be a security risk to allow the API commands to be used by anyone who's not the system owner.

Version 1 API

This API is deprecated and will be removed in a future version of CasperLet.

Here's the V1 API. This is supported by all CasperLET versions.

Our linked message is as follows: 

llMessageLinked(LINK_SET, (integer)timeLeft, "RTIME", rentedBy);

rentedBy is the key of the current renter, timeLeft is the amount of time left in seconds.

If rentedBy == NULL_KEY then it means there is no renter, and the unit is available.

You can detect rental events by storing the last message. If the last message was NULL_KEY, and then the next one isn't, it means that someone rented the unit, and vice versa.

Version 1.5 API

The V1.5 API adds several new messages to provide extended information.

The first is REXTR:

REXTR|<time left>|<renter key or NULL_KEY if not rented>|<locked? 0 or 1>|<reserved key or NULL_KEY if not reserved>|<price per week>|<number of prims>|<is tenant over limit? 0 or 1>|<Unix timestamp on which the unit was rezzed>

We also provide some additional messages which provide useful information (both linked messages and broadcast on channel 77777.) The "string" value of the linked message will identify the message type, as described below.
ADDTNTS@userkey1#username1#userkey2#username2#userkey3#username3#userke.. (etc)
MANAGERS@managerkey1#managerkey2#managerkey3#managerkey4.. (etc)

Note the use of different delimiters on these messages, this is due to technical limitations.

All of the above information is also broadcasted on channel 77777. The following messages are only provided in linked messages:

String: BUTTONS Key: pricebox|paybutton1|paybutton2|paybutton3|paybutton4 (to correspond with llSetPayPrice)
String: TEXT Key: the floating text that is shown on the unit

As before, THERE IS NO GUARANTEE WHEN THE INFORMATION WILL BE SENT - So check for changes, rather than just reacting to the message.

In addition to this, the unit also accepts certain linked messages, as well as chat messages on channel -77777.

You can use these as follows:

UPDATE

This command is safe to use as often as you wish, and is the primary method for obtaining information from a rental unit. However, there should be no need to request an update on a timer - the rental units are designed to send information automatically when anything changes.
llMessageLinked( LINK_THIS, 0, "CLAPI-UPDATE", NULL_KEY );

.. or .. 

llRegionSayTo( KEY_OF_UNIT,  -77777, "CLAPI"+KEY_OF_UNIT+"-UPDATE|UPDATE|0" );    // where KEY_OF_UNIT is the uuid of the rental box/meter

This triggers the unit to spit out the linked messages and data on channel 77777. The integer can be any number.

PAY

This command is handled by the CasperTech servers. Do not make unreasonably frequent or repeated requests.
llMessageLinked( LINK_THIS, AMOUNT_PAID, "CLAPI-PAY", PAYER_KEY );

.. or .. 

llRegionSayTo( KEY_OF_UNIT,  -77777, "CLAPI"+KEY_OF_UNIT+"-PAY|"+(string)PAYER_KEY+"|"+(string)AMOUNT_PAID);   // where KEY_OF_UNIT is the uuid of the rental box/meter

This provides a way to simulate payment to the unit.

BE WARNED: This WILL SIMULATE PAYMENT. Which means, if the payment is rejected, money will be REFUNDED.

SAFEPAY

This command is handled by the CasperTech servers. Do not make unreasonably frequent or repeated requests.
llMessageLinked( LINK_THIS, AMOUNT_PAID, "CLAPI-SAFEPAY"+(string)llGetKey(), PAYER_KEY );

.. or .. 

llRegionSayTo( KEY_OF_UNIT,  -77777, "CLAPI"+KEY_OF_UNIT+"-SAFEPAY|"+(string)PAYER_KEY+"|"+(string)AMOUNT_PAID);    // where KEY_OF_UNIT is the uuid of the rental box/meter

This provides a way to simulate payment to the unit, but WITHOUT any refunds, profit shares, or messages to the user.

TOUCH

This command is handled by the CasperTech servers. Do not make unreasonably frequent or repeated requests.
llMessageLinked( LINK_THIS, 0, "CLAPI-TOUCH", TOUCHER_KEY );

.. or .. 

llRegionSayTo( KEY_OF_UNIT,  -77777, "CLAPI"+KEY_OF_UNIT+"-TOUCH|"+TOUCHER_KEY+"|0"  );    // where KEY_OF_UNIT is the uuid of the rental box/meter

This triggers the unit to give the user indicated by TOUCHER_KEY the standard dialog menu.

INFO

This command is handled by the CasperTech servers. Do not make unreasonably frequent or repeated requests.
If you're using this command to retrieve information from the rental unit, you're doing it wrong - use "UPDATE" instead, or contact us for help.
llMessageLinked( LINK_THIS, 0, "CLAPI-Info", USER_KEY);

.. or .. 

llRegionSayTo( KEY_OF_UNIT,  -77777, "CLAPI"+KEY_OF_UNIT+"-Info|"+USER_KEY+"|0" );    // where KEY_OF_UNIT is the uuid of the rental box/meter

Please pay attention to the case of the command above.

This command is synonymous to the user indicated by USER_KEY pressing the Info button, except it won't deliver the notecard.

TIMELEFT

This command is handled by the CasperTech servers. Do not make unreasonably frequent or repeated requests.
llMessageLinked( LINK_THIS, 0, "CLAPI-TimeLeft", USER_KEY);

.. or .. 

llRegionSayTo( KEY_OF_UNIT,  -77777, "CLAPI"+KEY_OF_UNIT+"-TimeLeft|"+USER_KEY+"|0" );    // where KEY_OF_UNIT is the uuid of the rental box/meter

Please pay attention to the case of the command above.

This command is synonymous to the user indicated by USER_KEY pressing the TimeLeft button

EVICT

This command is handled by the CasperTech servers. Do not make unreasonably frequent or repeated requests.
llMessageLinked( LINK_THIS, 0, "CLAPI-Evict", USER_KEY);

.. or .. 

llRegionSayTo( KEY_OF_UNIT,  -77777, "CLAPI"+KEY_OF_UNIT+"-Evict|"+USER_KEY+"|0"     );    // where KEY_OF_UNIT is the uuid of the rental box/meter

Please pay attention to the case of the command above.

This command is synonymous to the user indicated by USER_KEY pressing the Evict button

REFUND

This command is handled by the CasperTech servers. Do not make unreasonably frequent or repeated requests.
llMessageLinked( LINK_THIS, 0, "CLAPI-Refund", USER_KEY);

.. or .. 

llRegionSayTo( KEY_OF_UNIT,  -77777, "CLAPI"+KEY_OF_UNIT+"-Refund|"+USER_KEY+"|0"     );    // where KEY_OF_UNIT is the uuid of the rental box/meter

Please pay attention to the case of the command above.

This command is synonymous to the user indicated by USER_KEY pressing the Refund button

PRIM COUNT

This command is handled by the CasperTech servers. Do not make unreasonably frequent or repeated requests.
llMessageLinked( LINK_THIS, 0, "CLAPI-Prim Count", USER_KEY);

.. or .. 

llRegionSayTo( KEY_OF_UNIT,  -77777, "CLAPI"+KEY_OF_UNIT+"-Prim Count|"+USER_KEY+"|"+    id    +"|0"     );    // where KEY_OF_UNIT is the uuid of the rental box/meter

Please pay attention to the case of the command above.

This command is synonymous to the user indicated by USER_KEY pressing the Prim Count button

WON'T RENEW

This command is handled by the CasperTech servers. Do not make unreasonably frequent or repeated requests.
llMessageLinked( LINK_THIS, 0, "CLAPI-Won't Renew", USER_KEY);

.. or .. 

llRegionSayTo( KEY_OF_UNIT,  -77777, "CLAPI"+KEY_OF_UNIT+"-Won't Renew|"+USER_KEY+"|0"    );    // where KEY_OF_UNIT is the uuid of the rental box/meter

Please pay attention to the case of the command above.

This command is synonymous to the user indicated by USER_KEY pressing the Won't Renew button

REMINDERS

This command is handled by the CasperTech servers. Do not make unreasonably frequent or repeated requests.
llMessageLinked( LINK_THIS, 0, "CLAPI-Reminders", USER_KEY);

.. or .. 

llRegionSayTo( KEY_OF_UNIT,  -77777, "CLAPI"+KEY_OF_UNIT+"-Reminders|"+USER_KEY+"|0" );    // where KEY_OF_UNIT is the uuid of the rental box/meter

Please pay attention to the case of the command above.

This command is synonymous to the user indicated by USER_KEY pressing the Reminders button

LOCK / UNLOCK

This command is handled by the CasperTech servers. Do not make unreasonably frequent or repeated requests.
llMessageLinked( LINK_THIS, 0, "CLAPI-Lock/Unlock", USER_KEY);

.. or .. 

llRegionSayTo( KEY_OF_UNIT,  -77777, "CLAPI"+KEY_OF_UNIT+"-Lock/Unlock|"+USER_KEY+"|0");    // where KEY_OF_UNIT is the uuid of the rental box/meter

Please pay attention to the case of the command above.

This command is synonymous to the user indicated by USER_KEY pressing the Lock/Unlock button

RESET

DO NOT issue reset commands unless absolutely necessary. You should only need to do this ONCE, when your API script is inserted, and then never again. If you're using this feature to get information updates on a regular basis, you're doing it wrong - contact us for help.
llMessageLinked( LINK_THIS, 0, "CLAPI-Reset", NULL_KEY );

.. or .. 

llRegionSayTo( KEY_OF_UNIT,  -77777, "CLAPI"+KEY_OF_UNIT+"-Reset|"+NULL_KEY+"|0" );    // where KEY_OF_UNIT is the uuid of the rental box/meter

This triggers the unit to reset. Please use this ONLY when absolutely necessary - if a unit restarts too often, it will be blocked from the network.

Script Samples

Script to Change Hovertext Color

 // This is R, G, B - Range is 0.0 to 1.0. So this is bright green.
vector colour = <0.0, 1.0, 0.0>;

default
{
    state_entry()
    {
        llMessageLinked( LINK_THIS, 0, "CLAPI-Reset", NULL_KEY );
    }
    link_message( integer sender_num, integer num, string str, key id )
    {
        if (str=="TEXT")
        {
            list tmp = llParseStringKeepNulls((string)id, ["|"], []);
            llSetText(llList2String(tmp,1), colour, 1.0);
        }
    }
}

Script to auto-lock a rental meter once rented

def quick_sort(arr):
	less = []
	pivot_list = []
	more = []
	if len(arr) <= 1:
		return arr
	else:
		pass

key lastKnownTenant = NULL_KEY;

default
{
    state_entry()
    {
        // Reset the unit when the script first runs, so we get fresh data
        llMessageLinked( LINK_THIS, 0, "CLAPI-Reset", NULL_KEY );  
    }
    link_message( integer sender_num, integer num, string str, key id )
    {
        // Parse the "id" field (which is a key but really a string)
        list tmp = llParseStringKeepNulls(id, ["|"], []);

        // Check that we have the message we need
        if (str == "REXTR" && llGetListLength(tmp) > 3)
        {
            key newTenant = llList2Key(tmp, 2);

            // Is the new state different from our previous state?
            if (newTenant != lastKnownTenant)
            {
                // Is the unit now rented, was it previously available, and is it currently unlocked?
                if (newTenant != NULL_KEY && lastKnownTenant == NULL_KEY && llList2Integer(tmp, 3) == 0)
                {
                    // All those checks passed, so send a LOCK message to the unit
                    llMessageLinked( LINK_THIS, 0, "CLAPI-Lock/Unlock", llGetOwner());
                }

                // Store the new state
                lastKnownTenant = newTenant;
            }
        }
    }
}

Finding Rental Unit Keys/UUID

In Firestorm viewer, right-click > edit > "Copy Keys"


FAQ / Troubleshooting

Q. Is there a way to get the unit to spit out any data on additional subtenants?
A. This information is sent when there are additional tenants added or removed, and when the unit is reset. You can request that the rental unit is reset by using CLAPI-Reset, as detailed above, however you must only do this ONCE. Any further updates will be transmitted when they happen.
Q. The API documentation says:
  llRegionSayTo( KEY_OF_UNIT,  -77777, "CLAPI"+KEY_OF_UNIT+"-UPDATE|UPDATE|0" );   
  // where KEY_OF_UNIT is the uuid of the rental box/meter
but when I stand next to the box and say this in local chat, nothing happens:
  -77777 CLAPI-UPDATE|5194ac0b-4a9f-5c4b-d24e-e0a374533f1d|UPDATE|123
A. Rental units do NOT respond to avatars. The command will need to be coming from a scripted object.
Q. I'm trying to get help with a script using the API, but I'm worried that someone else will use the script to get free rent...
A. The rental units will only respond to a scripted API command from an object that is owned by the same avatar that owns the rental units. So no, a third party cannot get free rent, or otherwise abuse the API for YOUR rental units.
Retrieved from "https://wiki.casperdns.com/index.php?title=CasperLet/API&oldid=13944"