Recommendation: GSI LEP (v1)
Hierarchical request-response protocol for LSL link_message events
The Global Scripting Institute (GSI) is an informal organization of Second Life® users that design and test standards for efficient, flexible, and readable scripts in Second Life. "Second Life®" and "Second Life Grid™" are trademarks of Linden Research, Inc., d/b/a Linden Lab. The Global Scripting Institute and its catalog are not affiliated with with or sponsored by Linden Research.
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.
The link_message Extension Protocol (LEP) is a message protocol for llMessageLinked/link_message in Linden Scripting Language (LSL).
LEP uses llMessageLinked to pass a set of bitwise flags as an integer; a list prepended with a structured metadata header, dumped to a string; and a string of arbitrary data, cast to a key. LEP takes advantage of an intentionally-maintained bug in llMessageLinked that allows any string, including non-UUIDs, in the key parameter.
The flags and metadata included in each LEP message permit other scripts to identify the source, target, and type of message to rapidly discard unwanted link_message events.
LEP messages MUST be constructed as follows:
llMessageLinked(target_link, flags, llDumpList2String([llGetScriptName(), target_script] + parameters, "\n"), data);
| Placeholder | Type | Description |
|---|---|---|
target_link |
integer | MUST be the target link number or any LINK_* constant. |
flags |
integer | MUST be a bitwise combination of applicable flags for this message (see below). |
target_script |
string | MUST be one of the following:
|
parameters |
list | MUST be a hierarchical series of commands, parameters, or other flags (for example, ["file", "open", "somefile.txt", 0x1]). The list MUST NOT contain any newline ("\n") characters. A hierarchical list is used here in lieu of arbitrary data so that recipients can quickly route the message through an if-else or if-return tree for better organization and performance. |
data |
string | MAY be any value. |
Valid bits for flags:
| Name | Value | Description |
|---|---|---|
| TYPE_REQUEST | 0x1 | Requests that the target send a response with TYPE_RESPONSE. |
| TYPE_RESPONSE | 0x2 | If a script is responding to a TYPE_REQUEST message, it MUST include this flag and MUST NOT include TYPE_REQUEST. If this flag is included, the sensor SHOULD use the request's source_script as the response's target_script so that the response is only sent to the script that requested it.If this flag is included, the sender SHOULD use the request's parameters as the response's parameters so that the requester can match the response to a previous request it sent. The sender MAY, however, append additional elements to the end of parameters with response data, if desired. |
| STATUS_ERROR | 0x4 | If a script is responding to a TYPE_REQUEST message, it SHOULD include this flag if the request was nominally unsuccessful for any reason. If this flag is included, the sender MUST append a string element to the end of parameters. This string MUST be one of the following:
|
Implementations MAY create constants (ideally preprocessor constants) to use these flags; names are provided for reference in this recommendation.
LEP-aware scripts MUST process incoming link_message events by running the below checks. If a check fails, the script SHOULD immediately release the event with return to reduce script time (or run additional code to interpret non-LEP messages). The script MAY log this dropped message.
For the purposes of this example, the link_message event handler is defined as follows:
link_message(integer source_link, integer flags, string message, key data)
flags contains required flags (for example, if the script only needs to process errors, check that flags & STATUS_ERROR = STATUS_ERROR).source_link is a known link number.message using list parameters = llParseStringKeepNulls(message, ["\n"], []).parameters contains at least two elements.parameters is either a blank string, matches the recipient script's name, or matches a substring of the recipient script's name.After a message passes these checks, recipient SHOULD process the message as desired. For performance, it is RECOMMENDED to iterate through the remaining elements of parameters, if any, through an if-else or if-return tree.
I need to pass a newline in the parameters list. Can I use a different llDumpList2String separator?
No. The implementation MUST use "\n" to be in compliance with the LEP specification. If your implementation needs to pass strings with newlines in parameters, consider using llEscapeURL/llUnescapeURL or llStringToBase64/llBase64ToString on individual elements of parameters.
Why is the metadata added to the string parameter instead of the key parameter?
Typecasting is almost free, but not totally free in LSL's limited memory space. If the message is discarded while processing the metadata, data is never typecast from key to string. Typecasting data into a new string is only necessary if the message needs to be processed.
LEP was authored by Nelson Jenkins on behalf of GSI.