Second Life Wiki - User contributions [en]

LSL Protocol/Restrained Love Open Relay Group/Satomi's Damn Fast Relay

2015-03-17T09:07:08Z

Satomi Ahn: /* Satomi's Damn Fast Relay */ (Did wiki syntax change?)

{{Restrained Love Open Relay Group TOC}}

= Satomi's Damn Fast Relay =

This is the shortest known implementation of an ORG compliant relay.

This relay only makes the minimal verifications (no ask mode, no distance checks, ping on relog only but safe-word on touch).

Code is under a BSD-style license, feel free to use in your own projects, provided you credit Satomi Ahn for the original script.

<source lang="lsl2">
//Damn Fast Relay, by Satomi Ahn
//
//This is a minimalist RLV Relay intended for laggy playgrounds, with the aim of making the answer to scan requests as fast as possible and decreasing the global lag.
//It only features the auto-accept mode but tries to fully comply to ORG 003 specifications.
//Touching the relay will make it release restrictions and reset (in other words: safewording).
//
//This script is provided as-is with mo guarrantee whatsoever.
//Feel free to use the code in anyway you want, provided you credit the original author, ie: myself, Satomi Ahn.
//(can be seen as a BSD-style license)

integer rlvrc = -1812221819;
key source = NULL_KEY;
key wearer = NULL_KEY;
integer viewerlistener;
key sitid;
list restrictions = [];

release(key id) {
llOwnerSay("@clear");
llRegionSayTo(id, rlvrc, "release,"+(string)id+",!release,ok");
llResetScript();
}

default {
state_entry() {
wearer = llGetOwner();
llListen(rlvrc,"", NULL_KEY, "");
}

touch_start(integer total_number) {
llOwnerSay("Now safewording. Restrictions will be removed and the relay reset.");
release(source);
}

listen(integer c, string w, key id, string msg) {
if (c == 12345) {
if (msg) sitid = (key) msg;
llListenRemove(viewerlistener);
return;
}
if (source) { if (source != id) return; } // already grabbed by another device
list args = llParseStringKeepNulls(msg,[","],[]);
if (llGetListLength(args)!=3) return;
if (llList2Key(args,1)!=wearer && llList2Key(args, 1)!=(key)"ffffffff-ffff-ffff-ffff-ffffffffffff") return;
string ident = llList2String(args,0);
list commands = llParseString2List(llList2String(args,2),["|"],[]);
integer i;
string command;
integer nc = llGetListLength(commands);
for (i=0; i<nc; ++i) {
command = llList2String(commands,i);
if (llGetSubString(command,0,0)=="@") {
llOwnerSay(command);
llRegionSayTo(id, rlvrc, ident+","+(string)id+","+command+",ok");
list subargs = llParseString2List(command, ["="], []);
string behav = llGetSubString(llList2String(subargs, 0), 1, -1);
integer index = llListFindList(restrictions, [behav]);
string comtype = llList2String(subargs, 1);
if (comtype == "n" || comtype == "add") {
if (index == -1) restrictions += [behav];
if (behav == "unsit" && llGetAgentInfo(wearer) & AGENT_SITTING) {
viewerlistener = llListen(12345, "", wearer, "");
llOwnerSay("@getsitid=12345");
}
}
else if (comtype=="y" || comtype == "rem") {
if (index != -1) restrictions = llDeleteSubList(restrictions, index, index);
if (behav == "unsit") sitid = NULL_KEY;
}
}
else if (command=="!pong") {
llOwnerSay("@sit:"+(string)sitid+"=force,"+llDumpList2String(restrictions, "=n,")+"=n");
llSetTimerEvent(0);
}
else if (command=="!version") llRegionSayTo(id, rlvrc, ident+","+(string)id+",!version,1100");
else if (command=="!implversion") llRegionSayTo(id, rlvrc, ident+","+(string)id+",!implversion,ORG=0003/Satomi's Damn Fast Relay v2");
else if (command=="!x-orgversions") llRegionSayTo(id, rlvrc, ident+","+(string)id+",!x-orgversions,ORG=0003");
else if (command=="!release") release(id);
else llRegionSayTo(id, rlvrc, ident+","+(string)id+","+command+",ko");
}
if (restrictions) { source = id; llOwnerSay("@detach=n"); }
else { llOwnerSay("@clear"); llResetScript(); }
}

changed(integer c) {
if (c & CHANGED_OWNER) llResetScript();
}

on_rez(integer i) {
if (source) {
llSleep(30);
llRegionSayTo(source, rlvrc, "ping,"+(string)source+",ping,ping");
llSetTimerEvent(30);
}
}

timer() {
llResetScript();
}
}

</source>

Talk:Limits

2012-06-06T11:32:49Z

Satomi Ahn: /* Description Not True UTF8? */

== Needs substantiation ==
Various items moved here to keep the main page clean. These require a source and confirmation.

* Building above 768m can cause prim drift, distortion, misalignment, shifting and general weirdness. For small/precise builds, it's best to work at a lower level.
** ''I'm familiar with some of this, but please provide a reference — like a reproducible bug on the [[Issue Tracker]]. Otherwise, it's unsubstantiated. '''- [[Image:Torley-favicon.png]] [[User:Torley Linden|Torley]] on 2009-05-06 @ 6:01 AM PST'''''
*** This could be related to http://jira.secondlife.com/browse/SVC-1170, but this describes "prim drift" not based on height.

* Estate (private island) terraformability is settable to a max of +/-100 m by the estate owner or managers.
** ''However, baking the land will allow it to be raised to at least 300 m. haven't tested any higher.--[[User:Liny Odell|Liny Odell]] 03:11, 6 May 2009 (UTC)''

* ''FPS as high as 120 and more have been observed, but FPS above 70 mostly seem to occur at times of network instability. --[[User:Bayru Jiagu|Bayru Jiagu]]''
** This isn't a limit, since the upper absolute isn't defined. '''- [[Image:Torley-favicon.png]] [[User:Torley Linden|Torley]] on 2009-10-07 @ 10:49 AM PST'''

== Ban List Limit ==
This page says that the number of people in an estate ban list is limited to 500. As far as I know, it's been 300 for a year or so. Did this change recently, maybe in the RC client? [[User:Lex Neva|Lex Neva]] 10:31, 5 July 2008 (PDT)
:I'm not a pro on this so it is just a guess, but I would tend to think that the limit change would be connected to new simulator software, rather then to a new client, since the sim stores the list of people who aren't allowed to enter. The client is just displaying it(?)
:That beeing said, please browse to {{Jira|SVC-747}} and watch for the comment made by [[User:Seraph Linden|Seraph Linden]] at 11/Jan/08 07:59 AM
:Because of the date, in case it was a client issue, then it should be at least fixed since 1.19
:Greetz, =) [[User:Zai Lynch|Zai Lynch]]([[User talk:Zai Lynch|talk]]|[[Special:Contributions/Zai Lynch|contribs]]) 11:29, 5 July 2008 (PDT)

== Ban Altitude Limits ==
It looks very much as if these limits on the effective altitude of a ban don't apply when the parcel is a complete region. Whether this is intentional, or a side effect of the parcel boundary being a region boundary, I don't know. Since you can't see a banline from the other side of a region boundary, something odd could be happening. [[User:WolfBaginski Bearsfoot|WolfBaginski Bearsfoot]] 17:40, 27 November 2010 (UTC)

== Prim Size Limits ==

I once saw instructions on how to make a prim that's larger than 10x10 but that the system considers to be 10x10. It isn't a megaprim and anyone can do it. It's a flat diamond shape. Does anyone know how? --[[User:Shadoe Landman|Shadoe Landman]] 13:04, 6 July 2008 (PDT)

You can create >10m disks from tubes, rings, and torii. Set the twist Twist at: Begin: 90, End: 90, and Hole Size at: X: 1.00, Y: 0.05. --[[User:McCabe Maxsted|McCabe Maxsted]] 23:38, 8 July 2008 (PDT)

for the one the OP was talking about, I believe what you do is flatten a box, then set shear in both axes to the max (I always forget the name fo the parameter, is it really shear? the one that kinda tilts the prim without rotating it). I could swear I knew another trick beside these 2, can't remember right now :/ I think it involved twist, or perhaps this one I siad also needs you to make twist begin and end be 45 degrees, I'm not sure now...I think there also used to be another one I can't remember right now, where if one of the axes (probably the Z, can't rememeber for sure) wasn't made flat, the prim wouldn't stretch to the maximum size achieved with that specific torture, I can't remember, oh wait, yeah, twist 45 degrees, then flatten in X or Y axis, for cubes only I believe --[[User:TigroSpottystripes Katsu|TigroSpottystripes Katsu]] 11:54, 17 July 2009 (UTC)

==Avatars per region limits==
The limits on the number of avatars per region are soft limits, I beliece... i.e., if you have more than that many avis on the sim, the server slows down and crashes. Is the larger number listed for a private estate sim caused by the fact that there are (typically) a very small number of other sims which can see that sim? [[User:Tammy Nowotny|Tammy Nowotny]] 11:43, 15 July 2008 (PDT)

== Region Name and Parcel Name Length Limits ==

Any way we can get both of these added to the limits list? Not sure what they are. -- [[User:Kenn Nilsson|Kenn Nilsson]] at 10:41 AM February 6th, 2009
:I added the max. parcel name length (63 characters). Don't know about max Region name length tho... [[Image:Zai_signature.png|45px]] '''[[User:Zai Lynch|Lynch]]''' ([[User talk:Zai Lynch|talk]]|[[Special:Contributions/Zai Lynch|contribs]]) 18:47, 6 February 2009 (UTC)
::Found the Region name limits in the KB. Although it might not be a technical limit, it's at least a limit via guidelines, see [[Linden_Lab_Official:Guidelines for Private Region Naming|Guidelines for Private Region Naming]]. The bar in Admin → God Tools accepts 63 characters tho. Dunno If they would be successfully saved in case one had the [[God mode|needed abilities]]...
::[[Image:Zai_signature.png|45px]] '''[[User:Zai Lynch|Lynch]]''' ([[User talk:Zai Lynch|talk]]|[[Special:Contributions/Zai Lynch|contribs]]) 02:57, 13 February 2009 (UTC)

== SLurls and (probably) the effects of converting integers to floating point numbers and back (Also: NOR rule for this article???) ==

I'd like to add the following, after "Absolute height limit"
:::* '''Highest z-value of an [[SLurl]], that will still teleport you to a positive altitude''' - 2147483583
:::** This is lower than the ''Absolute height limit'' above probably because of precision issues. Any value higher than 2147483583 would be rounded up to something beyond 2147483647 and thus cause an [http://en.wikipedia.org/wiki/Arithmetic_overflow overflow], while 2147483583 will still be rounded down to 2147483520 (see below).
:::* '''Highest altitude you can teleport to with an SLurl''' - 2147483520
, but I don't have sources to cite, as I found these values by trail and error (or rather, by manual [http://en.wikipedia.org/wiki/Bisection_method bisection]). Does the header of this article imply a [http://en.wikipedia.org/wiki/Wikipedia:NOR no original research] rule? --[[User:Boroondas Gupte|Boroondas Gupte]] 23:06, 9 September 2009 (UTC)
:Most of the stuff added to the article is original research (like testing how many characters fit into a certain window), so I think that we don't enforce [http://en.wikipedia.org/wiki/Wikipedia:NOR NOR]. A source would probably be the KB counterpart of this page, but it was derived from the Wiki version, hence it doesn't state more than the Wiki does. As long as a limit is verifyable by others, it should be added, I think.
:--[[File:Zai_signature.png|45px|link=User:Zai Lynch]] ([[User talk:Zai Lynch|talk]]|[[Special:Contributions/Zai Lynch|contribs]]) 00:42, 10 September 2009 (UTC)

:: [[Limits#Navigation|done]]. (I decided to start a new section for it.)
::--[[User:Boroondas Gupte|Boroondas Gupte]] 09:18, 10 September 2009 (UTC)
::: To prevent funny but not-really-useful trivia from squirreling in, I've updated the disclaimer. We can make exceptions — related to the above, "What's the highest an avatar has flown?" is a historically popular question that more Residents wonder about than test. So this contribution is appreciated. :) '''- [[Image:Torley-favicon.png]] [[User:Torley Linden|Torley]] on 2009-10-07 @ 10:52 AM PST'''

== Textures ==
The page strongly recommends using the smallest textures you can due to resource limits. It should be pointed out that uploaded textures can always be scaled down automatically and delivered at whatever resolution resources will allow but those resource limits will only become less limiting in time but the texture quality can never scale up beyond the original image resolutions. In other words, there are long-term trade-offs involved in texture size choice in addition to the short-term considerations and it might be best to temper the current advice or at least call this out.

== Object Contents ==

Is there any hard and/or practical limit to the number of items an object can have in its contents? [[User:Siann Beck|Siann Beck]] 12:16, 21 November 2009 (UTC)

There are hard limits but you are unlikely to ever hit them. On the other hand you are more likely to hit the practical limits. An object with a hundered plus items in it's inventory is hard to manage (updates due to adding or removing inventory can take a long time to complete). -- '''[[User:Strife_Onizuka|Strife]]''' ([[User talk:Strife_Onizuka|talk]]|[[Special:Contributions/Strife_Onizuka|contribs]]) 22:39, 21 November 2009 (UTC)

Although it may be true that one is unlikely to ever hit a certain hard limit, it would still be useful to have it stated instead of referred to cryptically, hm? [[User:Nemesis Greatrex|Nemesis Greatrex]] 13:22, 1 December 2009 (UTC)

:Could be 2^31. -- '''[[User:Strife_Onizuka|Strife]]''' ([[User talk:Strife_Onizuka|talk]]|[[Special:Contributions/Strife_Onizuka|contribs]]) 05:49, 3 December 2009 (UTC)

== Description Not True UTF8? ==
I remember playing with the description before and finding that it didn't accept/retain some characters, one of them being the pipe. Other text inputs handle it just fine. Might be something to look at. Also, I added hovertext and just used the standard formatting -- 254 bytes UTF8 string. I have no idea if it's a UTF8 string of 254 bytes, but I do know I shoved 254 characters into it and pulled them back out afterwards, even after a rerez. I recall the description losing half of its length after a rerez in the past. -[[User:Stickman Ingmann|Stickman]] 05:42, 30 March 2010 (UTC)
:Isn't the pipe ("|") part of ASCII? --[[User:Boroondas Gupte|Boroondas Gupte]] 21:59, 30 March 2010 (UTC)
::[[LlSetObjectDesc#footnote_1|LlSetObjectDesc Footnote]] -> The pipe character historically has been used to separate fields in the serialized version of inventory. --[[User:Kuraiko Yoshikawa|Kuraiko Yoshikawa]] 22:23, 30 March 2010 (UTC)
:::When we had pipe support (when it was also being used to separate fields in the serialized inventory), while it was never possible to create fake inventory items (description length limits nixed that), it was however possible to create an object that could not be rezzed. Not very useful. That was about the same time someone figured out they could generate inventory items for uuids by forging notecard inventory. I miss the good old days sometimes. Anyway, that is why pipe support was removed. -- '''[[User:Strife_Onizuka|Strife]]''' ([[User talk:Strife_Onizuka|talk]]|[[Special:Contributions/Strife_Onizuka|contribs]]) 00:22, 1 June 2011 (PDT)

It looks like only ASCII characters (and not all of them, see pipe for instance) can actually be used for prim names, prim descriptions and inventory names. So either this page about limits is plainly wrong, or there is an embarrassing bug. Since the bug would have been there for as long as I can remember (I was "born" in 2007), I guess the first explanation is the right one. Still, it would be nice being able to use accented characters and other unicode niceness. US English is not the only language around here! I am surprised I cannot find any JIRA reference about this. --[[User:Satomi Ahn|Satomi Ahn]] 04:32, 6 June 2012 (PDT)

== Profile Pictures ==

Profile pictures in Viewer 2.2 seem to be back to 4:3, rather than 1:1. Can anyone confirm this? And get the official word on whether this is a permanent change or not? --[[User:Samm Florian|Samm Florian]] 05:23, 31 October 2010 (UTC)
: It will stay messy for a while. The new 2.5 web profiles use 1:1, but there will be 4:3ish presentations until all older viewers and the current world.secondlife.com eventually fade away. --[[User:Cerise Sorbet|Cerise Sorbet]] 10:51, 1 February 2011 (PST)

:{{jira|VWR-21777}} is tagged "needs-design", so I guess there was no decision made, yet. --[[User:Boroondas Gupte|Boroondas Gupte]] 03:42, 5 February 2011 (PST)

LSL Protocol/Restrained Love Open Relay Group/Satomi's Damn Fast Relay

2011-07-11T13:54:08Z

Satomi Ahn: llParseListKeepNulls, as recommended in ORG 0004

{{ ORG Restrained Life Relay Specs TOC }}

= Satomi's Damn Fast Relay =

This is the shortest known implementation of an ORG compliant relay.

This relay only makes the minimal verifications (no ask mode, no distance checks, ping on relog only but safeword on touch).

Code is under a BSD-style license, feel free to use in your own projects, provided you credit Satomi Ahn for the original script.

<lsl>
//Damn Fast Relay, by Satomi Ahn
//
//This is a minimalist RLV Relay intended for laggy playgrounds, with the aim of making the answer to scan requests as fast as possible and decreasing the global lag.
//It only features the auto-accept mode but tries to fully comply to ORG 003 specifications.
//Touching the relay will make it release restrictions and reset (in other words: safewording).
//
//This script is provided as-is with mo guarrantee whatsoever.
//Feel free to use the code in anyway you want, provided you credit the original author, ie: myself, Satomi Ahn.
//(can be seen as a BSD-style license)

integer rlvrc = -1812221819;
key source = NULL_KEY;
key wearer = NULL_KEY;
integer viewerlistener;
key sitid;
list restrictions = [];

release(key id) {
llOwnerSay("@clear");
llRegionSayTo(id, rlvrc, "release,"+(string)id+",!release,ok");
llResetScript();
}

default {
state_entry() {
wearer = llGetOwner();
llListen(rlvrc,"", NULL_KEY, "");
}

touch_start(integer total_number) {
llOwnerSay("Now safewording. Restrictions will be removed and the relay reset.");
release(source);
}

listen(integer c, string w, key id, string msg) {
if (c == 12345) {
if (msg) sitid = (key) msg;
llListenRemove(viewerlistener);
return;
}
if (source) { if (source != id) return; } // already grabbed by another device
list args = llParseStringKeepNulls(msg,[","],[]);
if (llGetListLength(args)!=3) return;
if (llList2Key(args,1)!=wearer && llList2Key(args, 1)!=(key)"ffffffff-ffff-ffff-ffff-ffffffffffff") return;
string ident = llList2String(args,0);
list commands = llParseString2List(llList2String(args,2),["|"],[]);
integer i;
string command;
integer nc = llGetListLength(commands);
for (i=0; i<nc; ++i) {
command = llList2String(commands,i);
if (llGetSubString(command,0,0)=="@") {
llOwnerSay(command);
llRegionSayTo(id, rlvrc, ident+","+(string)id+","+command+",ok");
list subargs = llParseString2List(command, ["="], []);
string behav = llGetSubString(llList2String(subargs, 0), 1, -1);
integer index = llListFindList(restrictions, [behav]);
string comtype = llList2String(subargs, 1);
if (comtype == "n" || comtype == "add") {
if (index == -1) restrictions += [behav];
if (behav == "unsit" && llGetAgentInfo(wearer) & AGENT_SITTING) {
viewerlistener = llListen(12345, "", wearer, "");
llOwnerSay("@getsitid=12345");
}
}
else if (comtype=="y" || comtype == "rem") {
if (index != -1) restrictions = llDeleteSubList(restrictions, index, index);
if (behav == "unsit") sitid = NULL_KEY;
}
}
else if (command=="!pong") {
llOwnerSay("@sit:"+(string)sitid+"=force,"+llDumpList2String(restrictions, "=n,")+"=n");
llSetTimerEvent(0);
}
else if (command=="!version") llRegionSayTo(id, rlvrc, ident+","+(string)id+",!version,1100");
else if (command=="!implversion") llRegionSayTo(id, rlvrc, ident+","+(string)id+",!implversion,ORG=0003/Satomi's Damn Fast Relay v2");
else if (command=="!x-orgversions") llRegionSayTo(id, rlvrc, ident+","+(string)id+",!x-orgversions,ORG=0003");
else if (command=="!release") release(id);
else llRegionSayTo(id, rlvrc, ident+","+(string)id+","+command+",ko");
}
if (restrictions) { source = id; llOwnerSay("@detach=n"); }
else { llOwnerSay("@clear"); llResetScript(); }
}

changed(integer c) {
if (c & CHANGED_OWNER) llResetScript();
}

on_rez(integer i) {
if (source) {
llSleep(30);
llRegionSayTo(source, rlvrc, "ping,"+(string)source+",ping,ping");
llSetTimerEvent(30);
}
}

timer() {
llResetScript();
}
}

</lsl>

Talk:LSL Protocol/Restrained Love Relay/Specification

2011-07-11T13:51:54Z

Satomi Ahn: /* llRegionSayTo */

== Script name requirement ==

The current version of the spec contains rules for the name of the relay script. The problem is, the rules seem to preclude the possibility of updating using llRemoteLoadScriptPin, which requires a stable name for the target script in order to properly replace it. If the script is changed to support a new version, the spec requires the script be renamed, but that's impractical for a script subject to automatic updating. I'm also unsure if there's any point to this rule. In the case of the product I'm currently working on, the relay script is buried in a child prim (to prevent relayed rules interfering with its own rules), which makes attempting to check its name a pretty unfriendly way for the end user to determine version information. Having version information easily available to the end user is a good idea, but requiring the script be named a particular way doesn't provide that, it just interferes with auto-update functionality without apparent benefit. Is there some other reason for saying a script must be named a particular way (e.g. the viewer checks the script name for this info), or can that rule be safely ignored (despite the "must" in the spec)? If there's a technical reason for the naming requirement, can it be changed so that the prim containing the script is required to be named a particular way, rather than the script itself?
--[[User:Galatea Gynoid|Galatea Gynoid]] 17:48, 19 August 2008 (PDT)

: I think there is no technical reason. --[[User:Maike Short|Maike Short]] 12:26, 22 August 2008 (PDT)

: There is no technical reason indeed, and I think that naming rule may be lifted in the near future, especially if it is a problem for people to update their stuff... however the user 'must' be able to check the version one way or another. --[[User:Marine Kelley|Marine Kelley]] 11:44, 1 September 2008 (PDT)

::Fair enough -- I'm using a "Version..." command in my menus that prints:
::* Implant Version 0.7
::* Compatibility:
::* Restrained Life Viewer: 1.12.2 +
::* Relay Specification: 1.014
::iz gud? --[[User:Galatea Gynoid|Galatea Gynoid]] 23:44, 1 September 2008 (PDT)

== !release command from relay ==

Really just for clarification. But it's mentioned several times that a relay should issue a !release metacommand to force a session to end, however this isn't very clear. I'm assuming that the relay, for whatever reason, chooses to clear an object's commands, and sends a !release command to the object such as <code>CmdName,<object uuid>,!release,ok</code>. Should CmdName be something specific in this case? If not does that require in-world objects to recognise arbitrary command names other than those that it produced itself? This could do with some clarification and/or examples under the !release heading to avoid confusion, as I'm assuming objects should be aware of !release so that they know they no longer have control over an avatar. -- '''[[User:Haravikk_Mistral|Haravikk]]''' ([[User_talk:Haravikk_Mistral|talk]]|[[Special:Contributions/Haravikk_Mistral|contribs]]) 20:11, 24 October 2010 (UTC)
:I saw a few devices who send a !pong answer with another CmdName than ping, although the specification says it has to be ping. So... even if the specification was clear for !release, I would not be surprised if some relays still sent another CmdName string. So careful anyway ;-). --[[User:Satomi Ahn|Satomi Ahn]] 14:56, 27 October 2010 (UTC)

== [[llRegionSayTo]] ==

This new LSL command is a godsend for RLV relays and furniture. Its purpose is to send channel chat to one target key in the region only. If the key is that of an avatar, then all their attachments (including their RLV relay) will receive the message and no other object. Conversely, the relay can send acknowledgements back to the trap/furniture key, and no other object will hear them and even less process them with LSL.

In short, this new command helps easing on sim lag, and does not create backward compatibility issues for RLV devices who start using it.

Maybe this should be stated as an explicit recommendation in the RLV Relay protocol main page?

--[[User:Satomi Ahn|Satomi Ahn]] 09:21, 1 June 2011 (PDT)

I strongly support this! I am currently doing an application where I am getting crazy by some relays answering on llSay, some on llShout, some on llWhisper... and I need the responses!

--[[User:Unya Tigerfish|Unya Tigerfish]] 03:11, 7 July 2011 (PDT)

Just a few caveats for llRegionSayTo:
* I haven't met any furniture that would not work with a relay using llRegionSayTo, but I can see a possible scenario where it would fail. Imagine the furniture listens and speaks from two different prims. Then if the relay uses llRegionSayTo to speak to the primitive who spoke to it, then the furniture won't be able to hear the message. If this becomes an official recommendation, then it should also be recommended that the same prim is used for communication both ways.
* On the furniture side, the relay should obviously send the llRegionSayTo message to the avatar UUID, since the relay UUID is not known first. llRegionSayTo works in such a way that if an avatar UUID is given (and channel is not 0), then the message will be heard by all their attachments.
--[[User:Satomi Ahn|Satomi Ahn]] 06:51, 11 July 2011 (PDT)

LSL Protocol/Restrained Love Open Relay Group/ORG Requirements/0004 draft

2011-07-04T12:06:03Z

Satomi Ahn: /* Requirements */

{{ORG_Restrained_Life_Relay_Specs_TOC}}
STATUS: draft

VERSION: 0004

'''Summary'''

This page lists requirements that make a RLV relay or a RLVR controller "ORG compliant".
Main advantages of an ORG compliant device over a classic RLVR devices are the following:
* ORG devices follow a stricter specification (while keeping compatibility), thus making the experience more predictible for scripters;
* ORG devices support wildcards for easy and low lag relay scanning and mass effects;
* ORG devices can support optional x-tensions for more fun. Supported x-tensions can easily be discovered thanks to [[#!x-orgversions|a new query meta-command]].

For a quick overview of the motivations and general working of the RLVR protocol and a few examples, we refer the reader to [[LSL_Protocol/Restrained_Love_Relay/Specification|the original RLVR specification]].

If you are making furniture, traps, or other RLVR controllers and you are not interested in what [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] can offer, then you can stick with the original RLVR specification and still be compatible with [[LSL_Protocol/Restrained_Love_Relay/Comparison|ORG relays]]. However, to have the right to call your controller "ORG compatible", there are still a few light additional requirements such as:
* using only [[llRegionSayTo]] for communications (in both directions),
* not spamming the RLVR channel with messages that do not belong to the protocol,
* and remain responsive to ping messages at every time if you want the session to remain locked.

If you are interested in [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|ORG x-tensions]], then you should also read the part about [[#!x-orgversions|!x-orgversions]].

If you are making a relay, sorry we are afraid you will have to read all this page.

==Definition of an ORG device==

A RLVR device is compliant with ORG specifications if it implements the consolidated RLVR protocol and meta-commands described in sections below, along with the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] it announces supporting.

Remarks:
* An x-tension can constrain the core specification (this document) even more, but cannot alter its requirements or make them less constraining by the mere fact of being there.
* However requirements may be altered as the result of executing a meta-command belonging to an x-tension.
* Thus, although the protocol is extensible, a controller can always rely on the fact an ORG relay abides by the core requirements until the controller knowingly asks the relay to do otherwise.

If a device is ORG compliant, it may be advertised by the use of the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/ORG_Logo|ORG logo]]. ORG device makers are encouraged to do so.

==Consolidated RLVR protocol==
This consolidated RLVR protocol is roughly the same as [[LSL_Protocol/Restrained_Love_Relay/Specification|Marine Kelley's RLVR protocol version 1.100]], minus a few embarassing loose ends.

Main differences are highlighted at the beginning of each subsection.
=== Protocol Syntax ===
Summary of differences with original RLVR:
* we force use of llRegionSayTo,
* we explicitly forbid incorrect syntax on the relay channel
* the relay is supposed to ignore bad commands
* wildcards are supported

==== Definitions ====
* The '''Restrained Love Relay (RLVR) protocol''' implies two partners (SL objects): the '''relay''', attachment worn by the avatar commands are intended for, and a '''controller''', which sends commands to the relay.

* The goal of the protocol is to force the relay wearer to make perform actions and to toggle restrictions on their behavior. Both actions and restrictions can be enforced either through use of viewer hooks ([[LSL_Protocol/RestrainedLoveAPI|Restrained Love API]], or RLV) or through LSL scripting.

* Hence we distinguish between "'''RLV commands'''", starting with "@", which are commands following the syntax of the RLV API and which will ultimately be forwarded to the viewer, and "'''meta-commands'''", starting with "!", which are meant to be interpreted by LSL functions.

====Requirements====
RLVR protocol consists of messages exchanged between relay and controller
* on channel -1812221819 (called '''RLVR channel'''),
* using the LSL function [[llRegionSayTo]] (except for <c_msg>'s using a wildcard)
* all sent from the same prim of the controller or relay (within a [[#Protocol session|session]])
* and having the following syntax (non-terminal <c_msg> for controller messages/'''command messages''' and <r_msg> for relay messages/'''acknowledgement messages'''):

<c_msg> ::= IDENT "," KEY "," <commands>
<r_msg> ::= IDENT "," KEY "," <command> "," ACK
<commands> ::= <command> | <command> "|" <commands>
<command> ::= <rlvcommand> | <metacommand>
<rlvcommand> ::= "@" RLVCOMMAND
<metacommand> ::= "!" METACOMMANDNAME <metacommandarguments>
<metacommandarguments> ::= "" | "/" ARG <metacommandarguments>

where we explicit the different terminal tokens:
IDENT: any string without ","
KEY: any UUID
ACK: any string without ","
RLVCOMMAND: any string without ","
METACOMMANDNAME: any string without "/" and ","
ARG: any string without "/" and ","

* Relays can only send <r_msg>'s, and controllers <c_msg>'s. Nothing else is allowed on RLVR channel.
* In <c_msg>, KEY is always either the uuid of the relay wearer or ffffffff-ffff-ffff-ffff-ffffffffffff ('''wildcard''') if it is a message intended for all relays who can hear it. If llRegionSayTo is used, then the first parameter will also be the uuid of the relay wearer.
* In <r_msg>, KEY is always the uuid of the controller (more accurately: the uuid of the primitive sending the <c_msg>'s), this will also be used as the first parameter of llRegionSayTo.

'''Remark'''

IDENT and ARG can be empty, relay makers must take care of properly handling messages with empty IDENT or ARG (use [[llParseStringKeepNulls]] instead of [[llParseString2List]]). However, due to the fact many existing relays do not properly handle them, controllers should avoid using empty IDENTS.

====On the relay side only====
'''Further requirements:'''
*A relay MUST ignore any message on RLVR channel which is not a <c_msg> with KEY being either the key of the avatar wearing the relay or ffffffff-ffff-ffff-ffff-ffffffffffff.
Then, for every <command>:
* if <command> is neither a valid <rlvcommand> or <metacommand>, the relay must ignore it and process the next <command>'s;
* if <command> is a <rlvcommand> or a <metacommand>, the relay MUST send back to the controller a <r_msg> (see above) such that:
:*IDENT is the same as IDENT in the <c_msg> being processed,
:*<command> is the subcommand being processed
:*and ACK is a string called ''acknowledgement value''. By default the acknowledgement value is "ok" if the relay will execute the <command >, "ko" otherwise.

'''Remarks:'''
* Many meta-commands may have other acknowledgements than "ok" or "ko" (or none, for !pong). Their definitions supersede this specification.
* Note that unknown meta-commands cannot be executed and thus wil be acknowledged by "ko".
* Known meta-commands which are sent with not enough parameters or parameters with types incompatible with those in the definition known by the relay also cannot be executed and will also be acknowledged by "ko". (ex: the relay knows !x-who/key, but receives !x-who/integer/string).

===On executing commands===
Summary of differences with original RLVR:
* explanation on how to handle meta-commands with variable number of parameters,
* the relay knows commands in both core specification and x-tensions,
* clarification on multi-controller relays.

====Relay side====
'''Requirements:'''
* If a <rlvcommand> is acknowledged with value "ok", the relay ensures the viewer is affected the same way as if the LSL instruction llOwnerSay(<rlvcommand>) was executed by a script in a primitive that handles only one controller.
* When processing a <metacommand>, if the relay knows at least one definition of '!'+METACOMMANDNAME for which the received <metacommandarguments> provide enough parameters, then it will be handled according to the definition handling the most parameters among the latter. Extra parameters are ignored.
* A relays knows the following meta-command definitions:
:*[[#Core meta-commands and associated mechanisms|definitions listed in the core requirements]]
:*all definitions included in [[LSL_Protocol/Restrained_Love_Relay/Comparison|x-tensions]] announced by the relay.
* When acknowledging a <metacommand> by anything else than "ko", the relay commits itself to execute it.

'''Remarks:'''
* For first requirement, it must be understood that the reference behavior is that the relay would have if it had one controller per prim. However handling several controllers from one unique prim is possible but requires taking care that different controllers do not interfere with each other, releasing each other's restrictions, for instance.
* For the second requirement, the word "handled" means that if the meta-command with these parameters is known, then requirements in known definition cannot be ignored. Sometimes, this can imply that the meta-command cannot be refused, for instance.

====Controller side====
* The controller can send any command within allowed syntax.
* Only commands described in this specification and commands belonging to x-tensions announced by the relay are guaranteed to be understood by the relay. If not understood, the relay will just answer "ko", do nothing and skip to the next command.

===Protocol session===
Summary of differences with original RLVR:
* it is now clear when a session starts and stops (and what a session is!)
* it is clear when to expect interactive dialogs (and how to avoid spamming relay wearers with blue dialogs)
* no session for unreachable controllers (answer to ping is mandatory to ensure session persistence)

====Definitions====
* During an execution of the RLVR protocol, a relay and a controller establish a '''session''' together. A relay may manage several sessions with several controllers. Likewise, a controller could establish sessions with several relays.
* Restrictions on a relay wearer are relative to a session. So are most other variables (authorization state, key of the controller, ... ).
* A session is '''Opened''' whenever the relay accepts a RLVR command from a controller.
* A session is '''Closed''' (or '''released''') as soon as the relay forgets every variables and releases all restrictions pertaining to that session.
* A session is '''Locked''' whenever it holds active restrictions.
* A session is '''Authed''' if the controller has been allowed to control the relay (not only store some variables with no consequence). Once authed, no interactive "ask" dialog should pop up anymore concerning this session. Most commands should now normally be accepted (and maybe a few automatically rejected).
* A controller is called '''reachable''' if it can receive messages from the relay and can prove it by answering [[#ping/!pong|ping]] requests from the relay. By "can", it is meant by the method of communication agreed upon by the relay and controller (by default: chat messages sent on RLVR channel by llRegionSayTo). X-tensions such as email and delay can modify what is meant by reachable.

====Relay side requirements====
On closing sessions:
*Closing a session clears all RLV restrictions that belong only to that session, clears all session variables and disables all restrictions relative to that session. This MUST happen on the following events and no other:
:*on executing !release (received from the controller, or relay-triggered as in a safeword, see [[#!release]])
:*on noticing the controller is not reachable
:*on timeout, if the session is not Locked
*Sessions that are not locked MUST be closed after a reasonable timeout.

On interactive Auth:
*Unless specified otherwise (see !x-who), no command can trigger an interactive dialog unless the command requires an Authed session and the session is not already Authed.
*Relay implementations MAY require an authed session for all <rlvcommand>'s of the form @xxx=force, @xxx=add and @xxx=n, and for meta-commands whose specifications say it is allowed.
*Other RLV commands MUST automatically accepted or rejected by any relay.

On removing and adding restrictions:
* Commands that remove restrictions are always accepted (RLV @...=<channel_number>, @clear[=...] and @...=y/rem commands, !release, and !x-.../clear[/...] meta-commands).
* No restriction can be released unless as the result of one of the above commands, or of closing a session.
*@xxx=n/add <rlvcommand>'s, after being accepted, add a restriction and therefore Lock the session.
*Some meta-commands described in x-tensions can also add restrictions and therefore Lock the session.

Reachability:
*A relay MUST provide a mechanism for checking that every controlling device is reachable. It is not specified whether this checking process should be automatic or manually triggered.

====Controller side requirements====
* A controller MUST eventually close any Locked session using the meta-command !release.

In particular, non-portable controllers should not let a Locked relay wearer run free out of reach. Moreover, any controller should either react to some kind of event that is bound to happen (timer expiration being the most common) or provide a user interface for closing the session. It should be clear at least to the person who set the trap how the victim will be released.

==Core meta-commands and associated mechanisms==

An ORG device MUST at least support the meta-commands !release, !pong, !version, !implversion and !x-orgversions described below and implement their associated mechanisms.

Particular meta-commands definitions and mechanisms may override general requirements above.

New in ORG compared to RLVR: !x-orgversions

===!release===
Sent by a controller, this command closes the session.

* !release obviously opens no session, requires no Auth and is not Locking.
* If there is an actual session to close, !release MUST be accepted by the relay and acknowledeged by "ok".
* On accepting !release, the relay erases all data pertaining to the session and disables all restrictions of the session.
* When a relay decides to close a session on its own (user safeword, for instance) and it is not due to the controller being unreachable, the relay must send the following acknowledgement message:
release,<controller_key>,!release,ok

When receiving the latter message, the controller should act accordingly, for instance by resetting itself and making itself ready for the next session.

Note that !release is not the same as @clear. @clear is interpreted by the relay as a RLV command and, as such, can only clear RLV restrictions. If RLV restrictions were the only restrictions of the session, then the session will be closed, but some x-tensions also define pure LSL based restrictions.

===ping/!pong===

The ping/!pong mechanism exists so that relays can check presence and responsiveness of a controller. This was primarily meant to be used on relay wearer relog, in order to reactivate all restrictions so that sessions persist on relog if the controller still exists and is ready to continue the session.

''!pong'' cannot require auth and does not lock a session

We call ''ping message'' a message from the relay, having the following syntax:
ping,<controller_key>,ping,ping
We call ''!pong message'' a message from the controller, having the following syntax:
ping,<relay_key>,!pong

====Relay side====
*A relay SHOULD NOT send an acknowledgement in response to ''!pong''.
*A ping message can be sent any time by the relay to a known controller.
*On wearer relog, for each existing Locked session, the relay must send a ping message to the session controller.
*When a !pong message is received from a controller, if it was a reply to a previous ping message:
:#if the session RLV restrictions contain unsit and the avatar was sitting on some object when the restriction was applied, then the relay MUST force the avatar to sit back on the same object (if still existing);
:#the relay MUST make sure all restrictions belonging to the session are made active again.
*If a ping message is sent and is not answered by the controller, then the relay closes the session.

Note that the relay is responsible for storing restrictions and the key of the sit target across sessions, not the controller.

====Controller side====
*Unless it does not matter that the relay could close the session (or for another reason, the controller knows the relay will not close it), a controller SHOULD listen to ping messages and answer any ping message with a !pong message.
*A controller should ignore ping requests from relays it is not ready to handle.

Note controller don't have to poll for relay presence to resume a session but should just listen for ping messages instead. The relay should have stored all restrictions and handle sitting back to whatever furniture the relay wearer was tied up to.

Concerning the second bullet: for instance, if the controller is a furniture which is already in use by another relay wearer, it would be cause dysfunctions to let the pinging relay restore the restrictions without letting its wearer sit on the furniture. Or if the controller is not stateless and the state for the pinging relay has not been saved before, resuming the session from the initial state might be inconsistant.

===!version===
The purpose of this meta-command is to query the version of the RLVR protocol supported by a relay.

* !version opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !version with the version number of the RLVR protocol it supports ("1100" here, since ORG 0004 includes RLVR 1.100).

Note this is the most common command for a controller to scan for nearby relays, as non-ORG relays also accept this command and answer it the way described above.

===!implversion===
The purpose of this meta-command is to query the name and version of the relay implementation.

* !implversion opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !implversion with its implementation version string... which can be any string.

It is recommended this string includes the following elements:
* the relay name/brand/identifier,
* the version number of that relay name/brand/identifier,
* at the beginning, the string prefix "ORG=0004/"
The latter is convenient for checking for ORG compatibility using a command even non-ORG relay should understand.

===!x-orgversions===

This meta-command's purpose is to make it possible for the controller to have detailed informations on the protocol the relay supports. First the version of the ORG consolidated protocol, second the list of supported optional x-tensions, also with their version numbers.

'''Example:'''
C<->R
-> query,rUUID,!x-orgversions
<- query,cUUID,!x-orgversions,ORG=0004/who=002/email=006

'''Requirements:'''
* !x-orgversions should always be accepted with no Auth required, it does not open a session or Lock one.
* The acknowledgement value in a reply to !x-orgversions is a "/"-list of items of the form <package>=<version>. The first <package> is always "ORG" (representing the core specification package of ORG relays), its version string is the version of the specification (4 digits). The other packages are x-tension names, whose version string is 3 digits.
* If several incompatible versions of a same x-tension are supported, they must be listed ordered by version number. Ex: ORG=0004/who=002/email=005/email=006. If versions are backward compatible, only the last version should be reported.
* By announcing an x-tension, the relay commits itself to comply to all requirements of its specification.

'''Remarks:'''
* In a controller, it is however recommended to use !x-orgversions as soon as possible in order to avoid sending unsupported and useless metacommands later on.
* In the acknowledgement message, x-tension names are listed, not meta-command names (as one x-tension can have several meta-commands). Thus listed names do not include the prefix "!x-".
* x-tensions do not have to be standards defined by ORG but can also be proprietary. We recommend that the x-tension name then contains the name of the brand who proposes it.

===Other meta-commands===

Commands not listed here can belong to one of the following categories:
# (unlikely) commands from a future revision of Marine Kelley's original RLVR protocol.
# (more likely but not that much!) core commands from a future revision of ORG
# (very likely) commands from optional [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|x-tensions]]
# proprietary commands

ORG intends for its successive versions to be backward compatible. Therefore ORG relays handle all unknown meta-commands.

We also intend for future versions of ORG consolidated protocol to include last version of original RLVR protocol, hence the prefix "!x-" for all meta-commands comming from ORG, which ensures there will be reasonably no collision.

For the same reason, we require that proprietary commands use an obvious prefix such as "!a-" or "!b-", and so on. Not doing so would prevent ensuring backward compatibility, hence a relay or controller who would use proprietary commands with wrong prefixes are not ORG compliant.

Talk:LSL Protocol/Restrained Love Open Relay Group/ORG Requirements/0004 draft

2011-06-28T09:57:44Z

Satomi Ahn: /* What should 0004 change? */

=What should 0004 change?=
(discussion moved from the ORG Requirements talk page)

To add:
* llRegionSayTo recommended (except for wildcards)
* !implversion reply prefixed by ORG/
* make clear what commands are restricting/secondarily restricting/... and how they affect the relay state and when and how they should be accepted or not
* !x-clear/<string>: clears all meta-restrictions having the string

Definitions of types of commands:
# (primarily) restricting: any command which once executed produces a lasting effect restricting possible behaviors of the wearer until explicitly released. Example: all the RLV @xxx=n/add commands, !vision, !follow, !freeze, ...
# secondarily restricting: any command which has a lasting effect (and requires some global variable to store its state) but whose point is moot if there is no (primary) restriction: !x-email, !x-channel, !x-key, !x-ack, !x-noping, !x-autoforward...
# actions: commands having immediate concrete effect: RLV @xxx=force commands
# queries: commands querying the relay or avatar for data: RLV @xxx=channel commands, !version, !implversion, !x-orgversions, !x-fwd
# releasing: commands removing a restriction: @clear, @clear=xxx, !release, !x-xxxx/clear, @xxxx=y/rem.

Particular cases:
* !x-delay: should be seen as primarily restricting since the "timeout" is not at the discretion of the implementation and no currently effective restrictions needs to exist for !x-delay to make sense. On the other hand, no explicit release command is needed.
* For !x-takeover, there are 2 possible points of view
:* either releasing (never refused), but with the secondary effect that an open session will be transfered if the key was valid
:* or secondarily restricting... but then one must consider that the choice accept vs reject was based on a new criterion: the validity of the session key
:In either case, it must be clear that !x-takeover cannot ever open a new session or trigger an interactive dialog.
* !x-handover: a choice must be made. The most natural would be secondarily restricting, I believe. It can trigger an ask dialog. If accepted, then trust can be transfered over. If there is no actual restriction in the session, there is no point in keeping it open longer than the reasonable life of the auth token !x-handover creates.

Relay states (with respect to one controller):
# (disabled)
# free
# transient session
# persistent session

In my view:
* releasing and queries commands should be accepted without question in every relay state
* restrictions (primary and secondary) and actions are accepted without question within a session
* otherwise the income depends on relay settings: commands can be automatically rejected or accepted according to some criteria, or the wearer can be asked.

* accepting a secondary restriction or an action while free opens a transient session
* accepting a primary restriction while free or in a transient session opens a permanent session (or makes the session permanent)
* releasing *all* primary restrictions makes the session transient
* a transient session is always automatically closed after a reasonable timeout

* when no session (relative to a controller) is open, all sessions variables are forgotten, which includes various authentifications tokens and other communication preferences.

Does that make sense?

--[[User:Satomi Ahn|Satomi Ahn]] 09:32, 9 June 2011 (PDT)

Transient sessions may look like a useless complication, but from the point of view of trap scripters, it makes stuff much easier not having to explicitly open a session only to send @xxx=force commands. Consider the sheer amount of strip walls or forced teleportation traps (and who does want to answer 10 consecutive dialogs for each piece of clothing that will be stripped?). So we need transient sessions in practice anyway (my relays use them, and I believe other relays also do under some form).

Now coming back to commands such as !x-email, !x-channel, !x-key, !x-ack, !x-noping, !x-autoforward...
These set a lasting behavior which thus needs a session to be open at least for the duration of the effect. Also let's keep in mind that no session can be opened without authentification, so these commands need auth to have an effect.

The question is whether one of these effects alone (with no true restriction) justify keeping a session open until an explicit release. My feeling was that the answer was no, which makes these commands of a different nature than either instant effects and permanent restrictions.

If the answer is no, there is still one point that needs to be specified: the behavior when sent outside of an authed session
* should the command be ignored? (ko)
* or should the command be authed and open a (transient) session?
If the answer was yes, then these commands should add restrictions and be handled exactly like @xxx=n commands (and in this case, we must check that every of these commands has a corresponding command for releasing them).

--[[User:Satomi Ahn|Satomi Ahn]] 00:24, 10 June 2011 (PDT)

On a close topic, 004 should also make a clear statement about @xxx=channel commands. Do we consider them as a privacy risk? Are they acceptable for just "scanning" relays?

On the pros side:
* getting an actual answer from the viewer is something more reliable than answer from the relay (the controller knows that both relay and RLV work)
* it makes it possible to spare a few messages by asking directly what you need before attempting to grab (or not... if the answer is not satisfying)
* information the viewer can leak has pretty limited impact (and could be requested later on, after grabbing, anyway)

On the cons side:
* letting @xxx=channel commands get through makes it possible for the viewer to leak some potentially private information
* using several messages for scanning and requesting information is not as bad as it used to be, thanks to llRegionSayTo

Anyway, considering there is a demand for privacy protection, I don't think it is reasonable to require that relays should automatically accept @xxx=channel commands.

To mitigate with annoying ask dialogs, maybe we could propose the following extensions/commands:
* either something like !x-dontask, which would tell the relay not to interactively prompt the user (and refuse all subsequent commands if auth would have been required)
* or the !x-modeinfo command, already proposed before, which tells the controller what mode the relay is currently operating (in particular whether it is interactive... and maybe some more information like: "interactive, but channel commands go through")

Of course, !x-orgversions only can tell whether these x-tensions are supported. Fortunately !x-orgversions triggers no interactive dialog in any relay I know of.

--[[User:Satomi Ahn|Satomi Ahn]] 08:24, 20 June 2011 (PDT)

OK, I'm in a strange situation replying to this, since I represent 3 types of RLV scripter and I switch between those roles (furniture maker, wearable maker, relay maker) frequently. My answer to at leasr part of the discussion you've raised is from the furniture maker point of view.

I help make toys that have a force sitter embedded in them and I try my best to provide the toy operator the best possible information with respect to who can be forcibly sat. Now, there are three choices:
1) run a sensor for avs and present a list of people around the toy and hope that they have an active relay
2) run a sensor for avs and test them with !version to see if they have a relay that responds
3) run a sensor for avs and get their restrictions, eliminating anyone who cannot be forcibly sat on the toy.

We often got questions of "why can't the force sitter sit this or that av" when we used choice #2 and now the commonest question (after adopting #3) is "why can't I force sit myself". Which is for completely different reasons.

As a furniture maker with a force sitter, I don't care if an av is wearing a relay, I care if they can be forcibly sat. So, I want to know the av's status. For example, they may be sitting with an @unsit restriction, or they may be standing with an @sit restriction, or they may be leashed and have an @sittp restriction (OK, if they're within 1.5m they can be forcibly sat, but they might well not be when their name is selected even if they are when I test). All of these cases stop an av from being forcibly sat and therefore lead me to drop anyone with those conditions from the list I present to the operator.

So, if we require !version to know if someone is wearing a relay, fine, I'll do that, and then test their status and they'll get asked. Yes, it's different to use @getstatusall and not !version or @versionnew, but different isn't wrong, it is just different. From the point of view of a furniture maker I want to present the best information to the operator and the only way to do that is through @getstatusall.

If people are worried about privacy? Don't wear a relay, or wear a relay that is set on an ultra paranoid setting and queries the wearer on every @get.

[[User:Chloe1982 Constantine|Chloe1982 Constantine]] 21:02, 23 June 2011 (PDT)

I think it is a really good idea to have some concept of different levels of command, your definitions up top are fine. But, as a furniture maker, I don't think it is up to the relay to decide what a toy should or should not emit as a first command, so that leaves me with the view of use multiple levels, and then the question is how many should there be?

Marine's original (and current spec) leaves that wide open and I am comfortable with that both as a furniture maker, a relay maker, and a user. Of course, as a user I choose the relay I like the best and as a relay maker the relay I wear behaves in accord with my desires.

If ORG really wants to decide levels of command then I think that primarily, secondarily, actions, queries, and releases is a good definition of the levels. However, as a relay maker and a user I don't want too many levels and am very comfortable leaving it up to the relay maker to determine the levels they like and then the user to choose which relay they like.

This seems to me to be an area that *doesn't* need standardizing and allows for good variation in the community. I'll go with an ORG decision on standard levels, though I would like to be free to choose to combine levels.

Marine's relay spec originally used 3 levels, off, ask, auto. But that wasn't mandatory, just advisory. The current spec still makes it advisory to have a reasonable number of levels of protection, but doesn't say what those should be. This is an area best left to each relay maker to decide for themselves. For example, we think it's a good idea to introduce the concept of untrusted devices (ones that are not in the land group). In the tk PBA auto mode, you will get asked if an untrusted device is trying to control your relay (which gives some small protection against griefing). Should everyone adopt this strategy? I don't think so, should the PBA be stopped from adopting this strategy? I don't think so either.

With the definition of the levels, we can point people to that and it gives a common terminology, but after that it should be up to the relay makers to decide what they want to do. Particularly as there are oddities, like !x-vision which I consider to be a primary restricting command.

'''My vote (until persuaded by further discussion) is not to standardize on levels, I don't see the need.'''

[[User:Chloe1982 Constantine|Chloe1982 Constantine]] 21:29, 23 June 2011 (PDT)

:Chloe, I am afraid you answered to the early comments instead of the current version of the draft. In current draft, there is not real definition of levels, but only only 2 boolean variables associated to a session.
:# a variable that says that the relay will never again bother the user with an ask dialog (that's the '''Authed''' session state)
:# a variable that says that current session is '''Locked''', meaning it won't time out on its own and will be released only if asked by the source, or if the source becomes unreachable, or on safeword.
:My purpose in writing it this way was to minimize unpredictibility (such that questions like "if I scan with @getstatusall, will relay wearers be spammed with blue dialogs?" or "If I send !x-who|@sit:xxxxx=force, will the relay still be grabbed in 2 hours?" may be answered), while still keeping a lot open to implementation (in particular, actual relay modes).
:"Primary" and "Secondary" restrictions were my first attempt at formalizing my thoughts. Where the equivalent to "Primary" in current draft would be just a restriction (a command that Locks a session), and where Secondary would be any other command that stores some token in session memory, without locking it. Note that a command that can trigger an ask dialog can make the relay store an authentification token and could in some sense be considered as a secondary restriction... but anyway, I removed these definitions from the draft.
:Another important contribution of this draft was the formalization of the notion of '''session''', as fundamental to the relay protocol (I believe it was already implicitly there in most relays, although completely absent from Marine's specification, which made it unpredictible). This was necessary to specify more precisely how long stuff (like authentification state and tokens stored by various x-tensions) should be remembered. Moreover it made it easier to define what the session key (as defined in the Key x-tension) should apply to.
:Coming back to your point. It is now time to decide whether @getxxxx=channel commands should require Auth or not, as if the answer is yes, then you won't have to worry about your furniture spamming ORG relays with blue dialogs. If the answer is no, you will have to either scan with !version or accept that some relays may pop up dialogs (which will still be a minority I think... but the possibility will exist).
:--[[User:Satomi Ahn|Satomi Ahn]] 23:52, 23 June 2011 (PDT)

Speaking as a relay maker, the reason I resonated with the levels is that I have been thinking along these lines for the generation 2.0 of the tk PBA. Right now I have 3 levels named, nerdishly 0, 1, and 2. I've been assuming that level 0 is a pass through and is where I put most of the metacommands and also the @get's, then level 1 is all the non-restricting commands (all the =force) and level 2 is the restricting commands. Given that I have these three levels it made sense to allow authorization up to a defined level. So, a relay in ask mode would, on receiving a series of @get and or =force commands ask the wearer for authorization. The wearer might reply with an authorize to this level or authorize all. If the former, then the relay would pass through any level 0 or level 1 commands but would require a reauthorization if it received a level 2 command. If the latter, all commands would be accepted.

With this scheme in mind, if we split the @get commands into ones that need authorization, I would increase to 4 the number of levels in the relay, bumping my existing levels 1 and 2 up to 2 and 3 and then splitting my level 0 into the metacommands (still level 0) and the @get and @findfolder commands into level 1.

I still like the concept of authorization to a level with a need for reauthorization if a command in the incoming stream exceeds the existing auhtorization.

Speaking as a furniture maker, the concepts of '''Locked''' and '''Auth''' and '''Session''' are good, but I am not sure how important it is to standardize when they should be applied. I am much motivated by a long conversation I had yesterday by an individual who seemed to want me to change either the TK toys or the tk PBA or both to suit the individual's tastes. (The original discussion focused on @get.) I talked with one of the TK owners who thought that we should continue to use @getstatusall as the basis for our force sitter (I believe the other owner will also agree, but I've pointed her to this discussion to weigh in as she feels fit). Given this position, I'd like to see @get commands treated as a pass through, but I wouldn't require it. If someone wants to make a relay that raises a dialog box (I can't say blue since mine are all black) that's fine with me, they can make such a relay; I will choose not to use such a relay.

I guess my bottom line is this, I think it is really neat that the spec is underspecified with respect to concepts of '''Locked''', '''Auth''', and '''Session''', this allows for variation and allows wearers to choose the style that best suits them. This looseness extends to safeword interpretation; the spec used to say something about it being a good idea for the relay maker to specify a safeword. We agreed and had a way of doing so, and then I saw what Toy was doing in her relay which I thought to be a really neat idea. At that stage I asked her if she minded me borrowing the concept and with her blessing I implemented both Easy Out and Real World safewords. Yes, I know this is a side issue but is indicative of my general feeling of wanting some looseness so that we can have innovation.

[[User:Chloe1982 Constantine|Chloe1982 Constantine]] 05:38, 24 June 2011 (PDT)

A remark about !implversion; I cannot change the string sent by my relay as acknowledgment since this string is the first step for some objects to detect the presence of my relay (and not another one), so I cannot add "ORG=0004/"; I actually do not see the interest to change this definition of !implversion (which is actually only a recommendation) since !x-orgversions already contains the information. --[[User:Dahlia Orfan|Dahlia Orfan]] 02:48, 28 June 2011 (PDT)
:It's just one more place to have the information, moreover, in a command that is also supported by non-ORG devices, which can be convenient. Also this helpes advertising ORG.
:As for your devices who check !implversion, wouldn't it be better to that purpose to rely on !x-orgversion? (maybe adding proprietary x-tensions, if you are using stuff no ORG x-tension proposes?) --[[User:Satomi Ahn|Satomi Ahn]] 02:57, 28 June 2011 (PDT)

LSL Protocol/Restrained Love Open Relay Group/ORG Requirements/0004 draft

2011-06-27T19:39:24Z

Satomi Ahn: /* Consolidated RLVR protocol */

{{ORG_Restrained_Life_Relay_Specs_TOC}}
STATUS: draft

VERSION: 0004

'''Summary'''

This page lists requirements that make a RLV relay or a RLVR controller "ORG compliant".
Main advantages of an ORG compliant device over a classic RLVR devices are the following:
* ORG devices follow a stricter specification (while keeping compatibility), thus making the experience more predictible for scripters;
* ORG devices support wildcards for easy and low lag relay scanning and mass effects;
* ORG devices can support optional x-tensions for more fun. Supported x-tensions can easily be discovered thanks to [[#!x-orgversions|a new query meta-command]].

For a quick overview of the motivations and general working of the RLVR protocol and a few examples, we refer the reader to [[LSL_Protocol/Restrained_Love_Relay/Specification|the original RLVR specification]].

If you are making furniture, traps, or other RLVR controllers and you are not interested in what [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] can offer, then you can stick with the original RLVR specification and still be compatible with [[LSL_Protocol/Restrained_Love_Relay/Comparison|ORG relays]]. However, to have the right to call your controller "ORG compatible", there are still a few light additional requirements such as:
* using only [[llRegionSayTo]] for communications (in both directions),
* not spamming the RLVR channel with messages that do not belong to the protocol,
* and remain responsive to ping messages at every time if you want the session to remain locked.

If you are interested in [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|ORG x-tensions]], then you should also read the part about [[#!x-orgversions|!x-orgversions]].

If you are making a relay, sorry we are afraid you will have to read all this page.

==Definition of an ORG device==

A RLVR device is compliant with ORG specifications if it implements the consolidated RLVR protocol and meta-commands described in sections below, along with the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] it announces supporting.

Remarks:
* An x-tension can constrain the core specification (this document) even more, but cannot alter its requirements or make them less constraining by the mere fact of being there.
* However requirements may be altered as the result of executing a meta-command belonging to an x-tension.
* Thus, although the protocol is extensible, a controller can always rely on the fact an ORG relay abides by the core requirements until the controller knowingly asks the relay to do otherwise.

If a device is ORG compliant, it may be advertised by the use of the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/ORG_Logo|ORG logo]]. ORG device makers are encouraged to do so.

==Consolidated RLVR protocol==
This consolidated RLVR protocol is roughly the same as [[LSL_Protocol/Restrained_Love_Relay/Specification|Marine Kelley's RLVR protocol version 1.100]], minus a few embarassing loose ends.

Main differences are highlighted at the beginning of each subsection.
=== Protocol Syntax ===
Summary of differences with original RLVR:
* we force use of llRegionSayTo,
* we explicitly forbid incorrect syntax on the relay channel
* the relay is supposed to ignore bad commands
* wildcards are supported

==== Definitions ====
* The '''Restrained Love Relay (RLVR) protocol''' implies two partners (SL objects): the '''relay''', attachment worn by the avatar commands are intended for, and a '''controller''', which sends commands to the relay.

* The goal of the protocol is to force the relay wearer to make perform actions and to toggle restrictions on their behavior. Both actions and restrictions can be enforced either through use of viewer hooks ([[LSL_Protocol/RestrainedLoveAPI|Restrained Love API]], or RLV) or through LSL scripting.

* Hence we distinguish between "'''RLV commands'''", starting with "@", which are commands following the syntax of the RLV API and which will ultimately be forwarded to the viewer, and "'''meta-commands'''", starting with "!", which are meant to be interpreted by LSL functions.

====Requirements====
RLVR protocol consists of messages exchanged between relay and controller
* on channel -1812221819 (called '''RLVR channel'''),
* using the LSL function [[llRegionSayTo]] (except for <c_msg>'s using a wildcard)
* all sent from the same prim of the controller or relay (within a [[#Protocol session|session]])
* and having the following syntax (non-terminal <c_msg> for controller messages/'''command messages''' and <r_msg> for relay messages/'''acknowledgement messages'''):

<c_msg> ::= IDENT "," KEY "," <commands>
<r_msg> ::= IDENT "," KEY "," <command> "," ACK
<commands> ::= <command> | <command> "|" <commands>
<command> ::= <rlvcommand> | <metacommand>
<rlvcommand> ::= "@" RLVCOMMAND
<metacommand> ::= "!" METACOMMANDNAME <metacommandarguments>
<metacommandarguments> ::= "" | "/" ARG <metacommandarguments>

where we explicit the different terminal tokens:
IDENT: any string without ","
KEY: any UUID
ACK: any string without ","
RLVCOMMAND: any string without ","
METACOMMANDNAME: any string without "/" and ","
ARG: any string without "/" and ","

* Relays can only send <r_msg>'s, and controllers <c_msg>'s. Nothing else is allowed on RLVR channel.
* In <c_msg>, KEY is always either the uuid of the relay wearer or ffffffff-ffff-ffff-ffff-ffffffffffff ('''wildcard''') if it is a message intended for all relays who can hear it. If llRegionSayTo is used, then the first parameter will also be the uuid of the relay wearer.
* In <r_msg>, KEY is always the uuid of the controller (more accurately: the uuid of the primitive sending the <c_msg>'s), this will also be used as the first parameter of llRegionSayTo.

====On the relay side only====
'''Further requirements:'''
*A relay MUST ignore any message on RLVR channel which is not a <c_msg> with KEY being either the key of the avatar wearing the relay or ffffffff-ffff-ffff-ffff-ffffffffffff.
Then, for every <command>:
* if <command> is neither a valid <rlvcommand> or <metacommand>, the relay must ignore it and process the next <command>'s;
* if <command> is a <rlvcommand> or a <metacommand>, the relay MUST send back to the controller a <r_msg> (see above) such that:
:*IDENT is the same as IDENT in the <c_msg> being processed,
:*<command> is the subcommand being processed
:*and ACK is a string called ''acknowledgement value''. By default the acknowledgement value is "ok" if the relay will execute the <command >, "ko" otherwise.

'''Remarks:'''
* Many meta-commands may have other acknowledgements than "ok" or "ko" (or none, for !pong). Their definitions supersede this specification.
* Note that unknown meta-commands cannot be executed and thus wil be acknowledged by "ko".
* Known meta-commands which are sent with not enough parameters or parameters with types incompatible with those in the definition known by the relay also cannot be executed and will also be acknowledged by "ko". (ex: the relay knows !x-who/key, but receives !x-who/integer/string).

===On executing commands===
Summary of differences with original RLVR:
* explanation on how to handle meta-commands with variable number of parameters,
* the relay knows commands in both core specification and x-tensions,
* clarification on multi-controller relays.

====Relay side====
'''Requirements:'''
* If a <rlvcommand> is acknowledged with value "ok", the relay ensures the viewer is affected the same way as if the LSL instruction llOwnerSay(<rlvcommand>) was executed by a script in a primitive that handles only one controller.
* When processing a <metacommand>, if the relay knows at least one definition of '!'+METACOMMANDNAME for which the received <metacommandarguments> provide enough parameters, then it will be handled according to the definition handling the most parameters among the latter. Extra parameters are ignored.
* A relays knows the following meta-command definitions:
:*[[#Core meta-commands and associated mechanisms|definitions listed in the core requirements]]
:*all definitions included in [[LSL_Protocol/Restrained_Love_Relay/Comparison|x-tensions]] announced by the relay.
* When acknowledging a <metacommand> by anything else than "ko", the relay commits itself to execute it.

'''Remarks:'''
* For first requirement, it must be understood that the reference behavior is that the relay would have if it had one controller per prim. However handling several controllers from one unique prim is possible but requires taking care that different controllers do not interfere with each other, releasing each other's restrictions, for instance.
* For the second requirement, the word "handled" means that if the meta-command with these parameters is known, then requirements in known definition cannot be ignored. Sometimes, this can imply that the meta-command cannot be refused, for instance.

====Controller side====
* The controller can send any command within allowed syntax.
* Only commands described in this specification and commands belonging to x-tensions announced by the relay are guaranteed to be understood by the relay. If not understood, the relay will just answer "ko", do nothing and skip to the next command.

===Protocol session===
Summary of differences with original RLVR:
* it is now clear when a session starts and stops (and what a session is!)
* it is clear when to expect interactive dialogs (and how to avoid spamming relay wearers with blue dialogs)
* no session for unreachable controllers (answer to ping is mandatory to ensure session persistence)

====Definitions====
* During an execution of the RLVR protocol, a relay and a controller establish a '''session''' together. A relay may manage several sessions with several controllers. Likewise, a controller could establish sessions with several relays.
* Restrictions on a relay wearer are relative to a session. So are most other variables (authorization state, key of the controller, ... ).
* A session is '''Opened''' whenever the relay accepts a RLVR command from a controller.
* A session is '''Closed''' (or '''released''') as soon as the relay forgets every variables and releases all restrictions pertaining to that session.
* A session is '''Locked''' whenever it holds active restrictions.
* A session is '''Authed''' if the controller has been allowed to control the relay (not only store some variables with no consequence). Once authed, no interactive "ask" dialog should pop up anymore concerning this session. Most commands should now normally be accepted (and maybe a few automatically rejected).
* A controller is called '''reachable''' if it can receive messages from the relay and can prove it by answering [[#ping/!pong|ping]] requests from the relay. By "can", it is meant by the method of communication agreed upon by the relay and controller (by default: chat messages sent on RLVR channel by llRegionSayTo). X-tensions such as email and delay can modify what is meant by reachable.

====Relay side requirements====
On closing sessions:
*Closing a session clears all RLV restrictions that belong only to that session, clears all session variables and disables all restrictions relative to that session. This MUST happen on the following events and no other:
:*on executing !release (received from the controller, or relay-triggered as in a safeword, see [[#!release]])
:*on noticing the controller is not reachable
:*on timeout, if the session is not Locked
*Sessions that are not locked MUST be closed after a reasonable timeout.

On interactive Auth:
*Unless specified otherwise (see !x-who), no command can trigger an interactive dialog unless the command requires an Authed session and the session is not already Authed.
*Relay implementations MAY require an authed session for all <rlvcommand>'s of the form @xxx=force, @xxx=add and @xxx=n, and for meta-commands whose specifications say it is allowed.
*Other RLV commands MUST automatically accepted or rejected by any relay.

On removing and adding restrictions:
* Commands that remove restrictions are always accepted (RLV @...=<channel_number>, @clear[=...] and @...=y/rem commands, !release, and !x-.../clear[/...] meta-commands).
* No restriction can be released unless as the result of one of the above commands, or of closing a session.
*@xxx=n/add <rlvcommand>'s, after being accepted, add a restriction and therefore Lock the session.
*Some meta-commands described in x-tensions can also add restrictions and therefore Lock the session.

Reachability:
*A relay MUST provide a mechanism for checking that every controlling device is reachable. It is not specified whether this checking process should be automatic or manually triggered.

====Controller side requirements====
* A controller MUST eventually close any Locked session using the meta-command !release.

In particular, non-portable controllers should not let a Locked relay wearer run free out of reach. Moreover, any controller should either react to some kind of event that is bound to happen (timer expiration being the most common) or provide a user interface for closing the session. It should be clear at least to the person who set the trap how the victim will be released.

==Core meta-commands and associated mechanisms==

An ORG device MUST at least support the meta-commands !release, !pong, !version, !implversion and !x-orgversions described below and implement their associated mechanisms.

Particular meta-commands definitions and mechanisms may override general requirements above.

New in ORG compared to RLVR: !x-orgversions

===!release===
Sent by a controller, this command closes the session.

* !release obviously opens no session, requires no Auth and is not Locking.
* If there is an actual session to close, !release MUST be accepted by the relay and acknowledeged by "ok".
* On accepting !release, the relay erases all data pertaining to the session and disables all restrictions of the session.
* When a relay decides to close a session on its own (user safeword, for instance) and it is not due to the controller being unreachable, the relay must send the following acknowledgement message:
release,<controller_key>,!release,ok

When receiving the latter message, the controller should act accordingly, for instance by resetting itself and making itself ready for the next session.

Note that !release is not the same as @clear. @clear is interpreted by the relay as a RLV command and, as such, can only clear RLV restrictions. If RLV restrictions were the only restrictions of the session, then the session will be closed, but some x-tensions also define pure LSL based restrictions.

===ping/!pong===

The ping/!pong mechanism exists so that relays can check presence and responsiveness of a controller. This was primarily meant to be used on relay wearer relog, in order to reactivate all restrictions so that sessions persist on relog if the controller still exists and is ready to continue the session.

''!pong'' cannot require auth and does not lock a session

We call ''ping message'' a message from the relay, having the following syntax:
ping,<controller_key>,ping,ping
We call ''!pong message'' a message from the controller, having the following syntax:
ping,<relay_key>,!pong

====Relay side====
*A relay SHOULD NOT send an acknowledgement in response to ''!pong''.
*A ping message can be sent any time by the relay to a known controller.
*On wearer relog, for each existing Locked session, the relay must send a ping message to the session controller.
*When a !pong message is received from a controller, if it was a reply to a previous ping message:
:#if the session RLV restrictions contain unsit and the avatar was sitting on some object when the restriction was applied, then the relay MUST force the avatar to sit back on the same object (if still existing);
:#the relay MUST make sure all restrictions belonging to the session are made active again.
*If a ping message is sent and is not answered by the controller, then the relay closes the session.

Note that the relay is responsible for storing restrictions and the key of the sit target across sessions, not the controller.

====Controller side====
*Unless it does not matter that the relay could close the session (or for another reason, the controller knows the relay will not close it), a controller SHOULD listen to ping messages and answer any ping message with a !pong message.
*A controller should ignore ping requests from relays it is not ready to handle.

Note controller don't have to poll for relay presence to resume a session but should just listen for ping messages instead. The relay should have stored all restrictions and handle sitting back to whatever furniture the relay wearer was tied up to.

Concerning the second bullet: for instance, if the controller is a furniture which is already in use by another relay wearer, it would be cause dysfunctions to let the pinging relay restore the restrictions without letting its wearer sit on the furniture. Or if the controller is not stateless and the state for the pinging relay has not been saved before, resuming the session from the initial state might be inconsistant.

===!version===
The purpose of this meta-command is to query the version of the RLVR protocol supported by a relay.

* !version opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !version with the version number of the RLVR protocol it supports ("1100" here, since ORG 0004 includes RLVR 1.100).

Note this is the most common command for a controller to scan for nearby relays, as non-ORG relays also accept this command and answer it the way described above.

===!implversion===
The purpose of this meta-command is to query the name and version of the relay implementation.

* !implversion opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !implversion with its implementation version string... which can be any string.

It is recommended this string includes the following elements:
* the relay name/brand/identifier,
* the version number of that relay name/brand/identifier,
* at the beginning, the string prefix "ORG=0004/"
The latter is convenient for checking for ORG compatibility using a command even non-ORG relay should understand.

===!x-orgversions===

This meta-command's purpose is to make it possible for the controller to have detailed informations on the protocol the relay supports. First the version of the ORG consolidated protocol, second the list of supported optional x-tensions, also with their version numbers.

'''Example:'''
C<->R
-> query,rUUID,!x-orgversions
<- query,cUUID,!x-orgversions,ORG=0004/who=002/email=006

'''Requirements:'''
* !x-orgversions should always be accepted with no Auth required, it does not open a session or Lock one.
* The acknowledgement value in a reply to !x-orgversions is a "/"-list of items of the form <package>=<version>. The first <package> is always "ORG" (representing the core specification package of ORG relays), its version string is the version of the specification (4 digits). The other packages are x-tension names, whose version string is 3 digits.
* If several incompatible versions of a same x-tension are supported, they must be listed ordered by version number. Ex: ORG=0004/who=002/email=005/email=006. If versions are backward compatible, only the last version should be reported.
* By announcing an x-tension, the relay commits itself to comply to all requirements of its specification.

'''Remarks:'''
* In a controller, it is however recommended to use !x-orgversions as soon as possible in order to avoid sending unsupported and useless metacommands later on.
* In the acknowledgement message, x-tension names are listed, not meta-command names (as one x-tension can have several meta-commands). Thus listed names do not include the prefix "!x-".
* x-tensions do not have to be standards defined by ORG but can also be proprietary. We recommend that the x-tension name then contains the name of the brand who proposes it.

===Other meta-commands===

Commands not listed here can belong to one of the following categories:
# (unlikely) commands from a future revision of Marine Kelley's original RLVR protocol.
# (more likely but not that much!) core commands from a future revision of ORG
# (very likely) commands from optional [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|x-tensions]]
# proprietary commands

ORG intends for its successive versions to be backward compatible. Therefore ORG relays handle all unknown meta-commands.

We also intend for future versions of ORG consolidated protocol to include last version of original RLVR protocol, hence the prefix "!x-" for all meta-commands comming from ORG, which ensures there will be reasonably no collision.

For the same reason, we require that proprietary commands use an obvious prefix such as "!a-" or "!b-", and so on. Not doing so would prevent ensuring backward compatibility, hence a relay or controller who would use proprietary commands with wrong prefixes are not ORG compliant.

LSL Protocol/Restrained Love Open Relay Group/ORG Requirements/0004 draft

2011-06-27T18:06:51Z

Satomi Ahn: /* Definition of an ORG device */

{{ORG_Restrained_Life_Relay_Specs_TOC}}
STATUS: draft

VERSION: 0004

'''Summary'''

This page lists requirements that make a RLV relay or a RLVR controller "ORG compliant".
Main advantages of an ORG compliant device over a classic RLVR devices are the following:
* ORG devices follow a stricter specification (while keeping compatibility), thus making the experience more predictible for scripters;
* ORG devices support wildcards for easy and low lag relay scanning and mass effects;
* ORG devices can support optional x-tensions for more fun. Supported x-tensions can easily be discovered thanks to [[#!x-orgversions|a new query meta-command]].

For a quick overview of the motivations and general working of the RLVR protocol and a few examples, we refer the reader to [[LSL_Protocol/Restrained_Love_Relay/Specification|the original RLVR specification]].

If you are making furniture, traps, or other RLVR controllers and you are not interested in what [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] can offer, then you can stick with the original RLVR specification and still be compatible with [[LSL_Protocol/Restrained_Love_Relay/Comparison|ORG relays]]. However, to have the right to call your controller "ORG compatible", there are still a few light additional requirements such as:
* using only [[llRegionSayTo]] for communications (in both directions),
* not spamming the RLVR channel with messages that do not belong to the protocol,
* and remain responsive to ping messages at every time if you want the session to remain locked.

If you are interested in [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|ORG x-tensions]], then you should also read the part about [[#!x-orgversions|!x-orgversions]].

If you are making a relay, sorry we are afraid you will have to read all this page.

==Definition of an ORG device==

A RLVR device is compliant with ORG specifications if it implements the consolidated RLVR protocol and meta-commands described in sections below, along with the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] it announces supporting.

Remarks:
* An x-tension can constrain the core specification (this document) even more, but cannot alter its requirements or make them less constraining by the mere fact of being there.
* However requirements may be altered as the result of executing a meta-command belonging to an x-tension.
* Thus, although the protocol is extensible, a controller can always rely on the fact an ORG relay abides by the core requirements until the controller knowingly asks the relay to do otherwise.

If a device is ORG compliant, it may be advertised by the use of the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/ORG_Logo|ORG logo]]. ORG device makers are encouraged to do so.

==Consolidated RLVR protocol==
This consolidated RLVR protocol is roughly the same as [[LSL_Protocol/Restrained_Love_Relay/Specification|Marine Kelley's RLVR protocol version 1.100]], minus a few embarassing loose ends.

Main differences are highlighted at the beginning of each subsection.
=== Protocol Syntax ===
Summary of differences with original RLVR:
* we force use of llRegionSayTo,
* we explicitly forbid incorrect syntax on the relay channel
* the relay is supposed to ignore bad commands
* wildcards are supported

==== Definitions ====
* The '''Restrained Love Relay (RLVR) protocol''' implies two partners (SL objects): the '''relay''', attachment worn by the avatar commands are intended for, and a '''controller''', which sends commands to the relay.

* The goal of the protocol is to force the relay wearer to make perform actions and to toggle restrictions on their behavior. Both actions and restrictions can be enforced either through use of viewer hooks ([[LSL_Protocol/RestrainedLoveAPI|Restrained Love API]], or RLV) or through LSL scripting.

* Hence we distinguish between "'''RLV commands'''", starting with "@", which are commands following the syntax of the RLV API and which will ultimately be forwarded to the viewer, and "'''meta-commands'''", starting with "!", which are meant to be interpreted by LSL functions.

====Requirements====
RLVR protocol consists of messages exchanged between relay and controller
* on channel -1812221819 (called '''RLVR channel'''),
* using the LSL function [[llRegionSayTo]] (except for <c_msg>'s using a wildcard),
* all sent from the same prim of the controller or relay (within a [[#Protocol session|session]])
* and having the following syntax (non-terminal <c_msg> for controller messages/'''command messages''' and <r_msg> for relay messages/'''acknowledgement messages'''):

<c_msg> ::= IDENT "," KEY "," <commands>
<r_msg> ::= IDENT "," KEY "," <command> "," ACK
<commands> ::= <command> | <command> "|" <commands>
<command> ::= <rlvcommand> | <metacommand>
<rlvcommand> ::= "@" RLVCOMMAND
<metacommand> ::= "!" METACOMMANDNAME <metacommandarguments>
<metacommandarguments> ::= "" | "/" ARG <metacommandarguments>

where we explicit the different terminal tokens:
IDENT: any string without ","
KEY: any UUID
ACK: any string without ","
RLVCOMMAND: any string without ","
METACOMMANDNAME: any string without "/" and ","
ARG: any string without "/" and ","

* Relays can only send <r_msg>'s, and controllers <c_msg>'s. Nothing else is allowed on RLVR channel.
* In <c_msg>, KEY is always either the uuid of the relay wearer or ffffffff-ffff-ffff-ffff-ffffffffffff ('''wildcard''') if it is a message intended for all relays who can hear it.
* In <r_msg>, KEY is always the uuid of the controller.

====On the relay side only====
'''Further requirements:'''
*A relay MUST ignore any message on RLVR channel which is not a <c_msg> with KEY being either the key of the avatar wearing the relay or ffffffff-ffff-ffff-ffff-ffffffffffff.
Then, for every <command>:
* if <command> is neither a valid <rlvcommand> or <metacommand>, the relay must ignore it and process the next <command>'s;
* if <command> is a <rlvcommand> or a <metacommand>, the relay MUST send back to the controller a <r_msg> (see above) such that:
:*IDENT is the same as IDENT in the <c_msg> being processed,
:*<command> is the subcommand being processed
:*and ACK is a string called ''acknowledgement value''. By default the acknowledgement value is "ok" if the relay will execute the <command >, "ko" otherwise.

'''Remarks:'''
* Many meta-commands may have other acknowledgements than "ok" or "ko" (or none, for !pong). Their definitions supersede this specification.
* Note that unknown meta-commands cannot be executed and thus wil be acknowledged by "ko".
* Known meta-commands which are sent with not enough parameters or parameters with types incompatible with those in the definition known by the relay also cannot be executed and will also be acknowledged by "ko". (ex: the relay knows !x-who/key, but receives !x-who/integer/string).

===On executing commands===
Summary of differences with original RLVR:
* explanation on how to handle meta-commands with variable number of parameters,
* the relay knows commands in both core specification and x-tensions,
* clarification on multi-controller relays.

====Relay side====
'''Requirements:'''
* If a <rlvcommand> is acknowledged with value "ok", the relay ensures the viewer is affected the same way as if the LSL instruction llOwnerSay(<rlvcommand>) was executed by a script in a primitive that handles only one controller.
* When processing a <metacommand>, if the relay knows at least one definition of '!'+METACOMMANDNAME for which the received <metacommandarguments> provide enough parameters, then it will be handled according to the definition handling the most parameters among the latter. Extra parameters are ignored.
* A relays knows the following meta-command definitions:
:*[[#Core meta-commands and associated mechanisms|definitions listed in the core requirements]]
:*all definitions included in [[LSL_Protocol/Restrained_Love_Relay/Comparison|x-tensions]] announced by the relay.
* When acknowledging a <metacommand> by anything else than "ko", the relay commits itself to execute it.

'''Remarks:'''
* For first requirement, it must be understood that the reference behavior is that the relay would have if it had one controller per prim. However handling several controllers from one unique prim is possible but requires taking care that different controllers do not interfere with each other, releasing each other's restrictions, for instance.
* For the second requirement, the word "handled" means that if the meta-command with these parameters is known, then requirements in known definition cannot be ignored. Sometimes, this can imply that the meta-command cannot be refused, for instance.

====Controller side====
* The controller can send any command within allowed syntax.
* Only commands described in this specification and commands belonging to x-tensions announced by the relay are guaranteed to be understood by the relay. If not understood, the relay will just answer "ko", do nothing and skip to the next command.

===Protocol session===
Summary of differences with original RLVR:
* it is now clear when a session starts and stops (and what a session is!)
* it is clear when to expect interactive dialogs (and how to avoid spamming relay wearers with blue dialogs)
* no session for unreachable controllers (answer to ping is mandatory to ensure session persistence)

====Definitions====
* During an execution of the RLVR protocol, a relay and a controller establish a '''session''' together. A relay may manage several sessions with several controllers. Likewise, a controller could establish sessions with several relays.
* Restrictions on a relay wearer are relative to a session. So are most other variables (authorization state, key of the controller, ... ).
* A session is '''Opened''' whenever the relay accepts a RLVR command from a controller.
* A session is '''Closed''' (or '''released''') as soon as the relay forgets every variables and releases all restrictions pertaining to that session.
* A session is '''Locked''' whenever it holds active restrictions.
* A session is '''Authed''' if the controller has been allowed to control the relay (not only store some variables with no consequence). Once authed, no interactive "ask" dialog should pop up anymore concerning this session. Most commands should now normally be accepted (and maybe a few automatically rejected).
* A controller is called '''reachable''' if it can receive messages from the relay and can prove it by answering [[#ping/!pong|ping]] requests from the relay. By "can", it is meant by the method of communication agreed upon by the relay and controller (by default: chat messages sent on RLVR channel by llRegionSayTo). X-tensions such as email and delay can modify what is meant by reachable.

====Relay side requirements====
On closing sessions:
*Closing a session clears all RLV restrictions that belong only to that session, clears all session variables and disables all restrictions relative to that session. This MUST happen on the following events and no other:
:*on executing !release (received from the controller, or relay-triggered as in a safeword, see [[#!release]])
:*on noticing the controller is not reachable
:*on timeout, if the session is not Locked
*Sessions that are not locked MUST be closed after a reasonable timeout.

On interactive Auth:
*Unless specified otherwise (see !x-who), no command can trigger an interactive dialog unless the command requires an Authed session and the session is not already Authed.
*Relay implementations MAY require an authed session for all <rlvcommand>'s of the form @xxx=force, @xxx=add and @xxx=n, and for meta-commands whose specifications say it is allowed.
*Other RLV commands MUST automatically accepted or rejected by any relay.

On removing and adding restrictions:
* Commands that remove restrictions are always accepted (RLV @...=<channel_number>, @clear[=...] and @...=y/rem commands, !release, and !x-.../clear[/...] meta-commands).
* No restriction can be released unless as the result of one of the above commands, or of closing a session.
*@xxx=n/add <rlvcommand>'s, after being accepted, add a restriction and therefore Lock the session.
*Some meta-commands described in x-tensions can also add restrictions and therefore Lock the session.

Reachability:
*A relay MUST provide a mechanism for checking that every controlling device is reachable. It is not specified whether this checking process should be automatic or manually triggered.

====Controller side requirements====
* A controller MUST eventually close any Locked session using the meta-command !release.

In particular, non-portable controllers should not let a Locked relay wearer run free out of reach. Moreover, any controller should either react to some kind of event that is bound to happen (timer expiration being the most common) or provide a user interface for closing the session. It should be clear at least to the person who set the trap how the victim will be released.

==Core meta-commands and associated mechanisms==

An ORG device MUST at least support the meta-commands !release, !pong, !version, !implversion and !x-orgversions described below and implement their associated mechanisms.

Particular meta-commands definitions and mechanisms may override general requirements above.

New in ORG compared to RLVR: !x-orgversions

===!release===
Sent by a controller, this command closes the session.

* !release obviously opens no session, requires no Auth and is not Locking.
* If there is an actual session to close, !release MUST be accepted by the relay and acknowledeged by "ok".
* On accepting !release, the relay erases all data pertaining to the session and disables all restrictions of the session.
* When a relay decides to close a session on its own (user safeword, for instance) and it is not due to the controller being unreachable, the relay must send the following acknowledgement message:
release,<controller_key>,!release,ok

When receiving the latter message, the controller should act accordingly, for instance by resetting itself and making itself ready for the next session.

Note that !release is not the same as @clear. @clear is interpreted by the relay as a RLV command and, as such, can only clear RLV restrictions. If RLV restrictions were the only restrictions of the session, then the session will be closed, but some x-tensions also define pure LSL based restrictions.

===ping/!pong===

The ping/!pong mechanism exists so that relays can check presence and responsiveness of a controller. This was primarily meant to be used on relay wearer relog, in order to reactivate all restrictions so that sessions persist on relog if the controller still exists and is ready to continue the session.

''!pong'' cannot require auth and does not lock a session

We call ''ping message'' a message from the relay, having the following syntax:
ping,<controller_key>,ping,ping
We call ''!pong message'' a message from the controller, having the following syntax:
ping,<relay_key>,!pong

====Relay side====
*A relay SHOULD NOT send an acknowledgement in response to ''!pong''.
*A ping message can be sent any time by the relay to a known controller.
*On wearer relog, for each existing Locked session, the relay must send a ping message to the session controller.
*When a !pong message is received from a controller, if it was a reply to a previous ping message:
:#if the session RLV restrictions contain unsit and the avatar was sitting on some object when the restriction was applied, then the relay MUST force the avatar to sit back on the same object (if still existing);
:#the relay MUST make sure all restrictions belonging to the session are made active again.
*If a ping message is sent and is not answered by the controller, then the relay closes the session.

Note that the relay is responsible for storing restrictions and the key of the sit target across sessions, not the controller.

====Controller side====
*Unless it does not matter that the relay could close the session (or for another reason, the controller knows the relay will not close it), a controller SHOULD listen to ping messages and answer any ping message with a !pong message.
*A controller should ignore ping requests from relays it is not ready to handle.

Note controller don't have to poll for relay presence to resume a session but should just listen for ping messages instead. The relay should have stored all restrictions and handle sitting back to whatever furniture the relay wearer was tied up to.

Concerning the second bullet: for instance, if the controller is a furniture which is already in use by another relay wearer, it would be cause dysfunctions to let the pinging relay restore the restrictions without letting its wearer sit on the furniture. Or if the controller is not stateless and the state for the pinging relay has not been saved before, resuming the session from the initial state might be inconsistant.

===!version===
The purpose of this meta-command is to query the version of the RLVR protocol supported by a relay.

* !version opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !version with the version number of the RLVR protocol it supports ("1100" here, since ORG 0004 includes RLVR 1.100).

Note this is the most common command for a controller to scan for nearby relays, as non-ORG relays also accept this command and answer it the way described above.

===!implversion===
The purpose of this meta-command is to query the name and version of the relay implementation.

* !implversion opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !implversion with its implementation version string... which can be any string.

It is recommended this string includes the following elements:
* the relay name/brand/identifier,
* the version number of that relay name/brand/identifier,
* at the beginning, the string prefix "ORG=0004/"
The latter is convenient for checking for ORG compatibility using a command even non-ORG relay should understand.

===!x-orgversions===

This meta-command's purpose is to make it possible for the controller to have detailed informations on the protocol the relay supports. First the version of the ORG consolidated protocol, second the list of supported optional x-tensions, also with their version numbers.

'''Example:'''
C<->R
-> query,rUUID,!x-orgversions
<- query,cUUID,!x-orgversions,ORG=0004/who=002/email=006

'''Requirements:'''
* !x-orgversions should always be accepted with no Auth required, it does not open a session or Lock one.
* The acknowledgement value in a reply to !x-orgversions is a "/"-list of items of the form <package>=<version>. The first <package> is always "ORG" (representing the core specification package of ORG relays), its version string is the version of the specification (4 digits). The other packages are x-tension names, whose version string is 3 digits.
* If several incompatible versions of a same x-tension are supported, they must be listed ordered by version number. Ex: ORG=0004/who=002/email=005/email=006. If versions are backward compatible, only the last version should be reported.
* By announcing an x-tension, the relay commits itself to comply to all requirements of its specification.

'''Remarks:'''
* In a controller, it is however recommended to use !x-orgversions as soon as possible in order to avoid sending unsupported and useless metacommands later on.
* In the acknowledgement message, x-tension names are listed, not meta-command names (as one x-tension can have several meta-commands). Thus listed names do not include the prefix "!x-".
* x-tensions do not have to be standards defined by ORG but can also be proprietary. We recommend that the x-tension name then contains the name of the brand who proposes it.

===Other meta-commands===

Commands not listed here can belong to one of the following categories:
# (unlikely) commands from a future revision of Marine Kelley's original RLVR protocol.
# (more likely but not that much!) core commands from a future revision of ORG
# (very likely) commands from optional [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|x-tensions]]
# proprietary commands

ORG intends for its successive versions to be backward compatible. Therefore ORG relays handle all unknown meta-commands.

We also intend for future versions of ORG consolidated protocol to include last version of original RLVR protocol, hence the prefix "!x-" for all meta-commands comming from ORG, which ensures there will be reasonably no collision.

For the same reason, we require that proprietary commands use an obvious prefix such as "!a-" or "!b-", and so on. Not doing so would prevent ensuring backward compatibility, hence a relay or controller who would use proprietary commands with wrong prefixes are not ORG compliant.

LSL Protocol/Restrained Love Open Relay Group/ORG Requirements/0004 draft

2011-06-27T17:54:32Z

Satomi Ahn:

{{ORG_Restrained_Life_Relay_Specs_TOC}}
STATUS: draft

VERSION: 0004

'''Summary'''

This page lists requirements that make a RLV relay or a RLVR controller "ORG compliant".
Main advantages of an ORG compliant device over a classic RLVR devices are the following:
* ORG devices follow a stricter specification (while keeping compatibility), thus making the experience more predictible for scripters;
* ORG devices support wildcards for easy and low lag relay scanning and mass effects;
* ORG devices can support optional x-tensions for more fun. Supported x-tensions can easily be discovered thanks to [[#!x-orgversions|a new query meta-command]].

For a quick overview of the motivations and general working of the RLVR protocol and a few examples, we refer the reader to [[LSL_Protocol/Restrained_Love_Relay/Specification|the original RLVR specification]].

If you are making furniture, traps, or other RLVR controllers and you are not interested in what [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] can offer, then you can stick with the original RLVR specification and still be compatible with [[LSL_Protocol/Restrained_Love_Relay/Comparison|ORG relays]]. However, to have the right to call your controller "ORG compatible", there are still a few light additional requirements such as:
* using only [[llRegionSayTo]] for communications (in both directions),
* not spamming the RLVR channel with messages that do not belong to the protocol,
* and remain responsive to ping messages at every time if you want the session to remain locked.

If you are interested in [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|ORG x-tensions]], then you should also read the part about [[#!x-orgversions|!x-orgversions]].

If you are making a relay, sorry we are afraid you will have to read all this page.

==Definition of an ORG device==

A RLVR device is compliant with ORG specifications if it implements the consolidated RLVR protocol and meta-commands described in sections below, along with the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] it announces supporting.

Remarks:
* An x-tension can constrain the core specification (this document) even more, but cannot alter its requirements or make them less constraining if not as a result of the relay executing a meta-command from this x-tension.
* Thus, although the protocol is extensible, a controller can always rely on the fact an ORG relay abides by the core requirements until the controller knowingly asks the relay to do otherwise.

If a device is ORG compliant, it may be advertised by the use of the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/ORG_Logo|ORG logo]]. ORG device makers are encouraged to do so.

==Consolidated RLVR protocol==
This consolidated RLVR protocol is roughly the same as [[LSL_Protocol/Restrained_Love_Relay/Specification|Marine Kelley's RLVR protocol version 1.100]], minus a few embarassing loose ends.

Main differences are highlighted at the beginning of each subsection.
=== Protocol Syntax ===
Summary of differences with original RLVR:
* we force use of llRegionSayTo,
* we explicitly forbid incorrect syntax on the relay channel
* the relay is supposed to ignore bad commands
* wildcards are supported

==== Definitions ====
* The '''Restrained Love Relay (RLVR) protocol''' implies two partners (SL objects): the '''relay''', attachment worn by the avatar commands are intended for, and a '''controller''', which sends commands to the relay.

* The goal of the protocol is to force the relay wearer to make perform actions and to toggle restrictions on their behavior. Both actions and restrictions can be enforced either through use of viewer hooks ([[LSL_Protocol/RestrainedLoveAPI|Restrained Love API]], or RLV) or through LSL scripting.

* Hence we distinguish between "'''RLV commands'''", starting with "@", which are commands following the syntax of the RLV API and which will ultimately be forwarded to the viewer, and "'''meta-commands'''", starting with "!", which are meant to be interpreted by LSL functions.

====Requirements====
RLVR protocol consists of messages exchanged between relay and controller
* on channel -1812221819 (called '''RLVR channel'''),
* using the LSL function [[llRegionSayTo]] (except for <c_msg>'s using a wildcard),
* all sent from the same prim of the controller or relay (within a [[#Protocol session|session]])
* and having the following syntax (non-terminal <c_msg> for controller messages/'''command messages''' and <r_msg> for relay messages/'''acknowledgement messages'''):

<c_msg> ::= IDENT "," KEY "," <commands>
<r_msg> ::= IDENT "," KEY "," <command> "," ACK
<commands> ::= <command> | <command> "|" <commands>
<command> ::= <rlvcommand> | <metacommand>
<rlvcommand> ::= "@" RLVCOMMAND
<metacommand> ::= "!" METACOMMANDNAME <metacommandarguments>
<metacommandarguments> ::= "" | "/" ARG <metacommandarguments>

where we explicit the different terminal tokens:
IDENT: any string without ","
KEY: any UUID
ACK: any string without ","
RLVCOMMAND: any string without ","
METACOMMANDNAME: any string without "/" and ","
ARG: any string without "/" and ","

* Relays can only send <r_msg>'s, and controllers <c_msg>'s. Nothing else is allowed on RLVR channel.
* In <c_msg>, KEY is always either the uuid of the relay wearer or ffffffff-ffff-ffff-ffff-ffffffffffff ('''wildcard''') if it is a message intended for all relays who can hear it.
* In <r_msg>, KEY is always the uuid of the controller.

====On the relay side only====
'''Further requirements:'''
*A relay MUST ignore any message on RLVR channel which is not a <c_msg> with KEY being either the key of the avatar wearing the relay or ffffffff-ffff-ffff-ffff-ffffffffffff.
Then, for every <command>:
* if <command> is neither a valid <rlvcommand> or <metacommand>, the relay must ignore it and process the next <command>'s;
* if <command> is a <rlvcommand> or a <metacommand>, the relay MUST send back to the controller a <r_msg> (see above) such that:
:*IDENT is the same as IDENT in the <c_msg> being processed,
:*<command> is the subcommand being processed
:*and ACK is a string called ''acknowledgement value''. By default the acknowledgement value is "ok" if the relay will execute the <command >, "ko" otherwise.

'''Remarks:'''
* Many meta-commands may have other acknowledgements than "ok" or "ko" (or none, for !pong). Their definitions supersede this specification.
* Note that unknown meta-commands cannot be executed and thus wil be acknowledged by "ko".
* Known meta-commands which are sent with not enough parameters or parameters with types incompatible with those in the definition known by the relay also cannot be executed and will also be acknowledged by "ko". (ex: the relay knows !x-who/key, but receives !x-who/integer/string).

===On executing commands===
Summary of differences with original RLVR:
* explanation on how to handle meta-commands with variable number of parameters,
* the relay knows commands in both core specification and x-tensions,
* clarification on multi-controller relays.

====Relay side====
'''Requirements:'''
* If a <rlvcommand> is acknowledged with value "ok", the relay ensures the viewer is affected the same way as if the LSL instruction llOwnerSay(<rlvcommand>) was executed by a script in a primitive that handles only one controller.
* When processing a <metacommand>, if the relay knows at least one definition of '!'+METACOMMANDNAME for which the received <metacommandarguments> provide enough parameters, then it will be handled according to the definition handling the most parameters among the latter. Extra parameters are ignored.
* A relays knows the following meta-command definitions:
:*[[#Core meta-commands and associated mechanisms|definitions listed in the core requirements]]
:*all definitions included in [[LSL_Protocol/Restrained_Love_Relay/Comparison|x-tensions]] announced by the relay.
* When acknowledging a <metacommand> by anything else than "ko", the relay commits itself to execute it.

'''Remarks:'''
* For first requirement, it must be understood that the reference behavior is that the relay would have if it had one controller per prim. However handling several controllers from one unique prim is possible but requires taking care that different controllers do not interfere with each other, releasing each other's restrictions, for instance.
* For the second requirement, the word "handled" means that if the meta-command with these parameters is known, then requirements in known definition cannot be ignored. Sometimes, this can imply that the meta-command cannot be refused, for instance.

====Controller side====
* The controller can send any command within allowed syntax.
* Only commands described in this specification and commands belonging to x-tensions announced by the relay are guaranteed to be understood by the relay. If not understood, the relay will just answer "ko", do nothing and skip to the next command.

===Protocol session===
Summary of differences with original RLVR:
* it is now clear when a session starts and stops (and what a session is!)
* it is clear when to expect interactive dialogs (and how to avoid spamming relay wearers with blue dialogs)
* no session for unreachable controllers (answer to ping is mandatory to ensure session persistence)

====Definitions====
* During an execution of the RLVR protocol, a relay and a controller establish a '''session''' together. A relay may manage several sessions with several controllers. Likewise, a controller could establish sessions with several relays.
* Restrictions on a relay wearer are relative to a session. So are most other variables (authorization state, key of the controller, ... ).
* A session is '''Opened''' whenever the relay accepts a RLVR command from a controller.
* A session is '''Closed''' (or '''released''') as soon as the relay forgets every variables and releases all restrictions pertaining to that session.
* A session is '''Locked''' whenever it holds active restrictions.
* A session is '''Authed''' if the controller has been allowed to control the relay (not only store some variables with no consequence). Once authed, no interactive "ask" dialog should pop up anymore concerning this session. Most commands should now normally be accepted (and maybe a few automatically rejected).
* A controller is called '''reachable''' if it can receive messages from the relay and can prove it by answering [[#ping/!pong|ping]] requests from the relay. By "can", it is meant by the method of communication agreed upon by the relay and controller (by default: chat messages sent on RLVR channel by llRegionSayTo). X-tensions such as email and delay can modify what is meant by reachable.

====Relay side requirements====
On closing sessions:
*Closing a session clears all RLV restrictions that belong only to that session, clears all session variables and disables all restrictions relative to that session. This MUST happen on the following events and no other:
:*on executing !release (received from the controller, or relay-triggered as in a safeword, see [[#!release]])
:*on noticing the controller is not reachable
:*on timeout, if the session is not Locked
*Sessions that are not locked MUST be closed after a reasonable timeout.

On interactive Auth:
*Unless specified otherwise (see !x-who), no command can trigger an interactive dialog unless the command requires an Authed session and the session is not already Authed.
*Relay implementations MAY require an authed session for all <rlvcommand>'s of the form @xxx=force, @xxx=add and @xxx=n, and for meta-commands whose specifications say it is allowed.
*Other RLV commands MUST automatically accepted or rejected by any relay.

On removing and adding restrictions:
* Commands that remove restrictions are always accepted (RLV @...=<channel_number>, @clear[=...] and @...=y/rem commands, !release, and !x-.../clear[/...] meta-commands).
* No restriction can be released unless as the result of one of the above commands, or of closing a session.
*@xxx=n/add <rlvcommand>'s, after being accepted, add a restriction and therefore Lock the session.
*Some meta-commands described in x-tensions can also add restrictions and therefore Lock the session.

Reachability:
*A relay MUST provide a mechanism for checking that every controlling device is reachable. It is not specified whether this checking process should be automatic or manually triggered.

====Controller side requirements====
* A controller MUST eventually close any Locked session using the meta-command !release.

In particular, non-portable controllers should not let a Locked relay wearer run free out of reach. Moreover, any controller should either react to some kind of event that is bound to happen (timer expiration being the most common) or provide a user interface for closing the session. It should be clear at least to the person who set the trap how the victim will be released.

==Core meta-commands and associated mechanisms==

An ORG device MUST at least support the meta-commands !release, !pong, !version, !implversion and !x-orgversions described below and implement their associated mechanisms.

Particular meta-commands definitions and mechanisms may override general requirements above.

New in ORG compared to RLVR: !x-orgversions

===!release===
Sent by a controller, this command closes the session.

* !release obviously opens no session, requires no Auth and is not Locking.
* If there is an actual session to close, !release MUST be accepted by the relay and acknowledeged by "ok".
* On accepting !release, the relay erases all data pertaining to the session and disables all restrictions of the session.
* When a relay decides to close a session on its own (user safeword, for instance) and it is not due to the controller being unreachable, the relay must send the following acknowledgement message:
release,<controller_key>,!release,ok

When receiving the latter message, the controller should act accordingly, for instance by resetting itself and making itself ready for the next session.

Note that !release is not the same as @clear. @clear is interpreted by the relay as a RLV command and, as such, can only clear RLV restrictions. If RLV restrictions were the only restrictions of the session, then the session will be closed, but some x-tensions also define pure LSL based restrictions.

===ping/!pong===

The ping/!pong mechanism exists so that relays can check presence and responsiveness of a controller. This was primarily meant to be used on relay wearer relog, in order to reactivate all restrictions so that sessions persist on relog if the controller still exists and is ready to continue the session.

''!pong'' cannot require auth and does not lock a session

We call ''ping message'' a message from the relay, having the following syntax:
ping,<controller_key>,ping,ping
We call ''!pong message'' a message from the controller, having the following syntax:
ping,<relay_key>,!pong

====Relay side====
*A relay SHOULD NOT send an acknowledgement in response to ''!pong''.
*A ping message can be sent any time by the relay to a known controller.
*On wearer relog, for each existing Locked session, the relay must send a ping message to the session controller.
*When a !pong message is received from a controller, if it was a reply to a previous ping message:
:#if the session RLV restrictions contain unsit and the avatar was sitting on some object when the restriction was applied, then the relay MUST force the avatar to sit back on the same object (if still existing);
:#the relay MUST make sure all restrictions belonging to the session are made active again.
*If a ping message is sent and is not answered by the controller, then the relay closes the session.

Note that the relay is responsible for storing restrictions and the key of the sit target across sessions, not the controller.

====Controller side====
*Unless it does not matter that the relay could close the session (or for another reason, the controller knows the relay will not close it), a controller SHOULD listen to ping messages and answer any ping message with a !pong message.
*A controller should ignore ping requests from relays it is not ready to handle.

Note controller don't have to poll for relay presence to resume a session but should just listen for ping messages instead. The relay should have stored all restrictions and handle sitting back to whatever furniture the relay wearer was tied up to.

Concerning the second bullet: for instance, if the controller is a furniture which is already in use by another relay wearer, it would be cause dysfunctions to let the pinging relay restore the restrictions without letting its wearer sit on the furniture. Or if the controller is not stateless and the state for the pinging relay has not been saved before, resuming the session from the initial state might be inconsistant.

===!version===
The purpose of this meta-command is to query the version of the RLVR protocol supported by a relay.

* !version opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !version with the version number of the RLVR protocol it supports ("1100" here, since ORG 0004 includes RLVR 1.100).

Note this is the most common command for a controller to scan for nearby relays, as non-ORG relays also accept this command and answer it the way described above.

===!implversion===
The purpose of this meta-command is to query the name and version of the relay implementation.

* !implversion opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !implversion with its implementation version string... which can be any string.

It is recommended this string includes the following elements:
* the relay name/brand/identifier,
* the version number of that relay name/brand/identifier,
* at the beginning, the string prefix "ORG=0004/"
The latter is convenient for checking for ORG compatibility using a command even non-ORG relay should understand.

===!x-orgversions===

This meta-command's purpose is to make it possible for the controller to have detailed informations on the protocol the relay supports. First the version of the ORG consolidated protocol, second the list of supported optional x-tensions, also with their version numbers.

'''Example:'''
C<->R
-> query,rUUID,!x-orgversions
<- query,cUUID,!x-orgversions,ORG=0004/who=002/email=006

'''Requirements:'''
* !x-orgversions should always be accepted with no Auth required, it does not open a session or Lock one.
* The acknowledgement value in a reply to !x-orgversions is a "/"-list of items of the form <package>=<version>. The first <package> is always "ORG" (representing the core specification package of ORG relays), its version string is the version of the specification (4 digits). The other packages are x-tension names, whose version string is 3 digits.
* If several incompatible versions of a same x-tension are supported, they must be listed ordered by version number. Ex: ORG=0004/who=002/email=005/email=006. If versions are backward compatible, only the last version should be reported.
* By announcing an x-tension, the relay commits itself to comply to all requirements of its specification.

'''Remarks:'''
* In a controller, it is however recommended to use !x-orgversions as soon as possible in order to avoid sending unsupported and useless metacommands later on.
* In the acknowledgement message, x-tension names are listed, not meta-command names (as one x-tension can have several meta-commands). Thus listed names do not include the prefix "!x-".
* x-tensions do not have to be standards defined by ORG but can also be proprietary. We recommend that the x-tension name then contains the name of the brand who proposes it.

===Other meta-commands===

Commands not listed here can belong to one of the following categories:
# (unlikely) commands from a future revision of Marine Kelley's original RLVR protocol.
# (more likely but not that much!) core commands from a future revision of ORG
# (very likely) commands from optional [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|x-tensions]]
# proprietary commands

ORG intends for its successive versions to be backward compatible. Therefore ORG relays handle all unknown meta-commands.

We also intend for future versions of ORG consolidated protocol to include last version of original RLVR protocol, hence the prefix "!x-" for all meta-commands comming from ORG, which ensures there will be reasonably no collision.

For the same reason, we require that proprietary commands use an obvious prefix such as "!a-" or "!b-", and so on. Not doing so would prevent ensuring backward compatibility, hence a relay or controller who would use proprietary commands with wrong prefixes are not ORG compliant.

LSL Protocol/Restrained Love Open Relay Group/ORG Requirements/0004 draft

2011-06-27T16:42:51Z

Satomi Ahn: /* Other meta-commands */

{{ORG_Restrained_Life_Relay_Specs_TOC}}
STATUS: draft

VERSION: 0004

'''Summary'''

This page lists requirements that make a RLV relay or a RLVR controller "ORG compliant".
Main advantages of an ORG compliant device over a classic RLVR devices are the following:
* ORG devices follow a stricter specification (while keeping compatibility), thus making the experience more predictible for scripters;
* ORG devices support wildcards for easy and low lag relay scanning and mass effects;
* ORG devices can support optional x-tensions for more fun. Supported x-tensions can easily be discovered thanks to [[#!x-orgversions|a new query meta-command]].

For a quick overview of the motivations and general working of the RLVR protocol and a few examples, we refer the reader to [[LSL_Protocol/Restrained_Love_Relay/Specification|the original RLVR specification]].

If you are making furniture, traps, or other RLVR controllers and you are not interested in what [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] can offer, then you can stick with the original RLVR specification and still be compatible with [[LSL_Protocol/Restrained_Love_Relay/Comparison|ORG relays]]. However, to have the right to call your controller "ORG compatible", there are still a few light additional requirements such as:
* using only [[llRegionSayTo]] for communications with the relay,
* not spamming the RLVR channel with messages that do not belong to the protocol,
* and remain responsive to ping messages at every time if you want the session to remain locked.

If you are interested in [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|ORG x-tensions]], then you should also read the part about [[#!x-orgversions|!x-orgversions]].

If you are making a relay, sorry we are afraid you will have to read all this page.

==Definition of an ORG device==

A RLVR device is compliant with ORG specifications if it implements the consolidated RLVR protocol and meta-commands described in sections below, along with the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] it announces supporting.

Remarks:
* An x-tension can constrain the core specification (this document) even more, but cannot alter its requirements or make them less constraining if not as a result of the relay executing a meta-command from this x-tension.
* Thus, although the protocol is extensible, a controller can always rely on the fact an ORG relay abides by the core requirements until the controller knowingly asks the relay to do otherwise.

If a device is ORG compliant, it may be advertised by the use of the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/ORG_Logo|ORG logo]]. ORG device makers are encouraged to do so.

==Consolidated RLVR protocol==
This consolidated RLVR protocol is roughly the same as [[LSL_Protocol/Restrained_Love_Relay/Specification|Marine Kelley's RLVR protocol version 1.100]], minus a few embarassing loose ends.

Main differences are highlighted at the beginning of each subsection.
=== Protocol Syntax ===
Summary of differences with original RLVR:
* we force use of llRegionSayTo,
* we explicitly forbid incorrect syntax on the relay channel
* the relay is supposed to ignore bad commands
* wildcards are supported

==== Definitions ====
* The '''Restrained Love Relay (RLVR) protocol''' implies two partners (SL objects): the '''relay''', attachment worn by the avatar commands are intended for, and a '''controller''', which sends commands to the relay.

* The goal of the protocol is to force the relay wearer to make perform actions and to toggle restrictions on their behavior. Both actions and restrictions can be enforced either through use of viewer hooks ([[LSL_Protocol/RestrainedLoveAPI|Restrained Love API]], or RLV) or through LSL scripting.

* Hence we distinguish between "'''RLV commands'''", starting with "@", which are commands following the syntax of the RLV API and which will ultimately be forwarded to the viewer, and "'''meta-commands'''", starting with "!", which are meant to be interpreted by LSL functions.

====Requirements====
RLVR protocol consists of messages exchanged between relay and controller
* on channel -1812221819 (called '''RLVR channel'''),
* using the LSL function [[llRegionSayTo]] (except for <c_msg>'s using a wildcard),
* all sent from the same prim of the controller or relay (within a [[#Protocol session|session]])
* and having the following syntax (non-terminal <c_msg> for controller messages/'''command messages''' and <r_msg> for relay messages/'''acknowledgement messages'''):

<c_msg> ::= IDENT "," KEY "," <commands>
<r_msg> ::= IDENT "," KEY "," <command> "," ACK
<commands> ::= <command> | <command> "|" <commands>
<command> ::= <rlvcommand> | <metacommand>
<rlvcommand> ::= "@" RLVCOMMAND
<metacommand> ::= "!" METACOMMANDNAME <metacommandarguments>
<metacommandarguments> ::= "" | "/" ARG <metacommandarguments>

where we explicit the different terminal tokens:
IDENT: any string without ","
KEY: any UUID
ACK: any string without ","
RLVCOMMAND: any string without ","
METACOMMANDNAME: any string without "/" and ","
ARG: any string without "/" and ","

* Relays can only send <r_msg>'s, and controllers <c_msg>'s. Nothing else is allowed on RLVR channel.
* In <c_msg>, KEY is always either the uuid of the relay wearer or ffffffff-ffff-ffff-ffff-ffffffffffff ('''wildcard''') if it is a message intended for all relays who can hear it.
* In <r_msg>, KEY is always the uuid of the controller.

====On the relay side only====
'''Further requirements:'''
*A relay MUST ignore any message on RLVR channel which is not a <c_msg> with KEY being either the key of the avatar wearing the relay or ffffffff-ffff-ffff-ffff-ffffffffffff.
Then, for every <command>:
* if <command> is neither a valid <rlvcommand> or <metacommand>, the relay must ignore it and process the next <command>'s;
* if <command> is a <rlvcommand> or a <metacommand>, the relay MUST send back to the controller a <r_msg> (see above) such that:
:*IDENT is the same as IDENT in the <c_msg> being processed,
:*<command> is the subcommand being processed
:*and ACK is a string called ''acknowledgement value''. By default the acknowledgement value is "ok" if the relay will execute the <command >, "ko" otherwise.

'''Remarks:'''
* Many meta-commands may have other acknowledgements than "ok" or "ko" (or none, for !pong). Their definitions supersede this specification.
* Note that unknown meta-commands cannot be executed and thus wil be acknowledged by "ko".
* Known meta-commands which are sent with not enough parameters or parameters with types incompatible with those in the definition known by the relay also cannot be executed and will also be acknowledged by "ko". (ex: the relay knows !x-who/key, but receives !x-who/integer/string).

===On executing commands===
Summary of differences with original RLVR:
* explanation on how to handle meta-commands with variable number of parameters,
* the relay knows commands in both core specification and x-tensions,
* clarification on multi-controller relays.

====Relay side====
'''Requirements:'''
* If a <rlvcommand> is acknowledged with value "ok", the relay ensures the viewer is affected the same way as if the LSL instruction llOwnerSay(<rlvcommand>) was executed by a script in a primitive that handles only one controller.
* When processing a <metacommand>, if the relay knows at least one definition of '!'+METACOMMANDNAME for which the received <metacommandarguments> provide enough parameters, then it will be handled according to the definition handling the most parameters among the latter. Extra parameters are ignored.
* A relays knows the following meta-command definitions:
:*[[#Core meta-commands and associated mechanisms|definitions listed in the core requirements]]
:*all definitions included in [[LSL_Protocol/Restrained_Love_Relay/Comparison|x-tensions]] announced by the relay.
* When acknowledging a <metacommand> by anything else than "ko", the relay commits itself to execute it.

'''Remarks:'''
* For first requirement, it must be understood that the reference behavior is that the relay would have if it had one controller per prim. However handling several controllers from one unique prim is possible but requires taking care that different controllers do not interfere with each other, releasing each other's restrictions, for instance.
* For the second requirement, the word "handled" means that if the meta-command with these parameters is known, then requirements in known definition cannot be ignored. Sometimes, this can imply that the meta-command cannot be refused, for instance.

====Controller side====
* The controller can send any command within allowed syntax.
* Only commands described in this specification and commands belonging to x-tensions announced by the relay are guaranteed to be understood by the relay. If not understood, the relay will just answer "ko", do nothing and skip to the next command.

===Protocol session===
Summary of differences with original RLVR:
* it is now clear when a session starts and stops (and what a session is!)
* it is clear when to expect interactive dialogs (and how to avoid spamming relay wearers with blue dialogs)
* no session for unreachable controllers (answer to ping is mandatory to ensure session persistence)

====Definitions====
* During an execution of the RLVR protocol, a relay and a controller establish a '''session''' together. A relay may manage several sessions with several controllers. Likewise, a controller could establish sessions with several relays.
* Restrictions on a relay wearer are relative to a session. So are most other variables (authorization state, key of the controller, ... ).
* A session is '''Opened''' whenever the relay accepts a RLVR command from a controller.
* A session is '''Closed''' (or '''released''') as soon as the relay forgets every variables and releases all restrictions pertaining to that session.
* A session is '''Locked''' whenever it holds active restrictions.
* A session is '''Authed''' if the controller has been allowed to control the relay (not only store some variables with no consequence). Once authed, no interactive "ask" dialog should pop up anymore concerning this session. Most commands should now normally be accepted (and maybe a few automatically rejected).
* A controller is called '''reachable''' if it can receive messages from the relay and can prove it by answering [[#ping/!pong|ping]] requests from the relay. By "can", it is meant by the method of communication agreed upon by the relay and controller (by default: chat messages sent on RLVR channel by llRegionSayTo). X-tensions such as email and delay can modify what is meant by reachable.

====Relay side requirements====
On closing sessions:
*Closing a session clears all RLV restrictions that belong only to that session, clears all session variables and disables all restrictions relative to that session. This MUST happen on the following events and no other:
:*on executing !release (received from the controller, or relay-triggered as in a safeword, see [[#!release]])
:*on noticing the controller is not reachable
:*on timeout, if the session is not Locked
*Sessions that are not locked MUST be closed after a reasonable timeout.

On interactive Auth:
*Unless specified otherwise (see !x-who), no command can trigger an interactive dialog unless the command requires an Authed session and the session is not already Authed.
*Relay implementations MAY require an authed session for all <rlvcommand>'s of the form @xxx=force, @xxx=add and @xxx=n, and for meta-commands whose specifications say it is allowed.
*Other RLV commands MUST automatically accepted or rejected by any relay.

On removing and adding restrictions:
* Commands that remove restrictions are always accepted (RLV @...=<channel_number>, @clear[=...] and @...=y/rem commands, !release, and !x-.../clear[/...] meta-commands).
* No restriction can be released unless as the result of one of the above commands, or of closing a session.
*@xxx=n/add <rlvcommand>'s, after being accepted, add a restriction and therefore Lock the session.
*Some meta-commands described in x-tensions can also add restrictions and therefore Lock the session.

Reachability:
*A relay MUST provide a mechanism for checking that every controlling device is reachable. It is not specified whether this checking process should be automatic or manually triggered.

====Controller side requirements====
* A controller MUST eventually close any Locked session using the meta-command !release.

In particular, non-portable controllers should not let a Locked relay wearer run free out of reach. Moreover, any controller should either react to some kind of event that is bound to happen (timer expiration being the most common) or provide a user interface for closing the session. It should be clear at least to the person who set the trap how the victim will be released.

==Core meta-commands and associated mechanisms==

An ORG device MUST at least support the meta-commands !release, !pong, !version, !implversion and !x-orgversions described below and implement their associated mechanisms.

Particular meta-commands definitions and mechanisms may override general requirements above.

New in ORG compared to RLVR: !x-orgversions

===!release===
Sent by a controller, this command closes the session.

* !release obviously opens no session, requires no Auth and is not Locking.
* If there is an actual session to close, !release MUST be accepted by the relay and acknowledeged by "ok".
* On accepting !release, the relay erases all data pertaining to the session and disables all restrictions of the session.
* When a relay decides to close a session on its own (user safeword, for instance) and it is not due to the controller being unreachable, the relay must send the following acknowledgement message:
release,<controller_key>,!release,ok

When receiving the latter message, the controller should act accordingly, for instance by resetting itself and making itself ready for the next session.

Note that !release is not the same as @clear. @clear is interpreted by the relay as a RLV command and, as such, can only clear RLV restrictions. If RLV restrictions were the only restrictions of the session, then the session will be closed, but some x-tensions also define pure LSL based restrictions.

===ping/!pong===

The ping/!pong mechanism exists so that relays can check presence and responsiveness of a controller. This was primarily meant to be used on relay wearer relog, in order to reactivate all restrictions so that sessions persist on relog if the controller still exists and is ready to continue the session.

''!pong'' cannot require auth and does not lock a session

We call ''ping message'' a message from the relay, having the following syntax:
ping,<controller_key>,ping,ping
We call ''!pong message'' a message from the controller, having the following syntax:
ping,<relay_key>,!pong

====Relay side====
*A relay SHOULD NOT send an acknowledgement in response to ''!pong''.
*A ping message can be sent any time by the relay to a known controller.
*On wearer relog, for each existing Locked session, the relay must send a ping message to the session controller.
*When a !pong message is received from a controller, if it was a reply to a previous ping message:
:#if the session RLV restrictions contain unsit and the avatar was sitting on some object when the restriction was applied, then the relay MUST force the avatar to sit back on the same object (if still existing);
:#the relay MUST make sure all restrictions belonging to the session are made active again.
*If a ping message is sent and is not answered by the controller, then the relay closes the session.

Note that the relay is responsible for storing restrictions and the key of the sit target across sessions, not the controller.

====Controller side====
*Unless it does not matter that the relay could close the session (or for another reason, the controller knows the relay will not close it), a controller SHOULD listen to ping messages and answer any ping message with a !pong message.
*A controller should ignore ping requests from relays it is not ready to handle.

Note controller don't have to poll for relay presence to resume a session but should just listen for ping messages instead. The relay should have stored all restrictions and handle sitting back to whatever furniture the relay wearer was tied up to.

Concerning the second bullet: for instance, if the controller is a furniture which is already in use by another relay wearer, it would be cause dysfunctions to let the pinging relay restore the restrictions without letting its wearer sit on the furniture. Or if the controller is not stateless and the state for the pinging relay has not been saved before, resuming the session from the initial state might be inconsistant.

===!version===
The purpose of this meta-command is to query the version of the RLVR protocol supported by a relay.

* !version opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !version with the version number of the RLVR protocol it supports ("1100" here, since ORG 0004 includes RLVR 1.100).

Note this is the most common command for a controller to scan for nearby relays, as non-ORG relays also accept this command and answer it the way described above.

===!implversion===
The purpose of this meta-command is to query the name and version of the relay implementation.

* !implversion opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !implversion with its implementation version string... which can be any string.

It is recommended this string includes the following elements:
* the relay name/brand/identifier,
* the version number of that relay name/brand/identifier,
* at the beginning, the string prefix "ORG=0004/"
The latter is convenient for checking for ORG compatibility using a command even non-ORG relay should understand.

===!x-orgversions===

This meta-command's purpose is to make it possible for the controller to have detailed informations on the protocol the relay supports. First the version of the ORG consolidated protocol, second the list of supported optional x-tensions, also with their version numbers.

'''Example:'''
C<->R
-> query,rUUID,!x-orgversions
<- query,cUUID,!x-orgversions,ORG=0004/who=002/email=006

'''Requirements:'''
* !x-orgversions should always be accepted with no Auth required, it does not open a session or Lock one.
* The acknowledgement value in a reply to !x-orgversions is a "/"-list of items of the form <package>=<version>. The first <package> is always "ORG" (representing the core specification package of ORG relays), its version string is the version of the specification (4 digits). The other packages are x-tension names, whose version string is 3 digits.
* If several incompatible versions of a same x-tension are supported, they must be listed ordered by version number. Ex: ORG=0004/who=002/email=005/email=006. If versions are backward compatible, only the last version should be reported.
* By announcing an x-tension, the relay commits itself to comply to all requirements of its specification.

'''Remarks:'''
* In a controller, it is however recommended to use !x-orgversions as soon as possible in order to avoid sending unsupported and useless metacommands later on.
* In the acknowledgement message, x-tension names are listed, not meta-command names (as one x-tension can have several meta-commands). Thus listed names do not include the prefix "!x-".
* x-tensions do not have to be standards defined by ORG but can also be proprietary. We recommend that the x-tension name then contains the name of the brand who proposes it.

===Other meta-commands===

Commands not listed here can belong to one of the following categories:
# (unlikely) commands from a future revision of Marine Kelley's original RLVR protocol.
# (more likely but not that much!) core commands from a future revision of ORG
# (very likely) commands from optional [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|x-tensions]]
# proprietary commands

ORG intends for its successive versions to be backward compatible. Therefore ORG relays handle all unknown meta-commands.

We also intend for future versions of ORG consolidated protocol to include last version of original RLVR protocol, hence the prefix "!x-" for all meta-commands comming from ORG, which ensures there will be reasonably no collision.

For the same reason, we require that proprietary commands use an obvious prefix such as "!a-" or "!b-", and so on. Not doing so would prevent ensuring backward compatibility, hence a relay or controller who would use proprietary commands with wrong prefixes are not ORG compliant.

LSL Protocol/Restrained Love Open Relay Group/ORG Requirements/0004 draft

2011-06-27T16:40:48Z

Satomi Ahn:

{{ORG_Restrained_Life_Relay_Specs_TOC}}
STATUS: draft

VERSION: 0004

'''Summary'''

This page lists requirements that make a RLV relay or a RLVR controller "ORG compliant".
Main advantages of an ORG compliant device over a classic RLVR devices are the following:
* ORG devices follow a stricter specification (while keeping compatibility), thus making the experience more predictible for scripters;
* ORG devices support wildcards for easy and low lag relay scanning and mass effects;
* ORG devices can support optional x-tensions for more fun. Supported x-tensions can easily be discovered thanks to [[#!x-orgversions|a new query meta-command]].

For a quick overview of the motivations and general working of the RLVR protocol and a few examples, we refer the reader to [[LSL_Protocol/Restrained_Love_Relay/Specification|the original RLVR specification]].

If you are making furniture, traps, or other RLVR controllers and you are not interested in what [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] can offer, then you can stick with the original RLVR specification and still be compatible with [[LSL_Protocol/Restrained_Love_Relay/Comparison|ORG relays]]. However, to have the right to call your controller "ORG compatible", there are still a few light additional requirements such as:
* using only [[llRegionSayTo]] for communications with the relay,
* not spamming the RLVR channel with messages that do not belong to the protocol,
* and remain responsive to ping messages at every time if you want the session to remain locked.

If you are interested in [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|ORG x-tensions]], then you should also read the part about [[#!x-orgversions|!x-orgversions]].

If you are making a relay, sorry we are afraid you will have to read all this page.

==Definition of an ORG device==

A RLVR device is compliant with ORG specifications if it implements the consolidated RLVR protocol and meta-commands described in sections below, along with the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] it announces supporting.

Remarks:
* An x-tension can constrain the core specification (this document) even more, but cannot alter its requirements or make them less constraining if not as a result of the relay executing a meta-command from this x-tension.
* Thus, although the protocol is extensible, a controller can always rely on the fact an ORG relay abides by the core requirements until the controller knowingly asks the relay to do otherwise.

If a device is ORG compliant, it may be advertised by the use of the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/ORG_Logo|ORG logo]]. ORG device makers are encouraged to do so.

==Consolidated RLVR protocol==
This consolidated RLVR protocol is roughly the same as [[LSL_Protocol/Restrained_Love_Relay/Specification|Marine Kelley's RLVR protocol version 1.100]], minus a few embarassing loose ends.

Main differences are highlighted at the beginning of each subsection.
=== Protocol Syntax ===
Summary of differences with original RLVR:
* we force use of llRegionSayTo,
* we explicitly forbid incorrect syntax on the relay channel
* the relay is supposed to ignore bad commands
* wildcards are supported

==== Definitions ====
* The '''Restrained Love Relay (RLVR) protocol''' implies two partners (SL objects): the '''relay''', attachment worn by the avatar commands are intended for, and a '''controller''', which sends commands to the relay.

* The goal of the protocol is to force the relay wearer to make perform actions and to toggle restrictions on their behavior. Both actions and restrictions can be enforced either through use of viewer hooks ([[LSL_Protocol/RestrainedLoveAPI|Restrained Love API]], or RLV) or through LSL scripting.

* Hence we distinguish between "'''RLV commands'''", starting with "@", which are commands following the syntax of the RLV API and which will ultimately be forwarded to the viewer, and "'''meta-commands'''", starting with "!", which are meant to be interpreted by LSL functions.

====Requirements====
RLVR protocol consists of messages exchanged between relay and controller
* on channel -1812221819 (called '''RLVR channel'''),
* using the LSL function [[llRegionSayTo]] (except for <c_msg>'s using a wildcard),
* all sent from the same prim of the controller or relay (within a [[#Protocol session|session]])
* and having the following syntax (non-terminal <c_msg> for controller messages/'''command messages''' and <r_msg> for relay messages/'''acknowledgement messages'''):

<c_msg> ::= IDENT "," KEY "," <commands>
<r_msg> ::= IDENT "," KEY "," <command> "," ACK
<commands> ::= <command> | <command> "|" <commands>
<command> ::= <rlvcommand> | <metacommand>
<rlvcommand> ::= "@" RLVCOMMAND
<metacommand> ::= "!" METACOMMANDNAME <metacommandarguments>
<metacommandarguments> ::= "" | "/" ARG <metacommandarguments>

where we explicit the different terminal tokens:
IDENT: any string without ","
KEY: any UUID
ACK: any string without ","
RLVCOMMAND: any string without ","
METACOMMANDNAME: any string without "/" and ","
ARG: any string without "/" and ","

* Relays can only send <r_msg>'s, and controllers <c_msg>'s. Nothing else is allowed on RLVR channel.
* In <c_msg>, KEY is always either the uuid of the relay wearer or ffffffff-ffff-ffff-ffff-ffffffffffff ('''wildcard''') if it is a message intended for all relays who can hear it.
* In <r_msg>, KEY is always the uuid of the controller.

====On the relay side only====
'''Further requirements:'''
*A relay MUST ignore any message on RLVR channel which is not a <c_msg> with KEY being either the key of the avatar wearing the relay or ffffffff-ffff-ffff-ffff-ffffffffffff.
Then, for every <command>:
* if <command> is neither a valid <rlvcommand> or <metacommand>, the relay must ignore it and process the next <command>'s;
* if <command> is a <rlvcommand> or a <metacommand>, the relay MUST send back to the controller a <r_msg> (see above) such that:
:*IDENT is the same as IDENT in the <c_msg> being processed,
:*<command> is the subcommand being processed
:*and ACK is a string called ''acknowledgement value''. By default the acknowledgement value is "ok" if the relay will execute the <command >, "ko" otherwise.

'''Remarks:'''
* Many meta-commands may have other acknowledgements than "ok" or "ko" (or none, for !pong). Their definitions supersede this specification.
* Note that unknown meta-commands cannot be executed and thus wil be acknowledged by "ko".
* Known meta-commands which are sent with not enough parameters or parameters with types incompatible with those in the definition known by the relay also cannot be executed and will also be acknowledged by "ko". (ex: the relay knows !x-who/key, but receives !x-who/integer/string).

===On executing commands===
Summary of differences with original RLVR:
* explanation on how to handle meta-commands with variable number of parameters,
* the relay knows commands in both core specification and x-tensions,
* clarification on multi-controller relays.

====Relay side====
'''Requirements:'''
* If a <rlvcommand> is acknowledged with value "ok", the relay ensures the viewer is affected the same way as if the LSL instruction llOwnerSay(<rlvcommand>) was executed by a script in a primitive that handles only one controller.
* When processing a <metacommand>, if the relay knows at least one definition of '!'+METACOMMANDNAME for which the received <metacommandarguments> provide enough parameters, then it will be handled according to the definition handling the most parameters among the latter. Extra parameters are ignored.
* A relays knows the following meta-command definitions:
:*[[#Core meta-commands and associated mechanisms|definitions listed in the core requirements]]
:*all definitions included in [[LSL_Protocol/Restrained_Love_Relay/Comparison|x-tensions]] announced by the relay.
* When acknowledging a <metacommand> by anything else than "ko", the relay commits itself to execute it.

'''Remarks:'''
* For first requirement, it must be understood that the reference behavior is that the relay would have if it had one controller per prim. However handling several controllers from one unique prim is possible but requires taking care that different controllers do not interfere with each other, releasing each other's restrictions, for instance.
* For the second requirement, the word "handled" means that if the meta-command with these parameters is known, then requirements in known definition cannot be ignored. Sometimes, this can imply that the meta-command cannot be refused, for instance.

====Controller side====
* The controller can send any command within allowed syntax.
* Only commands described in this specification and commands belonging to x-tensions announced by the relay are guaranteed to be understood by the relay. If not understood, the relay will just answer "ko", do nothing and skip to the next command.

===Protocol session===
Summary of differences with original RLVR:
* it is now clear when a session starts and stops (and what a session is!)
* it is clear when to expect interactive dialogs (and how to avoid spamming relay wearers with blue dialogs)
* no session for unreachable controllers (answer to ping is mandatory to ensure session persistence)

====Definitions====
* During an execution of the RLVR protocol, a relay and a controller establish a '''session''' together. A relay may manage several sessions with several controllers. Likewise, a controller could establish sessions with several relays.
* Restrictions on a relay wearer are relative to a session. So are most other variables (authorization state, key of the controller, ... ).
* A session is '''Opened''' whenever the relay accepts a RLVR command from a controller.
* A session is '''Closed''' (or '''released''') as soon as the relay forgets every variables and releases all restrictions pertaining to that session.
* A session is '''Locked''' whenever it holds active restrictions.
* A session is '''Authed''' if the controller has been allowed to control the relay (not only store some variables with no consequence). Once authed, no interactive "ask" dialog should pop up anymore concerning this session. Most commands should now normally be accepted (and maybe a few automatically rejected).
* A controller is called '''reachable''' if it can receive messages from the relay and can prove it by answering [[#ping/!pong|ping]] requests from the relay. By "can", it is meant by the method of communication agreed upon by the relay and controller (by default: chat messages sent on RLVR channel by llRegionSayTo). X-tensions such as email and delay can modify what is meant by reachable.

====Relay side requirements====
On closing sessions:
*Closing a session clears all RLV restrictions that belong only to that session, clears all session variables and disables all restrictions relative to that session. This MUST happen on the following events and no other:
:*on executing !release (received from the controller, or relay-triggered as in a safeword, see [[#!release]])
:*on noticing the controller is not reachable
:*on timeout, if the session is not Locked
*Sessions that are not locked MUST be closed after a reasonable timeout.

On interactive Auth:
*Unless specified otherwise (see !x-who), no command can trigger an interactive dialog unless the command requires an Authed session and the session is not already Authed.
*Relay implementations MAY require an authed session for all <rlvcommand>'s of the form @xxx=force, @xxx=add and @xxx=n, and for meta-commands whose specifications say it is allowed.
*Other RLV commands MUST automatically accepted or rejected by any relay.

On removing and adding restrictions:
* Commands that remove restrictions are always accepted (RLV @...=<channel_number>, @clear[=...] and @...=y/rem commands, !release, and !x-.../clear[/...] meta-commands).
* No restriction can be released unless as the result of one of the above commands, or of closing a session.
*@xxx=n/add <rlvcommand>'s, after being accepted, add a restriction and therefore Lock the session.
*Some meta-commands described in x-tensions can also add restrictions and therefore Lock the session.

Reachability:
*A relay MUST provide a mechanism for checking that every controlling device is reachable. It is not specified whether this checking process should be automatic or manually triggered.

====Controller side requirements====
* A controller MUST eventually close any Locked session using the meta-command !release.

In particular, non-portable controllers should not let a Locked relay wearer run free out of reach. Moreover, any controller should either react to some kind of event that is bound to happen (timer expiration being the most common) or provide a user interface for closing the session. It should be clear at least to the person who set the trap how the victim will be released.

==Core meta-commands and associated mechanisms==

An ORG device MUST at least support the meta-commands !release, !pong, !version, !implversion and !x-orgversions described below and implement their associated mechanisms.

Particular meta-commands definitions and mechanisms may override general requirements above.

New in ORG compared to RLVR: !x-orgversions

===!release===
Sent by a controller, this command closes the session.

* !release obviously opens no session, requires no Auth and is not Locking.
* If there is an actual session to close, !release MUST be accepted by the relay and acknowledeged by "ok".
* On accepting !release, the relay erases all data pertaining to the session and disables all restrictions of the session.
* When a relay decides to close a session on its own (user safeword, for instance) and it is not due to the controller being unreachable, the relay must send the following acknowledgement message:
release,<controller_key>,!release,ok

When receiving the latter message, the controller should act accordingly, for instance by resetting itself and making itself ready for the next session.

Note that !release is not the same as @clear. @clear is interpreted by the relay as a RLV command and, as such, can only clear RLV restrictions. If RLV restrictions were the only restrictions of the session, then the session will be closed, but some x-tensions also define pure LSL based restrictions.

===ping/!pong===

The ping/!pong mechanism exists so that relays can check presence and responsiveness of a controller. This was primarily meant to be used on relay wearer relog, in order to reactivate all restrictions so that sessions persist on relog if the controller still exists and is ready to continue the session.

''!pong'' cannot require auth and does not lock a session

We call ''ping message'' a message from the relay, having the following syntax:
ping,<controller_key>,ping,ping
We call ''!pong message'' a message from the controller, having the following syntax:
ping,<relay_key>,!pong

====Relay side====
*A relay SHOULD NOT send an acknowledgement in response to ''!pong''.
*A ping message can be sent any time by the relay to a known controller.
*On wearer relog, for each existing Locked session, the relay must send a ping message to the session controller.
*When a !pong message is received from a controller, if it was a reply to a previous ping message:
:#if the session RLV restrictions contain unsit and the avatar was sitting on some object when the restriction was applied, then the relay MUST force the avatar to sit back on the same object (if still existing);
:#the relay MUST make sure all restrictions belonging to the session are made active again.
*If a ping message is sent and is not answered by the controller, then the relay closes the session.

Note that the relay is responsible for storing restrictions and the key of the sit target across sessions, not the controller.

====Controller side====
*Unless it does not matter that the relay could close the session (or for another reason, the controller knows the relay will not close it), a controller SHOULD listen to ping messages and answer any ping message with a !pong message.
*A controller should ignore ping requests from relays it is not ready to handle.

Note controller don't have to poll for relay presence to resume a session but should just listen for ping messages instead. The relay should have stored all restrictions and handle sitting back to whatever furniture the relay wearer was tied up to.

Concerning the second bullet: for instance, if the controller is a furniture which is already in use by another relay wearer, it would be cause dysfunctions to let the pinging relay restore the restrictions without letting its wearer sit on the furniture. Or if the controller is not stateless and the state for the pinging relay has not been saved before, resuming the session from the initial state might be inconsistant.

===!version===
The purpose of this meta-command is to query the version of the RLVR protocol supported by a relay.

* !version opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !version with the version number of the RLVR protocol it supports ("1100" here, since ORG 0004 includes RLVR 1.100).

Note this is the most common command for a controller to scan for nearby relays, as non-ORG relays also accept this command and answer it the way described above.

===!implversion===
The purpose of this meta-command is to query the name and version of the relay implementation.

* !implversion opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !implversion with its implementation version string... which can be any string.

It is recommended this string includes the following elements:
* the relay name/brand/identifier,
* the version number of that relay name/brand/identifier,
* at the beginning, the string prefix "ORG=0004/"
The latter is convenient for checking for ORG compatibility using a command even non-ORG relay should understand.

===!x-orgversions===

This meta-command's purpose is to make it possible for the controller to have detailed informations on the protocol the relay supports. First the version of the ORG consolidated protocol, second the list of supported optional x-tensions, also with their version numbers.

'''Example:'''
C<->R
-> query,rUUID,!x-orgversions
<- query,cUUID,!x-orgversions,ORG=0004/who=002/email=006

'''Requirements:'''
* !x-orgversions should always be accepted with no Auth required, it does not open a session or Lock one.
* The acknowledgement value in a reply to !x-orgversions is a "/"-list of items of the form <package>=<version>. The first <package> is always "ORG" (representing the core specification package of ORG relays), its version string is the version of the specification (4 digits). The other packages are x-tension names, whose version string is 3 digits.
* If several incompatible versions of a same x-tension are supported, they must be listed ordered by version number. Ex: ORG=0004/who=002/email=005/email=006. If versions are backward compatible, only the last version should be reported.
* By announcing an x-tension, the relay commits itself to comply to all requirements of its specification.

'''Remarks:'''
* In a controller, it is however recommended to use !x-orgversions as soon as possible in order to avoid sending unsupported and useless metacommands later on.
* In the acknowledgement message, x-tension names are listed, not meta-command names (as one x-tension can have several meta-commands). Thus listed names do not include the prefix "!x-".
* x-tensions do not have to be standards defined by ORG but can also be proprietary. We recommend that the x-tension name then contains the name of the brand who proposes it.

===Other meta-commands===

Commands not listed here can belong to one of the following categories:
# (unlikely) commands from a future revision of Marine Kelley's original RLVR protocol.
# (more likely but not that much!) core commands from a future revision of ORG
# (very likely) commands from optional x-tensions
# proprietary commands

ORG intends for its successive versions to be backward compatible. Therefore ORG relays handle all unknown meta-commands.

We also intend for future versions of ORG consolidated protocol to include last version of original RLVR protocol, hence the prefix "!x-" for all meta-commands comming from ORG, which ensures there will be reasonably no collision.

For the same reason, we require that proprietary commands use an obvious prefix such as "!a-" or "!b-", and so on. Not doing so would prevent ensuring backward compatibility, hence a relay or controller who would use proprietary commands with wrong prefixes are not ORG compliant.

LSL Protocol/Restrained Love Open Relay Group/ORG Requirements/0004 draft

2011-06-27T16:38:19Z

Satomi Ahn: /* Definition of an ORG device */

{{ORG_Restrained_Life_Relay_Specs_TOC}}
STATUS: draft

VERSION: 0004

'''Summary'''

This page lists requirements that make a RLV relay or a RLVR controller "ORG compliant".
Main advantages of an ORG compliant device over a classic RLVR devices are the following:
* ORG devices follow a stricter specification (while keeping compatibility), thus making the experience more predictible for scripters;
* ORG devices support wildcards for easy and low lag relay scanning and mass effects;
* ORG devices can support optional x-tensions for more fun. Supported x-tensions can easily be discovered thanks to a new query meta-command.

For a quick overview of the motivations and general working of the RLVR protocol and a few examples, we refer the reader to [[LSL_Protocol/Restrained_Love_Relay/Specification|the original RLVR specification]].

If you are making furniture, traps, or other RLVR controllers and you are not interested in what [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] can offer, then you can stick with the original RLVR specification and still be compatible with [[LSL_Protocol/Restrained_Love_Relay/Comparison|ORG relays]]. However, to have the right to call your controller "ORG compatible", there are still a few light additional requirements such as:
* using only [[llRegionSayTo]] for communications with the relay,
* not spamming the RLVR channel with messages that do not belong to the protocol,
* and remain responsive to ping messages at every time if you want the session to remain locked.

If you are interested in [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|ORG x-tensions]], then you should also read the part about [[#!x-orgversions|!x-orgversions]].

If you are making a relay, sorry we are afraid you will have to read all this page.

==Definition of an ORG device==

A RLVR device is compliant with ORG specifications if it implements the consolidated RLVR protocol and meta-commands described in sections below, along with the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] it announces supporting.

Remarks:
* An x-tension can constrain the core specification (this document) even more, but cannot alter its requirements or make them less constraining if not as a result of the relay executing a meta-command from this x-tension.
* Thus, although the protocol is extensible, a controller can always rely on the fact an ORG relay abides by the core requirements until the controller knowingly asks the relay to do otherwise.

If a device is ORG compliant, it may be advertised by the use of the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/ORG_Logo|ORG logo]]. ORG device makers are encouraged to do so.

==Consolidated RLVR protocol==
This consolidated RLVR protocol is roughly the same as [[LSL_Protocol/Restrained_Love_Relay/Specification|Marine Kelley's RLVR protocol version 1.100]], minus a few embarassing loose ends.

Main differences are highlighted at the beginning of each subsection.
=== Protocol Syntax ===
Summary of differences with original RLVR:
* we force use of llRegionSayTo,
* we explicitly forbid incorrect syntax on the relay channel
* the relay is supposed to ignore bad commands
* wildcards are supported

==== Definitions ====
* The '''Restrained Love Relay (RLVR) protocol''' implies two partners (SL objects): the '''relay''', attachment worn by the avatar commands are intended for, and a '''controller''', which sends commands to the relay.

* The goal of the protocol is to force the relay wearer to make perform actions and to toggle restrictions on their behavior. Both actions and restrictions can be enforced either through use of viewer hooks ([[LSL_Protocol/RestrainedLoveAPI|Restrained Love API]], or RLV) or through LSL scripting.

* Hence we distinguish between "'''RLV commands'''", starting with "@", which are commands following the syntax of the RLV API and which will ultimately be forwarded to the viewer, and "'''meta-commands'''", starting with "!", which are meant to be interpreted by LSL functions.

====Requirements====
RLVR protocol consists of messages exchanged between relay and controller
* on channel -1812221819 (called '''RLVR channel'''),
* using the LSL function [[llRegionSayTo]] (except for <c_msg>'s using a wildcard),
* all sent from the same prim of the controller or relay (within a [[#Protocol session|session]])
* and having the following syntax (non-terminal <c_msg> for controller messages/'''command messages''' and <r_msg> for relay messages/'''acknowledgement messages'''):

<c_msg> ::= IDENT "," KEY "," <commands>
<r_msg> ::= IDENT "," KEY "," <command> "," ACK
<commands> ::= <command> | <command> "|" <commands>
<command> ::= <rlvcommand> | <metacommand>
<rlvcommand> ::= "@" RLVCOMMAND
<metacommand> ::= "!" METACOMMANDNAME <metacommandarguments>
<metacommandarguments> ::= "" | "/" ARG <metacommandarguments>

where we explicit the different terminal tokens:
IDENT: any string without ","
KEY: any UUID
ACK: any string without ","
RLVCOMMAND: any string without ","
METACOMMANDNAME: any string without "/" and ","
ARG: any string without "/" and ","

* Relays can only send <r_msg>'s, and controllers <c_msg>'s. Nothing else is allowed on RLVR channel.
* In <c_msg>, KEY is always either the uuid of the relay wearer or ffffffff-ffff-ffff-ffff-ffffffffffff ('''wildcard''') if it is a message intended for all relays who can hear it.
* In <r_msg>, KEY is always the uuid of the controller.

====On the relay side only====
'''Further requirements:'''
*A relay MUST ignore any message on RLVR channel which is not a <c_msg> with KEY being either the key of the avatar wearing the relay or ffffffff-ffff-ffff-ffff-ffffffffffff.
Then, for every <command>:
* if <command> is neither a valid <rlvcommand> or <metacommand>, the relay must ignore it and process the next <command>'s;
* if <command> is a <rlvcommand> or a <metacommand>, the relay MUST send back to the controller a <r_msg> (see above) such that:
:*IDENT is the same as IDENT in the <c_msg> being processed,
:*<command> is the subcommand being processed
:*and ACK is a string called ''acknowledgement value''. By default the acknowledgement value is "ok" if the relay will execute the <command >, "ko" otherwise.

'''Remarks:'''
* Many meta-commands may have other acknowledgements than "ok" or "ko" (or none, for !pong). Their definitions supersede this specification.
* Note that unknown meta-commands cannot be executed and thus wil be acknowledged by "ko".
* Known meta-commands which are sent with not enough parameters or parameters with types incompatible with those in the definition known by the relay also cannot be executed and will also be acknowledged by "ko". (ex: the relay knows !x-who/key, but receives !x-who/integer/string).

===On executing commands===
Summary of differences with original RLVR:
* explanation on how to handle meta-commands with variable number of parameters,
* the relay knows commands in both core specification and x-tensions,
* clarification on multi-controller relays.

====Relay side====
'''Requirements:'''
* If a <rlvcommand> is acknowledged with value "ok", the relay ensures the viewer is affected the same way as if the LSL instruction llOwnerSay(<rlvcommand>) was executed by a script in a primitive that handles only one controller.
* When processing a <metacommand>, if the relay knows at least one definition of '!'+METACOMMANDNAME for which the received <metacommandarguments> provide enough parameters, then it will be handled according to the definition handling the most parameters among the latter. Extra parameters are ignored.
* A relays knows the following meta-command definitions:
:*[[#Core meta-commands and associated mechanisms|definitions listed in the core requirements]]
:*all definitions included in [[LSL_Protocol/Restrained_Love_Relay/Comparison|x-tensions]] announced by the relay.
* When acknowledging a <metacommand> by anything else than "ko", the relay commits itself to execute it.

'''Remarks:'''
* For first requirement, it must be understood that the reference behavior is that the relay would have if it had one controller per prim. However handling several controllers from one unique prim is possible but requires taking care that different controllers do not interfere with each other, releasing each other's restrictions, for instance.
* For the second requirement, the word "handled" means that if the meta-command with these parameters is known, then requirements in known definition cannot be ignored. Sometimes, this can imply that the meta-command cannot be refused, for instance.

====Controller side====
* The controller can send any command within allowed syntax.
* Only commands described in this specification and commands belonging to x-tensions announced by the relay are guaranteed to be understood by the relay. If not understood, the relay will just answer "ko", do nothing and skip to the next command.

===Protocol session===
Summary of differences with original RLVR:
* it is now clear when a session starts and stops (and what a session is!)
* it is clear when to expect interactive dialogs (and how to avoid spamming relay wearers with blue dialogs)
* no session for unreachable controllers (answer to ping is mandatory to ensure session persistence)

====Definitions====
* During an execution of the RLVR protocol, a relay and a controller establish a '''session''' together. A relay may manage several sessions with several controllers. Likewise, a controller could establish sessions with several relays.
* Restrictions on a relay wearer are relative to a session. So are most other variables (authorization state, key of the controller, ... ).
* A session is '''Opened''' whenever the relay accepts a RLVR command from a controller.
* A session is '''Closed''' (or '''released''') as soon as the relay forgets every variables and releases all restrictions pertaining to that session.
* A session is '''Locked''' whenever it holds active restrictions.
* A session is '''Authed''' if the controller has been allowed to control the relay (not only store some variables with no consequence). Once authed, no interactive "ask" dialog should pop up anymore concerning this session. Most commands should now normally be accepted (and maybe a few automatically rejected).
* A controller is called '''reachable''' if it can receive messages from the relay and can prove it by answering [[#ping/!pong|ping]] requests from the relay. By "can", it is meant by the method of communication agreed upon by the relay and controller (by default: chat messages sent on RLVR channel by llRegionSayTo). X-tensions such as email and delay can modify what is meant by reachable.

====Relay side requirements====
On closing sessions:
*Closing a session clears all RLV restrictions that belong only to that session, clears all session variables and disables all restrictions relative to that session. This MUST happen on the following events and no other:
:*on executing !release (received from the controller, or relay-triggered as in a safeword, see [[#!release]])
:*on noticing the controller is not reachable
:*on timeout, if the session is not Locked
*Sessions that are not locked MUST be closed after a reasonable timeout.

On interactive Auth:
*Unless specified otherwise (see !x-who), no command can trigger an interactive dialog unless the command requires an Authed session and the session is not already Authed.
*Relay implementations MAY require an authed session for all <rlvcommand>'s of the form @xxx=force, @xxx=add and @xxx=n, and for meta-commands whose specifications say it is allowed.
*Other RLV commands MUST automatically accepted or rejected by any relay.

On removing and adding restrictions:
* Commands that remove restrictions are always accepted (RLV @...=<channel_number>, @clear[=...] and @...=y/rem commands, !release, and !x-.../clear[/...] meta-commands).
* No restriction can be released unless as the result of one of the above commands, or of closing a session.
*@xxx=n/add <rlvcommand>'s, after being accepted, add a restriction and therefore Lock the session.
*Some meta-commands described in x-tensions can also add restrictions and therefore Lock the session.

Reachability:
*A relay MUST provide a mechanism for checking that every controlling device is reachable. It is not specified whether this checking process should be automatic or manually triggered.

====Controller side requirements====
* A controller MUST eventually close any Locked session using the meta-command !release.

In particular, non-portable controllers should not let a Locked relay wearer run free out of reach. Moreover, any controller should either react to some kind of event that is bound to happen (timer expiration being the most common) or provide a user interface for closing the session. It should be clear at least to the person who set the trap how the victim will be released.

==Core meta-commands and associated mechanisms==

An ORG device MUST at least support the meta-commands !release, !pong, !version, !implversion and !x-orgversions described below and implement their associated mechanisms.

Particular meta-commands definitions and mechanisms may override general requirements above.

New in ORG compared to RLVR: !x-orgversions

===!release===
Sent by a controller, this command closes the session.

* !release obviously opens no session, requires no Auth and is not Locking.
* If there is an actual session to close, !release MUST be accepted by the relay and acknowledeged by "ok".
* On accepting !release, the relay erases all data pertaining to the session and disables all restrictions of the session.
* When a relay decides to close a session on its own (user safeword, for instance) and it is not due to the controller being unreachable, the relay must send the following acknowledgement message:
release,<controller_key>,!release,ok

When receiving the latter message, the controller should act accordingly, for instance by resetting itself and making itself ready for the next session.

Note that !release is not the same as @clear. @clear is interpreted by the relay as a RLV command and, as such, can only clear RLV restrictions. If RLV restrictions were the only restrictions of the session, then the session will be closed, but some x-tensions also define pure LSL based restrictions.

===ping/!pong===

The ping/!pong mechanism exists so that relays can check presence and responsiveness of a controller. This was primarily meant to be used on relay wearer relog, in order to reactivate all restrictions so that sessions persist on relog if the controller still exists and is ready to continue the session.

''!pong'' cannot require auth and does not lock a session

We call ''ping message'' a message from the relay, having the following syntax:
ping,<controller_key>,ping,ping
We call ''!pong message'' a message from the controller, having the following syntax:
ping,<relay_key>,!pong

====Relay side====
*A relay SHOULD NOT send an acknowledgement in response to ''!pong''.
*A ping message can be sent any time by the relay to a known controller.
*On wearer relog, for each existing Locked session, the relay must send a ping message to the session controller.
*When a !pong message is received from a controller, if it was a reply to a previous ping message:
:#if the session RLV restrictions contain unsit and the avatar was sitting on some object when the restriction was applied, then the relay MUST force the avatar to sit back on the same object (if still existing);
:#the relay MUST make sure all restrictions belonging to the session are made active again.
*If a ping message is sent and is not answered by the controller, then the relay closes the session.

Note that the relay is responsible for storing restrictions and the key of the sit target across sessions, not the controller.

====Controller side====
*Unless it does not matter that the relay could close the session (or for another reason, the controller knows the relay will not close it), a controller SHOULD listen to ping messages and answer any ping message with a !pong message.
*A controller should ignore ping requests from relays it is not ready to handle.

Note controller don't have to poll for relay presence to resume a session but should just listen for ping messages instead. The relay should have stored all restrictions and handle sitting back to whatever furniture the relay wearer was tied up to.

Concerning the second bullet: for instance, if the controller is a furniture which is already in use by another relay wearer, it would be cause dysfunctions to let the pinging relay restore the restrictions without letting its wearer sit on the furniture. Or if the controller is not stateless and the state for the pinging relay has not been saved before, resuming the session from the initial state might be inconsistant.

===!version===
The purpose of this meta-command is to query the version of the RLVR protocol supported by a relay.

* !version opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !version with the version number of the RLVR protocol it supports ("1100" here, since ORG 0004 includes RLVR 1.100).

Note this is the most common command for a controller to scan for nearby relays, as non-ORG relays also accept this command and answer it the way described above.

===!implversion===
The purpose of this meta-command is to query the name and version of the relay implementation.

* !implversion opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !implversion with its implementation version string... which can be any string.

It is recommended this string includes the following elements:
* the relay name/brand/identifier,
* the version number of that relay name/brand/identifier,
* at the beginning, the string prefix "ORG=0004/"
The latter is convenient for checking for ORG compatibility using a command even non-ORG relay should understand.

===!x-orgversions===

This meta-command's purpose is to make it possible for the controller to have detailed informations on the protocol the relay supports. First the version of the ORG consolidated protocol, second the list of supported optional x-tensions, also with their version numbers.

'''Example:'''
C<->R
-> query,rUUID,!x-orgversions
<- query,cUUID,!x-orgversions,ORG=0004/who=002/email=006

'''Requirements:'''
* !x-orgversions should always be accepted with no Auth required, it does not open a session or Lock one.
* The acknowledgement value in a reply to !x-orgversions is a "/"-list of items of the form <package>=<version>. The first <package> is always "ORG" (representing the core specification package of ORG relays), its version string is the version of the specification (4 digits). The other packages are x-tension names, whose version string is 3 digits.
* If several incompatible versions of a same x-tension are supported, they must be listed ordered by version number. Ex: ORG=0004/who=002/email=005/email=006. If versions are backward compatible, only the last version should be reported.
* By announcing an x-tension, the relay commits itself to comply to all requirements of its specification.

'''Remarks:'''
* In a controller, it is however recommended to use !x-orgversions as soon as possible in order to avoid sending unsupported and useless metacommands later on.
* In the acknowledgement message, x-tension names are listed, not meta-command names (as one x-tension can have several meta-commands). Thus listed names do not include the prefix "!x-".
* x-tensions do not have to be standards defined by ORG but can also be proprietary. We recommend that the x-tension name then contains the name of the brand who proposes it.

===Other meta-commands===

Commands not listed here can belong to one of the following categories:
# (unlikely) commands from a future revision of Marine Kelley's original RLVR protocol.
# (more likely but not that much!) core commands from a future revision of ORG
# (very likely) commands from optional x-tensions
# proprietary commands

ORG intends for its successive versions to be backward compatible. Therefore ORG relays handle all unknown meta-commands.

We also intend for future versions of ORG consolidated protocol to include last version of original RLVR protocol, hence the prefix "!x-" for all meta-commands comming from ORG, which ensures there will be reasonably no collision.

For the same reason, we require that proprietary commands use an obvious prefix such as "!a-" or "!b-", and so on. Not doing so would prevent ensuring backward compatibility, hence a relay or controller who would use proprietary commands with wrong prefixes are not ORG compliant.

LSL Protocol/Restrained Love Open Relay Group/ORG Requirements/0004 draft

2011-06-27T16:35:37Z

Satomi Ahn:

{{ORG_Restrained_Life_Relay_Specs_TOC}}
STATUS: draft

VERSION: 0004

'''Summary'''

This page lists requirements that make a RLV relay or a RLVR controller "ORG compliant".
Main advantages of an ORG compliant device over a classic RLVR devices are the following:
* ORG devices follow a stricter specification (while keeping compatibility), thus making the experience more predictible for scripters;
* ORG devices support wildcards for easy and low lag relay scanning and mass effects;
* ORG devices can support optional x-tensions for more fun. Supported x-tensions can easily be discovered thanks to a new query meta-command.

For a quick overview of the motivations and general working of the RLVR protocol and a few examples, we refer the reader to [[LSL_Protocol/Restrained_Love_Relay/Specification|the original RLVR specification]].

If you are making furniture, traps, or other RLVR controllers and you are not interested in what [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] can offer, then you can stick with the original RLVR specification and still be compatible with [[LSL_Protocol/Restrained_Love_Relay/Comparison|ORG relays]]. However, to have the right to call your controller "ORG compatible", there are still a few light additional requirements such as:
* using only [[llRegionSayTo]] for communications with the relay,
* not spamming the RLVR channel with messages that do not belong to the protocol,
* and remain responsive to ping messages at every time if you want the session to remain locked.

If you are interested in [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|ORG x-tensions]], then you should also read the part about [[#!x-orgversions|!x-orgversions]].

If you are making a relay, sorry we are afraid you will have to read all this page.

==Definition of an ORG device==

A RLVR device is compliant with ORG specifications if it implements the consolidated RLVR protocol and meta-commands described in sections below, along with the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] it announces supporting.

Remarks:
* Supported x-tensions can constrain the core specification (this document) even more, but cannot alter its requirements or make them less constraining if not as a result of the relay executing a meta-command of this x-tension sent by the controller.
* Thus, although the protocol is extensible, a controller can always rely on the fact an ORG relay abides by the requirements in this document until the controller knowingly asks the relay to do otherwise.

If a device is ORG compliant, it may be advertised by the use of the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/ORG_Logo|ORG logo]]. ORG device makers are encouraged to do so.

==Consolidated RLVR protocol==
This consolidated RLVR protocol is roughly the same as [[LSL_Protocol/Restrained_Love_Relay/Specification|Marine Kelley's RLVR protocol version 1.100]], minus a few embarassing loose ends.

Main differences are highlighted at the beginning of each subsection.
=== Protocol Syntax ===
Summary of differences with original RLVR:
* we force use of llRegionSayTo,
* we explicitly forbid incorrect syntax on the relay channel
* the relay is supposed to ignore bad commands
* wildcards are supported

==== Definitions ====
* The '''Restrained Love Relay (RLVR) protocol''' implies two partners (SL objects): the '''relay''', attachment worn by the avatar commands are intended for, and a '''controller''', which sends commands to the relay.

* The goal of the protocol is to force the relay wearer to make perform actions and to toggle restrictions on their behavior. Both actions and restrictions can be enforced either through use of viewer hooks ([[LSL_Protocol/RestrainedLoveAPI|Restrained Love API]], or RLV) or through LSL scripting.

* Hence we distinguish between "'''RLV commands'''", starting with "@", which are commands following the syntax of the RLV API and which will ultimately be forwarded to the viewer, and "'''meta-commands'''", starting with "!", which are meant to be interpreted by LSL functions.

====Requirements====
RLVR protocol consists of messages exchanged between relay and controller
* on channel -1812221819 (called '''RLVR channel'''),
* using the LSL function [[llRegionSayTo]] (except for <c_msg>'s using a wildcard),
* all sent from the same prim of the controller or relay (within a [[#Protocol session|session]])
* and having the following syntax (non-terminal <c_msg> for controller messages/'''command messages''' and <r_msg> for relay messages/'''acknowledgement messages'''):

<c_msg> ::= IDENT "," KEY "," <commands>
<r_msg> ::= IDENT "," KEY "," <command> "," ACK
<commands> ::= <command> | <command> "|" <commands>
<command> ::= <rlvcommand> | <metacommand>
<rlvcommand> ::= "@" RLVCOMMAND
<metacommand> ::= "!" METACOMMANDNAME <metacommandarguments>
<metacommandarguments> ::= "" | "/" ARG <metacommandarguments>

where we explicit the different terminal tokens:
IDENT: any string without ","
KEY: any UUID
ACK: any string without ","
RLVCOMMAND: any string without ","
METACOMMANDNAME: any string without "/" and ","
ARG: any string without "/" and ","

* Relays can only send <r_msg>'s, and controllers <c_msg>'s. Nothing else is allowed on RLVR channel.
* In <c_msg>, KEY is always either the uuid of the relay wearer or ffffffff-ffff-ffff-ffff-ffffffffffff ('''wildcard''') if it is a message intended for all relays who can hear it.
* In <r_msg>, KEY is always the uuid of the controller.

====On the relay side only====
'''Further requirements:'''
*A relay MUST ignore any message on RLVR channel which is not a <c_msg> with KEY being either the key of the avatar wearing the relay or ffffffff-ffff-ffff-ffff-ffffffffffff.
Then, for every <command>:
* if <command> is neither a valid <rlvcommand> or <metacommand>, the relay must ignore it and process the next <command>'s;
* if <command> is a <rlvcommand> or a <metacommand>, the relay MUST send back to the controller a <r_msg> (see above) such that:
:*IDENT is the same as IDENT in the <c_msg> being processed,
:*<command> is the subcommand being processed
:*and ACK is a string called ''acknowledgement value''. By default the acknowledgement value is "ok" if the relay will execute the <command >, "ko" otherwise.

'''Remarks:'''
* Many meta-commands may have other acknowledgements than "ok" or "ko" (or none, for !pong). Their definitions supersede this specification.
* Note that unknown meta-commands cannot be executed and thus wil be acknowledged by "ko".
* Known meta-commands which are sent with not enough parameters or parameters with types incompatible with those in the definition known by the relay also cannot be executed and will also be acknowledged by "ko". (ex: the relay knows !x-who/key, but receives !x-who/integer/string).

===On executing commands===
Summary of differences with original RLVR:
* explanation on how to handle meta-commands with variable number of parameters,
* the relay knows commands in both core specification and x-tensions,
* clarification on multi-controller relays.

====Relay side====
'''Requirements:'''
* If a <rlvcommand> is acknowledged with value "ok", the relay ensures the viewer is affected the same way as if the LSL instruction llOwnerSay(<rlvcommand>) was executed by a script in a primitive that handles only one controller.
* When processing a <metacommand>, if the relay knows at least one definition of '!'+METACOMMANDNAME for which the received <metacommandarguments> provide enough parameters, then it will be handled according to the definition handling the most parameters among the latter. Extra parameters are ignored.
* A relays knows the following meta-command definitions:
:*[[#Core meta-commands and associated mechanisms|definitions listed in the core requirements]]
:*all definitions included in [[LSL_Protocol/Restrained_Love_Relay/Comparison|x-tensions]] announced by the relay.
* When acknowledging a <metacommand> by anything else than "ko", the relay commits itself to execute it.

'''Remarks:'''
* For first requirement, it must be understood that the reference behavior is that the relay would have if it had one controller per prim. However handling several controllers from one unique prim is possible but requires taking care that different controllers do not interfere with each other, releasing each other's restrictions, for instance.
* For the second requirement, the word "handled" means that if the meta-command with these parameters is known, then requirements in known definition cannot be ignored. Sometimes, this can imply that the meta-command cannot be refused, for instance.

====Controller side====
* The controller can send any command within allowed syntax.
* Only commands described in this specification and commands belonging to x-tensions announced by the relay are guaranteed to be understood by the relay. If not understood, the relay will just answer "ko", do nothing and skip to the next command.

===Protocol session===
Summary of differences with original RLVR:
* it is now clear when a session starts and stops (and what a session is!)
* it is clear when to expect interactive dialogs (and how to avoid spamming relay wearers with blue dialogs)
* no session for unreachable controllers (answer to ping is mandatory to ensure session persistence)

====Definitions====
* During an execution of the RLVR protocol, a relay and a controller establish a '''session''' together. A relay may manage several sessions with several controllers. Likewise, a controller could establish sessions with several relays.
* Restrictions on a relay wearer are relative to a session. So are most other variables (authorization state, key of the controller, ... ).
* A session is '''Opened''' whenever the relay accepts a RLVR command from a controller.
* A session is '''Closed''' (or '''released''') as soon as the relay forgets every variables and releases all restrictions pertaining to that session.
* A session is '''Locked''' whenever it holds active restrictions.
* A session is '''Authed''' if the controller has been allowed to control the relay (not only store some variables with no consequence). Once authed, no interactive "ask" dialog should pop up anymore concerning this session. Most commands should now normally be accepted (and maybe a few automatically rejected).
* A controller is called '''reachable''' if it can receive messages from the relay and can prove it by answering [[#ping/!pong|ping]] requests from the relay. By "can", it is meant by the method of communication agreed upon by the relay and controller (by default: chat messages sent on RLVR channel by llRegionSayTo). X-tensions such as email and delay can modify what is meant by reachable.

====Relay side requirements====
On closing sessions:
*Closing a session clears all RLV restrictions that belong only to that session, clears all session variables and disables all restrictions relative to that session. This MUST happen on the following events and no other:
:*on executing !release (received from the controller, or relay-triggered as in a safeword, see [[#!release]])
:*on noticing the controller is not reachable
:*on timeout, if the session is not Locked
*Sessions that are not locked MUST be closed after a reasonable timeout.

On interactive Auth:
*Unless specified otherwise (see !x-who), no command can trigger an interactive dialog unless the command requires an Authed session and the session is not already Authed.
*Relay implementations MAY require an authed session for all <rlvcommand>'s of the form @xxx=force, @xxx=add and @xxx=n, and for meta-commands whose specifications say it is allowed.
*Other RLV commands MUST automatically accepted or rejected by any relay.

On removing and adding restrictions:
* Commands that remove restrictions are always accepted (RLV @...=<channel_number>, @clear[=...] and @...=y/rem commands, !release, and !x-.../clear[/...] meta-commands).
* No restriction can be released unless as the result of one of the above commands, or of closing a session.
*@xxx=n/add <rlvcommand>'s, after being accepted, add a restriction and therefore Lock the session.
*Some meta-commands described in x-tensions can also add restrictions and therefore Lock the session.

Reachability:
*A relay MUST provide a mechanism for checking that every controlling device is reachable. It is not specified whether this checking process should be automatic or manually triggered.

====Controller side requirements====
* A controller MUST eventually close any Locked session using the meta-command !release.

In particular, non-portable controllers should not let a Locked relay wearer run free out of reach. Moreover, any controller should either react to some kind of event that is bound to happen (timer expiration being the most common) or provide a user interface for closing the session. It should be clear at least to the person who set the trap how the victim will be released.

==Core meta-commands and associated mechanisms==

An ORG device MUST at least support the meta-commands !release, !pong, !version, !implversion and !x-orgversions described below and implement their associated mechanisms.

Particular meta-commands definitions and mechanisms may override general requirements above.

New in ORG compared to RLVR: !x-orgversions

===!release===
Sent by a controller, this command closes the session.

* !release obviously opens no session, requires no Auth and is not Locking.
* If there is an actual session to close, !release MUST be accepted by the relay and acknowledeged by "ok".
* On accepting !release, the relay erases all data pertaining to the session and disables all restrictions of the session.
* When a relay decides to close a session on its own (user safeword, for instance) and it is not due to the controller being unreachable, the relay must send the following acknowledgement message:
release,<controller_key>,!release,ok

When receiving the latter message, the controller should act accordingly, for instance by resetting itself and making itself ready for the next session.

Note that !release is not the same as @clear. @clear is interpreted by the relay as a RLV command and, as such, can only clear RLV restrictions. If RLV restrictions were the only restrictions of the session, then the session will be closed, but some x-tensions also define pure LSL based restrictions.

===ping/!pong===

The ping/!pong mechanism exists so that relays can check presence and responsiveness of a controller. This was primarily meant to be used on relay wearer relog, in order to reactivate all restrictions so that sessions persist on relog if the controller still exists and is ready to continue the session.

''!pong'' cannot require auth and does not lock a session

We call ''ping message'' a message from the relay, having the following syntax:
ping,<controller_key>,ping,ping
We call ''!pong message'' a message from the controller, having the following syntax:
ping,<relay_key>,!pong

====Relay side====
*A relay SHOULD NOT send an acknowledgement in response to ''!pong''.
*A ping message can be sent any time by the relay to a known controller.
*On wearer relog, for each existing Locked session, the relay must send a ping message to the session controller.
*When a !pong message is received from a controller, if it was a reply to a previous ping message:
:#if the session RLV restrictions contain unsit and the avatar was sitting on some object when the restriction was applied, then the relay MUST force the avatar to sit back on the same object (if still existing);
:#the relay MUST make sure all restrictions belonging to the session are made active again.
*If a ping message is sent and is not answered by the controller, then the relay closes the session.

Note that the relay is responsible for storing restrictions and the key of the sit target across sessions, not the controller.

====Controller side====
*Unless it does not matter that the relay could close the session (or for another reason, the controller knows the relay will not close it), a controller SHOULD listen to ping messages and answer any ping message with a !pong message.
*A controller should ignore ping requests from relays it is not ready to handle.

Note controller don't have to poll for relay presence to resume a session but should just listen for ping messages instead. The relay should have stored all restrictions and handle sitting back to whatever furniture the relay wearer was tied up to.

Concerning the second bullet: for instance, if the controller is a furniture which is already in use by another relay wearer, it would be cause dysfunctions to let the pinging relay restore the restrictions without letting its wearer sit on the furniture. Or if the controller is not stateless and the state for the pinging relay has not been saved before, resuming the session from the initial state might be inconsistant.

===!version===
The purpose of this meta-command is to query the version of the RLVR protocol supported by a relay.

* !version opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !version with the version number of the RLVR protocol it supports ("1100" here, since ORG 0004 includes RLVR 1.100).

Note this is the most common command for a controller to scan for nearby relays, as non-ORG relays also accept this command and answer it the way described above.

===!implversion===
The purpose of this meta-command is to query the name and version of the relay implementation.

* !implversion opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !implversion with its implementation version string... which can be any string.

It is recommended this string includes the following elements:
* the relay name/brand/identifier,
* the version number of that relay name/brand/identifier,
* at the beginning, the string prefix "ORG=0004/"
The latter is convenient for checking for ORG compatibility using a command even non-ORG relay should understand.

===!x-orgversions===

This meta-command's purpose is to make it possible for the controller to have detailed informations on the protocol the relay supports. First the version of the ORG consolidated protocol, second the list of supported optional x-tensions, also with their version numbers.

'''Example:'''
C<->R
-> query,rUUID,!x-orgversions
<- query,cUUID,!x-orgversions,ORG=0004/who=002/email=006

'''Requirements:'''
* !x-orgversions should always be accepted with no Auth required, it does not open a session or Lock one.
* The acknowledgement value in a reply to !x-orgversions is a "/"-list of items of the form <package>=<version>. The first <package> is always "ORG" (representing the core specification package of ORG relays), its version string is the version of the specification (4 digits). The other packages are x-tension names, whose version string is 3 digits.
* If several incompatible versions of a same x-tension are supported, they must be listed ordered by version number. Ex: ORG=0004/who=002/email=005/email=006. If versions are backward compatible, only the last version should be reported.
* By announcing an x-tension, the relay commits itself to comply to all requirements of its specification.

'''Remarks:'''
* In a controller, it is however recommended to use !x-orgversions as soon as possible in order to avoid sending unsupported and useless metacommands later on.
* In the acknowledgement message, x-tension names are listed, not meta-command names (as one x-tension can have several meta-commands). Thus listed names do not include the prefix "!x-".
* x-tensions do not have to be standards defined by ORG but can also be proprietary. We recommend that the x-tension name then contains the name of the brand who proposes it.

===Other meta-commands===

Commands not listed here can belong to one of the following categories:
# (unlikely) commands from a future revision of Marine Kelley's original RLVR protocol.
# (more likely but not that much!) core commands from a future revision of ORG
# (very likely) commands from optional x-tensions
# proprietary commands

ORG intends for its successive versions to be backward compatible. Therefore ORG relays handle all unknown meta-commands.

We also intend for future versions of ORG consolidated protocol to include last version of original RLVR protocol, hence the prefix "!x-" for all meta-commands comming from ORG, which ensures there will be reasonably no collision.

For the same reason, we require that proprietary commands use an obvious prefix such as "!a-" or "!b-", and so on. Not doing so would prevent ensuring backward compatibility, hence a relay or controller who would use proprietary commands with wrong prefixes are not ORG compliant.

LSL Protocol/Restrained Love Open Relay Group/ORG Requirements/0004 draft

2011-06-27T16:35:02Z

Satomi Ahn:

{{ORG_Restrained_Life_Relay_Specs_TOC}}
STATUS: draft

VERSION: 0004

'''Summary'''

This page lists requirements that make a RLV relay or a RLVR controller "ORG compliant".
Main advantages of an ORG compliant device over a classic RLVR devices are the following:
* ORG devices follow a stricter specification (while keeping compatibility), thus making the experience more predictible for scripters;
* ORG devices support wildcards for easy and low lag mass effects;
* ORG devices can support optional x-tensions for more fun. Supported x-tensions can easily be discovered thanks to a new query meta-command.

For a quick overview of the motivations and general working of the RLVR protocol and a few examples, we refer the reader to [[LSL_Protocol/Restrained_Love_Relay/Specification|the original RLVR specification]].

If you are making furniture, traps, or other RLVR controllers and you are not interested in what [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] can offer, then you can stick with the original RLVR specification and still be compatible with [[LSL_Protocol/Restrained_Love_Relay/Comparison|ORG relays]]. However, to have the right to call your controller "ORG compatible", there are still a few light additional requirements such as:
* using only [[llRegionSayTo]] for communications with the relay,
* not spamming the RLVR channel with messages that do not belong to the protocol,
* and remain responsive to ping messages at every time if you want the session to remain locked.

If you are interested in [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|ORG x-tensions]], then you should also read the part about [[#!x-orgversions|!x-orgversions]].

If you are making a relay, sorry we are afraid you will have to read all this page.

==Definition of an ORG device==

A RLVR device is compliant with ORG specifications if it implements the consolidated RLVR protocol and meta-commands described in sections below, along with the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] it announces supporting.

Remarks:
* Supported x-tensions can constrain the core specification (this document) even more, but cannot alter its requirements or make them less constraining if not as a result of the relay executing a meta-command of this x-tension sent by the controller.
* Thus, although the protocol is extensible, a controller can always rely on the fact an ORG relay abides by the requirements in this document until the controller knowingly asks the relay to do otherwise.

If a device is ORG compliant, it may be advertised by the use of the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/ORG_Logo|ORG logo]]. ORG device makers are encouraged to do so.

==Consolidated RLVR protocol==
This consolidated RLVR protocol is roughly the same as [[LSL_Protocol/Restrained_Love_Relay/Specification|Marine Kelley's RLVR protocol version 1.100]], minus a few embarassing loose ends.

Main differences are highlighted at the beginning of each subsection.
=== Protocol Syntax ===
Summary of differences with original RLVR:
* we force use of llRegionSayTo,
* we explicitly forbid incorrect syntax on the relay channel
* the relay is supposed to ignore bad commands
* wildcards are supported

==== Definitions ====
* The '''Restrained Love Relay (RLVR) protocol''' implies two partners (SL objects): the '''relay''', attachment worn by the avatar commands are intended for, and a '''controller''', which sends commands to the relay.

* The goal of the protocol is to force the relay wearer to make perform actions and to toggle restrictions on their behavior. Both actions and restrictions can be enforced either through use of viewer hooks ([[LSL_Protocol/RestrainedLoveAPI|Restrained Love API]], or RLV) or through LSL scripting.

* Hence we distinguish between "'''RLV commands'''", starting with "@", which are commands following the syntax of the RLV API and which will ultimately be forwarded to the viewer, and "'''meta-commands'''", starting with "!", which are meant to be interpreted by LSL functions.

====Requirements====
RLVR protocol consists of messages exchanged between relay and controller
* on channel -1812221819 (called '''RLVR channel'''),
* using the LSL function [[llRegionSayTo]] (except for <c_msg>'s using a wildcard),
* all sent from the same prim of the controller or relay (within a [[#Protocol session|session]])
* and having the following syntax (non-terminal <c_msg> for controller messages/'''command messages''' and <r_msg> for relay messages/'''acknowledgement messages'''):

<c_msg> ::= IDENT "," KEY "," <commands>
<r_msg> ::= IDENT "," KEY "," <command> "," ACK
<commands> ::= <command> | <command> "|" <commands>
<command> ::= <rlvcommand> | <metacommand>
<rlvcommand> ::= "@" RLVCOMMAND
<metacommand> ::= "!" METACOMMANDNAME <metacommandarguments>
<metacommandarguments> ::= "" | "/" ARG <metacommandarguments>

where we explicit the different terminal tokens:
IDENT: any string without ","
KEY: any UUID
ACK: any string without ","
RLVCOMMAND: any string without ","
METACOMMANDNAME: any string without "/" and ","
ARG: any string without "/" and ","

* Relays can only send <r_msg>'s, and controllers <c_msg>'s. Nothing else is allowed on RLVR channel.
* In <c_msg>, KEY is always either the uuid of the relay wearer or ffffffff-ffff-ffff-ffff-ffffffffffff ('''wildcard''') if it is a message intended for all relays who can hear it.
* In <r_msg>, KEY is always the uuid of the controller.

====On the relay side only====
'''Further requirements:'''
*A relay MUST ignore any message on RLVR channel which is not a <c_msg> with KEY being either the key of the avatar wearing the relay or ffffffff-ffff-ffff-ffff-ffffffffffff.
Then, for every <command>:
* if <command> is neither a valid <rlvcommand> or <metacommand>, the relay must ignore it and process the next <command>'s;
* if <command> is a <rlvcommand> or a <metacommand>, the relay MUST send back to the controller a <r_msg> (see above) such that:
:*IDENT is the same as IDENT in the <c_msg> being processed,
:*<command> is the subcommand being processed
:*and ACK is a string called ''acknowledgement value''. By default the acknowledgement value is "ok" if the relay will execute the <command >, "ko" otherwise.

'''Remarks:'''
* Many meta-commands may have other acknowledgements than "ok" or "ko" (or none, for !pong). Their definitions supersede this specification.
* Note that unknown meta-commands cannot be executed and thus wil be acknowledged by "ko".
* Known meta-commands which are sent with not enough parameters or parameters with types incompatible with those in the definition known by the relay also cannot be executed and will also be acknowledged by "ko". (ex: the relay knows !x-who/key, but receives !x-who/integer/string).

===On executing commands===
Summary of differences with original RLVR:
* explanation on how to handle meta-commands with variable number of parameters,
* the relay knows commands in both core specification and x-tensions,
* clarification on multi-controller relays.

====Relay side====
'''Requirements:'''
* If a <rlvcommand> is acknowledged with value "ok", the relay ensures the viewer is affected the same way as if the LSL instruction llOwnerSay(<rlvcommand>) was executed by a script in a primitive that handles only one controller.
* When processing a <metacommand>, if the relay knows at least one definition of '!'+METACOMMANDNAME for which the received <metacommandarguments> provide enough parameters, then it will be handled according to the definition handling the most parameters among the latter. Extra parameters are ignored.
* A relays knows the following meta-command definitions:
:*[[#Core meta-commands and associated mechanisms|definitions listed in the core requirements]]
:*all definitions included in [[LSL_Protocol/Restrained_Love_Relay/Comparison|x-tensions]] announced by the relay.
* When acknowledging a <metacommand> by anything else than "ko", the relay commits itself to execute it.

'''Remarks:'''
* For first requirement, it must be understood that the reference behavior is that the relay would have if it had one controller per prim. However handling several controllers from one unique prim is possible but requires taking care that different controllers do not interfere with each other, releasing each other's restrictions, for instance.
* For the second requirement, the word "handled" means that if the meta-command with these parameters is known, then requirements in known definition cannot be ignored. Sometimes, this can imply that the meta-command cannot be refused, for instance.

====Controller side====
* The controller can send any command within allowed syntax.
* Only commands described in this specification and commands belonging to x-tensions announced by the relay are guaranteed to be understood by the relay. If not understood, the relay will just answer "ko", do nothing and skip to the next command.

===Protocol session===
Summary of differences with original RLVR:
* it is now clear when a session starts and stops (and what a session is!)
* it is clear when to expect interactive dialogs (and how to avoid spamming relay wearers with blue dialogs)
* no session for unreachable controllers (answer to ping is mandatory to ensure session persistence)

====Definitions====
* During an execution of the RLVR protocol, a relay and a controller establish a '''session''' together. A relay may manage several sessions with several controllers. Likewise, a controller could establish sessions with several relays.
* Restrictions on a relay wearer are relative to a session. So are most other variables (authorization state, key of the controller, ... ).
* A session is '''Opened''' whenever the relay accepts a RLVR command from a controller.
* A session is '''Closed''' (or '''released''') as soon as the relay forgets every variables and releases all restrictions pertaining to that session.
* A session is '''Locked''' whenever it holds active restrictions.
* A session is '''Authed''' if the controller has been allowed to control the relay (not only store some variables with no consequence). Once authed, no interactive "ask" dialog should pop up anymore concerning this session. Most commands should now normally be accepted (and maybe a few automatically rejected).
* A controller is called '''reachable''' if it can receive messages from the relay and can prove it by answering [[#ping/!pong|ping]] requests from the relay. By "can", it is meant by the method of communication agreed upon by the relay and controller (by default: chat messages sent on RLVR channel by llRegionSayTo). X-tensions such as email and delay can modify what is meant by reachable.

====Relay side requirements====
On closing sessions:
*Closing a session clears all RLV restrictions that belong only to that session, clears all session variables and disables all restrictions relative to that session. This MUST happen on the following events and no other:
:*on executing !release (received from the controller, or relay-triggered as in a safeword, see [[#!release]])
:*on noticing the controller is not reachable
:*on timeout, if the session is not Locked
*Sessions that are not locked MUST be closed after a reasonable timeout.

On interactive Auth:
*Unless specified otherwise (see !x-who), no command can trigger an interactive dialog unless the command requires an Authed session and the session is not already Authed.
*Relay implementations MAY require an authed session for all <rlvcommand>'s of the form @xxx=force, @xxx=add and @xxx=n, and for meta-commands whose specifications say it is allowed.
*Other RLV commands MUST automatically accepted or rejected by any relay.

On removing and adding restrictions:
* Commands that remove restrictions are always accepted (RLV @...=<channel_number>, @clear[=...] and @...=y/rem commands, !release, and !x-.../clear[/...] meta-commands).
* No restriction can be released unless as the result of one of the above commands, or of closing a session.
*@xxx=n/add <rlvcommand>'s, after being accepted, add a restriction and therefore Lock the session.
*Some meta-commands described in x-tensions can also add restrictions and therefore Lock the session.

Reachability:
*A relay MUST provide a mechanism for checking that every controlling device is reachable. It is not specified whether this checking process should be automatic or manually triggered.

====Controller side requirements====
* A controller MUST eventually close any Locked session using the meta-command !release.

In particular, non-portable controllers should not let a Locked relay wearer run free out of reach. Moreover, any controller should either react to some kind of event that is bound to happen (timer expiration being the most common) or provide a user interface for closing the session. It should be clear at least to the person who set the trap how the victim will be released.

==Core meta-commands and associated mechanisms==

An ORG device MUST at least support the meta-commands !release, !pong, !version, !implversion and !x-orgversions described below and implement their associated mechanisms.

Particular meta-commands definitions and mechanisms may override general requirements above.

New in ORG compared to RLVR: !x-orgversions

===!release===
Sent by a controller, this command closes the session.

* !release obviously opens no session, requires no Auth and is not Locking.
* If there is an actual session to close, !release MUST be accepted by the relay and acknowledeged by "ok".
* On accepting !release, the relay erases all data pertaining to the session and disables all restrictions of the session.
* When a relay decides to close a session on its own (user safeword, for instance) and it is not due to the controller being unreachable, the relay must send the following acknowledgement message:
release,<controller_key>,!release,ok

When receiving the latter message, the controller should act accordingly, for instance by resetting itself and making itself ready for the next session.

Note that !release is not the same as @clear. @clear is interpreted by the relay as a RLV command and, as such, can only clear RLV restrictions. If RLV restrictions were the only restrictions of the session, then the session will be closed, but some x-tensions also define pure LSL based restrictions.

===ping/!pong===

The ping/!pong mechanism exists so that relays can check presence and responsiveness of a controller. This was primarily meant to be used on relay wearer relog, in order to reactivate all restrictions so that sessions persist on relog if the controller still exists and is ready to continue the session.

''!pong'' cannot require auth and does not lock a session

We call ''ping message'' a message from the relay, having the following syntax:
ping,<controller_key>,ping,ping
We call ''!pong message'' a message from the controller, having the following syntax:
ping,<relay_key>,!pong

====Relay side====
*A relay SHOULD NOT send an acknowledgement in response to ''!pong''.
*A ping message can be sent any time by the relay to a known controller.
*On wearer relog, for each existing Locked session, the relay must send a ping message to the session controller.
*When a !pong message is received from a controller, if it was a reply to a previous ping message:
:#if the session RLV restrictions contain unsit and the avatar was sitting on some object when the restriction was applied, then the relay MUST force the avatar to sit back on the same object (if still existing);
:#the relay MUST make sure all restrictions belonging to the session are made active again.
*If a ping message is sent and is not answered by the controller, then the relay closes the session.

Note that the relay is responsible for storing restrictions and the key of the sit target across sessions, not the controller.

====Controller side====
*Unless it does not matter that the relay could close the session (or for another reason, the controller knows the relay will not close it), a controller SHOULD listen to ping messages and answer any ping message with a !pong message.
*A controller should ignore ping requests from relays it is not ready to handle.

Note controller don't have to poll for relay presence to resume a session but should just listen for ping messages instead. The relay should have stored all restrictions and handle sitting back to whatever furniture the relay wearer was tied up to.

Concerning the second bullet: for instance, if the controller is a furniture which is already in use by another relay wearer, it would be cause dysfunctions to let the pinging relay restore the restrictions without letting its wearer sit on the furniture. Or if the controller is not stateless and the state for the pinging relay has not been saved before, resuming the session from the initial state might be inconsistant.

===!version===
The purpose of this meta-command is to query the version of the RLVR protocol supported by a relay.

* !version opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !version with the version number of the RLVR protocol it supports ("1100" here, since ORG 0004 includes RLVR 1.100).

Note this is the most common command for a controller to scan for nearby relays, as non-ORG relays also accept this command and answer it the way described above.

===!implversion===
The purpose of this meta-command is to query the name and version of the relay implementation.

* !implversion opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !implversion with its implementation version string... which can be any string.

It is recommended this string includes the following elements:
* the relay name/brand/identifier,
* the version number of that relay name/brand/identifier,
* at the beginning, the string prefix "ORG=0004/"
The latter is convenient for checking for ORG compatibility using a command even non-ORG relay should understand.

===!x-orgversions===

This meta-command's purpose is to make it possible for the controller to have detailed informations on the protocol the relay supports. First the version of the ORG consolidated protocol, second the list of supported optional x-tensions, also with their version numbers.

'''Example:'''
C<->R
-> query,rUUID,!x-orgversions
<- query,cUUID,!x-orgversions,ORG=0004/who=002/email=006

'''Requirements:'''
* !x-orgversions should always be accepted with no Auth required, it does not open a session or Lock one.
* The acknowledgement value in a reply to !x-orgversions is a "/"-list of items of the form <package>=<version>. The first <package> is always "ORG" (representing the core specification package of ORG relays), its version string is the version of the specification (4 digits). The other packages are x-tension names, whose version string is 3 digits.
* If several incompatible versions of a same x-tension are supported, they must be listed ordered by version number. Ex: ORG=0004/who=002/email=005/email=006. If versions are backward compatible, only the last version should be reported.
* By announcing an x-tension, the relay commits itself to comply to all requirements of its specification.

'''Remarks:'''
* In a controller, it is however recommended to use !x-orgversions as soon as possible in order to avoid sending unsupported and useless metacommands later on.
* In the acknowledgement message, x-tension names are listed, not meta-command names (as one x-tension can have several meta-commands). Thus listed names do not include the prefix "!x-".
* x-tensions do not have to be standards defined by ORG but can also be proprietary. We recommend that the x-tension name then contains the name of the brand who proposes it.

===Other meta-commands===

Commands not listed here can belong to one of the following categories:
# (unlikely) commands from a future revision of Marine Kelley's original RLVR protocol.
# (more likely but not that much!) core commands from a future revision of ORG
# (very likely) commands from optional x-tensions
# proprietary commands

ORG intends for its successive versions to be backward compatible. Therefore ORG relays handle all unknown meta-commands.

We also intend for future versions of ORG consolidated protocol to include last version of original RLVR protocol, hence the prefix "!x-" for all meta-commands comming from ORG, which ensures there will be reasonably no collision.

For the same reason, we require that proprietary commands use an obvious prefix such as "!a-" or "!b-", and so on. Not doing so would prevent ensuring backward compatibility, hence a relay or controller who would use proprietary commands with wrong prefixes are not ORG compliant.

LSL Protocol/Restrained Love Open Relay Group/ORG Requirements/0004 draft

2011-06-27T16:27:17Z

Satomi Ahn:

{{ORG_Restrained_Life_Relay_Specs_TOC}}
STATUS: draft

VERSION: 0004

'''Summary'''

This page lists requirements that make a RLV relay or a RLVR controller "ORG compliant".
Main advantages of an ORG compliant device over a classic RLVR devices are the following:
* ORG devices follow a stricter specification (while keeping compatibility), thus making the experience more predictible for scripters
* ORG devices can support optional x-tensions for more fun. Supported x-tensions can easily be discovered thanks to a new query meta-command.

For a quick overview of the motivations and general working of the RLVR protocol and a few examples, we refer the reader to [[LSL_Protocol/Restrained_Love_Relay/Specification|the original RLVR specification]].

If you are making furniture, traps, or other RLVR controllers and you are not interested in what [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] can offer, then you can stick with the original RLVR specification and still be compatible with [[LSL_Protocol/Restrained_Love_Relay/Comparison|ORG relays]]. However, to have the right to call your controller "ORG compatible", there are still a few light additional requirements such as:
* using only [[llRegionSayTo]] for communications with the relay,
* not spamming the RLVR channel with messages that do not belong to the protocol,
* and remain responsive to ping messages at every time if you want the session to remain locked.

If you are interested in [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|ORG x-tensions]], then you should also read the part about [[#!x-orgversions|!x-orgversions]].

If you are making a relay, sorry we are afraid you will have to read all this page.

==Definition of an ORG device==

A RLVR device is compliant with ORG specifications if it implements the consolidated RLVR protocol described below along with the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] it announces supporting.

Note in particular that
* the consolidated protocol is backward compatible with [[LSL_Protocol/Restrained_Love_Relay/Specification|Marine Kelley's RLVR protocol version 1.100]] but resolves most loose ends of that document;
* ORG relays handle controller messages using wildcards (sent to all relays within range)
* one-to-one chat messages (not using a wildcard) are sent by using [[llRegionSayTo]] LSL function;
* there is an additional command, for a controller to query for optional x-tensions the relay supports.

Supported x-tensions can constrain the core specification (this document) even more, but cannot alter it or make it less constraining unless as a result of the relay executing a meta-command of this x-tension sent by the controller. Thus, although the protocol is extensible, a controller can always rely on the fact an ORG relay abides by the requirements in this document until it asks the relay to do otherwise.

ORG devices may be advertised by the use of the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/ORG_Logo|ORG logo]] for advertising compliance with ORG requirements. ORG devices makers are encouraged to do so.

==Consolidated RLVR protocol==
This consolidated RLVR protocol is roughly the same as the original RLVR protocol, minus a few embarassing loose ends.

Main differences are highlighted at the beginning of each subsection.
=== Protocol Syntax ===
Summary of differences with original RLVR:
* we force use of llRegionSayTo,
* we explicitly forbid incorrect syntax on the relay channel
* the relay is supposed to ignore bad commands
* wildcards are supported

==== Definitions ====
* The '''Restrained Love Relay (RLVR) protocol''' implies two partners (SL objects): the '''relay''', attachment worn by the avatar commands are intended for, and a '''controller''', which sends commands to the relay.

* The goal of the protocol is to force the relay wearer to make perform actions and to toggle restrictions on their behavior. Both actions and restrictions can be enforced either through use of viewer hooks ([[LSL_Protocol/RestrainedLoveAPI|Restrained Love API]], or RLV) or through LSL scripting.

* Hence we distinguish between "'''RLV commands'''", starting with "@", which are commands following the syntax of the RLV API and which will ultimately be forwarded to the viewer, and "'''meta-commands'''", starting with "!", which are meant to be interpreted by LSL functions.

====Requirements====
RLVR protocol consists of messages exchanged between relay and controller
* on channel -1812221819 (called '''RLVR channel'''),
* using the LSL function [[llRegionSayTo]] (except for <c_msg>'s using a wildcard),
* all sent from the same prim of the controller or relay (within a [[#Protocol session|session]])
* and having the following syntax (non-terminal <c_msg> for controller messages/'''command messages''' and <r_msg> for relay messages/'''acknowledgement messages'''):

<c_msg> ::= IDENT "," KEY "," <commands>
<r_msg> ::= IDENT "," KEY "," <command> "," ACK
<commands> ::= <command> | <command> "|" <commands>
<command> ::= <rlvcommand> | <metacommand>
<rlvcommand> ::= "@" RLVCOMMAND
<metacommand> ::= "!" METACOMMANDNAME <metacommandarguments>
<metacommandarguments> ::= "" | "/" ARG <metacommandarguments>

where we explicit the different terminal tokens:
IDENT: any string without ","
KEY: any UUID
ACK: any string without ","
RLVCOMMAND: any string without ","
METACOMMANDNAME: any string without "/" and ","
ARG: any string without "/" and ","

* Relays can only send <r_msg>'s, and controllers <c_msg>'s. Nothing else is allowed on RLVR channel.
* In <c_msg>, KEY is always either the uuid of the relay wearer or ffffffff-ffff-ffff-ffff-ffffffffffff ('''wildcard''') if it is a message intended for all relays who can hear it.
* In <r_msg>, KEY is always the uuid of the controller.

====On the relay side only====
'''Further requirements:'''
*A relay MUST ignore any message on RLVR channel which is not a <c_msg> with KEY being either the key of the avatar wearing the relay or ffffffff-ffff-ffff-ffff-ffffffffffff.
Then, for every <command>:
* if <command> is neither a valid <rlvcommand> or <metacommand>, the relay must ignore it and process the next <command>'s;
* if <command> is a <rlvcommand> or a <metacommand>, the relay MUST send back to the controller a <r_msg> (see above) such that:
:*IDENT is the same as IDENT in the <c_msg> being processed,
:*<command> is the subcommand being processed
:*and ACK is a string called ''acknowledgement value''. By default the acknowledgement value is "ok" if the relay will execute the <command >, "ko" otherwise.

'''Remarks:'''
* Many meta-commands may have other acknowledgements than "ok" or "ko" (or none, for !pong). Their definitions supersede this specification.
* Note that unknown meta-commands cannot be executed and thus wil be acknowledged by "ko".
* Known meta-commands which are sent with not enough parameters or parameters with types incompatible with those in the definition known by the relay also cannot be executed and will also be acknowledged by "ko". (ex: the relay knows !x-who/key, but receives !x-who/integer/string).

===On executing commands===
Summary of differences with original RLVR:
* explanation on how to handle meta-commands with variable number of parameters,
* the relay knows commands in both core specification and x-tensions,
* clarification on multi-controller relays.

====Relay side====
'''Requirements:'''
* If a <rlvcommand> is acknowledged with value "ok", the relay ensures the viewer is affected the same way as if the LSL instruction llOwnerSay(<rlvcommand>) was executed by a script in a primitive that handles only one controller.
* When processing a <metacommand>, if the relay knows at least one definition of '!'+METACOMMANDNAME for which the received <metacommandarguments> provide enough parameters, then it will be handled according to the definition handling the most parameters among the latter. Extra parameters are ignored.
* A relays knows the following meta-command definitions:
:*[[#Core meta-commands and associated mechanisms|definitions listed in the core requirements]]
:*all definitions included in [[LSL_Protocol/Restrained_Love_Relay/Comparison|x-tensions]] announced by the relay.
* When acknowledging a <metacommand> by anything else than "ko", the relay commits itself to execute it.

'''Remarks:'''
* For first requirement, it must be understood that the reference behavior is that the relay would have if it had one controller per prim. However handling several controllers from one unique prim is possible but requires taking care that different controllers do not interfere with each other, releasing each other's restrictions, for instance.
* For the second requirement, the word "handled" means that if the meta-command with these parameters is known, then requirements in known definition cannot be ignored. Sometimes, this can imply that the meta-command cannot be refused, for instance.

====Controller side====
* The controller can send any command within allowed syntax.
* Only commands described in this specification and commands belonging to x-tensions announced by the relay are guaranteed to be understood by the relay. If not understood, the relay will just answer "ko", do nothing and skip to the next command.

===Protocol session===
Summary of differences with original RLVR:
* it is now clear when a session starts and stops (and what a session is!)
* it is clear when to expect interactive dialogs (and how to avoid spamming relay wearers with blue dialogs)
* no session for unreachable controllers (answer to ping is mandatory to ensure session persistence)

====Definitions====
* During an execution of the RLVR protocol, a relay and a controller establish a '''session''' together. A relay may manage several sessions with several controllers. Likewise, a controller could establish sessions with several relays.
* Restrictions on a relay wearer are relative to a session. So are most other variables (authorization state, key of the controller, ... ).
* A session is '''Opened''' whenever the relay accepts a RLVR command from a controller.
* A session is '''Closed''' (or '''released''') as soon as the relay forgets every variables and releases all restrictions pertaining to that session.
* A session is '''Locked''' whenever it holds active restrictions.
* A session is '''Authed''' if the controller has been allowed to control the relay (not only store some variables with no consequence). Once authed, no interactive "ask" dialog should pop up anymore concerning this session. Most commands should now normally be accepted (and maybe a few automatically rejected).
* A controller is called '''reachable''' if it can receive messages from the relay and can prove it by answering [[#ping/!pong|ping]] requests from the relay. By "can", it is meant by the method of communication agreed upon by the relay and controller (by default: chat messages sent on RLVR channel by llRegionSayTo). X-tensions such as email and delay can modify what is meant by reachable.

====Relay side requirements====
On closing sessions:
*Closing a session clears all RLV restrictions that belong only to that session, clears all session variables and disables all restrictions relative to that session. This MUST happen on the following events and no other:
:*on executing !release (received from the controller, or relay-triggered as in a safeword, see [[#!release]])
:*on noticing the controller is not reachable
:*on timeout, if the session is not Locked
*Sessions that are not locked MUST be closed after a reasonable timeout.

On interactive Auth:
*Unless specified otherwise (see !x-who), no command can trigger an interactive dialog unless the command requires an Authed session and the session is not already Authed.
*Relay implementations MAY require an authed session for all <rlvcommand>'s of the form @xxx=force, @xxx=add and @xxx=n, and for meta-commands whose specifications say it is allowed.
*Other RLV commands MUST automatically accepted or rejected by any relay.

On removing and adding restrictions:
* Commands that remove restrictions are always accepted (RLV @...=<channel_number>, @clear[=...] and @...=y/rem commands, !release, and !x-.../clear[/...] meta-commands).
* No restriction can be released unless as the result of one of the above commands, or of closing a session.
*@xxx=n/add <rlvcommand>'s, after being accepted, add a restriction and therefore Lock the session.
*Some meta-commands described in x-tensions can also add restrictions and therefore Lock the session.

Reachability:
*A relay MUST provide a mechanism for checking that every controlling device is reachable. It is not specified whether this checking process should be automatic or manually triggered.

====Controller side requirements====
* A controller MUST eventually close any Locked session using the meta-command !release.

In particular, non-portable controllers should not let a Locked relay wearer run free out of reach. Moreover, any controller should either react to some kind of event that is bound to happen (timer expiration being the most common) or provide a user interface for closing the session. It should be clear at least to the person who set the trap how the victim will be released.

==Core meta-commands and associated mechanisms==

An ORG device MUST at least support the meta-commands !release, !pong, !version, !implversion and !x-orgversions described below and implement their associated mechanisms.

Particular meta-commands definitions and mechanisms may override general requirements above.

New in ORG compared to RLVR: !x-orgversions

===!release===
Sent by a controller, this command closes the session.

* !release obviously opens no session, requires no Auth and is not Locking.
* If there is an actual session to close, !release MUST be accepted by the relay and acknowledeged by "ok".
* On accepting !release, the relay erases all data pertaining to the session and disables all restrictions of the session.
* When a relay decides to close a session on its own (user safeword, for instance) and it is not due to the controller being unreachable, the relay must send the following acknowledgement message:
release,<controller_key>,!release,ok

When receiving the latter message, the controller should act accordingly, for instance by resetting itself and making itself ready for the next session.

Note that !release is not the same as @clear. @clear is interpreted by the relay as a RLV command and, as such, can only clear RLV restrictions. If RLV restrictions were the only restrictions of the session, then the session will be closed, but some x-tensions also define pure LSL based restrictions.

===ping/!pong===

The ping/!pong mechanism exists so that relays can check presence and responsiveness of a controller. This was primarily meant to be used on relay wearer relog, in order to reactivate all restrictions so that sessions persist on relog if the controller still exists and is ready to continue the session.

''!pong'' cannot require auth and does not lock a session

We call ''ping message'' a message from the relay, having the following syntax:
ping,<controller_key>,ping,ping
We call ''!pong message'' a message from the controller, having the following syntax:
ping,<relay_key>,!pong

====Relay side====
*A relay SHOULD NOT send an acknowledgement in response to ''!pong''.
*A ping message can be sent any time by the relay to a known controller.
*On wearer relog, for each existing Locked session, the relay must send a ping message to the session controller.
*When a !pong message is received from a controller, if it was a reply to a previous ping message:
:#if the session RLV restrictions contain unsit and the avatar was sitting on some object when the restriction was applied, then the relay MUST force the avatar to sit back on the same object (if still existing);
:#the relay MUST make sure all restrictions belonging to the session are made active again.
*If a ping message is sent and is not answered by the controller, then the relay closes the session.

Note that the relay is responsible for storing restrictions and the key of the sit target across sessions, not the controller.

====Controller side====
*Unless it does not matter that the relay could close the session (or for another reason, the controller knows the relay will not close it), a controller SHOULD listen to ping messages and answer any ping message with a !pong message.
*A controller should ignore ping requests from relays it is not ready to handle.

Note controller don't have to poll for relay presence to resume a session but should just listen for ping messages instead. The relay should have stored all restrictions and handle sitting back to whatever furniture the relay wearer was tied up to.

Concerning the second bullet: for instance, if the controller is a furniture which is already in use by another relay wearer, it would be cause dysfunctions to let the pinging relay restore the restrictions without letting its wearer sit on the furniture. Or if the controller is not stateless and the state for the pinging relay has not been saved before, resuming the session from the initial state might be inconsistant.

===!version===
The purpose of this meta-command is to query the version of the RLVR protocol supported by a relay.

* !version opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !version with the version number of the RLVR protocol it supports ("1100" here, since ORG 0004 includes RLVR 1.100).

Note this is the most common command for a controller to scan for nearby relays, as non-ORG relays also accept this command and answer it the way described above.

===!implversion===
The purpose of this meta-command is to query the name and version of the relay implementation.

* !implversion opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !implversion with its implementation version string... which can be any string.

It is recommended this string includes the following elements:
* the relay name/brand/identifier,
* the version number of that relay name/brand/identifier,
* at the beginning, the string prefix "ORG=0004/"
The latter is convenient for checking for ORG compatibility using a command even non-ORG relay should understand.

===!x-orgversions===

This meta-command's purpose is to make it possible for the controller to have detailed informations on the protocol the relay supports. First the version of the ORG consolidated protocol, second the list of supported optional x-tensions, also with their version numbers.

'''Example:'''
C<->R
-> query,rUUID,!x-orgversions
<- query,cUUID,!x-orgversions,ORG=0004/who=002/email=006

'''Requirements:'''
* !x-orgversions should always be accepted with no Auth required, it does not open a session or Lock one.
* The acknowledgement value in a reply to !x-orgversions is a "/"-list of items of the form <package>=<version>. The first <package> is always "ORG" (representing the core specification package of ORG relays), its version string is the version of the specification (4 digits). The other packages are x-tension names, whose version string is 3 digits.
* If several incompatible versions of a same x-tension are supported, they must be listed ordered by version number. Ex: ORG=0004/who=002/email=005/email=006. If versions are backward compatible, only the last version should be reported.
* By announcing an x-tension, the relay commits itself to comply to all requirements of its specification.

'''Remarks:'''
* In a controller, it is however recommended to use !x-orgversions as soon as possible in order to avoid sending unsupported and useless metacommands later on.
* In the acknowledgement message, x-tension names are listed, not meta-command names (as one x-tension can have several meta-commands). Thus listed names do not include the prefix "!x-".
* x-tensions do not have to be standards defined by ORG but can also be proprietary. We recommend that the x-tension name then contains the name of the brand who proposes it.

===Other meta-commands===

Commands not listed here can belong to one of the following categories:
# (unlikely) commands from a future revision of Marine Kelley's original RLVR protocol.
# (more likely but not that much!) core commands from a future revision of ORG
# (very likely) commands from optional x-tensions
# proprietary commands

ORG intends for its successive versions to be backward compatible. Therefore ORG relays handle all unknown meta-commands.

We also intend for future versions of ORG consolidated protocol to include last version of original RLVR protocol, hence the prefix "!x-" for all meta-commands comming from ORG, which ensures there will be reasonably no collision.

For the same reason, we require that proprietary commands use an obvious prefix such as "!a-" or "!b-", and so on. Not doing so would prevent ensuring backward compatibility, hence a relay or controller who would use proprietary commands with wrong prefixes are not ORG compliant.

LSL Protocol/Restrained Love Open Relay Group/ORG Requirements/0004 draft

2011-06-27T16:23:07Z

Satomi Ahn:

{{ORG_Restrained_Life_Relay_Specs_TOC}}
STATUS: draft

VERSION: 0004

'''Summary'''

This page lists requirements that make a RLV relay or a RLVR controller "ORG compliant". Main features of an ORG compliant device compared to a classic RLVR device are the support of an additional meta-command, for querying compatibility with optional x-tensions, and adherence to stricter specifications while preserving full compatibility with Marine Kelley's original RLVR protocol.

For a quick overview of the motivations and general working of the RLVR protocol and a few examples, we refer the reader to [[LSL_Protocol/Restrained_Love_Relay/Specification|the original RLVR specification]].

If you are making furniture, traps, or other RLVR controllers and you are not interested in what [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] can offer, then you can stick with the original RLVR specification and still be compatible with [[LSL_Protocol/Restrained_Love_Relay/Comparison|ORG relays]]. However, to have the right to call your controller "ORG compatible", there are still a few light additional requirements such as:
* using only [[llRegionSayTo]] for communications with the relay,
* not spamming the RLVR channel with messages that do not belong to the protocol,
* and remain responsive to ping messages at every time if you want the session to remain locked.

If you are interested in [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|ORG x-tensions]], then you should also read the part about [[#!x-orgversions|!x-orgversions]].

If you are making a relay, sorry we are afraid you will have to read all this page.

==Definition of an ORG device==

A RLVR device is compliant with ORG specifications if it implements the consolidated RLVR protocol described below along with the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] it announces supporting.

Note in particular that
* the consolidated protocol is backward compatible with [[LSL_Protocol/Restrained_Love_Relay/Specification|Marine Kelley's RLVR protocol version 1.100]] but resolves most loose ends of that document;
* ORG relays handle controller messages using wildcards (sent to all relays within range)
* one-to-one chat messages (not using a wildcard) are sent by using [[llRegionSayTo]] LSL function;
* there is an additional command, for a controller to query for optional x-tensions the relay supports.

Supported x-tensions can constrain the core specification (this document) even more, but cannot alter it or make it less constraining unless as a result of the relay executing a meta-command of this x-tension sent by the controller. Thus, although the protocol is extensible, a controller can always rely on the fact an ORG relay abides by the requirements in this document until it asks the relay to do otherwise.

ORG devices may be advertised by the use of the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/ORG_Logo|ORG logo]] for advertising compliance with ORG requirements. ORG devices makers are encouraged to do so.

==Consolidated RLVR protocol==
This consolidated RLVR protocol is roughly the same as the original RLVR protocol, minus a few embarassing loose ends.

Main differences are highlighted at the beginning of each subsection.
=== Protocol Syntax ===
Summary of differences with original RLVR:
* we force use of llRegionSayTo,
* we explicitly forbid incorrect syntax on the relay channel
* the relay is supposed to ignore bad commands
* wildcards are supported

==== Definitions ====
* The '''Restrained Love Relay (RLVR) protocol''' implies two partners (SL objects): the '''relay''', attachment worn by the avatar commands are intended for, and a '''controller''', which sends commands to the relay.

* The goal of the protocol is to force the relay wearer to make perform actions and to toggle restrictions on their behavior. Both actions and restrictions can be enforced either through use of viewer hooks ([[LSL_Protocol/RestrainedLoveAPI|Restrained Love API]], or RLV) or through LSL scripting.

* Hence we distinguish between "'''RLV commands'''", starting with "@", which are commands following the syntax of the RLV API and which will ultimately be forwarded to the viewer, and "'''meta-commands'''", starting with "!", which are meant to be interpreted by LSL functions.

====Requirements====
RLVR protocol consists of messages exchanged between relay and controller
* on channel -1812221819 (called '''RLVR channel'''),
* using the LSL function [[llRegionSayTo]] (except for <c_msg>'s using a wildcard),
* all sent from the same prim of the controller or relay (within a [[#Protocol session|session]])
* and having the following syntax (non-terminal <c_msg> for controller messages/'''command messages''' and <r_msg> for relay messages/'''acknowledgement messages'''):

<c_msg> ::= IDENT "," KEY "," <commands>
<r_msg> ::= IDENT "," KEY "," <command> "," ACK
<commands> ::= <command> | <command> "|" <commands>
<command> ::= <rlvcommand> | <metacommand>
<rlvcommand> ::= "@" RLVCOMMAND
<metacommand> ::= "!" METACOMMANDNAME <metacommandarguments>
<metacommandarguments> ::= "" | "/" ARG <metacommandarguments>

where we explicit the different terminal tokens:
IDENT: any string without ","
KEY: any UUID
ACK: any string without ","
RLVCOMMAND: any string without ","
METACOMMANDNAME: any string without "/" and ","
ARG: any string without "/" and ","

* Relays can only send <r_msg>'s, and controllers <c_msg>'s. Nothing else is allowed on RLVR channel.
* In <c_msg>, KEY is always either the uuid of the relay wearer or ffffffff-ffff-ffff-ffff-ffffffffffff ('''wildcard''') if it is a message intended for all relays who can hear it.
* In <r_msg>, KEY is always the uuid of the controller.

====On the relay side only====
'''Further requirements:'''
*A relay MUST ignore any message on RLVR channel which is not a <c_msg> with KEY being either the key of the avatar wearing the relay or ffffffff-ffff-ffff-ffff-ffffffffffff.
Then, for every <command>:
* if <command> is neither a valid <rlvcommand> or <metacommand>, the relay must ignore it and process the next <command>'s;
* if <command> is a <rlvcommand> or a <metacommand>, the relay MUST send back to the controller a <r_msg> (see above) such that:
:*IDENT is the same as IDENT in the <c_msg> being processed,
:*<command> is the subcommand being processed
:*and ACK is a string called ''acknowledgement value''. By default the acknowledgement value is "ok" if the relay will execute the <command >, "ko" otherwise.

'''Remarks:'''
* Many meta-commands may have other acknowledgements than "ok" or "ko" (or none, for !pong). Their definitions supersede this specification.
* Note that unknown meta-commands cannot be executed and thus wil be acknowledged by "ko".
* Known meta-commands which are sent with not enough parameters or parameters with types incompatible with those in the definition known by the relay also cannot be executed and will also be acknowledged by "ko". (ex: the relay knows !x-who/key, but receives !x-who/integer/string).

===On executing commands===
Summary of differences with original RLVR:
* explanation on how to handle meta-commands with variable number of parameters,
* the relay knows commands in both core specification and x-tensions,
* clarification on multi-controller relays.

====Relay side====
'''Requirements:'''
* If a <rlvcommand> is acknowledged with value "ok", the relay ensures the viewer is affected the same way as if the LSL instruction llOwnerSay(<rlvcommand>) was executed by a script in a primitive that handles only one controller.
* When processing a <metacommand>, if the relay knows at least one definition of '!'+METACOMMANDNAME for which the received <metacommandarguments> provide enough parameters, then it will be handled according to the definition handling the most parameters among the latter. Extra parameters are ignored.
* A relays knows the following meta-command definitions:
:*[[#Core meta-commands and associated mechanisms|definitions listed in the core requirements]]
:*all definitions included in [[LSL_Protocol/Restrained_Love_Relay/Comparison|x-tensions]] announced by the relay.
* When acknowledging a <metacommand> by anything else than "ko", the relay commits itself to execute it.

'''Remarks:'''
* For first requirement, it must be understood that the reference behavior is that the relay would have if it had one controller per prim. However handling several controllers from one unique prim is possible but requires taking care that different controllers do not interfere with each other, releasing each other's restrictions, for instance.
* For the second requirement, the word "handled" means that if the meta-command with these parameters is known, then requirements in known definition cannot be ignored. Sometimes, this can imply that the meta-command cannot be refused, for instance.

====Controller side====
* The controller can send any command within allowed syntax.
* Only commands described in this specification and commands belonging to x-tensions announced by the relay are guaranteed to be understood by the relay. If not understood, the relay will just answer "ko", do nothing and skip to the next command.

===Protocol session===
Summary of differences with original RLVR:
* it is now clear when a session starts and stops (and what a session is!)
* it is clear when to expect interactive dialogs (and how to avoid spamming relay wearers with blue dialogs)
* no session for unreachable controllers (answer to ping is mandatory to ensure session persistence)

====Definitions====
* During an execution of the RLVR protocol, a relay and a controller establish a '''session''' together. A relay may manage several sessions with several controllers. Likewise, a controller could establish sessions with several relays.
* Restrictions on a relay wearer are relative to a session. So are most other variables (authorization state, key of the controller, ... ).
* A session is '''Opened''' whenever the relay accepts a RLVR command from a controller.
* A session is '''Closed''' (or '''released''') as soon as the relay forgets every variables and releases all restrictions pertaining to that session.
* A session is '''Locked''' whenever it holds active restrictions.
* A session is '''Authed''' if the controller has been allowed to control the relay (not only store some variables with no consequence). Once authed, no interactive "ask" dialog should pop up anymore concerning this session. Most commands should now normally be accepted (and maybe a few automatically rejected).
* A controller is called '''reachable''' if it can receive messages from the relay and can prove it by answering [[#ping/!pong|ping]] requests from the relay. By "can", it is meant by the method of communication agreed upon by the relay and controller (by default: chat messages sent on RLVR channel by llRegionSayTo). X-tensions such as email and delay can modify what is meant by reachable.

====Relay side requirements====
On closing sessions:
*Closing a session clears all RLV restrictions that belong only to that session, clears all session variables and disables all restrictions relative to that session. This MUST happen on the following events and no other:
:*on executing !release (received from the controller, or relay-triggered as in a safeword, see [[#!release]])
:*on noticing the controller is not reachable
:*on timeout, if the session is not Locked
*Sessions that are not locked MUST be closed after a reasonable timeout.

On interactive Auth:
*Unless specified otherwise (see !x-who), no command can trigger an interactive dialog unless the command requires an Authed session and the session is not already Authed.
*Relay implementations MAY require an authed session for all <rlvcommand>'s of the form @xxx=force, @xxx=add and @xxx=n, and for meta-commands whose specifications say it is allowed.
*Other RLV commands MUST automatically accepted or rejected by any relay.

On removing and adding restrictions:
* Commands that remove restrictions are always accepted (RLV @...=<channel_number>, @clear[=...] and @...=y/rem commands, !release, and !x-.../clear[/...] meta-commands).
* No restriction can be released unless as the result of one of the above commands, or of closing a session.
*@xxx=n/add <rlvcommand>'s, after being accepted, add a restriction and therefore Lock the session.
*Some meta-commands described in x-tensions can also add restrictions and therefore Lock the session.

Reachability:
*A relay MUST provide a mechanism for checking that every controlling device is reachable. It is not specified whether this checking process should be automatic or manually triggered.

====Controller side requirements====
* A controller MUST eventually close any Locked session using the meta-command !release.

In particular, non-portable controllers should not let a Locked relay wearer run free out of reach. Moreover, any controller should either react to some kind of event that is bound to happen (timer expiration being the most common) or provide a user interface for closing the session. It should be clear at least to the person who set the trap how the victim will be released.

==Core meta-commands and associated mechanisms==

An ORG device MUST at least support the meta-commands !release, !pong, !version, !implversion and !x-orgversions described below and implement their associated mechanisms.

Particular meta-commands definitions and mechanisms may override general requirements above.

New in ORG compared to RLVR: !x-orgversions

===!release===
Sent by a controller, this command closes the session.

* !release obviously opens no session, requires no Auth and is not Locking.
* If there is an actual session to close, !release MUST be accepted by the relay and acknowledeged by "ok".
* On accepting !release, the relay erases all data pertaining to the session and disables all restrictions of the session.
* When a relay decides to close a session on its own (user safeword, for instance) and it is not due to the controller being unreachable, the relay must send the following acknowledgement message:
release,<controller_key>,!release,ok

When receiving the latter message, the controller should act accordingly, for instance by resetting itself and making itself ready for the next session.

Note that !release is not the same as @clear. @clear is interpreted by the relay as a RLV command and, as such, can only clear RLV restrictions. If RLV restrictions were the only restrictions of the session, then the session will be closed, but some x-tensions also define pure LSL based restrictions.

===ping/!pong===

The ping/!pong mechanism exists so that relays can check presence and responsiveness of a controller. This was primarily meant to be used on relay wearer relog, in order to reactivate all restrictions so that sessions persist on relog if the controller still exists and is ready to continue the session.

''!pong'' cannot require auth and does not lock a session

We call ''ping message'' a message from the relay, having the following syntax:
ping,<controller_key>,ping,ping
We call ''!pong message'' a message from the controller, having the following syntax:
ping,<relay_key>,!pong

====Relay side====
*A relay SHOULD NOT send an acknowledgement in response to ''!pong''.
*A ping message can be sent any time by the relay to a known controller.
*On wearer relog, for each existing Locked session, the relay must send a ping message to the session controller.
*When a !pong message is received from a controller, if it was a reply to a previous ping message:
:#if the session RLV restrictions contain unsit and the avatar was sitting on some object when the restriction was applied, then the relay MUST force the avatar to sit back on the same object (if still existing);
:#the relay MUST make sure all restrictions belonging to the session are made active again.
*If a ping message is sent and is not answered by the controller, then the relay closes the session.

Note that the relay is responsible for storing restrictions and the key of the sit target across sessions, not the controller.

====Controller side====
*Unless it does not matter that the relay could close the session (or for another reason, the controller knows the relay will not close it), a controller SHOULD listen to ping messages and answer any ping message with a !pong message.
*A controller should ignore ping requests from relays it is not ready to handle.

Note controller don't have to poll for relay presence to resume a session but should just listen for ping messages instead. The relay should have stored all restrictions and handle sitting back to whatever furniture the relay wearer was tied up to.

Concerning the second bullet: for instance, if the controller is a furniture which is already in use by another relay wearer, it would be cause dysfunctions to let the pinging relay restore the restrictions without letting its wearer sit on the furniture. Or if the controller is not stateless and the state for the pinging relay has not been saved before, resuming the session from the initial state might be inconsistant.

===!version===
The purpose of this meta-command is to query the version of the RLVR protocol supported by a relay.

* !version opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !version with the version number of the RLVR protocol it supports ("1100" here, since ORG 0004 includes RLVR 1.100).

Note this is the most common command for a controller to scan for nearby relays, as non-ORG relays also accept this command and answer it the way described above.

===!implversion===
The purpose of this meta-command is to query the name and version of the relay implementation.

* !implversion opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !implversion with its implementation version string... which can be any string.

It is recommended this string includes the following elements:
* the relay name/brand/identifier,
* the version number of that relay name/brand/identifier,
* at the beginning, the string prefix "ORG=0004/"
The latter is convenient for checking for ORG compatibility using a command even non-ORG relay should understand.

===!x-orgversions===

This meta-command's purpose is to make it possible for the controller to have detailed informations on the protocol the relay supports. First the version of the ORG consolidated protocol, second the list of supported optional x-tensions, also with their version numbers.

'''Example:'''
C<->R
-> query,rUUID,!x-orgversions
<- query,cUUID,!x-orgversions,ORG=0004/who=002/email=006

'''Requirements:'''
* !x-orgversions should always be accepted with no Auth required, it does not open a session or Lock one.
* The acknowledgement value in a reply to !x-orgversions is a "/"-list of items of the form <package>=<version>. The first <package> is always "ORG" (representing the core specification package of ORG relays), its version string is the version of the specification (4 digits). The other packages are x-tension names, whose version string is 3 digits.
* If several incompatible versions of a same x-tension are supported, they must be listed ordered by version number. Ex: ORG=0004/who=002/email=005/email=006. If versions are backward compatible, only the last version should be reported.
* By announcing an x-tension, the relay commits itself to comply to all requirements of its specification.

'''Remarks:'''
* In a controller, it is however recommended to use !x-orgversions as soon as possible in order to avoid sending unsupported and useless metacommands later on.
* In the acknowledgement message, x-tension names are listed, not meta-command names (as one x-tension can have several meta-commands). Thus listed names do not include the prefix "!x-".
* x-tensions do not have to be standards defined by ORG but can also be proprietary. We recommend that the x-tension name then contains the name of the brand who proposes it.

===Other meta-commands===

Commands not listed here can belong to one of the following categories:
# (unlikely) commands from a future revision of Marine Kelley's original RLVR protocol.
# (more likely but not that much!) core commands from a future revision of ORG
# (very likely) commands from optional x-tensions
# proprietary commands

ORG intends for its successive versions to be backward compatible. Therefore ORG relays handle all unknown meta-commands.

We also intend for future versions of ORG consolidated protocol to include last version of original RLVR protocol, hence the prefix "!x-" for all meta-commands comming from ORG, which ensures there will be reasonably no collision.

For the same reason, we require that proprietary commands use an obvious prefix such as "!a-" or "!b-", and so on. Not doing so would prevent ensuring backward compatibility, hence a relay or controller who would use proprietary commands with wrong prefixes are not ORG compliant.

LSL Protocol/Restrained Love Open Relay Group/ORG Requirements/0004 draft

2011-06-27T16:21:34Z

Satomi Ahn:

{{ORG_Restrained_Life_Relay_Specs_TOC}}
STATUS: draft

VERSION: 0004

'''Summary'''

This page lists requirements that make a RLV relay or a RLVR controller "ORG compliant". Main features of an ORG compliant device compared to a classic RLVR device are the support of an additional meta-command, for querying compatibility with optional x-tensions, and adherence to stricter specifications while preserving full compatibility with Marine Kelley's original RLVR protocol.

For a quick overview of the motivations and general working of the RLVR protocol and a few examples, we refer the reader to [[LSL_Protocol/Restrained_Love_Relay/Specification|the original specification page by Marine Kelley]].

If you are making furniture, traps, or other RLVR controllers and you are not interested in what [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] can offer, then you can stick with the original specification by Marine Kelley and still be compatible with [[LSL_Protocol/Restrained_Love_Relay/Comparison|ORG relays]]. However, to have the right to call your controller "ORG compatible", there are still a few light additional requirements such as:
* using only [[llRegionSayTo]] for communications with the relay,
* not spamming the RLVR channel with messages that do not belong to the protocol,
* and remain responsive to ping messages at every time if you want the session to remain locked.

If you are interested in [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|ORG x-tensions]], then you should also read the part about [[#!x-orgversions|!x-orgversions]].

If you are making a relay, sorry we are afraid you will have to read all this page.

==Definition of an ORG device==

A RLVR device is compliant with ORG specifications if it implements the consolidated RLVR protocol described below along with the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] it announces supporting.

Note in particular that
* the consolidated protocol is backward compatible with [[LSL_Protocol/Restrained_Love_Relay/Specification|Marine Kelley's RLVR protocol version 1.100]] but resolves most loose ends of that document;
* ORG relays handle controller messages using wildcards (sent to all relays within range)
* one-to-one chat messages (not using a wildcard) are sent by using [[llRegionSayTo]] LSL function;
* there is an additional command, for a controller to query for optional x-tensions the relay supports.

Supported x-tensions can constrain the core specification (this document) even more, but cannot alter it or make it less constraining unless as a result of the relay executing a meta-command of this x-tension sent by the controller. Thus, although the protocol is extensible, a controller can always rely on the fact an ORG relay abides by the requirements in this document until it asks the relay to do otherwise.

ORG devices may be advertised by the use of the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/ORG_Logo|ORG logo]] for advertising compliance with ORG requirements. ORG devices makers are encouraged to do so.

==Consolidated RLVR protocol==
This consolidated RLVR protocol is roughly the same as the original RLVR protocol, minus a few embarassing loose ends.

Main differences are highlighted at the beginning of each subsection.
=== Protocol Syntax ===
Summary of differences with original RLVR:
* we force use of llRegionSayTo,
* we explicitly forbid incorrect syntax on the relay channel
* the relay is supposed to ignore bad commands
* wildcards are supported

==== Definitions ====
* The '''Restrained Love Relay (RLVR) protocol''' implies two partners (SL objects): the '''relay''', attachment worn by the avatar commands are intended for, and a '''controller''', which sends commands to the relay.

* The goal of the protocol is to force the relay wearer to make perform actions and to toggle restrictions on their behavior. Both actions and restrictions can be enforced either through use of viewer hooks ([[LSL_Protocol/RestrainedLoveAPI|Restrained Love API]], or RLV) or through LSL scripting.

* Hence we distinguish between "'''RLV commands'''", starting with "@", which are commands following the syntax of the RLV API and which will ultimately be forwarded to the viewer, and "'''meta-commands'''", starting with "!", which are meant to be interpreted by LSL functions.

====Requirements====
RLVR protocol consists of messages exchanged between relay and controller
* on channel -1812221819 (called '''RLVR channel'''),
* using the LSL function [[llRegionSayTo]] (except for <c_msg>'s using a wildcard),
* all sent from the same prim of the controller or relay (within a [[#Protocol session|session]])
* and having the following syntax (non-terminal <c_msg> for controller messages/'''command messages''' and <r_msg> for relay messages/'''acknowledgement messages'''):

<c_msg> ::= IDENT "," KEY "," <commands>
<r_msg> ::= IDENT "," KEY "," <command> "," ACK
<commands> ::= <command> | <command> "|" <commands>
<command> ::= <rlvcommand> | <metacommand>
<rlvcommand> ::= "@" RLVCOMMAND
<metacommand> ::= "!" METACOMMANDNAME <metacommandarguments>
<metacommandarguments> ::= "" | "/" ARG <metacommandarguments>

where we explicit the different terminal tokens:
IDENT: any string without ","
KEY: any UUID
ACK: any string without ","
RLVCOMMAND: any string without ","
METACOMMANDNAME: any string without "/" and ","
ARG: any string without "/" and ","

* Relays can only send <r_msg>'s, and controllers <c_msg>'s. Nothing else is allowed on RLVR channel.
* In <c_msg>, KEY is always either the uuid of the relay wearer or ffffffff-ffff-ffff-ffff-ffffffffffff ('''wildcard''') if it is a message intended for all relays who can hear it.
* In <r_msg>, KEY is always the uuid of the controller.

====On the relay side only====
'''Further requirements:'''
*A relay MUST ignore any message on RLVR channel which is not a <c_msg> with KEY being either the key of the avatar wearing the relay or ffffffff-ffff-ffff-ffff-ffffffffffff.
Then, for every <command>:
* if <command> is neither a valid <rlvcommand> or <metacommand>, the relay must ignore it and process the next <command>'s;
* if <command> is a <rlvcommand> or a <metacommand>, the relay MUST send back to the controller a <r_msg> (see above) such that:
:*IDENT is the same as IDENT in the <c_msg> being processed,
:*<command> is the subcommand being processed
:*and ACK is a string called ''acknowledgement value''. By default the acknowledgement value is "ok" if the relay will execute the <command >, "ko" otherwise.

'''Remarks:'''
* Many meta-commands may have other acknowledgements than "ok" or "ko" (or none, for !pong). Their definitions supersede this specification.
* Note that unknown meta-commands cannot be executed and thus wil be acknowledged by "ko".
* Known meta-commands which are sent with not enough parameters or parameters with types incompatible with those in the definition known by the relay also cannot be executed and will also be acknowledged by "ko". (ex: the relay knows !x-who/key, but receives !x-who/integer/string).

===On executing commands===
Summary of differences with original RLVR:
* explanation on how to handle meta-commands with variable number of parameters,
* the relay knows commands in both core specification and x-tensions,
* clarification on multi-controller relays.

====Relay side====
'''Requirements:'''
* If a <rlvcommand> is acknowledged with value "ok", the relay ensures the viewer is affected the same way as if the LSL instruction llOwnerSay(<rlvcommand>) was executed by a script in a primitive that handles only one controller.
* When processing a <metacommand>, if the relay knows at least one definition of '!'+METACOMMANDNAME for which the received <metacommandarguments> provide enough parameters, then it will be handled according to the definition handling the most parameters among the latter. Extra parameters are ignored.
* A relays knows the following meta-command definitions:
:*[[#Core meta-commands and associated mechanisms|definitions listed in the core requirements]]
:*all definitions included in [[LSL_Protocol/Restrained_Love_Relay/Comparison|x-tensions]] announced by the relay.
* When acknowledging a <metacommand> by anything else than "ko", the relay commits itself to execute it.

'''Remarks:'''
* For first requirement, it must be understood that the reference behavior is that the relay would have if it had one controller per prim. However handling several controllers from one unique prim is possible but requires taking care that different controllers do not interfere with each other, releasing each other's restrictions, for instance.
* For the second requirement, the word "handled" means that if the meta-command with these parameters is known, then requirements in known definition cannot be ignored. Sometimes, this can imply that the meta-command cannot be refused, for instance.

====Controller side====
* The controller can send any command within allowed syntax.
* Only commands described in this specification and commands belonging to x-tensions announced by the relay are guaranteed to be understood by the relay. If not understood, the relay will just answer "ko", do nothing and skip to the next command.

===Protocol session===
Summary of differences with original RLVR:
* it is now clear when a session starts and stops (and what a session is!)
* it is clear when to expect interactive dialogs (and how to avoid spamming relay wearers with blue dialogs)
* no session for unreachable controllers (answer to ping is mandatory to ensure session persistence)

====Definitions====
* During an execution of the RLVR protocol, a relay and a controller establish a '''session''' together. A relay may manage several sessions with several controllers. Likewise, a controller could establish sessions with several relays.
* Restrictions on a relay wearer are relative to a session. So are most other variables (authorization state, key of the controller, ... ).
* A session is '''Opened''' whenever the relay accepts a RLVR command from a controller.
* A session is '''Closed''' (or '''released''') as soon as the relay forgets every variables and releases all restrictions pertaining to that session.
* A session is '''Locked''' whenever it holds active restrictions.
* A session is '''Authed''' if the controller has been allowed to control the relay (not only store some variables with no consequence). Once authed, no interactive "ask" dialog should pop up anymore concerning this session. Most commands should now normally be accepted (and maybe a few automatically rejected).
* A controller is called '''reachable''' if it can receive messages from the relay and can prove it by answering [[#ping/!pong|ping]] requests from the relay. By "can", it is meant by the method of communication agreed upon by the relay and controller (by default: chat messages sent on RLVR channel by llRegionSayTo). X-tensions such as email and delay can modify what is meant by reachable.

====Relay side requirements====
On closing sessions:
*Closing a session clears all RLV restrictions that belong only to that session, clears all session variables and disables all restrictions relative to that session. This MUST happen on the following events and no other:
:*on executing !release (received from the controller, or relay-triggered as in a safeword, see [[#!release]])
:*on noticing the controller is not reachable
:*on timeout, if the session is not Locked
*Sessions that are not locked MUST be closed after a reasonable timeout.

On interactive Auth:
*Unless specified otherwise (see !x-who), no command can trigger an interactive dialog unless the command requires an Authed session and the session is not already Authed.
*Relay implementations MAY require an authed session for all <rlvcommand>'s of the form @xxx=force, @xxx=add and @xxx=n, and for meta-commands whose specifications say it is allowed.
*Other RLV commands MUST automatically accepted or rejected by any relay.

On removing and adding restrictions:
* Commands that remove restrictions are always accepted (RLV @...=<channel_number>, @clear[=...] and @...=y/rem commands, !release, and !x-.../clear[/...] meta-commands).
* No restriction can be released unless as the result of one of the above commands, or of closing a session.
*@xxx=n/add <rlvcommand>'s, after being accepted, add a restriction and therefore Lock the session.
*Some meta-commands described in x-tensions can also add restrictions and therefore Lock the session.

Reachability:
*A relay MUST provide a mechanism for checking that every controlling device is reachable. It is not specified whether this checking process should be automatic or manually triggered.

====Controller side requirements====
* A controller MUST eventually close any Locked session using the meta-command !release.

In particular, non-portable controllers should not let a Locked relay wearer run free out of reach. Moreover, any controller should either react to some kind of event that is bound to happen (timer expiration being the most common) or provide a user interface for closing the session. It should be clear at least to the person who set the trap how the victim will be released.

==Core meta-commands and associated mechanisms==

An ORG device MUST at least support the meta-commands !release, !pong, !version, !implversion and !x-orgversions described below and implement their associated mechanisms.

Particular meta-commands definitions and mechanisms may override general requirements above.

New in ORG compared to RLVR: !x-orgversions

===!release===
Sent by a controller, this command closes the session.

* !release obviously opens no session, requires no Auth and is not Locking.
* If there is an actual session to close, !release MUST be accepted by the relay and acknowledeged by "ok".
* On accepting !release, the relay erases all data pertaining to the session and disables all restrictions of the session.
* When a relay decides to close a session on its own (user safeword, for instance) and it is not due to the controller being unreachable, the relay must send the following acknowledgement message:
release,<controller_key>,!release,ok

When receiving the latter message, the controller should act accordingly, for instance by resetting itself and making itself ready for the next session.

Note that !release is not the same as @clear. @clear is interpreted by the relay as a RLV command and, as such, can only clear RLV restrictions. If RLV restrictions were the only restrictions of the session, then the session will be closed, but some x-tensions also define pure LSL based restrictions.

===ping/!pong===

The ping/!pong mechanism exists so that relays can check presence and responsiveness of a controller. This was primarily meant to be used on relay wearer relog, in order to reactivate all restrictions so that sessions persist on relog if the controller still exists and is ready to continue the session.

''!pong'' cannot require auth and does not lock a session

We call ''ping message'' a message from the relay, having the following syntax:
ping,<controller_key>,ping,ping
We call ''!pong message'' a message from the controller, having the following syntax:
ping,<relay_key>,!pong

====Relay side====
*A relay SHOULD NOT send an acknowledgement in response to ''!pong''.
*A ping message can be sent any time by the relay to a known controller.
*On wearer relog, for each existing Locked session, the relay must send a ping message to the session controller.
*When a !pong message is received from a controller, if it was a reply to a previous ping message:
:#if the session RLV restrictions contain unsit and the avatar was sitting on some object when the restriction was applied, then the relay MUST force the avatar to sit back on the same object (if still existing);
:#the relay MUST make sure all restrictions belonging to the session are made active again.
*If a ping message is sent and is not answered by the controller, then the relay closes the session.

Note that the relay is responsible for storing restrictions and the key of the sit target across sessions, not the controller.

====Controller side====
*Unless it does not matter that the relay could close the session (or for another reason, the controller knows the relay will not close it), a controller SHOULD listen to ping messages and answer any ping message with a !pong message.
*A controller should ignore ping requests from relays it is not ready to handle.

Note controller don't have to poll for relay presence to resume a session but should just listen for ping messages instead. The relay should have stored all restrictions and handle sitting back to whatever furniture the relay wearer was tied up to.

Concerning the second bullet: for instance, if the controller is a furniture which is already in use by another relay wearer, it would be cause dysfunctions to let the pinging relay restore the restrictions without letting its wearer sit on the furniture. Or if the controller is not stateless and the state for the pinging relay has not been saved before, resuming the session from the initial state might be inconsistant.

===!version===
The purpose of this meta-command is to query the version of the RLVR protocol supported by a relay.

* !version opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !version with the version number of the RLVR protocol it supports ("1100" here, since ORG 0004 includes RLVR 1.100).

Note this is the most common command for a controller to scan for nearby relays, as non-ORG relays also accept this command and answer it the way described above.

===!implversion===
The purpose of this meta-command is to query the name and version of the relay implementation.

* !implversion opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !implversion with its implementation version string... which can be any string.

It is recommended this string includes the following elements:
* the relay name/brand/identifier,
* the version number of that relay name/brand/identifier,
* at the beginning, the string prefix "ORG=0004/"
The latter is convenient for checking for ORG compatibility using a command even non-ORG relay should understand.

===!x-orgversions===

This meta-command's purpose is to make it possible for the controller to have detailed informations on the protocol the relay supports. First the version of the ORG consolidated protocol, second the list of supported optional x-tensions, also with their version numbers.

'''Example:'''
C<->R
-> query,rUUID,!x-orgversions
<- query,cUUID,!x-orgversions,ORG=0004/who=002/email=006

'''Requirements:'''
* !x-orgversions should always be accepted with no Auth required, it does not open a session or Lock one.
* The acknowledgement value in a reply to !x-orgversions is a "/"-list of items of the form <package>=<version>. The first <package> is always "ORG" (representing the core specification package of ORG relays), its version string is the version of the specification (4 digits). The other packages are x-tension names, whose version string is 3 digits.
* If several incompatible versions of a same x-tension are supported, they must be listed ordered by version number. Ex: ORG=0004/who=002/email=005/email=006. If versions are backward compatible, only the last version should be reported.
* By announcing an x-tension, the relay commits itself to comply to all requirements of its specification.

'''Remarks:'''
* In a controller, it is however recommended to use !x-orgversions as soon as possible in order to avoid sending unsupported and useless metacommands later on.
* In the acknowledgement message, x-tension names are listed, not meta-command names (as one x-tension can have several meta-commands). Thus listed names do not include the prefix "!x-".
* x-tensions do not have to be standards defined by ORG but can also be proprietary. We recommend that the x-tension name then contains the name of the brand who proposes it.

===Other meta-commands===

Commands not listed here can belong to one of the following categories:
# (unlikely) commands from a future revision of Marine Kelley's original RLVR protocol.
# (more likely but not that much!) core commands from a future revision of ORG
# (very likely) commands from optional x-tensions
# proprietary commands

ORG intends for its successive versions to be backward compatible. Therefore ORG relays handle all unknown meta-commands.

We also intend for future versions of ORG consolidated protocol to include last version of original RLVR protocol, hence the prefix "!x-" for all meta-commands comming from ORG, which ensures there will be reasonably no collision.

For the same reason, we require that proprietary commands use an obvious prefix such as "!a-" or "!b-", and so on. Not doing so would prevent ensuring backward compatibility, hence a relay or controller who would use proprietary commands with wrong prefixes are not ORG compliant.

LSL Protocol/Restrained Love Open Relay Group/ORG Requirements/0004 draft

2011-06-27T16:16:01Z

Satomi Ahn:

{{ORG_Restrained_Life_Relay_Specs_TOC}}
STATUS: draft

VERSION: 0004

'''Summary'''

This page is a list of requirements for a relay or an in-world device to have the right to be called "ORG compliant". Main features of an ORG device are the support for an ORG-centered informational meta-command and adherence to a stricter specification than Marine Kelley's original RLVR protocol while preserving full compatibility with it.

For a quick overview of the motivations and general working of the RLVR protocol and a few examples, we refer the reader to [[LSL_Protocol/Restrained_Love_Relay/Specification|the original specification page by Marine Kelley]].

If you are making furniture, traps, or other RLVR controllers and you are not interested in what [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] can offer, then you can stick with the original specification by Marine Kelley and still be compatible with [[LSL_Protocol/Restrained_Love_Relay/Comparison|ORG relays]]. However, to have the right to call your controller "ORG compatible", there are still a few light additional requirements such as:
* using only [[llRegionSayTo]] for communications with the relay,
* not spamming the RLVR channel with messages that do not belong to the protocol,
* and remain responsive to ping messages at every time if you want the session to remain locked.

If you are interested in [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|ORG x-tensions]], then you should also read the part about [[#!x-orgversions|!x-orgversions]].

If you are making a relay, sorry we are afraid you will have to read all this page.

==Definition of an ORG device==

A RLVR device is compliant with ORG specifications if it implements the consolidated RLVR protocol described below along with the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] it announces supporting.

Note in particular that
* the consolidated protocol is backward compatible with [[LSL_Protocol/Restrained_Love_Relay/Specification|Marine Kelley's RLVR protocol version 1.100]] but resolves most loose ends of that document;
* ORG relays handle controller messages using wildcards (sent to all relays within range)
* one-to-one chat messages (not using a wildcard) are sent by using [[llRegionSayTo]] LSL function;
* there is an additional command, for a controller to query for optional x-tensions the relay supports.

Supported x-tensions can constrain the core specification (this document) even more, but cannot alter it or make it less constraining unless as a result of the relay executing a meta-command of this x-tension sent by the controller. Thus, although the protocol is extensible, a controller can always rely on the fact an ORG relay abides by the requirements in this document until it asks the relay to do otherwise.

ORG devices may be advertised by the use of the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/ORG_Logo|ORG logo]] for advertising compliance with ORG requirements. ORG devices makers are encouraged to do so.

==Consolidated RLVR protocol==
This consolidated RLVR protocol is roughly the same as the original RLVR protocol, minus a few embarassing loose ends.

Main differences are highlighted at the beginning of each subsection.
=== Protocol Syntax ===
Summary of differences with original RLVR:
* we force use of llRegionSayTo,
* we explicitly forbid incorrect syntax on the relay channel
* the relay is supposed to ignore bad commands
* wildcards are supported

==== Definitions ====
* The '''Restrained Love Relay (RLVR) protocol''' implies two partners (SL objects): the '''relay''', attachment worn by the avatar commands are intended for, and a '''controller''', which sends commands to the relay.

* The goal of the protocol is to force the relay wearer to make perform actions and to toggle restrictions on their behavior. Both actions and restrictions can be enforced either through use of viewer hooks ([[LSL_Protocol/RestrainedLoveAPI|Restrained Love API]], or RLV) or through LSL scripting.

* Hence we distinguish between "'''RLV commands'''", starting with "@", which are commands following the syntax of the RLV API and which will ultimately be forwarded to the viewer, and "'''meta-commands'''", starting with "!", which are meant to be interpreted by LSL functions.

====Requirements====
RLVR protocol consists of messages exchanged between relay and controller
* on channel -1812221819 (called '''RLVR channel'''),
* using the LSL function [[llRegionSayTo]] (except for <c_msg>'s using a wildcard),
* all sent from the same prim of the controller or relay (within a [[#Protocol session|session]])
* and having the following syntax (non-terminal <c_msg> for controller messages/'''command messages''' and <r_msg> for relay messages/'''acknowledgement messages'''):

<c_msg> ::= IDENT "," KEY "," <commands>
<r_msg> ::= IDENT "," KEY "," <command> "," ACK
<commands> ::= <command> | <command> "|" <commands>
<command> ::= <rlvcommand> | <metacommand>
<rlvcommand> ::= "@" RLVCOMMAND
<metacommand> ::= "!" METACOMMANDNAME <metacommandarguments>
<metacommandarguments> ::= "" | "/" ARG <metacommandarguments>

where we explicit the different terminal tokens:
IDENT: any string without ","
KEY: any UUID
ACK: any string without ","
RLVCOMMAND: any string without ","
METACOMMANDNAME: any string without "/" and ","
ARG: any string without "/" and ","

* Relays can only send <r_msg>'s, and controllers <c_msg>'s. Nothing else is allowed on RLVR channel.
* In <c_msg>, KEY is always either the uuid of the relay wearer or ffffffff-ffff-ffff-ffff-ffffffffffff ('''wildcard''') if it is a message intended for all relays who can hear it.
* In <r_msg>, KEY is always the uuid of the controller.

====On the relay side only====
'''Further requirements:'''
*A relay MUST ignore any message on RLVR channel which is not a <c_msg> with KEY being either the key of the avatar wearing the relay or ffffffff-ffff-ffff-ffff-ffffffffffff.
Then, for every <command>:
* if <command> is neither a valid <rlvcommand> or <metacommand>, the relay must ignore it and process the next <command>'s;
* if <command> is a <rlvcommand> or a <metacommand>, the relay MUST send back to the controller a <r_msg> (see above) such that:
:*IDENT is the same as IDENT in the <c_msg> being processed,
:*<command> is the subcommand being processed
:*and ACK is a string called ''acknowledgement value''. By default the acknowledgement value is "ok" if the relay will execute the <command >, "ko" otherwise.

'''Remarks:'''
* Many meta-commands may have other acknowledgements than "ok" or "ko" (or none, for !pong). Their definitions supersede this specification.
* Note that unknown meta-commands cannot be executed and thus wil be acknowledged by "ko".
* Known meta-commands which are sent with not enough parameters or parameters with types incompatible with those in the definition known by the relay also cannot be executed and will also be acknowledged by "ko". (ex: the relay knows !x-who/key, but receives !x-who/integer/string).

===On executing commands===
Summary of differences with original RLVR:
* explanation on how to handle meta-commands with variable number of parameters,
* the relay knows commands in both core specification and x-tensions,
* clarification on multi-controller relays.

====Relay side====
'''Requirements:'''
* If a <rlvcommand> is acknowledged with value "ok", the relay ensures the viewer is affected the same way as if the LSL instruction llOwnerSay(<rlvcommand>) was executed by a script in a primitive that handles only one controller.
* When processing a <metacommand>, if the relay knows at least one definition of '!'+METACOMMANDNAME for which the received <metacommandarguments> provide enough parameters, then it will be handled according to the definition handling the most parameters among the latter. Extra parameters are ignored.
* A relays knows the following meta-command definitions:
:*[[#Core meta-commands and associated mechanisms|definitions listed in the core requirements]]
:*all definitions included in [[LSL_Protocol/Restrained_Love_Relay/Comparison|x-tensions]] announced by the relay.
* When acknowledging a <metacommand> by anything else than "ko", the relay commits itself to execute it.

'''Remarks:'''
* For first requirement, it must be understood that the reference behavior is that the relay would have if it had one controller per prim. However handling several controllers from one unique prim is possible but requires taking care that different controllers do not interfere with each other, releasing each other's restrictions, for instance.
* For the second requirement, the word "handled" means that if the meta-command with these parameters is known, then requirements in known definition cannot be ignored. Sometimes, this can imply that the meta-command cannot be refused, for instance.

====Controller side====
* The controller can send any command within allowed syntax.
* Only commands described in this specification and commands belonging to x-tensions announced by the relay are guaranteed to be understood by the relay. If not understood, the relay will just answer "ko", do nothing and skip to the next command.

===Protocol session===
Summary of differences with original RLVR:
* it is now clear when a session starts and stops (and what a session is!)
* it is clear when to expect interactive dialogs (and how to avoid spamming relay wearers with blue dialogs)
* no session for unreachable controllers (answer to ping is mandatory to ensure session persistence)

====Definitions====
* During an execution of the RLVR protocol, a relay and a controller establish a '''session''' together. A relay may manage several sessions with several controllers. Likewise, a controller could establish sessions with several relays.
* Restrictions on a relay wearer are relative to a session. So are most other variables (authorization state, key of the controller, ... ).
* A session is '''Opened''' whenever the relay accepts a RLVR command from a controller.
* A session is '''Closed''' (or '''released''') as soon as the relay forgets every variables and releases all restrictions pertaining to that session.
* A session is '''Locked''' whenever it holds active restrictions.
* A session is '''Authed''' if the controller has been allowed to control the relay (not only store some variables with no consequence). Once authed, no interactive "ask" dialog should pop up anymore concerning this session. Most commands should now normally be accepted (and maybe a few automatically rejected).
* A controller is called '''reachable''' if it can receive messages from the relay and can prove it by answering [[#ping/!pong|ping]] requests from the relay. By "can", it is meant by the method of communication agreed upon by the relay and controller (by default: chat messages sent on RLVR channel by llRegionSayTo). X-tensions such as email and delay can modify what is meant by reachable.

====Relay side requirements====
On closing sessions:
*Closing a session clears all RLV restrictions that belong only to that session, clears all session variables and disables all restrictions relative to that session. This MUST happen on the following events and no other:
:*on executing !release (received from the controller, or relay-triggered as in a safeword, see [[#!release]])
:*on noticing the controller is not reachable
:*on timeout, if the session is not Locked
*Sessions that are not locked MUST be closed after a reasonable timeout.

On interactive Auth:
*Unless specified otherwise (see !x-who), no command can trigger an interactive dialog unless the command requires an Authed session and the session is not already Authed.
*Relay implementations MAY require an authed session for all <rlvcommand>'s of the form @xxx=force, @xxx=add and @xxx=n, and for meta-commands whose specifications say it is allowed.
*Other RLV commands MUST automatically accepted or rejected by any relay.

On removing and adding restrictions:
* Commands that remove restrictions are always accepted (RLV @...=<channel_number>, @clear[=...] and @...=y/rem commands, !release, and !x-.../clear[/...] meta-commands).
* No restriction can be released unless as the result of one of the above commands, or of closing a session.
*@xxx=n/add <rlvcommand>'s, after being accepted, add a restriction and therefore Lock the session.
*Some meta-commands described in x-tensions can also add restrictions and therefore Lock the session.

Reachability:
*A relay MUST provide a mechanism for checking that every controlling device is reachable. It is not specified whether this checking process should be automatic or manually triggered.

====Controller side requirements====
* A controller MUST eventually close any Locked session using the meta-command !release.

In particular, non-portable controllers should not let a Locked relay wearer run free out of reach. Moreover, any controller should either react to some kind of event that is bound to happen (timer expiration being the most common) or provide a user interface for closing the session. It should be clear at least to the person who set the trap how the victim will be released.

==Core meta-commands and associated mechanisms==

An ORG device MUST at least support the meta-commands !release, !pong, !version, !implversion and !x-orgversions described below and implement their associated mechanisms.

Particular meta-commands definitions and mechanisms may override general requirements above.

New in ORG compared to RLVR: !x-orgversions

===!release===
Sent by a controller, this command closes the session.

* !release obviously opens no session, requires no Auth and is not Locking.
* If there is an actual session to close, !release MUST be accepted by the relay and acknowledeged by "ok".
* On accepting !release, the relay erases all data pertaining to the session and disables all restrictions of the session.
* When a relay decides to close a session on its own (user safeword, for instance) and it is not due to the controller being unreachable, the relay must send the following acknowledgement message:
release,<controller_key>,!release,ok

When receiving the latter message, the controller should act accordingly, for instance by resetting itself and making itself ready for the next session.

Note that !release is not the same as @clear. @clear is interpreted by the relay as a RLV command and, as such, can only clear RLV restrictions. If RLV restrictions were the only restrictions of the session, then the session will be closed, but some x-tensions also define pure LSL based restrictions.

===ping/!pong===

The ping/!pong mechanism exists so that relays can check presence and responsiveness of a controller. This was primarily meant to be used on relay wearer relog, in order to reactivate all restrictions so that sessions persist on relog if the controller still exists and is ready to continue the session.

''!pong'' cannot require auth and does not lock a session

We call ''ping message'' a message from the relay, having the following syntax:
ping,<controller_key>,ping,ping
We call ''!pong message'' a message from the controller, having the following syntax:
ping,<relay_key>,!pong

====Relay side====
*A relay SHOULD NOT send an acknowledgement in response to ''!pong''.
*A ping message can be sent any time by the relay to a known controller.
*On wearer relog, for each existing Locked session, the relay must send a ping message to the session controller.
*When a !pong message is received from a controller, if it was a reply to a previous ping message:
:#if the session RLV restrictions contain unsit and the avatar was sitting on some object when the restriction was applied, then the relay MUST force the avatar to sit back on the same object (if still existing);
:#the relay MUST make sure all restrictions belonging to the session are made active again.
*If a ping message is sent and is not answered by the controller, then the relay closes the session.

Note that the relay is responsible for storing restrictions and the key of the sit target across sessions, not the controller.

====Controller side====
*Unless it does not matter that the relay could close the session (or for another reason, the controller knows the relay will not close it), a controller SHOULD listen to ping messages and answer any ping message with a !pong message.
*A controller should ignore ping requests from relays it is not ready to handle.

Note controller don't have to poll for relay presence to resume a session but should just listen for ping messages instead. The relay should have stored all restrictions and handle sitting back to whatever furniture the relay wearer was tied up to.

Concerning the second bullet: for instance, if the controller is a furniture which is already in use by another relay wearer, it would be cause dysfunctions to let the pinging relay restore the restrictions without letting its wearer sit on the furniture. Or if the controller is not stateless and the state for the pinging relay has not been saved before, resuming the session from the initial state might be inconsistant.

===!version===
The purpose of this meta-command is to query the version of the RLVR protocol supported by a relay.

* !version opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !version with the version number of the RLVR protocol it supports ("1100" here, since ORG 0004 includes RLVR 1.100).

Note this is the most common command for a controller to scan for nearby relays, as non-ORG relays also accept this command and answer it the way described above.

===!implversion===
The purpose of this meta-command is to query the name and version of the relay implementation.

* !implversion opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !implversion with its implementation version string... which can be any string.

It is recommended this string includes the following elements:
* the relay name/brand/identifier,
* the version number of that relay name/brand/identifier,
* at the beginning, the string prefix "ORG=0004/"
The latter is convenient for checking for ORG compatibility using a command even non-ORG relay should understand.

===!x-orgversions===

This meta-command's purpose is to make it possible for the controller to have detailed informations on the protocol the relay supports. First the version of the ORG consolidated protocol, second the list of supported optional x-tensions, also with their version numbers.

'''Example:'''
C<->R
-> query,rUUID,!x-orgversions
<- query,cUUID,!x-orgversions,ORG=0004/who=002/email=006

'''Requirements:'''
* !x-orgversions should always be accepted with no Auth required, it does not open a session or Lock one.
* The acknowledgement value in a reply to !x-orgversions is a "/"-list of items of the form <package>=<version>. The first <package> is always "ORG" (representing the core specification package of ORG relays), its version string is the version of the specification (4 digits). The other packages are x-tension names, whose version string is 3 digits.
* If several incompatible versions of a same x-tension are supported, they must be listed ordered by version number. Ex: ORG=0004/who=002/email=005/email=006. If versions are backward compatible, only the last version should be reported.
* By announcing an x-tension, the relay commits itself to comply to all requirements of its specification.

'''Remarks:'''
* In a controller, it is however recommended to use !x-orgversions as soon as possible in order to avoid sending unsupported and useless metacommands later on.
* In the acknowledgement message, x-tension names are listed, not meta-command names (as one x-tension can have several meta-commands). Thus listed names do not include the prefix "!x-".
* x-tensions do not have to be standards defined by ORG but can also be proprietary. We recommend that the x-tension name then contains the name of the brand who proposes it.

===Other meta-commands===

Commands not listed here can belong to one of the following categories:
# (unlikely) commands from a future revision of Marine Kelley's original RLVR protocol.
# (more likely but not that much!) core commands from a future revision of ORG
# (very likely) commands from optional x-tensions
# proprietary commands

ORG intends for its successive versions to be backward compatible. Therefore ORG relays handle all unknown meta-commands.

We also intend for future versions of ORG consolidated protocol to include last version of original RLVR protocol, hence the prefix "!x-" for all meta-commands comming from ORG, which ensures there will be reasonably no collision.

For the same reason, we require that proprietary commands use an obvious prefix such as "!a-" or "!b-", and so on. Not doing so would prevent ensuring backward compatibility, hence a relay or controller who would use proprietary commands with wrong prefixes are not ORG compliant.

LSL Protocol/Restrained Love Open Relay Group/ORG Requirements/0004 draft

2011-06-27T16:11:50Z

Satomi Ahn: /* Summary */

{{ORG_Restrained_Life_Relay_Specs_TOC}}
STATUS: draft

VERSION: 0004

'''Summary'''

This page is a list of requirements for a relay or an in-world device to have the right to be called "ORG compliant". It is mostly about adding support for an ORG-centered informational metacommand and specifying Marine Kelley's RLVR protocol a bit more that it is now, while of course preserving full compatibility.

For a quick overview of the motivations and general working of this protocol and a few examples, we refer the reader to [[LSL_Protocol/Restrained_Love_Relay/Specification|the original specification page by Marine Kelley]].

If you are making furniture, traps, or other RLVR controllers and you are not interested in what [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] can offer, then you can stick with the original specification by Marine Kelley and still be compatible with [[LSL_Protocol/Restrained_Love_Relay/Comparison|ORG relays]]. However, to have the right to call your controller "ORG compatible", there are still a few light additional requirements such as:
* using only [[llRegionSayTo]] for communications with the relay,
* not spamming the RLVR channel with messages that do not belong to the protocol,
* and remain responsive to ping messages at every time if you want the session to remain locked.

If you are interested in [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|ORG x-tensions]], then you should also read the part about [[#!x-orgversions|!x-orgversions]].

If you are making a relay, sorry we are afraid you will have to read all this page.

==Definition of an ORG device==

A RLVR device is compliant with ORG specifications if it implements the consolidated RLVR protocol described below along with the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] it announces supporting.

Note in particular that
* the consolidated protocol is backward compatible with [[LSL_Protocol/Restrained_Love_Relay/Specification|Marine Kelley's RLVR protocol version 1.100]] but resolves most loose ends of that document;
* ORG relays handle controller messages using wildcards (sent to all relays within range)
* one-to-one chat messages (not using a wildcard) are sent by using [[llRegionSayTo]] LSL function;
* there is an additional command, for a controller to query for optional x-tensions the relay supports.

Supported x-tensions can constrain the core specification (this document) even more, but cannot alter it or make it less constraining unless as a result of the relay executing a meta-command of this x-tension sent by the controller. Thus, although the protocol is extensible, a controller can always rely on the fact an ORG relay abides by the requirements in this document until it asks the relay to do otherwise.

ORG devices may be advertised by the use of the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/ORG_Logo|ORG logo]] for advertising compliance with ORG requirements. ORG devices makers are encouraged to do so.

==Consolidated RLVR protocol==
This consolidated RLVR protocol is roughly the same as the original RLVR protocol, minus a few embarassing loose ends.

Main differences are highlighted at the beginning of each subsection.
=== Protocol Syntax ===
Summary of differences with original RLVR:
* we force use of llRegionSayTo,
* we explicitly forbid incorrect syntax on the relay channel
* the relay is supposed to ignore bad commands
* wildcards are supported

==== Definitions ====
* The '''Restrained Love Relay (RLVR) protocol''' implies two partners (SL objects): the '''relay''', attachment worn by the avatar commands are intended for, and a '''controller''', which sends commands to the relay.

* The goal of the protocol is to force the relay wearer to make perform actions and to toggle restrictions on their behavior. Both actions and restrictions can be enforced either through use of viewer hooks ([[LSL_Protocol/RestrainedLoveAPI|Restrained Love API]], or RLV) or through LSL scripting.

* Hence we distinguish between "'''RLV commands'''", starting with "@", which are commands following the syntax of the RLV API and which will ultimately be forwarded to the viewer, and "'''meta-commands'''", starting with "!", which are meant to be interpreted by LSL functions.

====Requirements====
RLVR protocol consists of messages exchanged between relay and controller
* on channel -1812221819 (called '''RLVR channel'''),
* using the LSL function [[llRegionSayTo]] (except for <c_msg>'s using a wildcard),
* all sent from the same prim of the controller or relay (within a [[#Protocol session|session]])
* and having the following syntax (non-terminal <c_msg> for controller messages/'''command messages''' and <r_msg> for relay messages/'''acknowledgement messages'''):

<c_msg> ::= IDENT "," KEY "," <commands>
<r_msg> ::= IDENT "," KEY "," <command> "," ACK
<commands> ::= <command> | <command> "|" <commands>
<command> ::= <rlvcommand> | <metacommand>
<rlvcommand> ::= "@" RLVCOMMAND
<metacommand> ::= "!" METACOMMANDNAME <metacommandarguments>
<metacommandarguments> ::= "" | "/" ARG <metacommandarguments>

where we explicit the different terminal tokens:
IDENT: any string without ","
KEY: any UUID
ACK: any string without ","
RLVCOMMAND: any string without ","
METACOMMANDNAME: any string without "/" and ","
ARG: any string without "/" and ","

* Relays can only send <r_msg>'s, and controllers <c_msg>'s. Nothing else is allowed on RLVR channel.
* In <c_msg>, KEY is always either the uuid of the relay wearer or ffffffff-ffff-ffff-ffff-ffffffffffff ('''wildcard''') if it is a message intended for all relays who can hear it.
* In <r_msg>, KEY is always the uuid of the controller.

====On the relay side only====
'''Further requirements:'''
*A relay MUST ignore any message on RLVR channel which is not a <c_msg> with KEY being either the key of the avatar wearing the relay or ffffffff-ffff-ffff-ffff-ffffffffffff.
Then, for every <command>:
* if <command> is neither a valid <rlvcommand> or <metacommand>, the relay must ignore it and process the next <command>'s;
* if <command> is a <rlvcommand> or a <metacommand>, the relay MUST send back to the controller a <r_msg> (see above) such that:
:*IDENT is the same as IDENT in the <c_msg> being processed,
:*<command> is the subcommand being processed
:*and ACK is a string called ''acknowledgement value''. By default the acknowledgement value is "ok" if the relay will execute the <command >, "ko" otherwise.

'''Remarks:'''
* Many meta-commands may have other acknowledgements than "ok" or "ko" (or none, for !pong). Their definitions supersede this specification.
* Note that unknown meta-commands cannot be executed and thus wil be acknowledged by "ko".
* Known meta-commands which are sent with not enough parameters or parameters with types incompatible with those in the definition known by the relay also cannot be executed and will also be acknowledged by "ko". (ex: the relay knows !x-who/key, but receives !x-who/integer/string).

===On executing commands===
Summary of differences with original RLVR:
* explanation on how to handle meta-commands with variable number of parameters,
* the relay knows commands in both core specification and x-tensions,
* clarification on multi-controller relays.

====Relay side====
'''Requirements:'''
* If a <rlvcommand> is acknowledged with value "ok", the relay ensures the viewer is affected the same way as if the LSL instruction llOwnerSay(<rlvcommand>) was executed by a script in a primitive that handles only one controller.
* When processing a <metacommand>, if the relay knows at least one definition of '!'+METACOMMANDNAME for which the received <metacommandarguments> provide enough parameters, then it will be handled according to the definition handling the most parameters among the latter. Extra parameters are ignored.
* A relays knows the following meta-command definitions:
:*[[#Core meta-commands and associated mechanisms|definitions listed in the core requirements]]
:*all definitions included in [[LSL_Protocol/Restrained_Love_Relay/Comparison|x-tensions]] announced by the relay.
* When acknowledging a <metacommand> by anything else than "ko", the relay commits itself to execute it.

'''Remarks:'''
* For first requirement, it must be understood that the reference behavior is that the relay would have if it had one controller per prim. However handling several controllers from one unique prim is possible but requires taking care that different controllers do not interfere with each other, releasing each other's restrictions, for instance.
* For the second requirement, the word "handled" means that if the meta-command with these parameters is known, then requirements in known definition cannot be ignored. Sometimes, this can imply that the meta-command cannot be refused, for instance.

====Controller side====
* The controller can send any command within allowed syntax.
* Only commands described in this specification and commands belonging to x-tensions announced by the relay are guaranteed to be understood by the relay. If not understood, the relay will just answer "ko", do nothing and skip to the next command.

===Protocol session===
Summary of differences with original RLVR:
* it is now clear when a session starts and stops (and what a session is!)
* it is clear when to expect interactive dialogs (and how to avoid spamming relay wearers with blue dialogs)
* no session for unreachable controllers (answer to ping is mandatory to ensure session persistence)

====Definitions====
* During an execution of the RLVR protocol, a relay and a controller establish a '''session''' together. A relay may manage several sessions with several controllers. Likewise, a controller could establish sessions with several relays.
* Restrictions on a relay wearer are relative to a session. So are most other variables (authorization state, key of the controller, ... ).
* A session is '''Opened''' whenever the relay accepts a RLVR command from a controller.
* A session is '''Closed''' (or '''released''') as soon as the relay forgets every variables and releases all restrictions pertaining to that session.
* A session is '''Locked''' whenever it holds active restrictions.
* A session is '''Authed''' if the controller has been allowed to control the relay (not only store some variables with no consequence). Once authed, no interactive "ask" dialog should pop up anymore concerning this session. Most commands should now normally be accepted (and maybe a few automatically rejected).
* A controller is called '''reachable''' if it can receive messages from the relay and can prove it by answering [[#ping/!pong|ping]] requests from the relay. By "can", it is meant by the method of communication agreed upon by the relay and controller (by default: chat messages sent on RLVR channel by llRegionSayTo). X-tensions such as email and delay can modify what is meant by reachable.

====Relay side requirements====
On closing sessions:
*Closing a session clears all RLV restrictions that belong only to that session, clears all session variables and disables all restrictions relative to that session. This MUST happen on the following events and no other:
:*on executing !release (received from the controller, or relay-triggered as in a safeword, see [[#!release]])
:*on noticing the controller is not reachable
:*on timeout, if the session is not Locked
*Sessions that are not locked MUST be closed after a reasonable timeout.

On interactive Auth:
*Unless specified otherwise (see !x-who), no command can trigger an interactive dialog unless the command requires an Authed session and the session is not already Authed.
*Relay implementations MAY require an authed session for all <rlvcommand>'s of the form @xxx=force, @xxx=add and @xxx=n, and for meta-commands whose specifications say it is allowed.
*Other RLV commands MUST automatically accepted or rejected by any relay.

On removing and adding restrictions:
* Commands that remove restrictions are always accepted (RLV @...=<channel_number>, @clear[=...] and @...=y/rem commands, !release, and !x-.../clear[/...] meta-commands).
* No restriction can be released unless as the result of one of the above commands, or of closing a session.
*@xxx=n/add <rlvcommand>'s, after being accepted, add a restriction and therefore Lock the session.
*Some meta-commands described in x-tensions can also add restrictions and therefore Lock the session.

Reachability:
*A relay MUST provide a mechanism for checking that every controlling device is reachable. It is not specified whether this checking process should be automatic or manually triggered.

====Controller side requirements====
* A controller MUST eventually close any Locked session using the meta-command !release.

In particular, non-portable controllers should not let a Locked relay wearer run free out of reach. Moreover, any controller should either react to some kind of event that is bound to happen (timer expiration being the most common) or provide a user interface for closing the session. It should be clear at least to the person who set the trap how the victim will be released.

==Core meta-commands and associated mechanisms==

An ORG device MUST at least support the meta-commands !release, !pong, !version, !implversion and !x-orgversions described below and implement their associated mechanisms.

Particular meta-commands definitions and mechanisms may override general requirements above.

New in ORG compared to RLVR: !x-orgversions

===!release===
Sent by a controller, this command closes the session.

* !release obviously opens no session, requires no Auth and is not Locking.
* If there is an actual session to close, !release MUST be accepted by the relay and acknowledeged by "ok".
* On accepting !release, the relay erases all data pertaining to the session and disables all restrictions of the session.
* When a relay decides to close a session on its own (user safeword, for instance) and it is not due to the controller being unreachable, the relay must send the following acknowledgement message:
release,<controller_key>,!release,ok

When receiving the latter message, the controller should act accordingly, for instance by resetting itself and making itself ready for the next session.

Note that !release is not the same as @clear. @clear is interpreted by the relay as a RLV command and, as such, can only clear RLV restrictions. If RLV restrictions were the only restrictions of the session, then the session will be closed, but some x-tensions also define pure LSL based restrictions.

===ping/!pong===

The ping/!pong mechanism exists so that relays can check presence and responsiveness of a controller. This was primarily meant to be used on relay wearer relog, in order to reactivate all restrictions so that sessions persist on relog if the controller still exists and is ready to continue the session.

''!pong'' cannot require auth and does not lock a session

We call ''ping message'' a message from the relay, having the following syntax:
ping,<controller_key>,ping,ping
We call ''!pong message'' a message from the controller, having the following syntax:
ping,<relay_key>,!pong

====Relay side====
*A relay SHOULD NOT send an acknowledgement in response to ''!pong''.
*A ping message can be sent any time by the relay to a known controller.
*On wearer relog, for each existing Locked session, the relay must send a ping message to the session controller.
*When a !pong message is received from a controller, if it was a reply to a previous ping message:
:#if the session RLV restrictions contain unsit and the avatar was sitting on some object when the restriction was applied, then the relay MUST force the avatar to sit back on the same object (if still existing);
:#the relay MUST make sure all restrictions belonging to the session are made active again.
*If a ping message is sent and is not answered by the controller, then the relay closes the session.

Note that the relay is responsible for storing restrictions and the key of the sit target across sessions, not the controller.

====Controller side====
*Unless it does not matter that the relay could close the session (or for another reason, the controller knows the relay will not close it), a controller SHOULD listen to ping messages and answer any ping message with a !pong message.
*A controller should ignore ping requests from relays it is not ready to handle.

Note controller don't have to poll for relay presence to resume a session but should just listen for ping messages instead. The relay should have stored all restrictions and handle sitting back to whatever furniture the relay wearer was tied up to.

Concerning the second bullet: for instance, if the controller is a furniture which is already in use by another relay wearer, it would be cause dysfunctions to let the pinging relay restore the restrictions without letting its wearer sit on the furniture. Or if the controller is not stateless and the state for the pinging relay has not been saved before, resuming the session from the initial state might be inconsistant.

===!version===
The purpose of this meta-command is to query the version of the RLVR protocol supported by a relay.

* !version opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !version with the version number of the RLVR protocol it supports ("1100" here, since ORG 0004 includes RLVR 1.100).

Note this is the most common command for a controller to scan for nearby relays, as non-ORG relays also accept this command and answer it the way described above.

===!implversion===
The purpose of this meta-command is to query the name and version of the relay implementation.

* !implversion opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !implversion with its implementation version string... which can be any string.

It is recommended this string includes the following elements:
* the relay name/brand/identifier,
* the version number of that relay name/brand/identifier,
* at the beginning, the string prefix "ORG=0004/"
The latter is convenient for checking for ORG compatibility using a command even non-ORG relay should understand.

===!x-orgversions===

This meta-command's purpose is to make it possible for the controller to have detailed informations on the protocol the relay supports. First the version of the ORG consolidated protocol, second the list of supported optional x-tensions, also with their version numbers.

'''Example:'''
C<->R
-> query,rUUID,!x-orgversions
<- query,cUUID,!x-orgversions,ORG=0004/who=002/email=006

'''Requirements:'''
* !x-orgversions should always be accepted with no Auth required, it does not open a session or Lock one.
* The acknowledgement value in a reply to !x-orgversions is a "/"-list of items of the form <package>=<version>. The first <package> is always "ORG" (representing the core specification package of ORG relays), its version string is the version of the specification (4 digits). The other packages are x-tension names, whose version string is 3 digits.
* If several incompatible versions of a same x-tension are supported, they must be listed ordered by version number. Ex: ORG=0004/who=002/email=005/email=006. If versions are backward compatible, only the last version should be reported.
* By announcing an x-tension, the relay commits itself to comply to all requirements of its specification.

'''Remarks:'''
* In a controller, it is however recommended to use !x-orgversions as soon as possible in order to avoid sending unsupported and useless metacommands later on.
* In the acknowledgement message, x-tension names are listed, not meta-command names (as one x-tension can have several meta-commands). Thus listed names do not include the prefix "!x-".
* x-tensions do not have to be standards defined by ORG but can also be proprietary. We recommend that the x-tension name then contains the name of the brand who proposes it.

===Other meta-commands===

Commands not listed here can belong to one of the following categories:
# (unlikely) commands from a future revision of Marine Kelley's original RLVR protocol.
# (more likely but not that much!) core commands from a future revision of ORG
# (very likely) commands from optional x-tensions
# proprietary commands

ORG intends for its successive versions to be backward compatible. Therefore ORG relays handle all unknown meta-commands.

We also intend for future versions of ORG consolidated protocol to include last version of original RLVR protocol, hence the prefix "!x-" for all meta-commands comming from ORG, which ensures there will be reasonably no collision.

For the same reason, we require that proprietary commands use an obvious prefix such as "!a-" or "!b-", and so on. Not doing so would prevent ensuring backward compatibility, hence a relay or controller who would use proprietary commands with wrong prefixes are not ORG compliant.

LSL Protocol/Restrained Love Open Relay Group/ORG Requirements/0004 draft

2011-06-27T16:07:24Z

Satomi Ahn: /* !release */

{{ORG_Restrained_Life_Relay_Specs_TOC}}
STATUS: draft

VERSION: 0004

==Summary==

This page is a list of requirements for a relay or an in-world device to have the right to be called "ORG compliant". It is mostly about adding support for an ORG-centered informational metacommand and specifying Marine Kelley's RLVR protocol a bit more that it is now, while of course preserving full compatibility.

For a quick overview of the motivations and general working of this protocol and a few examples, we refer the reader to [[LSL_Protocol/Restrained_Love_Relay/Specification|the original specification page by Marine Kelley]].

If you are making furniture, traps, or other RLVR controllers and you are not interested in what [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] can offer, then you can stick with the original specification by Marine Kelley and still be compatible with [[LSL_Protocol/Restrained_Love_Relay/Comparison|ORG relays]]. However, to have the right to call your controller "ORG compatible", there are still a few light additional requirements such as:
* using only [[llRegionSayTo]] for communications with the relay,
* not spamming the RLVR channel with messages that do not belong to the protocol,
* and remain responsive to ping messages at every time if you want the session to remain locked.

If you are interested in [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|ORG x-tensions]], then you should also read the part about [[#!x-orgversions|!x-orgversions]].

If you are making a relay, sorry we are afraid you will have to read all this page.

==Definition of an ORG device==

A RLVR device is compliant with ORG specifications if it implements the consolidated RLVR protocol described below along with the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] it announces supporting.

Note in particular that
* the consolidated protocol is backward compatible with [[LSL_Protocol/Restrained_Love_Relay/Specification|Marine Kelley's RLVR protocol version 1.100]] but resolves most loose ends of that document;
* ORG relays handle controller messages using wildcards (sent to all relays within range)
* one-to-one chat messages (not using a wildcard) are sent by using [[llRegionSayTo]] LSL function;
* there is an additional command, for a controller to query for optional x-tensions the relay supports.

Supported x-tensions can constrain the core specification (this document) even more, but cannot alter it or make it less constraining unless as a result of the relay executing a meta-command of this x-tension sent by the controller. Thus, although the protocol is extensible, a controller can always rely on the fact an ORG relay abides by the requirements in this document until it asks the relay to do otherwise.

ORG devices may be advertised by the use of the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/ORG_Logo|ORG logo]] for advertising compliance with ORG requirements. ORG devices makers are encouraged to do so.

==Consolidated RLVR protocol==
This consolidated RLVR protocol is roughly the same as the original RLVR protocol, minus a few embarassing loose ends.

Main differences are highlighted at the beginning of each subsection.
=== Protocol Syntax ===
Summary of differences with original RLVR:
* we force use of llRegionSayTo,
* we explicitly forbid incorrect syntax on the relay channel
* the relay is supposed to ignore bad commands
* wildcards are supported

==== Definitions ====
* The '''Restrained Love Relay (RLVR) protocol''' implies two partners (SL objects): the '''relay''', attachment worn by the avatar commands are intended for, and a '''controller''', which sends commands to the relay.

* The goal of the protocol is to force the relay wearer to make perform actions and to toggle restrictions on their behavior. Both actions and restrictions can be enforced either through use of viewer hooks ([[LSL_Protocol/RestrainedLoveAPI|Restrained Love API]], or RLV) or through LSL scripting.

* Hence we distinguish between "'''RLV commands'''", starting with "@", which are commands following the syntax of the RLV API and which will ultimately be forwarded to the viewer, and "'''meta-commands'''", starting with "!", which are meant to be interpreted by LSL functions.

====Requirements====
RLVR protocol consists of messages exchanged between relay and controller
* on channel -1812221819 (called '''RLVR channel'''),
* using the LSL function [[llRegionSayTo]] (except for <c_msg>'s using a wildcard),
* all sent from the same prim of the controller or relay (within a [[#Protocol session|session]])
* and having the following syntax (non-terminal <c_msg> for controller messages/'''command messages''' and <r_msg> for relay messages/'''acknowledgement messages'''):

<c_msg> ::= IDENT "," KEY "," <commands>
<r_msg> ::= IDENT "," KEY "," <command> "," ACK
<commands> ::= <command> | <command> "|" <commands>
<command> ::= <rlvcommand> | <metacommand>
<rlvcommand> ::= "@" RLVCOMMAND
<metacommand> ::= "!" METACOMMANDNAME <metacommandarguments>
<metacommandarguments> ::= "" | "/" ARG <metacommandarguments>

where we explicit the different terminal tokens:
IDENT: any string without ","
KEY: any UUID
ACK: any string without ","
RLVCOMMAND: any string without ","
METACOMMANDNAME: any string without "/" and ","
ARG: any string without "/" and ","

* Relays can only send <r_msg>'s, and controllers <c_msg>'s. Nothing else is allowed on RLVR channel.
* In <c_msg>, KEY is always either the uuid of the relay wearer or ffffffff-ffff-ffff-ffff-ffffffffffff ('''wildcard''') if it is a message intended for all relays who can hear it.
* In <r_msg>, KEY is always the uuid of the controller.

====On the relay side only====
'''Further requirements:'''
*A relay MUST ignore any message on RLVR channel which is not a <c_msg> with KEY being either the key of the avatar wearing the relay or ffffffff-ffff-ffff-ffff-ffffffffffff.
Then, for every <command>:
* if <command> is neither a valid <rlvcommand> or <metacommand>, the relay must ignore it and process the next <command>'s;
* if <command> is a <rlvcommand> or a <metacommand>, the relay MUST send back to the controller a <r_msg> (see above) such that:
:*IDENT is the same as IDENT in the <c_msg> being processed,
:*<command> is the subcommand being processed
:*and ACK is a string called ''acknowledgement value''. By default the acknowledgement value is "ok" if the relay will execute the <command >, "ko" otherwise.

'''Remarks:'''
* Many meta-commands may have other acknowledgements than "ok" or "ko" (or none, for !pong). Their definitions supersede this specification.
* Note that unknown meta-commands cannot be executed and thus wil be acknowledged by "ko".
* Known meta-commands which are sent with not enough parameters or parameters with types incompatible with those in the definition known by the relay also cannot be executed and will also be acknowledged by "ko". (ex: the relay knows !x-who/key, but receives !x-who/integer/string).

===On executing commands===
Summary of differences with original RLVR:
* explanation on how to handle meta-commands with variable number of parameters,
* the relay knows commands in both core specification and x-tensions,
* clarification on multi-controller relays.

====Relay side====
'''Requirements:'''
* If a <rlvcommand> is acknowledged with value "ok", the relay ensures the viewer is affected the same way as if the LSL instruction llOwnerSay(<rlvcommand>) was executed by a script in a primitive that handles only one controller.
* When processing a <metacommand>, if the relay knows at least one definition of '!'+METACOMMANDNAME for which the received <metacommandarguments> provide enough parameters, then it will be handled according to the definition handling the most parameters among the latter. Extra parameters are ignored.
* A relays knows the following meta-command definitions:
:*[[#Core meta-commands and associated mechanisms|definitions listed in the core requirements]]
:*all definitions included in [[LSL_Protocol/Restrained_Love_Relay/Comparison|x-tensions]] announced by the relay.
* When acknowledging a <metacommand> by anything else than "ko", the relay commits itself to execute it.

'''Remarks:'''
* For first requirement, it must be understood that the reference behavior is that the relay would have if it had one controller per prim. However handling several controllers from one unique prim is possible but requires taking care that different controllers do not interfere with each other, releasing each other's restrictions, for instance.
* For the second requirement, the word "handled" means that if the meta-command with these parameters is known, then requirements in known definition cannot be ignored. Sometimes, this can imply that the meta-command cannot be refused, for instance.

====Controller side====
* The controller can send any command within allowed syntax.
* Only commands described in this specification and commands belonging to x-tensions announced by the relay are guaranteed to be understood by the relay. If not understood, the relay will just answer "ko", do nothing and skip to the next command.

===Protocol session===
Summary of differences with original RLVR:
* it is now clear when a session starts and stops (and what a session is!)
* it is clear when to expect interactive dialogs (and how to avoid spamming relay wearers with blue dialogs)
* no session for unreachable controllers (answer to ping is mandatory to ensure session persistence)

====Definitions====
* During an execution of the RLVR protocol, a relay and a controller establish a '''session''' together. A relay may manage several sessions with several controllers. Likewise, a controller could establish sessions with several relays.
* Restrictions on a relay wearer are relative to a session. So are most other variables (authorization state, key of the controller, ... ).
* A session is '''Opened''' whenever the relay accepts a RLVR command from a controller.
* A session is '''Closed''' (or '''released''') as soon as the relay forgets every variables and releases all restrictions pertaining to that session.
* A session is '''Locked''' whenever it holds active restrictions.
* A session is '''Authed''' if the controller has been allowed to control the relay (not only store some variables with no consequence). Once authed, no interactive "ask" dialog should pop up anymore concerning this session. Most commands should now normally be accepted (and maybe a few automatically rejected).
* A controller is called '''reachable''' if it can receive messages from the relay and can prove it by answering [[#ping/!pong|ping]] requests from the relay. By "can", it is meant by the method of communication agreed upon by the relay and controller (by default: chat messages sent on RLVR channel by llRegionSayTo). X-tensions such as email and delay can modify what is meant by reachable.

====Relay side requirements====
On closing sessions:
*Closing a session clears all RLV restrictions that belong only to that session, clears all session variables and disables all restrictions relative to that session. This MUST happen on the following events and no other:
:*on executing !release (received from the controller, or relay-triggered as in a safeword, see [[#!release]])
:*on noticing the controller is not reachable
:*on timeout, if the session is not Locked
*Sessions that are not locked MUST be closed after a reasonable timeout.

On interactive Auth:
*Unless specified otherwise (see !x-who), no command can trigger an interactive dialog unless the command requires an Authed session and the session is not already Authed.
*Relay implementations MAY require an authed session for all <rlvcommand>'s of the form @xxx=force, @xxx=add and @xxx=n, and for meta-commands whose specifications say it is allowed.
*Other RLV commands MUST automatically accepted or rejected by any relay.

On removing and adding restrictions:
* Commands that remove restrictions are always accepted (RLV @...=<channel_number>, @clear[=...] and @...=y/rem commands, !release, and !x-.../clear[/...] meta-commands).
* No restriction can be released unless as the result of one of the above commands, or of closing a session.
*@xxx=n/add <rlvcommand>'s, after being accepted, add a restriction and therefore Lock the session.
*Some meta-commands described in x-tensions can also add restrictions and therefore Lock the session.

Reachability:
*A relay MUST provide a mechanism for checking that every controlling device is reachable. It is not specified whether this checking process should be automatic or manually triggered.

====Controller side requirements====
* A controller MUST eventually close any Locked session using the meta-command !release.

In particular, non-portable controllers should not let a Locked relay wearer run free out of reach. Moreover, any controller should either react to some kind of event that is bound to happen (timer expiration being the most common) or provide a user interface for closing the session. It should be clear at least to the person who set the trap how the victim will be released.

==Core meta-commands and associated mechanisms==

An ORG device MUST at least support the meta-commands !release, !pong, !version, !implversion and !x-orgversions described below and implement their associated mechanisms.

Particular meta-commands definitions and mechanisms may override general requirements above.

New in ORG compared to RLVR: !x-orgversions

===!release===
Sent by a controller, this command closes the session.

* !release obviously opens no session, requires no Auth and is not Locking.
* If there is an actual session to close, !release MUST be accepted by the relay and acknowledeged by "ok".
* On accepting !release, the relay erases all data pertaining to the session and disables all restrictions of the session.
* When a relay decides to close a session on its own (user safeword, for instance) and it is not due to the controller being unreachable, the relay must send the following acknowledgement message:
release,<controller_key>,!release,ok

When receiving the latter message, the controller should act accordingly, for instance by resetting itself and making itself ready for the next session.

Note that !release is not the same as @clear. @clear is interpreted by the relay as a RLV command and, as such, can only clear RLV restrictions. If RLV restrictions were the only restrictions of the session, then the session will be closed, but some x-tensions also define pure LSL based restrictions.

===ping/!pong===

The ping/!pong mechanism exists so that relays can check presence and responsiveness of a controller. This was primarily meant to be used on relay wearer relog, in order to reactivate all restrictions so that sessions persist on relog if the controller still exists and is ready to continue the session.

''!pong'' cannot require auth and does not lock a session

We call ''ping message'' a message from the relay, having the following syntax:
ping,<controller_key>,ping,ping
We call ''!pong message'' a message from the controller, having the following syntax:
ping,<relay_key>,!pong

====Relay side====
*A relay SHOULD NOT send an acknowledgement in response to ''!pong''.
*A ping message can be sent any time by the relay to a known controller.
*On wearer relog, for each existing Locked session, the relay must send a ping message to the session controller.
*When a !pong message is received from a controller, if it was a reply to a previous ping message:
:#if the session RLV restrictions contain unsit and the avatar was sitting on some object when the restriction was applied, then the relay MUST force the avatar to sit back on the same object (if still existing);
:#the relay MUST make sure all restrictions belonging to the session are made active again.
*If a ping message is sent and is not answered by the controller, then the relay closes the session.

Note that the relay is responsible for storing restrictions and the key of the sit target across sessions, not the controller.

====Controller side====
*Unless it does not matter that the relay could close the session (or for another reason, the controller knows the relay will not close it), a controller SHOULD listen to ping messages and answer any ping message with a !pong message.
*A controller should ignore ping requests from relays it is not ready to handle.

Note controller don't have to poll for relay presence to resume a session but should just listen for ping messages instead. The relay should have stored all restrictions and handle sitting back to whatever furniture the relay wearer was tied up to.

Concerning the second bullet: for instance, if the controller is a furniture which is already in use by another relay wearer, it would be cause dysfunctions to let the pinging relay restore the restrictions without letting its wearer sit on the furniture. Or if the controller is not stateless and the state for the pinging relay has not been saved before, resuming the session from the initial state might be inconsistant.

===!version===
The purpose of this meta-command is to query the version of the RLVR protocol supported by a relay.

* !version opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !version with the version number of the RLVR protocol it supports ("1100" here, since ORG 0004 includes RLVR 1.100).

Note this is the most common command for a controller to scan for nearby relays, as non-ORG relays also accept this command and answer it the way described above.

===!implversion===
The purpose of this meta-command is to query the name and version of the relay implementation.

* !implversion opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !implversion with its implementation version string... which can be any string.

It is recommended this string includes the following elements:
* the relay name/brand/identifier,
* the version number of that relay name/brand/identifier,
* at the beginning, the string prefix "ORG=0004/"
The latter is convenient for checking for ORG compatibility using a command even non-ORG relay should understand.

===!x-orgversions===

This meta-command's purpose is to make it possible for the controller to have detailed informations on the protocol the relay supports. First the version of the ORG consolidated protocol, second the list of supported optional x-tensions, also with their version numbers.

'''Example:'''
C<->R
-> query,rUUID,!x-orgversions
<- query,cUUID,!x-orgversions,ORG=0004/who=002/email=006

'''Requirements:'''
* !x-orgversions should always be accepted with no Auth required, it does not open a session or Lock one.
* The acknowledgement value in a reply to !x-orgversions is a "/"-list of items of the form <package>=<version>. The first <package> is always "ORG" (representing the core specification package of ORG relays), its version string is the version of the specification (4 digits). The other packages are x-tension names, whose version string is 3 digits.
* If several incompatible versions of a same x-tension are supported, they must be listed ordered by version number. Ex: ORG=0004/who=002/email=005/email=006. If versions are backward compatible, only the last version should be reported.
* By announcing an x-tension, the relay commits itself to comply to all requirements of its specification.

'''Remarks:'''
* In a controller, it is however recommended to use !x-orgversions as soon as possible in order to avoid sending unsupported and useless metacommands later on.
* In the acknowledgement message, x-tension names are listed, not meta-command names (as one x-tension can have several meta-commands). Thus listed names do not include the prefix "!x-".
* x-tensions do not have to be standards defined by ORG but can also be proprietary. We recommend that the x-tension name then contains the name of the brand who proposes it.

===Other meta-commands===

Commands not listed here can belong to one of the following categories:
# (unlikely) commands from a future revision of Marine Kelley's original RLVR protocol.
# (more likely but not that much!) core commands from a future revision of ORG
# (very likely) commands from optional x-tensions
# proprietary commands

ORG intends for its successive versions to be backward compatible. Therefore ORG relays handle all unknown meta-commands.

We also intend for future versions of ORG consolidated protocol to include last version of original RLVR protocol, hence the prefix "!x-" for all meta-commands comming from ORG, which ensures there will be reasonably no collision.

For the same reason, we require that proprietary commands use an obvious prefix such as "!a-" or "!b-", and so on. Not doing so would prevent ensuring backward compatibility, hence a relay or controller who would use proprietary commands with wrong prefixes are not ORG compliant.

LSL Protocol/Restrained Love Open Relay Group/ORG Requirements/0004 draft

2011-06-27T16:05:55Z

Satomi Ahn: /* Consolidated RLVR protocol */

{{ORG_Restrained_Life_Relay_Specs_TOC}}
STATUS: draft

VERSION: 0004

==Summary==

This page is a list of requirements for a relay or an in-world device to have the right to be called "ORG compliant". It is mostly about adding support for an ORG-centered informational metacommand and specifying Marine Kelley's RLVR protocol a bit more that it is now, while of course preserving full compatibility.

For a quick overview of the motivations and general working of this protocol and a few examples, we refer the reader to [[LSL_Protocol/Restrained_Love_Relay/Specification|the original specification page by Marine Kelley]].

If you are making furniture, traps, or other RLVR controllers and you are not interested in what [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] can offer, then you can stick with the original specification by Marine Kelley and still be compatible with [[LSL_Protocol/Restrained_Love_Relay/Comparison|ORG relays]]. However, to have the right to call your controller "ORG compatible", there are still a few light additional requirements such as:
* using only [[llRegionSayTo]] for communications with the relay,
* not spamming the RLVR channel with messages that do not belong to the protocol,
* and remain responsive to ping messages at every time if you want the session to remain locked.

If you are interested in [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|ORG x-tensions]], then you should also read the part about [[#!x-orgversions|!x-orgversions]].

If you are making a relay, sorry we are afraid you will have to read all this page.

==Definition of an ORG device==

A RLVR device is compliant with ORG specifications if it implements the consolidated RLVR protocol described below along with the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] it announces supporting.

Note in particular that
* the consolidated protocol is backward compatible with [[LSL_Protocol/Restrained_Love_Relay/Specification|Marine Kelley's RLVR protocol version 1.100]] but resolves most loose ends of that document;
* ORG relays handle controller messages using wildcards (sent to all relays within range)
* one-to-one chat messages (not using a wildcard) are sent by using [[llRegionSayTo]] LSL function;
* there is an additional command, for a controller to query for optional x-tensions the relay supports.

Supported x-tensions can constrain the core specification (this document) even more, but cannot alter it or make it less constraining unless as a result of the relay executing a meta-command of this x-tension sent by the controller. Thus, although the protocol is extensible, a controller can always rely on the fact an ORG relay abides by the requirements in this document until it asks the relay to do otherwise.

ORG devices may be advertised by the use of the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/ORG_Logo|ORG logo]] for advertising compliance with ORG requirements. ORG devices makers are encouraged to do so.

==Consolidated RLVR protocol==
This consolidated RLVR protocol is roughly the same as the original RLVR protocol, minus a few embarassing loose ends.

Main differences are highlighted at the beginning of each subsection.
=== Protocol Syntax ===
Summary of differences with original RLVR:
* we force use of llRegionSayTo,
* we explicitly forbid incorrect syntax on the relay channel
* the relay is supposed to ignore bad commands
* wildcards are supported

==== Definitions ====
* The '''Restrained Love Relay (RLVR) protocol''' implies two partners (SL objects): the '''relay''', attachment worn by the avatar commands are intended for, and a '''controller''', which sends commands to the relay.

* The goal of the protocol is to force the relay wearer to make perform actions and to toggle restrictions on their behavior. Both actions and restrictions can be enforced either through use of viewer hooks ([[LSL_Protocol/RestrainedLoveAPI|Restrained Love API]], or RLV) or through LSL scripting.

* Hence we distinguish between "'''RLV commands'''", starting with "@", which are commands following the syntax of the RLV API and which will ultimately be forwarded to the viewer, and "'''meta-commands'''", starting with "!", which are meant to be interpreted by LSL functions.

====Requirements====
RLVR protocol consists of messages exchanged between relay and controller
* on channel -1812221819 (called '''RLVR channel'''),
* using the LSL function [[llRegionSayTo]] (except for <c_msg>'s using a wildcard),
* all sent from the same prim of the controller or relay (within a [[#Protocol session|session]])
* and having the following syntax (non-terminal <c_msg> for controller messages/'''command messages''' and <r_msg> for relay messages/'''acknowledgement messages'''):

<c_msg> ::= IDENT "," KEY "," <commands>
<r_msg> ::= IDENT "," KEY "," <command> "," ACK
<commands> ::= <command> | <command> "|" <commands>
<command> ::= <rlvcommand> | <metacommand>
<rlvcommand> ::= "@" RLVCOMMAND
<metacommand> ::= "!" METACOMMANDNAME <metacommandarguments>
<metacommandarguments> ::= "" | "/" ARG <metacommandarguments>

where we explicit the different terminal tokens:
IDENT: any string without ","
KEY: any UUID
ACK: any string without ","
RLVCOMMAND: any string without ","
METACOMMANDNAME: any string without "/" and ","
ARG: any string without "/" and ","

* Relays can only send <r_msg>'s, and controllers <c_msg>'s. Nothing else is allowed on RLVR channel.
* In <c_msg>, KEY is always either the uuid of the relay wearer or ffffffff-ffff-ffff-ffff-ffffffffffff ('''wildcard''') if it is a message intended for all relays who can hear it.
* In <r_msg>, KEY is always the uuid of the controller.

====On the relay side only====
'''Further requirements:'''
*A relay MUST ignore any message on RLVR channel which is not a <c_msg> with KEY being either the key of the avatar wearing the relay or ffffffff-ffff-ffff-ffff-ffffffffffff.
Then, for every <command>:
* if <command> is neither a valid <rlvcommand> or <metacommand>, the relay must ignore it and process the next <command>'s;
* if <command> is a <rlvcommand> or a <metacommand>, the relay MUST send back to the controller a <r_msg> (see above) such that:
:*IDENT is the same as IDENT in the <c_msg> being processed,
:*<command> is the subcommand being processed
:*and ACK is a string called ''acknowledgement value''. By default the acknowledgement value is "ok" if the relay will execute the <command >, "ko" otherwise.

'''Remarks:'''
* Many meta-commands may have other acknowledgements than "ok" or "ko" (or none, for !pong). Their definitions supersede this specification.
* Note that unknown meta-commands cannot be executed and thus wil be acknowledged by "ko".
* Known meta-commands which are sent with not enough parameters or parameters with types incompatible with those in the definition known by the relay also cannot be executed and will also be acknowledged by "ko". (ex: the relay knows !x-who/key, but receives !x-who/integer/string).

===On executing commands===
Summary of differences with original RLVR:
* explanation on how to handle meta-commands with variable number of parameters,
* the relay knows commands in both core specification and x-tensions,
* clarification on multi-controller relays.

====Relay side====
'''Requirements:'''
* If a <rlvcommand> is acknowledged with value "ok", the relay ensures the viewer is affected the same way as if the LSL instruction llOwnerSay(<rlvcommand>) was executed by a script in a primitive that handles only one controller.
* When processing a <metacommand>, if the relay knows at least one definition of '!'+METACOMMANDNAME for which the received <metacommandarguments> provide enough parameters, then it will be handled according to the definition handling the most parameters among the latter. Extra parameters are ignored.
* A relays knows the following meta-command definitions:
:*[[#Core meta-commands and associated mechanisms|definitions listed in the core requirements]]
:*all definitions included in [[LSL_Protocol/Restrained_Love_Relay/Comparison|x-tensions]] announced by the relay.
* When acknowledging a <metacommand> by anything else than "ko", the relay commits itself to execute it.

'''Remarks:'''
* For first requirement, it must be understood that the reference behavior is that the relay would have if it had one controller per prim. However handling several controllers from one unique prim is possible but requires taking care that different controllers do not interfere with each other, releasing each other's restrictions, for instance.
* For the second requirement, the word "handled" means that if the meta-command with these parameters is known, then requirements in known definition cannot be ignored. Sometimes, this can imply that the meta-command cannot be refused, for instance.

====Controller side====
* The controller can send any command within allowed syntax.
* Only commands described in this specification and commands belonging to x-tensions announced by the relay are guaranteed to be understood by the relay. If not understood, the relay will just answer "ko", do nothing and skip to the next command.

===Protocol session===
Summary of differences with original RLVR:
* it is now clear when a session starts and stops (and what a session is!)
* it is clear when to expect interactive dialogs (and how to avoid spamming relay wearers with blue dialogs)
* no session for unreachable controllers (answer to ping is mandatory to ensure session persistence)

====Definitions====
* During an execution of the RLVR protocol, a relay and a controller establish a '''session''' together. A relay may manage several sessions with several controllers. Likewise, a controller could establish sessions with several relays.
* Restrictions on a relay wearer are relative to a session. So are most other variables (authorization state, key of the controller, ... ).
* A session is '''Opened''' whenever the relay accepts a RLVR command from a controller.
* A session is '''Closed''' (or '''released''') as soon as the relay forgets every variables and releases all restrictions pertaining to that session.
* A session is '''Locked''' whenever it holds active restrictions.
* A session is '''Authed''' if the controller has been allowed to control the relay (not only store some variables with no consequence). Once authed, no interactive "ask" dialog should pop up anymore concerning this session. Most commands should now normally be accepted (and maybe a few automatically rejected).
* A controller is called '''reachable''' if it can receive messages from the relay and can prove it by answering [[#ping/!pong|ping]] requests from the relay. By "can", it is meant by the method of communication agreed upon by the relay and controller (by default: chat messages sent on RLVR channel by llRegionSayTo). X-tensions such as email and delay can modify what is meant by reachable.

====Relay side requirements====
On closing sessions:
*Closing a session clears all RLV restrictions that belong only to that session, clears all session variables and disables all restrictions relative to that session. This MUST happen on the following events and no other:
:*on executing !release (received from the controller, or relay-triggered as in a safeword, see [[#!release]])
:*on noticing the controller is not reachable
:*on timeout, if the session is not Locked
*Sessions that are not locked MUST be closed after a reasonable timeout.

On interactive Auth:
*Unless specified otherwise (see !x-who), no command can trigger an interactive dialog unless the command requires an Authed session and the session is not already Authed.
*Relay implementations MAY require an authed session for all <rlvcommand>'s of the form @xxx=force, @xxx=add and @xxx=n, and for meta-commands whose specifications say it is allowed.
*Other RLV commands MUST automatically accepted or rejected by any relay.

On removing and adding restrictions:
* Commands that remove restrictions are always accepted (RLV @...=<channel_number>, @clear[=...] and @...=y/rem commands, !release, and !x-.../clear[/...] meta-commands).
* No restriction can be released unless as the result of one of the above commands, or of closing a session.
*@xxx=n/add <rlvcommand>'s, after being accepted, add a restriction and therefore Lock the session.
*Some meta-commands described in x-tensions can also add restrictions and therefore Lock the session.

Reachability:
*A relay MUST provide a mechanism for checking that every controlling device is reachable. It is not specified whether this checking process should be automatic or manually triggered.

====Controller side requirements====
* A controller MUST eventually close any Locked session using the meta-command !release.

In particular, non-portable controllers should not let a Locked relay wearer run free out of reach. Moreover, any controller should either react to some kind of event that is bound to happen (timer expiration being the most common) or provide a user interface for closing the session. It should be clear at least to the person who set the trap how the victim will be released.

==Core meta-commands and associated mechanisms==

An ORG device MUST at least support the meta-commands !release, !pong, !version, !implversion and !x-orgversions described below and implement their associated mechanisms.

Particular meta-commands definitions and mechanisms may override general requirements above.

New in ORG compared to RLVR: !x-orgversions

===!release===
Sent by a controller, this command closes the session.

* !release obviously opens no session, requires no Auth and is not Locking.
* If there is an actual session to close !release MUST be accepted by the relay and acknowledeged by "ok".
* On accepting !release, the relay erases all data pertaining to the session and disables all restrictions of the session.
* When a relay decides to close a session on its own (user safeword, for instance) and it is not due to the controller being unreachable, the relay must send the following acknowledgement message:
release,<controller_key>,!release,ok

When receiving the latter message, the controller should act accordingly, for instance by resetting itself and making itself ready for the next session.

Note that !release is not the same as @clear. @clear is interpreted by the relay as a RLV command and, as such, can only clear RLV restrictions. If RLV restrictions were the only restrictions of the session, then the session will be closed, but some x-tensions also define pure LSL based restrictions.

===ping/!pong===

The ping/!pong mechanism exists so that relays can check presence and responsiveness of a controller. This was primarily meant to be used on relay wearer relog, in order to reactivate all restrictions so that sessions persist on relog if the controller still exists and is ready to continue the session.

''!pong'' cannot require auth and does not lock a session

We call ''ping message'' a message from the relay, having the following syntax:
ping,<controller_key>,ping,ping
We call ''!pong message'' a message from the controller, having the following syntax:
ping,<relay_key>,!pong

====Relay side====
*A relay SHOULD NOT send an acknowledgement in response to ''!pong''.
*A ping message can be sent any time by the relay to a known controller.
*On wearer relog, for each existing Locked session, the relay must send a ping message to the session controller.
*When a !pong message is received from a controller, if it was a reply to a previous ping message:
:#if the session RLV restrictions contain unsit and the avatar was sitting on some object when the restriction was applied, then the relay MUST force the avatar to sit back on the same object (if still existing);
:#the relay MUST make sure all restrictions belonging to the session are made active again.
*If a ping message is sent and is not answered by the controller, then the relay closes the session.

Note that the relay is responsible for storing restrictions and the key of the sit target across sessions, not the controller.

====Controller side====
*Unless it does not matter that the relay could close the session (or for another reason, the controller knows the relay will not close it), a controller SHOULD listen to ping messages and answer any ping message with a !pong message.
*A controller should ignore ping requests from relays it is not ready to handle.

Note controller don't have to poll for relay presence to resume a session but should just listen for ping messages instead. The relay should have stored all restrictions and handle sitting back to whatever furniture the relay wearer was tied up to.

Concerning the second bullet: for instance, if the controller is a furniture which is already in use by another relay wearer, it would be cause dysfunctions to let the pinging relay restore the restrictions without letting its wearer sit on the furniture. Or if the controller is not stateless and the state for the pinging relay has not been saved before, resuming the session from the initial state might be inconsistant.

===!version===
The purpose of this meta-command is to query the version of the RLVR protocol supported by a relay.

* !version opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !version with the version number of the RLVR protocol it supports ("1100" here, since ORG 0004 includes RLVR 1.100).

Note this is the most common command for a controller to scan for nearby relays, as non-ORG relays also accept this command and answer it the way described above.

===!implversion===
The purpose of this meta-command is to query the name and version of the relay implementation.

* !implversion opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !implversion with its implementation version string... which can be any string.

It is recommended this string includes the following elements:
* the relay name/brand/identifier,
* the version number of that relay name/brand/identifier,
* at the beginning, the string prefix "ORG=0004/"
The latter is convenient for checking for ORG compatibility using a command even non-ORG relay should understand.

===!x-orgversions===

This meta-command's purpose is to make it possible for the controller to have detailed informations on the protocol the relay supports. First the version of the ORG consolidated protocol, second the list of supported optional x-tensions, also with their version numbers.

'''Example:'''
C<->R
-> query,rUUID,!x-orgversions
<- query,cUUID,!x-orgversions,ORG=0004/who=002/email=006

'''Requirements:'''
* !x-orgversions should always be accepted with no Auth required, it does not open a session or Lock one.
* The acknowledgement value in a reply to !x-orgversions is a "/"-list of items of the form <package>=<version>. The first <package> is always "ORG" (representing the core specification package of ORG relays), its version string is the version of the specification (4 digits). The other packages are x-tension names, whose version string is 3 digits.
* If several incompatible versions of a same x-tension are supported, they must be listed ordered by version number. Ex: ORG=0004/who=002/email=005/email=006. If versions are backward compatible, only the last version should be reported.
* By announcing an x-tension, the relay commits itself to comply to all requirements of its specification.

'''Remarks:'''
* In a controller, it is however recommended to use !x-orgversions as soon as possible in order to avoid sending unsupported and useless metacommands later on.
* In the acknowledgement message, x-tension names are listed, not meta-command names (as one x-tension can have several meta-commands). Thus listed names do not include the prefix "!x-".
* x-tensions do not have to be standards defined by ORG but can also be proprietary. We recommend that the x-tension name then contains the name of the brand who proposes it.

===Other meta-commands===

Commands not listed here can belong to one of the following categories:
# (unlikely) commands from a future revision of Marine Kelley's original RLVR protocol.
# (more likely but not that much!) core commands from a future revision of ORG
# (very likely) commands from optional x-tensions
# proprietary commands

ORG intends for its successive versions to be backward compatible. Therefore ORG relays handle all unknown meta-commands.

We also intend for future versions of ORG consolidated protocol to include last version of original RLVR protocol, hence the prefix "!x-" for all meta-commands comming from ORG, which ensures there will be reasonably no collision.

For the same reason, we require that proprietary commands use an obvious prefix such as "!a-" or "!b-", and so on. Not doing so would prevent ensuring backward compatibility, hence a relay or controller who would use proprietary commands with wrong prefixes are not ORG compliant.

LSL Protocol/Restrained Love Open Relay Group/ORG Requirements/0004 draft

2011-06-27T15:54:32Z

Satomi Ahn: /* Requirements */

{{ORG_Restrained_Life_Relay_Specs_TOC}}
STATUS: draft

VERSION: 0004

==Summary==

This page is a list of requirements for a relay or an in-world device to have the right to be called "ORG compliant". It is mostly about adding support for an ORG-centered informational metacommand and specifying Marine Kelley's RLVR protocol a bit more that it is now, while of course preserving full compatibility.

For a quick overview of the motivations and general working of this protocol and a few examples, we refer the reader to [[LSL_Protocol/Restrained_Love_Relay/Specification|the original specification page by Marine Kelley]].

If you are making furniture, traps, or other RLVR controllers and you are not interested in what [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] can offer, then you can stick with the original specification by Marine Kelley and still be compatible with [[LSL_Protocol/Restrained_Love_Relay/Comparison|ORG relays]]. However, to have the right to call your controller "ORG compatible", there are still a few light additional requirements such as:
* using only [[llRegionSayTo]] for communications with the relay,
* not spamming the RLVR channel with messages that do not belong to the protocol,
* and remain responsive to ping messages at every time if you want the session to remain locked.

If you are interested in [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|ORG x-tensions]], then you should also read the part about [[#!x-orgversions|!x-orgversions]].

If you are making a relay, sorry we are afraid you will have to read all this page.

==Definition of an ORG device==

A RLVR device is compliant with ORG specifications if it implements the consolidated RLVR protocol described below along with the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] it announces supporting.

Note in particular that
* the consolidated protocol is backward compatible with [[LSL_Protocol/Restrained_Love_Relay/Specification|Marine Kelley's RLVR protocol version 1.100]] but resolves most loose ends of that document;
* ORG relays handle controller messages using wildcards (sent to all relays within range)
* one-to-one chat messages (not using a wildcard) are sent by using [[llRegionSayTo]] LSL function;
* there is an additional command, for a controller to query for optional x-tensions the relay supports.

Supported x-tensions can constrain the core specification (this document) even more, but cannot alter it or make it less constraining unless as a result of the relay executing a meta-command of this x-tension sent by the controller. Thus, although the protocol is extensible, a controller can always rely on the fact an ORG relay abides by the requirements in this document until it asks the relay to do otherwise.

ORG devices may be advertised by the use of the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/ORG_Logo|ORG logo]] for advertising compliance with ORG requirements. ORG devices makers are encouraged to do so.

==Consolidated RLVR protocol==

=== Protocol Syntax ===
Summary of differences with original RLVR:
* we force use of llRegionSayTo,
* we explicitly forbid incorrect syntax on the relay channel
* the relay is supposed to ignore bad commands
* wildcards are supported

==== Definitions ====
* The '''Restrained Love Relay (RLVR) protocol''' implies two partners (SL objects): the '''relay''', attachment worn by the avatar commands are intended for, and a '''controller''', which sends commands to the relay.

* The goal of the protocol is to force the relay wearer to make perform actions and to toggle restrictions on their behavior. Both actions and restrictions can be enforced either through use of viewer hooks ([[LSL_Protocol/RestrainedLoveAPI|Restrained Love API]], or RLV) or through LSL scripting.

* Hence we distinguish between "'''RLV commands'''", starting with "@", which are commands following the syntax of the RLV API and which will ultimately be forwarded to the viewer, and "'''meta-commands'''", starting with "!", which are meant to be interpreted by LSL functions.

====Requirements====
RLVR protocol consists of messages exchanged between relay and controller
* on channel -1812221819 (called '''RLVR channel'''),
* using the LSL function [[llRegionSayTo]] (except for <c_msg>'s using a wildcard),
* all sent from the same prim of the controller or relay (within a [[#Protocol session|session]])
* and having the following syntax (non-terminal <c_msg> for controller messages/'''command messages''' and <r_msg> for relay messages/'''acknowledgement messages'''):

<c_msg> ::= IDENT "," KEY "," <commands>
<r_msg> ::= IDENT "," KEY "," <command> "," ACK
<commands> ::= <command> | <command> "|" <commands>
<command> ::= <rlvcommand> | <metacommand>
<rlvcommand> ::= "@" RLVCOMMAND
<metacommand> ::= "!" METACOMMANDNAME <metacommandarguments>
<metacommandarguments> ::= "" | "/" ARG <metacommandarguments>

where we explicit the different terminal tokens:
IDENT: any string without ","
KEY: any UUID
ACK: any string without ","
RLVCOMMAND: any string without ","
METACOMMANDNAME: any string without "/" and ","
ARG: any string without "/" and ","

* Relays can only send <r_msg>'s, and controllers <c_msg>'s. Nothing else is allowed on RLVR channel.
* In <c_msg>, KEY is always either the uuid of the relay wearer or ffffffff-ffff-ffff-ffff-ffffffffffff ('''wildcard''') if it is a message intended for all relays who can hear it.
* In <r_msg>, KEY is always the uuid of the controller.

====On the relay side only====
'''Further requirements:'''
*A relay MUST ignore any message on RLVR channel which is not a <c_msg> with KEY being either the key of the avatar wearing the relay or ffffffff-ffff-ffff-ffff-ffffffffffff.
Then, for every <command>:
* if <command> is neither a valid <rlvcommand> or <metacommand>, the relay must ignore it and process the next <command>'s;
* if <command> is a <rlvcommand> or a <metacommand>, the relay MUST send back to the controller a <r_msg> (see above) such that:
:*IDENT is the same as IDENT in the <c_msg> being processed,
:*<command> is the subcommand being processed
:*and ACK is a string called ''acknowledgement value''. By default the acknowledgement value is "ok" if the relay will execute the <command >, "ko" otherwise.

'''Remarks:'''
* Many meta-commands may have other acknowledgements than "ok" or "ko" (or none, for !pong). Their definitions supersede this specification.
* Note that unknown meta-commands cannot be executed and thus wil be acknowledged by "ko".
* Known meta-commands which are sent with not enough parameters or parameters with types incompatible with those in the definition known by the relay also cannot be executed and will also be acknowledged by "ko". (ex: the relay knows !x-who/key, but receives !x-who/integer/string).

===On executing commands===
Summary of differences with original RLVR:
* explanation on how to handle meta-commands with variable number of parameters,
* the relay knows commands in both core specification and x-tensions,
* clarification on multi-controller relays.

====Relay side====
'''Requirements:'''
* If a <rlvcommand> is acknowledged with value "ok", the relay ensures the viewer is affected the same way as if the LSL instruction llOwnerSay(<rlvcommand>) was executed by a script in a primitive that handles only one controller.
* When processing a <metacommand>, if the relay knows at least one definition of '!'+METACOMMANDNAME for which the received <metacommandarguments> provide enough parameters, then it will be handled according to the definition handling the most parameters among the latter. Extra parameters are ignored.
* A relays knows the following meta-command definitions:
:*[[#Core meta-commands and associated mechanisms|definitions listed in the core requirements]]
:*all definitions included in [[LSL_Protocol/Restrained_Love_Relay/Comparison|x-tensions]] announced by the relay.
* When acknowledging a <metacommand> by anything else than "ko", the relay commits itself to execute it.

'''Remarks:'''
* For first requirement, it must be understood that the reference behavior is that the relay would have if it had one controller per prim. However handling several controllers from one unique prim is possible but requires taking care that different controllers do not interfere with each other, releasing each other's restrictions, for instance.
* For the second requirement, the word "handled" means that if the meta-command with these parameters is known, then requirements in known definition cannot be ignored. Sometimes, this can imply that the meta-command cannot be refused, for instance.

====Controller side====
* The controller can send any command within allowed syntax.
* Only commands described in this specification and commands belonging to x-tensions announced by the relay are guaranteed to be understood by the relay. If not understood, the relay will just answer "ko", do nothing and skip to the next command.

===Protocol session===
Summary of differences with original RLVR:
* it is now clear when a session starts and stops (and what a session is!)
* it is clear when to expect interactive dialogs (and how to avoid spamming relay wearers with blue dialogs)
* no session for unreachable controllers (answer to ping is mandatory to ensure session persistence)

====Definitions====
* During an execution of the RLVR protocol, a relay and a controller establish a '''session''' together. A relay may manage several sessions with several controllers. Likewise, a controller could establish sessions with several relays.
* Restrictions on a relay wearer are relative to a session. So are most other variables (authorization state, key of the controller, ... ).
* A session is '''Opened''' whenever the relay accepts a RLVR command from a controller.
* A session is '''Closed''' (or '''released''') as soon as the relay forgets every variables and releases all restrictions pertaining to that session.
* A session is '''Locked''' whenever it holds active restrictions.
* A session is '''Authed''' if the controller has been allowed to control the relay (not only store some variables with no consequence). Once authed, no interactive "ask" dialog should pop up anymore concerning this session. Most commands should now normally be accepted (and maybe a few automatically rejected).
* A controller is called '''reachable''' if it can receive messages from the relay and can prove it by answering [[#ping/!pong|ping]] requests from the relay. By "can", it is meant by the method of communication agreed upon by the relay and controller (by default: chat messages sent on RLVR channel by llRegionSayTo). X-tensions such as email and delay can modify what is meant by reachable.

====Relay side requirements====
On closing sessions:
*Closing a session clears all RLV restrictions that belong only to that session, clears all session variables and disables all restrictions relative to that session. This MUST happen on the following events and no other:
:*on executing !release (received from the controller, or relay-triggered as in a safeword, see [[#!release]])
:*on noticing the controller is not reachable
:*on timeout, if the session is not Locked
*Sessions that are not locked MUST be closed after a reasonable timeout.

On interactive Auth:
*Unless specified otherwise (see !x-who), no command can trigger an interactive dialog unless the command requires an Authed session and the session is not already Authed.
*Relay implementations MAY require an authed session for all <rlvcommand>'s of the form @xxx=force, @xxx=add and @xxx=n, and for meta-commands whose specifications say it is allowed.
*Other RLV commands MUST automatically accepted or rejected by any relay.

On removing and adding restrictions:
* Commands that remove restrictions are always accepted (RLV @...=<channel_number>, @clear[=...] and @...=y/rem commands, !release, and !x-.../clear[/...] meta-commands).
* No restriction can be released unless as the result of one of the above commands, or of closing a session.
*@xxx=n/add <rlvcommand>'s, after being accepted, add a restriction and therefore Lock the session.
*Some meta-commands described in x-tensions can also add restrictions and therefore Lock the session.

Reachability:
*A relay MUST provide a mechanism for checking that every controlling device is reachable. It is not specified whether this checking process should be automatic or manually triggered.

====Controller side requirements====
* A controller MUST eventually close any Locked session using the meta-command !release.

In particular, non-portable controllers should not let a Locked relay wearer run free out of reach. Moreover, any controller should either react to some kind of event that is bound to happen (timer expiration being the most common) or provide a user interface for closing the session. It should be clear at least to the person who set the trap how the victim will be released.

==Core meta-commands and associated mechanisms==

An ORG device MUST at least support the meta-commands !release, !pong, !version, !implversion and !x-orgversions described below and implement their associated mechanisms.

Particular meta-commands definitions and mechanisms may override general requirements above.

New in ORG compared to RLVR: !x-orgversions

===!release===
Sent by a controller, this command closes the session.

* !release obviously opens no session, requires no Auth and is not Locking.
* If there is an actual session to close !release MUST be accepted by the relay and acknowledeged by "ok".
* On accepting !release, the relay erases all data pertaining to the session and disables all restrictions of the session.
* When a relay decides to close a session on its own (user safeword, for instance) and it is not due to the controller being unreachable, the relay must send the following acknowledgement message:
release,<controller_key>,!release,ok

When receiving the latter message, the controller should act accordingly, for instance by resetting itself and making itself ready for the next session.

Note that !release is not the same as @clear. @clear is interpreted by the relay as a RLV command and, as such, can only clear RLV restrictions. If RLV restrictions were the only restrictions of the session, then the session will be closed, but some x-tensions also define pure LSL based restrictions.

===ping/!pong===

The ping/!pong mechanism exists so that relays can check presence and responsiveness of a controller. This was primarily meant to be used on relay wearer relog, in order to reactivate all restrictions so that sessions persist on relog if the controller still exists and is ready to continue the session.

''!pong'' cannot require auth and does not lock a session

We call ''ping message'' a message from the relay, having the following syntax:
ping,<controller_key>,ping,ping
We call ''!pong message'' a message from the controller, having the following syntax:
ping,<relay_key>,!pong

====Relay side====
*A relay SHOULD NOT send an acknowledgement in response to ''!pong''.
*A ping message can be sent any time by the relay to a known controller.
*On wearer relog, for each existing Locked session, the relay must send a ping message to the session controller.
*When a !pong message is received from a controller, if it was a reply to a previous ping message:
:#if the session RLV restrictions contain unsit and the avatar was sitting on some object when the restriction was applied, then the relay MUST force the avatar to sit back on the same object (if still existing);
:#the relay MUST make sure all restrictions belonging to the session are made active again.
*If a ping message is sent and is not answered by the controller, then the relay closes the session.

Note that the relay is responsible for storing restrictions and the key of the sit target across sessions, not the controller.

====Controller side====
*Unless it does not matter that the relay could close the session (or for another reason, the controller knows the relay will not close it), a controller SHOULD listen to ping messages and answer any ping message with a !pong message.
*A controller should ignore ping requests from relays it is not ready to handle.

Note controller don't have to poll for relay presence to resume a session but should just listen for ping messages instead. The relay should have stored all restrictions and handle sitting back to whatever furniture the relay wearer was tied up to.

Concerning the second bullet: for instance, if the controller is a furniture which is already in use by another relay wearer, it would be cause dysfunctions to let the pinging relay restore the restrictions without letting its wearer sit on the furniture. Or if the controller is not stateless and the state for the pinging relay has not been saved before, resuming the session from the initial state might be inconsistant.

===!version===
The purpose of this meta-command is to query the version of the RLVR protocol supported by a relay.

* !version opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !version with the version number of the RLVR protocol it supports ("1100" here, since ORG 0004 includes RLVR 1.100).

Note this is the most common command for a controller to scan for nearby relays, as non-ORG relays also accept this command and answer it the way described above.

===!implversion===
The purpose of this meta-command is to query the name and version of the relay implementation.

* !implversion opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !implversion with its implementation version string... which can be any string.

It is recommended this string includes the following elements:
* the relay name/brand/identifier,
* the version number of that relay name/brand/identifier,
* at the beginning, the string prefix "ORG=0004/"
The latter is convenient for checking for ORG compatibility using a command even non-ORG relay should understand.

===!x-orgversions===

This meta-command's purpose is to make it possible for the controller to have detailed informations on the protocol the relay supports. First the version of the ORG consolidated protocol, second the list of supported optional x-tensions, also with their version numbers.

'''Example:'''
C<->R
-> query,rUUID,!x-orgversions
<- query,cUUID,!x-orgversions,ORG=0004/who=002/email=006

'''Requirements:'''
* !x-orgversions should always be accepted with no Auth required, it does not open a session or Lock one.
* The acknowledgement value in a reply to !x-orgversions is a "/"-list of items of the form <package>=<version>. The first <package> is always "ORG" (representing the core specification package of ORG relays), its version string is the version of the specification (4 digits). The other packages are x-tension names, whose version string is 3 digits.
* If several incompatible versions of a same x-tension are supported, they must be listed ordered by version number. Ex: ORG=0004/who=002/email=005/email=006. If versions are backward compatible, only the last version should be reported.
* By announcing an x-tension, the relay commits itself to comply to all requirements of its specification.

'''Remarks:'''
* In a controller, it is however recommended to use !x-orgversions as soon as possible in order to avoid sending unsupported and useless metacommands later on.
* In the acknowledgement message, x-tension names are listed, not meta-command names (as one x-tension can have several meta-commands). Thus listed names do not include the prefix "!x-".
* x-tensions do not have to be standards defined by ORG but can also be proprietary. We recommend that the x-tension name then contains the name of the brand who proposes it.

===Other meta-commands===

Commands not listed here can belong to one of the following categories:
# (unlikely) commands from a future revision of Marine Kelley's original RLVR protocol.
# (more likely but not that much!) core commands from a future revision of ORG
# (very likely) commands from optional x-tensions
# proprietary commands

ORG intends for its successive versions to be backward compatible. Therefore ORG relays handle all unknown meta-commands.

We also intend for future versions of ORG consolidated protocol to include last version of original RLVR protocol, hence the prefix "!x-" for all meta-commands comming from ORG, which ensures there will be reasonably no collision.

For the same reason, we require that proprietary commands use an obvious prefix such as "!a-" or "!b-", and so on. Not doing so would prevent ensuring backward compatibility, hence a relay or controller who would use proprietary commands with wrong prefixes are not ORG compliant.

LSL Protocol/Restrained Love Open Relay Group/ORG Requirements/0004 draft

2011-06-27T15:53:12Z

Satomi Ahn: /* Definition of an ORG device */

{{ORG_Restrained_Life_Relay_Specs_TOC}}
STATUS: draft

VERSION: 0004

==Summary==

This page is a list of requirements for a relay or an in-world device to have the right to be called "ORG compliant". It is mostly about adding support for an ORG-centered informational metacommand and specifying Marine Kelley's RLVR protocol a bit more that it is now, while of course preserving full compatibility.

For a quick overview of the motivations and general working of this protocol and a few examples, we refer the reader to [[LSL_Protocol/Restrained_Love_Relay/Specification|the original specification page by Marine Kelley]].

If you are making furniture, traps, or other RLVR controllers and you are not interested in what [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] can offer, then you can stick with the original specification by Marine Kelley and still be compatible with [[LSL_Protocol/Restrained_Love_Relay/Comparison|ORG relays]]. However, to have the right to call your controller "ORG compatible", there are still a few light additional requirements such as:
* using only [[llRegionSayTo]] for communications with the relay,
* not spamming the RLVR channel with messages that do not belong to the protocol,
* and remain responsive to ping messages at every time if you want the session to remain locked.

If you are interested in [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|ORG x-tensions]], then you should also read the part about [[#!x-orgversions|!x-orgversions]].

If you are making a relay, sorry we are afraid you will have to read all this page.

==Definition of an ORG device==

A RLVR device is compliant with ORG specifications if it implements the consolidated RLVR protocol described below along with the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] it announces supporting.

Note in particular that
* the consolidated protocol is backward compatible with [[LSL_Protocol/Restrained_Love_Relay/Specification|Marine Kelley's RLVR protocol version 1.100]] but resolves most loose ends of that document;
* ORG relays handle controller messages using wildcards (sent to all relays within range)
* one-to-one chat messages (not using a wildcard) are sent by using [[llRegionSayTo]] LSL function;
* there is an additional command, for a controller to query for optional x-tensions the relay supports.

Supported x-tensions can constrain the core specification (this document) even more, but cannot alter it or make it less constraining unless as a result of the relay executing a meta-command of this x-tension sent by the controller. Thus, although the protocol is extensible, a controller can always rely on the fact an ORG relay abides by the requirements in this document until it asks the relay to do otherwise.

ORG devices may be advertised by the use of the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/ORG_Logo|ORG logo]] for advertising compliance with ORG requirements. ORG devices makers are encouraged to do so.

==Consolidated RLVR protocol==

=== Protocol Syntax ===
Summary of differences with original RLVR:
* we force use of llRegionSayTo,
* we explicitly forbid incorrect syntax on the relay channel
* the relay is supposed to ignore bad commands
* wildcards are supported

==== Definitions ====
* The '''Restrained Love Relay (RLVR) protocol''' implies two partners (SL objects): the '''relay''', attachment worn by the avatar commands are intended for, and a '''controller''', which sends commands to the relay.

* The goal of the protocol is to force the relay wearer to make perform actions and to toggle restrictions on their behavior. Both actions and restrictions can be enforced either through use of viewer hooks ([[LSL_Protocol/RestrainedLoveAPI|Restrained Love API]], or RLV) or through LSL scripting.

* Hence we distinguish between "'''RLV commands'''", starting with "@", which are commands following the syntax of the RLV API and which will ultimately be forwarded to the viewer, and "'''meta-commands'''", starting with "!", which are meant to be interpreted by LSL functions.

====Requirements====
RLVR protocol consists of messages exchanged between relay and controller
* on channel -1812221819 (called '''RLVR channel'''),
* using the LSL function [[llRegionSayTo]],
* all sent from the same prim of the controller or relay (within a [[#Protocol session|session]])
* and having the following syntax (non-terminal <c_msg> for controller messages/'''command messages''' and <r_msg> for relay messages/'''acknowledgement messages'''):

<c_msg> ::= IDENT "," KEY "," <commands>
<r_msg> ::= IDENT "," KEY "," <command> "," ACK
<commands> ::= <command> | <command> "|" <commands>
<command> ::= <rlvcommand> | <metacommand>
<rlvcommand> ::= "@" RLVCOMMAND
<metacommand> ::= "!" METACOMMANDNAME <metacommandarguments>
<metacommandarguments> ::= "" | "/" ARG <metacommandarguments>

where we explicit the different terminal tokens:
IDENT: any string without ","
KEY: any UUID
ACK: any string without ","
RLVCOMMAND: any string without ","
METACOMMANDNAME: any string without "/" and ","
ARG: any string without "/" and ","

* Relays can only send <r_msg>'s, and controllers <c_msg>'s. Nothing else is allowed on RLVR channel.
* In <c_msg>, KEY is always either the uuid of the relay wearer or ffffffff-ffff-ffff-ffff-ffffffffffff ('''wildcard''') if it is a message intended for all relays who can hear it.
* In <r_msg>, KEY is always the uuid of the controller.

====On the relay side only====
'''Further requirements:'''
*A relay MUST ignore any message on RLVR channel which is not a <c_msg> with KEY being either the key of the avatar wearing the relay or ffffffff-ffff-ffff-ffff-ffffffffffff.
Then, for every <command>:
* if <command> is neither a valid <rlvcommand> or <metacommand>, the relay must ignore it and process the next <command>'s;
* if <command> is a <rlvcommand> or a <metacommand>, the relay MUST send back to the controller a <r_msg> (see above) such that:
:*IDENT is the same as IDENT in the <c_msg> being processed,
:*<command> is the subcommand being processed
:*and ACK is a string called ''acknowledgement value''. By default the acknowledgement value is "ok" if the relay will execute the <command >, "ko" otherwise.

'''Remarks:'''
* Many meta-commands may have other acknowledgements than "ok" or "ko" (or none, for !pong). Their definitions supersede this specification.
* Note that unknown meta-commands cannot be executed and thus wil be acknowledged by "ko".
* Known meta-commands which are sent with not enough parameters or parameters with types incompatible with those in the definition known by the relay also cannot be executed and will also be acknowledged by "ko". (ex: the relay knows !x-who/key, but receives !x-who/integer/string).

===On executing commands===
Summary of differences with original RLVR:
* explanation on how to handle meta-commands with variable number of parameters,
* the relay knows commands in both core specification and x-tensions,
* clarification on multi-controller relays.

====Relay side====
'''Requirements:'''
* If a <rlvcommand> is acknowledged with value "ok", the relay ensures the viewer is affected the same way as if the LSL instruction llOwnerSay(<rlvcommand>) was executed by a script in a primitive that handles only one controller.
* When processing a <metacommand>, if the relay knows at least one definition of '!'+METACOMMANDNAME for which the received <metacommandarguments> provide enough parameters, then it will be handled according to the definition handling the most parameters among the latter. Extra parameters are ignored.
* A relays knows the following meta-command definitions:
:*[[#Core meta-commands and associated mechanisms|definitions listed in the core requirements]]
:*all definitions included in [[LSL_Protocol/Restrained_Love_Relay/Comparison|x-tensions]] announced by the relay.
* When acknowledging a <metacommand> by anything else than "ko", the relay commits itself to execute it.

'''Remarks:'''
* For first requirement, it must be understood that the reference behavior is that the relay would have if it had one controller per prim. However handling several controllers from one unique prim is possible but requires taking care that different controllers do not interfere with each other, releasing each other's restrictions, for instance.
* For the second requirement, the word "handled" means that if the meta-command with these parameters is known, then requirements in known definition cannot be ignored. Sometimes, this can imply that the meta-command cannot be refused, for instance.

====Controller side====
* The controller can send any command within allowed syntax.
* Only commands described in this specification and commands belonging to x-tensions announced by the relay are guaranteed to be understood by the relay. If not understood, the relay will just answer "ko", do nothing and skip to the next command.

===Protocol session===
Summary of differences with original RLVR:
* it is now clear when a session starts and stops (and what a session is!)
* it is clear when to expect interactive dialogs (and how to avoid spamming relay wearers with blue dialogs)
* no session for unreachable controllers (answer to ping is mandatory to ensure session persistence)

====Definitions====
* During an execution of the RLVR protocol, a relay and a controller establish a '''session''' together. A relay may manage several sessions with several controllers. Likewise, a controller could establish sessions with several relays.
* Restrictions on a relay wearer are relative to a session. So are most other variables (authorization state, key of the controller, ... ).
* A session is '''Opened''' whenever the relay accepts a RLVR command from a controller.
* A session is '''Closed''' (or '''released''') as soon as the relay forgets every variables and releases all restrictions pertaining to that session.
* A session is '''Locked''' whenever it holds active restrictions.
* A session is '''Authed''' if the controller has been allowed to control the relay (not only store some variables with no consequence). Once authed, no interactive "ask" dialog should pop up anymore concerning this session. Most commands should now normally be accepted (and maybe a few automatically rejected).
* A controller is called '''reachable''' if it can receive messages from the relay and can prove it by answering [[#ping/!pong|ping]] requests from the relay. By "can", it is meant by the method of communication agreed upon by the relay and controller (by default: chat messages sent on RLVR channel by llRegionSayTo). X-tensions such as email and delay can modify what is meant by reachable.

====Relay side requirements====
On closing sessions:
*Closing a session clears all RLV restrictions that belong only to that session, clears all session variables and disables all restrictions relative to that session. This MUST happen on the following events and no other:
:*on executing !release (received from the controller, or relay-triggered as in a safeword, see [[#!release]])
:*on noticing the controller is not reachable
:*on timeout, if the session is not Locked
*Sessions that are not locked MUST be closed after a reasonable timeout.

On interactive Auth:
*Unless specified otherwise (see !x-who), no command can trigger an interactive dialog unless the command requires an Authed session and the session is not already Authed.
*Relay implementations MAY require an authed session for all <rlvcommand>'s of the form @xxx=force, @xxx=add and @xxx=n, and for meta-commands whose specifications say it is allowed.
*Other RLV commands MUST automatically accepted or rejected by any relay.

On removing and adding restrictions:
* Commands that remove restrictions are always accepted (RLV @...=<channel_number>, @clear[=...] and @...=y/rem commands, !release, and !x-.../clear[/...] meta-commands).
* No restriction can be released unless as the result of one of the above commands, or of closing a session.
*@xxx=n/add <rlvcommand>'s, after being accepted, add a restriction and therefore Lock the session.
*Some meta-commands described in x-tensions can also add restrictions and therefore Lock the session.

Reachability:
*A relay MUST provide a mechanism for checking that every controlling device is reachable. It is not specified whether this checking process should be automatic or manually triggered.

====Controller side requirements====
* A controller MUST eventually close any Locked session using the meta-command !release.

In particular, non-portable controllers should not let a Locked relay wearer run free out of reach. Moreover, any controller should either react to some kind of event that is bound to happen (timer expiration being the most common) or provide a user interface for closing the session. It should be clear at least to the person who set the trap how the victim will be released.

==Core meta-commands and associated mechanisms==

An ORG device MUST at least support the meta-commands !release, !pong, !version, !implversion and !x-orgversions described below and implement their associated mechanisms.

Particular meta-commands definitions and mechanisms may override general requirements above.

New in ORG compared to RLVR: !x-orgversions

===!release===
Sent by a controller, this command closes the session.

* !release obviously opens no session, requires no Auth and is not Locking.
* If there is an actual session to close !release MUST be accepted by the relay and acknowledeged by "ok".
* On accepting !release, the relay erases all data pertaining to the session and disables all restrictions of the session.
* When a relay decides to close a session on its own (user safeword, for instance) and it is not due to the controller being unreachable, the relay must send the following acknowledgement message:
release,<controller_key>,!release,ok

When receiving the latter message, the controller should act accordingly, for instance by resetting itself and making itself ready for the next session.

Note that !release is not the same as @clear. @clear is interpreted by the relay as a RLV command and, as such, can only clear RLV restrictions. If RLV restrictions were the only restrictions of the session, then the session will be closed, but some x-tensions also define pure LSL based restrictions.

===ping/!pong===

The ping/!pong mechanism exists so that relays can check presence and responsiveness of a controller. This was primarily meant to be used on relay wearer relog, in order to reactivate all restrictions so that sessions persist on relog if the controller still exists and is ready to continue the session.

''!pong'' cannot require auth and does not lock a session

We call ''ping message'' a message from the relay, having the following syntax:
ping,<controller_key>,ping,ping
We call ''!pong message'' a message from the controller, having the following syntax:
ping,<relay_key>,!pong

====Relay side====
*A relay SHOULD NOT send an acknowledgement in response to ''!pong''.
*A ping message can be sent any time by the relay to a known controller.
*On wearer relog, for each existing Locked session, the relay must send a ping message to the session controller.
*When a !pong message is received from a controller, if it was a reply to a previous ping message:
:#if the session RLV restrictions contain unsit and the avatar was sitting on some object when the restriction was applied, then the relay MUST force the avatar to sit back on the same object (if still existing);
:#the relay MUST make sure all restrictions belonging to the session are made active again.
*If a ping message is sent and is not answered by the controller, then the relay closes the session.

Note that the relay is responsible for storing restrictions and the key of the sit target across sessions, not the controller.

====Controller side====
*Unless it does not matter that the relay could close the session (or for another reason, the controller knows the relay will not close it), a controller SHOULD listen to ping messages and answer any ping message with a !pong message.
*A controller should ignore ping requests from relays it is not ready to handle.

Note controller don't have to poll for relay presence to resume a session but should just listen for ping messages instead. The relay should have stored all restrictions and handle sitting back to whatever furniture the relay wearer was tied up to.

Concerning the second bullet: for instance, if the controller is a furniture which is already in use by another relay wearer, it would be cause dysfunctions to let the pinging relay restore the restrictions without letting its wearer sit on the furniture. Or if the controller is not stateless and the state for the pinging relay has not been saved before, resuming the session from the initial state might be inconsistant.

===!version===
The purpose of this meta-command is to query the version of the RLVR protocol supported by a relay.

* !version opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !version with the version number of the RLVR protocol it supports ("1100" here, since ORG 0004 includes RLVR 1.100).

Note this is the most common command for a controller to scan for nearby relays, as non-ORG relays also accept this command and answer it the way described above.

===!implversion===
The purpose of this meta-command is to query the name and version of the relay implementation.

* !implversion opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !implversion with its implementation version string... which can be any string.

It is recommended this string includes the following elements:
* the relay name/brand/identifier,
* the version number of that relay name/brand/identifier,
* at the beginning, the string prefix "ORG=0004/"
The latter is convenient for checking for ORG compatibility using a command even non-ORG relay should understand.

===!x-orgversions===

This meta-command's purpose is to make it possible for the controller to have detailed informations on the protocol the relay supports. First the version of the ORG consolidated protocol, second the list of supported optional x-tensions, also with their version numbers.

'''Example:'''
C<->R
-> query,rUUID,!x-orgversions
<- query,cUUID,!x-orgversions,ORG=0004/who=002/email=006

'''Requirements:'''
* !x-orgversions should always be accepted with no Auth required, it does not open a session or Lock one.
* The acknowledgement value in a reply to !x-orgversions is a "/"-list of items of the form <package>=<version>. The first <package> is always "ORG" (representing the core specification package of ORG relays), its version string is the version of the specification (4 digits). The other packages are x-tension names, whose version string is 3 digits.
* If several incompatible versions of a same x-tension are supported, they must be listed ordered by version number. Ex: ORG=0004/who=002/email=005/email=006. If versions are backward compatible, only the last version should be reported.
* By announcing an x-tension, the relay commits itself to comply to all requirements of its specification.

'''Remarks:'''
* In a controller, it is however recommended to use !x-orgversions as soon as possible in order to avoid sending unsupported and useless metacommands later on.
* In the acknowledgement message, x-tension names are listed, not meta-command names (as one x-tension can have several meta-commands). Thus listed names do not include the prefix "!x-".
* x-tensions do not have to be standards defined by ORG but can also be proprietary. We recommend that the x-tension name then contains the name of the brand who proposes it.

===Other meta-commands===

Commands not listed here can belong to one of the following categories:
# (unlikely) commands from a future revision of Marine Kelley's original RLVR protocol.
# (more likely but not that much!) core commands from a future revision of ORG
# (very likely) commands from optional x-tensions
# proprietary commands

ORG intends for its successive versions to be backward compatible. Therefore ORG relays handle all unknown meta-commands.

We also intend for future versions of ORG consolidated protocol to include last version of original RLVR protocol, hence the prefix "!x-" for all meta-commands comming from ORG, which ensures there will be reasonably no collision.

For the same reason, we require that proprietary commands use an obvious prefix such as "!a-" or "!b-", and so on. Not doing so would prevent ensuring backward compatibility, hence a relay or controller who would use proprietary commands with wrong prefixes are not ORG compliant.

LSL Protocol/Restrained Love Open Relay Group/ORG Requirements/0004 draft

2011-06-27T15:50:33Z

Satomi Ahn: /* !x-orgversions */

{{ORG_Restrained_Life_Relay_Specs_TOC}}
STATUS: draft

VERSION: 0004

==Summary==

This page is a list of requirements for a relay or an in-world device to have the right to be called "ORG compliant". It is mostly about adding support for an ORG-centered informational metacommand and specifying Marine Kelley's RLVR protocol a bit more that it is now, while of course preserving full compatibility.

For a quick overview of the motivations and general working of this protocol and a few examples, we refer the reader to [[LSL_Protocol/Restrained_Love_Relay/Specification|the original specification page by Marine Kelley]].

If you are making furniture, traps, or other RLVR controllers and you are not interested in what [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] can offer, then you can stick with the original specification by Marine Kelley and still be compatible with [[LSL_Protocol/Restrained_Love_Relay/Comparison|ORG relays]]. However, to have the right to call your controller "ORG compatible", there are still a few light additional requirements such as:
* using only [[llRegionSayTo]] for communications with the relay,
* not spamming the RLVR channel with messages that do not belong to the protocol,
* and remain responsive to ping messages at every time if you want the session to remain locked.

If you are interested in [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|ORG x-tensions]], then you should also read the part about [[#!x-orgversions|!x-orgversions]].

If you are making a relay, sorry we are afraid you will have to read all this page.

==Definition of an ORG device==

A RLVR device is compliant with ORG specifications if it implements the consolidated RLVR protocol described below along with the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] it announces supporting.

Note in particular that
* the consolidated protocol is backward compatible with [[LSL_Protocol/Restrained_Love_Relay/Specification|Marine Kelley's RLVR protocol version 1.100]] but resolves most loose ends of that document;
* ORG relays handle controller messages whose second field is ffffffff-ffff-ffff-ffff-ffffffffffff exactly the same as if it was the key of the wearer (NULL_KEY is a wildcard);
* one-to-one chat messages (not using a wildcard) are sent by using [[llRegionSayTo]] LSL function;
* there is an additional meta-command, !x-orgversions for a relay to announce supported x-tensions;
* each supported x-tension can imply other supported metacommands, ORG x-tensions meta-command all having names starting with prefix "!x-";
* other proprietary metacommands with prefix "!_-" (replace "_" by any letter that is not "x") can be supported;

Supported x-tensions can constrain the core specification (this document) even more, but cannot alter it or make it less constraining unless as a result of the relay executing a meta-command of this x-tension sent by the controller. Thus, although the protocol is extensible, a controller can always rely on the fact an ORG relay abides by the requirements in this document until it asks the relay to do otherwise.

ORG devices may be advertised by the use of the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/ORG_Logo|ORG logo]] for advertising compliance with ORG requirements. ORG devices makers are encouraged to do so.

==Consolidated RLVR protocol==

=== Protocol Syntax ===
Summary of differences with original RLVR:
* we force use of llRegionSayTo,
* we explicitly forbid incorrect syntax on the relay channel
* the relay is supposed to ignore bad commands
* wildcards are supported

==== Definitions ====
* The '''Restrained Love Relay (RLVR) protocol''' implies two partners (SL objects): the '''relay''', attachment worn by the avatar commands are intended for, and a '''controller''', which sends commands to the relay.

* The goal of the protocol is to force the relay wearer to make perform actions and to toggle restrictions on their behavior. Both actions and restrictions can be enforced either through use of viewer hooks ([[LSL_Protocol/RestrainedLoveAPI|Restrained Love API]], or RLV) or through LSL scripting.

* Hence we distinguish between "'''RLV commands'''", starting with "@", which are commands following the syntax of the RLV API and which will ultimately be forwarded to the viewer, and "'''meta-commands'''", starting with "!", which are meant to be interpreted by LSL functions.

====Requirements====
RLVR protocol consists of messages exchanged between relay and controller
* on channel -1812221819 (called '''RLVR channel'''),
* using the LSL function [[llRegionSayTo]],
* all sent from the same prim of the controller or relay (within a [[#Protocol session|session]])
* and having the following syntax (non-terminal <c_msg> for controller messages/'''command messages''' and <r_msg> for relay messages/'''acknowledgement messages'''):

<c_msg> ::= IDENT "," KEY "," <commands>
<r_msg> ::= IDENT "," KEY "," <command> "," ACK
<commands> ::= <command> | <command> "|" <commands>
<command> ::= <rlvcommand> | <metacommand>
<rlvcommand> ::= "@" RLVCOMMAND
<metacommand> ::= "!" METACOMMANDNAME <metacommandarguments>
<metacommandarguments> ::= "" | "/" ARG <metacommandarguments>

where we explicit the different terminal tokens:
IDENT: any string without ","
KEY: any UUID
ACK: any string without ","
RLVCOMMAND: any string without ","
METACOMMANDNAME: any string without "/" and ","
ARG: any string without "/" and ","

* Relays can only send <r_msg>'s, and controllers <c_msg>'s. Nothing else is allowed on RLVR channel.
* In <c_msg>, KEY is always either the uuid of the relay wearer or ffffffff-ffff-ffff-ffff-ffffffffffff ('''wildcard''') if it is a message intended for all relays who can hear it.
* In <r_msg>, KEY is always the uuid of the controller.

====On the relay side only====
'''Further requirements:'''
*A relay MUST ignore any message on RLVR channel which is not a <c_msg> with KEY being either the key of the avatar wearing the relay or ffffffff-ffff-ffff-ffff-ffffffffffff.
Then, for every <command>:
* if <command> is neither a valid <rlvcommand> or <metacommand>, the relay must ignore it and process the next <command>'s;
* if <command> is a <rlvcommand> or a <metacommand>, the relay MUST send back to the controller a <r_msg> (see above) such that:
:*IDENT is the same as IDENT in the <c_msg> being processed,
:*<command> is the subcommand being processed
:*and ACK is a string called ''acknowledgement value''. By default the acknowledgement value is "ok" if the relay will execute the <command >, "ko" otherwise.

'''Remarks:'''
* Many meta-commands may have other acknowledgements than "ok" or "ko" (or none, for !pong). Their definitions supersede this specification.
* Note that unknown meta-commands cannot be executed and thus wil be acknowledged by "ko".
* Known meta-commands which are sent with not enough parameters or parameters with types incompatible with those in the definition known by the relay also cannot be executed and will also be acknowledged by "ko". (ex: the relay knows !x-who/key, but receives !x-who/integer/string).

===On executing commands===
Summary of differences with original RLVR:
* explanation on how to handle meta-commands with variable number of parameters,
* the relay knows commands in both core specification and x-tensions,
* clarification on multi-controller relays.

====Relay side====
'''Requirements:'''
* If a <rlvcommand> is acknowledged with value "ok", the relay ensures the viewer is affected the same way as if the LSL instruction llOwnerSay(<rlvcommand>) was executed by a script in a primitive that handles only one controller.
* When processing a <metacommand>, if the relay knows at least one definition of '!'+METACOMMANDNAME for which the received <metacommandarguments> provide enough parameters, then it will be handled according to the definition handling the most parameters among the latter. Extra parameters are ignored.
* A relays knows the following meta-command definitions:
:*[[#Core meta-commands and associated mechanisms|definitions listed in the core requirements]]
:*all definitions included in [[LSL_Protocol/Restrained_Love_Relay/Comparison|x-tensions]] announced by the relay.
* When acknowledging a <metacommand> by anything else than "ko", the relay commits itself to execute it.

'''Remarks:'''
* For first requirement, it must be understood that the reference behavior is that the relay would have if it had one controller per prim. However handling several controllers from one unique prim is possible but requires taking care that different controllers do not interfere with each other, releasing each other's restrictions, for instance.
* For the second requirement, the word "handled" means that if the meta-command with these parameters is known, then requirements in known definition cannot be ignored. Sometimes, this can imply that the meta-command cannot be refused, for instance.

====Controller side====
* The controller can send any command within allowed syntax.
* Only commands described in this specification and commands belonging to x-tensions announced by the relay are guaranteed to be understood by the relay. If not understood, the relay will just answer "ko", do nothing and skip to the next command.

===Protocol session===
Summary of differences with original RLVR:
* it is now clear when a session starts and stops (and what a session is!)
* it is clear when to expect interactive dialogs (and how to avoid spamming relay wearers with blue dialogs)
* no session for unreachable controllers (answer to ping is mandatory to ensure session persistence)

====Definitions====
* During an execution of the RLVR protocol, a relay and a controller establish a '''session''' together. A relay may manage several sessions with several controllers. Likewise, a controller could establish sessions with several relays.
* Restrictions on a relay wearer are relative to a session. So are most other variables (authorization state, key of the controller, ... ).
* A session is '''Opened''' whenever the relay accepts a RLVR command from a controller.
* A session is '''Closed''' (or '''released''') as soon as the relay forgets every variables and releases all restrictions pertaining to that session.
* A session is '''Locked''' whenever it holds active restrictions.
* A session is '''Authed''' if the controller has been allowed to control the relay (not only store some variables with no consequence). Once authed, no interactive "ask" dialog should pop up anymore concerning this session. Most commands should now normally be accepted (and maybe a few automatically rejected).
* A controller is called '''reachable''' if it can receive messages from the relay and can prove it by answering [[#ping/!pong|ping]] requests from the relay. By "can", it is meant by the method of communication agreed upon by the relay and controller (by default: chat messages sent on RLVR channel by llRegionSayTo). X-tensions such as email and delay can modify what is meant by reachable.

====Relay side requirements====
On closing sessions:
*Closing a session clears all RLV restrictions that belong only to that session, clears all session variables and disables all restrictions relative to that session. This MUST happen on the following events and no other:
:*on executing !release (received from the controller, or relay-triggered as in a safeword, see [[#!release]])
:*on noticing the controller is not reachable
:*on timeout, if the session is not Locked
*Sessions that are not locked MUST be closed after a reasonable timeout.

On interactive Auth:
*Unless specified otherwise (see !x-who), no command can trigger an interactive dialog unless the command requires an Authed session and the session is not already Authed.
*Relay implementations MAY require an authed session for all <rlvcommand>'s of the form @xxx=force, @xxx=add and @xxx=n, and for meta-commands whose specifications say it is allowed.
*Other RLV commands MUST automatically accepted or rejected by any relay.

On removing and adding restrictions:
* Commands that remove restrictions are always accepted (RLV @...=<channel_number>, @clear[=...] and @...=y/rem commands, !release, and !x-.../clear[/...] meta-commands).
* No restriction can be released unless as the result of one of the above commands, or of closing a session.
*@xxx=n/add <rlvcommand>'s, after being accepted, add a restriction and therefore Lock the session.
*Some meta-commands described in x-tensions can also add restrictions and therefore Lock the session.

Reachability:
*A relay MUST provide a mechanism for checking that every controlling device is reachable. It is not specified whether this checking process should be automatic or manually triggered.

====Controller side requirements====
* A controller MUST eventually close any Locked session using the meta-command !release.

In particular, non-portable controllers should not let a Locked relay wearer run free out of reach. Moreover, any controller should either react to some kind of event that is bound to happen (timer expiration being the most common) or provide a user interface for closing the session. It should be clear at least to the person who set the trap how the victim will be released.

==Core meta-commands and associated mechanisms==

An ORG device MUST at least support the meta-commands !release, !pong, !version, !implversion and !x-orgversions described below and implement their associated mechanisms.

Particular meta-commands definitions and mechanisms may override general requirements above.

New in ORG compared to RLVR: !x-orgversions

===!release===
Sent by a controller, this command closes the session.

* !release obviously opens no session, requires no Auth and is not Locking.
* If there is an actual session to close !release MUST be accepted by the relay and acknowledeged by "ok".
* On accepting !release, the relay erases all data pertaining to the session and disables all restrictions of the session.
* When a relay decides to close a session on its own (user safeword, for instance) and it is not due to the controller being unreachable, the relay must send the following acknowledgement message:
release,<controller_key>,!release,ok

When receiving the latter message, the controller should act accordingly, for instance by resetting itself and making itself ready for the next session.

Note that !release is not the same as @clear. @clear is interpreted by the relay as a RLV command and, as such, can only clear RLV restrictions. If RLV restrictions were the only restrictions of the session, then the session will be closed, but some x-tensions also define pure LSL based restrictions.

===ping/!pong===

The ping/!pong mechanism exists so that relays can check presence and responsiveness of a controller. This was primarily meant to be used on relay wearer relog, in order to reactivate all restrictions so that sessions persist on relog if the controller still exists and is ready to continue the session.

''!pong'' cannot require auth and does not lock a session

We call ''ping message'' a message from the relay, having the following syntax:
ping,<controller_key>,ping,ping
We call ''!pong message'' a message from the controller, having the following syntax:
ping,<relay_key>,!pong

====Relay side====
*A relay SHOULD NOT send an acknowledgement in response to ''!pong''.
*A ping message can be sent any time by the relay to a known controller.
*On wearer relog, for each existing Locked session, the relay must send a ping message to the session controller.
*When a !pong message is received from a controller, if it was a reply to a previous ping message:
:#if the session RLV restrictions contain unsit and the avatar was sitting on some object when the restriction was applied, then the relay MUST force the avatar to sit back on the same object (if still existing);
:#the relay MUST make sure all restrictions belonging to the session are made active again.
*If a ping message is sent and is not answered by the controller, then the relay closes the session.

Note that the relay is responsible for storing restrictions and the key of the sit target across sessions, not the controller.

====Controller side====
*Unless it does not matter that the relay could close the session (or for another reason, the controller knows the relay will not close it), a controller SHOULD listen to ping messages and answer any ping message with a !pong message.
*A controller should ignore ping requests from relays it is not ready to handle.

Note controller don't have to poll for relay presence to resume a session but should just listen for ping messages instead. The relay should have stored all restrictions and handle sitting back to whatever furniture the relay wearer was tied up to.

Concerning the second bullet: for instance, if the controller is a furniture which is already in use by another relay wearer, it would be cause dysfunctions to let the pinging relay restore the restrictions without letting its wearer sit on the furniture. Or if the controller is not stateless and the state for the pinging relay has not been saved before, resuming the session from the initial state might be inconsistant.

===!version===
The purpose of this meta-command is to query the version of the RLVR protocol supported by a relay.

* !version opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !version with the version number of the RLVR protocol it supports ("1100" here, since ORG 0004 includes RLVR 1.100).

Note this is the most common command for a controller to scan for nearby relays, as non-ORG relays also accept this command and answer it the way described above.

===!implversion===
The purpose of this meta-command is to query the name and version of the relay implementation.

* !implversion opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !implversion with its implementation version string... which can be any string.

It is recommended this string includes the following elements:
* the relay name/brand/identifier,
* the version number of that relay name/brand/identifier,
* at the beginning, the string prefix "ORG=0004/"
The latter is convenient for checking for ORG compatibility using a command even non-ORG relay should understand.

===!x-orgversions===

This meta-command's purpose is to make it possible for the controller to have detailed informations on the protocol the relay supports. First the version of the ORG consolidated protocol, second the list of supported optional x-tensions, also with their version numbers.

'''Example:'''
C<->R
-> query,rUUID,!x-orgversions
<- query,cUUID,!x-orgversions,ORG=0004/who=002/email=006

'''Requirements:'''
* !x-orgversions should always be accepted with no Auth required, it does not open a session or Lock one.
* The acknowledgement value in a reply to !x-orgversions is a "/"-list of items of the form <package>=<version>. The first <package> is always "ORG" (representing the core specification package of ORG relays), its version string is the version of the specification (4 digits). The other packages are x-tension names, whose version string is 3 digits.
* If several incompatible versions of a same x-tension are supported, they must be listed ordered by version number. Ex: ORG=0004/who=002/email=005/email=006. If versions are backward compatible, only the last version should be reported.
* By announcing an x-tension, the relay commits itself to comply to all requirements of its specification.

'''Remarks:'''
* In a controller, it is however recommended to use !x-orgversions as soon as possible in order to avoid sending unsupported and useless metacommands later on.
* In the acknowledgement message, x-tension names are listed, not meta-command names (as one x-tension can have several meta-commands). Thus listed names do not include the prefix "!x-".
* x-tensions do not have to be standards defined by ORG but can also be proprietary. We recommend that the x-tension name then contains the name of the brand who proposes it.

===Other meta-commands===

Commands not listed here can belong to one of the following categories:
# (unlikely) commands from a future revision of Marine Kelley's original RLVR protocol.
# (more likely but not that much!) core commands from a future revision of ORG
# (very likely) commands from optional x-tensions
# proprietary commands

ORG intends for its successive versions to be backward compatible. Therefore ORG relays handle all unknown meta-commands.

We also intend for future versions of ORG consolidated protocol to include last version of original RLVR protocol, hence the prefix "!x-" for all meta-commands comming from ORG, which ensures there will be reasonably no collision.

For the same reason, we require that proprietary commands use an obvious prefix such as "!a-" or "!b-", and so on. Not doing so would prevent ensuring backward compatibility, hence a relay or controller who would use proprietary commands with wrong prefixes are not ORG compliant.

LSL Protocol/Restrained Love Open Relay Group/ORG Requirements/0004 draft

2011-06-27T15:29:42Z

Satomi Ahn: /* !x-orgversions */

{{ORG_Restrained_Life_Relay_Specs_TOC}}
STATUS: draft

VERSION: 0004

==Summary==

This page is a list of requirements for a relay or an in-world device to have the right to be called "ORG compliant". It is mostly about adding support for an ORG-centered informational metacommand and specifying Marine Kelley's RLVR protocol a bit more that it is now, while of course preserving full compatibility.

For a quick overview of the motivations and general working of this protocol and a few examples, we refer the reader to [[LSL_Protocol/Restrained_Love_Relay/Specification|the original specification page by Marine Kelley]].

If you are making furniture, traps, or other RLVR controllers and you are not interested in what [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] can offer, then you can stick with the original specification by Marine Kelley and still be compatible with [[LSL_Protocol/Restrained_Love_Relay/Comparison|ORG relays]]. However, to have the right to call your controller "ORG compatible", there are still a few light additional requirements such as:
* using only [[llRegionSayTo]] for communications with the relay,
* not spamming the RLVR channel with messages that do not belong to the protocol,
* and remain responsive to ping messages at every time if you want the session to remain locked.

If you are interested in [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|ORG x-tensions]], then you should also read the part about [[#!x-orgversions|!x-orgversions]].

If you are making a relay, sorry we are afraid you will have to read all this page.

==Definition of an ORG device==

A RLVR device is compliant with ORG specifications if it implements the consolidated RLVR protocol described below along with the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] it announces supporting.

Note in particular that
* the consolidated protocol is backward compatible with [[LSL_Protocol/Restrained_Love_Relay/Specification|Marine Kelley's RLVR protocol version 1.100]] but resolves most loose ends of that document;
* ORG relays handle controller messages whose second field is ffffffff-ffff-ffff-ffff-ffffffffffff exactly the same as if it was the key of the wearer (NULL_KEY is a wildcard);
* one-to-one chat messages (not using a wildcard) are sent by using [[llRegionSayTo]] LSL function;
* there is an additional meta-command, !x-orgversions for a relay to announce supported x-tensions;
* each supported x-tension can imply other supported metacommands, ORG x-tensions meta-command all having names starting with prefix "!x-";
* other proprietary metacommands with prefix "!_-" (replace "_" by any letter that is not "x") can be supported;

Supported x-tensions can constrain the core specification (this document) even more, but cannot alter it or make it less constraining unless as a result of the relay executing a meta-command of this x-tension sent by the controller. Thus, although the protocol is extensible, a controller can always rely on the fact an ORG relay abides by the requirements in this document until it asks the relay to do otherwise.

ORG devices may be advertised by the use of the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/ORG_Logo|ORG logo]] for advertising compliance with ORG requirements. ORG devices makers are encouraged to do so.

==Consolidated RLVR protocol==

=== Protocol Syntax ===
Summary of differences with original RLVR:
* we force use of llRegionSayTo,
* we explicitly forbid incorrect syntax on the relay channel
* the relay is supposed to ignore bad commands
* wildcards are supported

==== Definitions ====
* The '''Restrained Love Relay (RLVR) protocol''' implies two partners (SL objects): the '''relay''', attachment worn by the avatar commands are intended for, and a '''controller''', which sends commands to the relay.

* The goal of the protocol is to force the relay wearer to make perform actions and to toggle restrictions on their behavior. Both actions and restrictions can be enforced either through use of viewer hooks ([[LSL_Protocol/RestrainedLoveAPI|Restrained Love API]], or RLV) or through LSL scripting.

* Hence we distinguish between "'''RLV commands'''", starting with "@", which are commands following the syntax of the RLV API and which will ultimately be forwarded to the viewer, and "'''meta-commands'''", starting with "!", which are meant to be interpreted by LSL functions.

====Requirements====
RLVR protocol consists of messages exchanged between relay and controller
* on channel -1812221819 (called '''RLVR channel'''),
* using the LSL function [[llRegionSayTo]],
* all sent from the same prim of the controller or relay (within a [[#Protocol session|session]])
* and having the following syntax (non-terminal <c_msg> for controller messages/'''command messages''' and <r_msg> for relay messages/'''acknowledgement messages'''):

<c_msg> ::= IDENT "," KEY "," <commands>
<r_msg> ::= IDENT "," KEY "," <command> "," ACK
<commands> ::= <command> | <command> "|" <commands>
<command> ::= <rlvcommand> | <metacommand>
<rlvcommand> ::= "@" RLVCOMMAND
<metacommand> ::= "!" METACOMMANDNAME <metacommandarguments>
<metacommandarguments> ::= "" | "/" ARG <metacommandarguments>

where we explicit the different terminal tokens:
IDENT: any string without ","
KEY: any UUID
ACK: any string without ","
RLVCOMMAND: any string without ","
METACOMMANDNAME: any string without "/" and ","
ARG: any string without "/" and ","

* Relays can only send <r_msg>'s, and controllers <c_msg>'s. Nothing else is allowed on RLVR channel.
* In <c_msg>, KEY is always either the uuid of the relay wearer or ffffffff-ffff-ffff-ffff-ffffffffffff ('''wildcard''') if it is a message intended for all relays who can hear it.
* In <r_msg>, KEY is always the uuid of the controller.

====On the relay side only====
'''Further requirements:'''
*A relay MUST ignore any message on RLVR channel which is not a <c_msg> with KEY being either the key of the avatar wearing the relay or ffffffff-ffff-ffff-ffff-ffffffffffff.
Then, for every <command>:
* if <command> is neither a valid <rlvcommand> or <metacommand>, the relay must ignore it and process the next <command>'s;
* if <command> is a <rlvcommand> or a <metacommand>, the relay MUST send back to the controller a <r_msg> (see above) such that:
:*IDENT is the same as IDENT in the <c_msg> being processed,
:*<command> is the subcommand being processed
:*and ACK is a string called ''acknowledgement value''. By default the acknowledgement value is "ok" if the relay will execute the <command >, "ko" otherwise.

'''Remarks:'''
* Many meta-commands may have other acknowledgements than "ok" or "ko" (or none, for !pong). Their definitions supersede this specification.
* Note that unknown meta-commands cannot be executed and thus wil be acknowledged by "ko".
* Known meta-commands which are sent with not enough parameters or parameters with types incompatible with those in the definition known by the relay also cannot be executed and will also be acknowledged by "ko". (ex: the relay knows !x-who/key, but receives !x-who/integer/string).

===On executing commands===
Summary of differences with original RLVR:
* explanation on how to handle meta-commands with variable number of parameters,
* the relay knows commands in both core specification and x-tensions,
* clarification on multi-controller relays.

====Relay side====
'''Requirements:'''
* If a <rlvcommand> is acknowledged with value "ok", the relay ensures the viewer is affected the same way as if the LSL instruction llOwnerSay(<rlvcommand>) was executed by a script in a primitive that handles only one controller.
* When processing a <metacommand>, if the relay knows at least one definition of '!'+METACOMMANDNAME for which the received <metacommandarguments> provide enough parameters, then it will be handled according to the definition handling the most parameters among the latter. Extra parameters are ignored.
* A relays knows the following meta-command definitions:
:*[[#Core meta-commands and associated mechanisms|definitions listed in the core requirements]]
:*all definitions included in [[LSL_Protocol/Restrained_Love_Relay/Comparison|x-tensions]] announced by the relay.
* When acknowledging a <metacommand> by anything else than "ko", the relay commits itself to execute it.

'''Remarks:'''
* For first requirement, it must be understood that the reference behavior is that the relay would have if it had one controller per prim. However handling several controllers from one unique prim is possible but requires taking care that different controllers do not interfere with each other, releasing each other's restrictions, for instance.
* For the second requirement, the word "handled" means that if the meta-command with these parameters is known, then requirements in known definition cannot be ignored. Sometimes, this can imply that the meta-command cannot be refused, for instance.

====Controller side====
* The controller can send any command within allowed syntax.
* Only commands described in this specification and commands belonging to x-tensions announced by the relay are guaranteed to be understood by the relay. If not understood, the relay will just answer "ko", do nothing and skip to the next command.

===Protocol session===
Summary of differences with original RLVR:
* it is now clear when a session starts and stops (and what a session is!)
* it is clear when to expect interactive dialogs (and how to avoid spamming relay wearers with blue dialogs)
* no session for unreachable controllers (answer to ping is mandatory to ensure session persistence)

====Definitions====
* During an execution of the RLVR protocol, a relay and a controller establish a '''session''' together. A relay may manage several sessions with several controllers. Likewise, a controller could establish sessions with several relays.
* Restrictions on a relay wearer are relative to a session. So are most other variables (authorization state, key of the controller, ... ).
* A session is '''Opened''' whenever the relay accepts a RLVR command from a controller.
* A session is '''Closed''' (or '''released''') as soon as the relay forgets every variables and releases all restrictions pertaining to that session.
* A session is '''Locked''' whenever it holds active restrictions.
* A session is '''Authed''' if the controller has been allowed to control the relay (not only store some variables with no consequence). Once authed, no interactive "ask" dialog should pop up anymore concerning this session. Most commands should now normally be accepted (and maybe a few automatically rejected).
* A controller is called '''reachable''' if it can receive messages from the relay and can prove it by answering [[#ping/!pong|ping]] requests from the relay. By "can", it is meant by the method of communication agreed upon by the relay and controller (by default: chat messages sent on RLVR channel by llRegionSayTo). X-tensions such as email and delay can modify what is meant by reachable.

====Relay side requirements====
On closing sessions:
*Closing a session clears all RLV restrictions that belong only to that session, clears all session variables and disables all restrictions relative to that session. This MUST happen on the following events and no other:
:*on executing !release (received from the controller, or relay-triggered as in a safeword, see [[#!release]])
:*on noticing the controller is not reachable
:*on timeout, if the session is not Locked
*Sessions that are not locked MUST be closed after a reasonable timeout.

On interactive Auth:
*Unless specified otherwise (see !x-who), no command can trigger an interactive dialog unless the command requires an Authed session and the session is not already Authed.
*Relay implementations MAY require an authed session for all <rlvcommand>'s of the form @xxx=force, @xxx=add and @xxx=n, and for meta-commands whose specifications say it is allowed.
*Other RLV commands MUST automatically accepted or rejected by any relay.

On removing and adding restrictions:
* Commands that remove restrictions are always accepted (RLV @...=<channel_number>, @clear[=...] and @...=y/rem commands, !release, and !x-.../clear[/...] meta-commands).
* No restriction can be released unless as the result of one of the above commands, or of closing a session.
*@xxx=n/add <rlvcommand>'s, after being accepted, add a restriction and therefore Lock the session.
*Some meta-commands described in x-tensions can also add restrictions and therefore Lock the session.

Reachability:
*A relay MUST provide a mechanism for checking that every controlling device is reachable. It is not specified whether this checking process should be automatic or manually triggered.

====Controller side requirements====
* A controller MUST eventually close any Locked session using the meta-command !release.

In particular, non-portable controllers should not let a Locked relay wearer run free out of reach. Moreover, any controller should either react to some kind of event that is bound to happen (timer expiration being the most common) or provide a user interface for closing the session. It should be clear at least to the person who set the trap how the victim will be released.

==Core meta-commands and associated mechanisms==

An ORG device MUST at least support the meta-commands !release, !pong, !version, !implversion and !x-orgversions described below and implement their associated mechanisms.

Particular meta-commands definitions and mechanisms may override general requirements above.

New in ORG compared to RLVR: !x-orgversions

===!release===
Sent by a controller, this command closes the session.

* !release obviously opens no session, requires no Auth and is not Locking.
* If there is an actual session to close !release MUST be accepted by the relay and acknowledeged by "ok".
* On accepting !release, the relay erases all data pertaining to the session and disables all restrictions of the session.
* When a relay decides to close a session on its own (user safeword, for instance) and it is not due to the controller being unreachable, the relay must send the following acknowledgement message:
release,<controller_key>,!release,ok

When receiving the latter message, the controller should act accordingly, for instance by resetting itself and making itself ready for the next session.

Note that !release is not the same as @clear. @clear is interpreted by the relay as a RLV command and, as such, can only clear RLV restrictions. If RLV restrictions were the only restrictions of the session, then the session will be closed, but some x-tensions also define pure LSL based restrictions.

===ping/!pong===

The ping/!pong mechanism exists so that relays can check presence and responsiveness of a controller. This was primarily meant to be used on relay wearer relog, in order to reactivate all restrictions so that sessions persist on relog if the controller still exists and is ready to continue the session.

''!pong'' cannot require auth and does not lock a session

We call ''ping message'' a message from the relay, having the following syntax:
ping,<controller_key>,ping,ping
We call ''!pong message'' a message from the controller, having the following syntax:
ping,<relay_key>,!pong

====Relay side====
*A relay SHOULD NOT send an acknowledgement in response to ''!pong''.
*A ping message can be sent any time by the relay to a known controller.
*On wearer relog, for each existing Locked session, the relay must send a ping message to the session controller.
*When a !pong message is received from a controller, if it was a reply to a previous ping message:
:#if the session RLV restrictions contain unsit and the avatar was sitting on some object when the restriction was applied, then the relay MUST force the avatar to sit back on the same object (if still existing);
:#the relay MUST make sure all restrictions belonging to the session are made active again.
*If a ping message is sent and is not answered by the controller, then the relay closes the session.

Note that the relay is responsible for storing restrictions and the key of the sit target across sessions, not the controller.

====Controller side====
*Unless it does not matter that the relay could close the session (or for another reason, the controller knows the relay will not close it), a controller SHOULD listen to ping messages and answer any ping message with a !pong message.
*A controller should ignore ping requests from relays it is not ready to handle.

Note controller don't have to poll for relay presence to resume a session but should just listen for ping messages instead. The relay should have stored all restrictions and handle sitting back to whatever furniture the relay wearer was tied up to.

Concerning the second bullet: for instance, if the controller is a furniture which is already in use by another relay wearer, it would be cause dysfunctions to let the pinging relay restore the restrictions without letting its wearer sit on the furniture. Or if the controller is not stateless and the state for the pinging relay has not been saved before, resuming the session from the initial state might be inconsistant.

===!version===
The purpose of this meta-command is to query the version of the RLVR protocol supported by a relay.

* !version opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !version with the version number of the RLVR protocol it supports ("1100" here, since ORG 0004 includes RLVR 1.100).

Note this is the most common command for a controller to scan for nearby relays, as non-ORG relays also accept this command and answer it the way described above.

===!implversion===
The purpose of this meta-command is to query the name and version of the relay implementation.

* !implversion opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !implversion with its implementation version string... which can be any string.

It is recommended this string includes the following elements:
* the relay name/brand/identifier,
* the version number of that relay name/brand/identifier,
* at the beginning, the string prefix "ORG=0004/"
The latter is convenient for checking for ORG compatibility using a command even non-ORG relay should understand.

===!x-orgversions===

This meta-command's purpose is to make it possible for the controller to have detailed informations on the protocol the relay supports. First the version of the ORG consolidated protocol, second the list of supported optional x-tensions, also with their version numbers.

'''Example:'''
C<->R
-> query,rUUID,!x-orgversions
<- query,cUUID,!x-orgversions,ORG=0004/who=002/email=006

'''Requirements:'''
* !x-orgversions should always be accepted with no Auth required, it does not open a session or Lock one.
* The acknowledgement value in a reply to !x-orgversions is a "/"-list of items of the form <package>=<version>. The first <package> is always "ORG" (representing the core specification package of ORG relays), its version string is the version of the specification (4 digits). The other packages are x-tension names, whose version string is 3 digits.
* If several incompatible versions of a same x-tension are supported, they must be listed ordered by version number. Ex: ORG=0004/who=002/email=005/email=006. If versions are backward compatible, only the last version should be reported.
* By announcing an x-tension, the relay commits itself to comply to all requirements of its specification.

'''Remarks:'''
* In a controller, it is however recommended to use !x-orgversions as soon as possible in order to avoid sending unsupported and useless metacommands later on.
* In the acknowledgement message, x-tension names are listed, not meta-command names (as one x-tension can have several meta-commands). Thus listed names do not include the prefix "!x-".
* x-tensions do not have to be standards defined by ORG but can also be proprietary. We recommend that the x-tension name then contains the name of the brand who proposes it.

LSL Protocol/Restrained Love Open Relay Group/ORG Requirements/0004 draft

2011-06-27T15:21:02Z

Satomi Ahn: /* Core meta-commands and associated mechanisms */

{{ORG_Restrained_Life_Relay_Specs_TOC}}
STATUS: draft

VERSION: 0004

==Summary==

This page is a list of requirements for a relay or an in-world device to have the right to be called "ORG compliant". It is mostly about adding support for an ORG-centered informational metacommand and specifying Marine Kelley's RLVR protocol a bit more that it is now, while of course preserving full compatibility.

For a quick overview of the motivations and general working of this protocol and a few examples, we refer the reader to [[LSL_Protocol/Restrained_Love_Relay/Specification|the original specification page by Marine Kelley]].

If you are making furniture, traps, or other RLVR controllers and you are not interested in what [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] can offer, then you can stick with the original specification by Marine Kelley and still be compatible with [[LSL_Protocol/Restrained_Love_Relay/Comparison|ORG relays]]. However, to have the right to call your controller "ORG compatible", there are still a few light additional requirements such as:
* using only [[llRegionSayTo]] for communications with the relay,
* not spamming the RLVR channel with messages that do not belong to the protocol,
* and remain responsive to ping messages at every time if you want the session to remain locked.

If you are interested in [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|ORG x-tensions]], then you should also read the part about [[#!x-orgversions|!x-orgversions]].

If you are making a relay, sorry we are afraid you will have to read all this page.

==Definition of an ORG device==

A RLVR device is compliant with ORG specifications if it implements the consolidated RLVR protocol described below along with the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] it announces supporting.

Note in particular that
* the consolidated protocol is backward compatible with [[LSL_Protocol/Restrained_Love_Relay/Specification|Marine Kelley's RLVR protocol version 1.100]] but resolves most loose ends of that document;
* ORG relays handle controller messages whose second field is ffffffff-ffff-ffff-ffff-ffffffffffff exactly the same as if it was the key of the wearer (NULL_KEY is a wildcard);
* one-to-one chat messages (not using a wildcard) are sent by using [[llRegionSayTo]] LSL function;
* there is an additional meta-command, !x-orgversions for a relay to announce supported x-tensions;
* each supported x-tension can imply other supported metacommands, ORG x-tensions meta-command all having names starting with prefix "!x-";
* other proprietary metacommands with prefix "!_-" (replace "_" by any letter that is not "x") can be supported;

Supported x-tensions can constrain the core specification (this document) even more, but cannot alter it or make it less constraining unless as a result of the relay executing a meta-command of this x-tension sent by the controller. Thus, although the protocol is extensible, a controller can always rely on the fact an ORG relay abides by the requirements in this document until it asks the relay to do otherwise.

ORG devices may be advertised by the use of the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/ORG_Logo|ORG logo]] for advertising compliance with ORG requirements. ORG devices makers are encouraged to do so.

==Consolidated RLVR protocol==

=== Protocol Syntax ===
Summary of differences with original RLVR:
* we force use of llRegionSayTo,
* we explicitly forbid incorrect syntax on the relay channel
* the relay is supposed to ignore bad commands
* wildcards are supported

==== Definitions ====
* The '''Restrained Love Relay (RLVR) protocol''' implies two partners (SL objects): the '''relay''', attachment worn by the avatar commands are intended for, and a '''controller''', which sends commands to the relay.

* The goal of the protocol is to force the relay wearer to make perform actions and to toggle restrictions on their behavior. Both actions and restrictions can be enforced either through use of viewer hooks ([[LSL_Protocol/RestrainedLoveAPI|Restrained Love API]], or RLV) or through LSL scripting.

* Hence we distinguish between "'''RLV commands'''", starting with "@", which are commands following the syntax of the RLV API and which will ultimately be forwarded to the viewer, and "'''meta-commands'''", starting with "!", which are meant to be interpreted by LSL functions.

====Requirements====
RLVR protocol consists of messages exchanged between relay and controller
* on channel -1812221819 (called '''RLVR channel'''),
* using the LSL function [[llRegionSayTo]],
* all sent from the same prim of the controller or relay (within a [[#Protocol session|session]])
* and having the following syntax (non-terminal <c_msg> for controller messages/'''command messages''' and <r_msg> for relay messages/'''acknowledgement messages'''):

<c_msg> ::= IDENT "," KEY "," <commands>
<r_msg> ::= IDENT "," KEY "," <command> "," ACK
<commands> ::= <command> | <command> "|" <commands>
<command> ::= <rlvcommand> | <metacommand>
<rlvcommand> ::= "@" RLVCOMMAND
<metacommand> ::= "!" METACOMMANDNAME <metacommandarguments>
<metacommandarguments> ::= "" | "/" ARG <metacommandarguments>

where we explicit the different terminal tokens:
IDENT: any string without ","
KEY: any UUID
ACK: any string without ","
RLVCOMMAND: any string without ","
METACOMMANDNAME: any string without "/" and ","
ARG: any string without "/" and ","

* Relays can only send <r_msg>'s, and controllers <c_msg>'s. Nothing else is allowed on RLVR channel.
* In <c_msg>, KEY is always either the uuid of the relay wearer or ffffffff-ffff-ffff-ffff-ffffffffffff ('''wildcard''') if it is a message intended for all relays who can hear it.
* In <r_msg>, KEY is always the uuid of the controller.

====On the relay side only====
'''Further requirements:'''
*A relay MUST ignore any message on RLVR channel which is not a <c_msg> with KEY being either the key of the avatar wearing the relay or ffffffff-ffff-ffff-ffff-ffffffffffff.
Then, for every <command>:
* if <command> is neither a valid <rlvcommand> or <metacommand>, the relay must ignore it and process the next <command>'s;
* if <command> is a <rlvcommand> or a <metacommand>, the relay MUST send back to the controller a <r_msg> (see above) such that:
:*IDENT is the same as IDENT in the <c_msg> being processed,
:*<command> is the subcommand being processed
:*and ACK is a string called ''acknowledgement value''. By default the acknowledgement value is "ok" if the relay will execute the <command >, "ko" otherwise.

'''Remarks:'''
* Many meta-commands may have other acknowledgements than "ok" or "ko" (or none, for !pong). Their definitions supersede this specification.
* Note that unknown meta-commands cannot be executed and thus wil be acknowledged by "ko".
* Known meta-commands which are sent with not enough parameters or parameters with types incompatible with those in the definition known by the relay also cannot be executed and will also be acknowledged by "ko". (ex: the relay knows !x-who/key, but receives !x-who/integer/string).

===On executing commands===
Summary of differences with original RLVR:
* explanation on how to handle meta-commands with variable number of parameters,
* the relay knows commands in both core specification and x-tensions,
* clarification on multi-controller relays.

====Relay side====
'''Requirements:'''
* If a <rlvcommand> is acknowledged with value "ok", the relay ensures the viewer is affected the same way as if the LSL instruction llOwnerSay(<rlvcommand>) was executed by a script in a primitive that handles only one controller.
* When processing a <metacommand>, if the relay knows at least one definition of '!'+METACOMMANDNAME for which the received <metacommandarguments> provide enough parameters, then it will be handled according to the definition handling the most parameters among the latter. Extra parameters are ignored.
* A relays knows the following meta-command definitions:
:*[[#Core meta-commands and associated mechanisms|definitions listed in the core requirements]]
:*all definitions included in [[LSL_Protocol/Restrained_Love_Relay/Comparison|x-tensions]] announced by the relay.
* When acknowledging a <metacommand> by anything else than "ko", the relay commits itself to execute it.

'''Remarks:'''
* For first requirement, it must be understood that the reference behavior is that the relay would have if it had one controller per prim. However handling several controllers from one unique prim is possible but requires taking care that different controllers do not interfere with each other, releasing each other's restrictions, for instance.
* For the second requirement, the word "handled" means that if the meta-command with these parameters is known, then requirements in known definition cannot be ignored. Sometimes, this can imply that the meta-command cannot be refused, for instance.

====Controller side====
* The controller can send any command within allowed syntax.
* Only commands described in this specification and commands belonging to x-tensions announced by the relay are guaranteed to be understood by the relay. If not understood, the relay will just answer "ko", do nothing and skip to the next command.

===Protocol session===
Summary of differences with original RLVR:
* it is now clear when a session starts and stops (and what a session is!)
* it is clear when to expect interactive dialogs (and how to avoid spamming relay wearers with blue dialogs)
* no session for unreachable controllers (answer to ping is mandatory to ensure session persistence)

====Definitions====
* During an execution of the RLVR protocol, a relay and a controller establish a '''session''' together. A relay may manage several sessions with several controllers. Likewise, a controller could establish sessions with several relays.
* Restrictions on a relay wearer are relative to a session. So are most other variables (authorization state, key of the controller, ... ).
* A session is '''Opened''' whenever the relay accepts a RLVR command from a controller.
* A session is '''Closed''' (or '''released''') as soon as the relay forgets every variables and releases all restrictions pertaining to that session.
* A session is '''Locked''' whenever it holds active restrictions.
* A session is '''Authed''' if the controller has been allowed to control the relay (not only store some variables with no consequence). Once authed, no interactive "ask" dialog should pop up anymore concerning this session. Most commands should now normally be accepted (and maybe a few automatically rejected).
* A controller is called '''reachable''' if it can receive messages from the relay and can prove it by answering [[#ping/!pong|ping]] requests from the relay. By "can", it is meant by the method of communication agreed upon by the relay and controller (by default: chat messages sent on RLVR channel by llRegionSayTo). X-tensions such as email and delay can modify what is meant by reachable.

====Relay side requirements====
On closing sessions:
*Closing a session clears all RLV restrictions that belong only to that session, clears all session variables and disables all restrictions relative to that session. This MUST happen on the following events and no other:
:*on executing !release (received from the controller, or relay-triggered as in a safeword, see [[#!release]])
:*on noticing the controller is not reachable
:*on timeout, if the session is not Locked
*Sessions that are not locked MUST be closed after a reasonable timeout.

On interactive Auth:
*Unless specified otherwise (see !x-who), no command can trigger an interactive dialog unless the command requires an Authed session and the session is not already Authed.
*Relay implementations MAY require an authed session for all <rlvcommand>'s of the form @xxx=force, @xxx=add and @xxx=n, and for meta-commands whose specifications say it is allowed.
*Other RLV commands MUST automatically accepted or rejected by any relay.

On removing and adding restrictions:
* Commands that remove restrictions are always accepted (RLV @...=<channel_number>, @clear[=...] and @...=y/rem commands, !release, and !x-.../clear[/...] meta-commands).
* No restriction can be released unless as the result of one of the above commands, or of closing a session.
*@xxx=n/add <rlvcommand>'s, after being accepted, add a restriction and therefore Lock the session.
*Some meta-commands described in x-tensions can also add restrictions and therefore Lock the session.

Reachability:
*A relay MUST provide a mechanism for checking that every controlling device is reachable. It is not specified whether this checking process should be automatic or manually triggered.

====Controller side requirements====
* A controller MUST eventually close any Locked session using the meta-command !release.

In particular, non-portable controllers should not let a Locked relay wearer run free out of reach. Moreover, any controller should either react to some kind of event that is bound to happen (timer expiration being the most common) or provide a user interface for closing the session. It should be clear at least to the person who set the trap how the victim will be released.

==Core meta-commands and associated mechanisms==

An ORG device MUST at least support the meta-commands !release, !pong, !version, !implversion and !x-orgversions described below and implement their associated mechanisms.

Particular meta-commands definitions and mechanisms may override general requirements above.

New in ORG compared to RLVR: !x-orgversions

===!release===
Sent by a controller, this command closes the session.

* !release obviously opens no session, requires no Auth and is not Locking.
* If there is an actual session to close !release MUST be accepted by the relay and acknowledeged by "ok".
* On accepting !release, the relay erases all data pertaining to the session and disables all restrictions of the session.
* When a relay decides to close a session on its own (user safeword, for instance) and it is not due to the controller being unreachable, the relay must send the following acknowledgement message:
release,<controller_key>,!release,ok

When receiving the latter message, the controller should act accordingly, for instance by resetting itself and making itself ready for the next session.

Note that !release is not the same as @clear. @clear is interpreted by the relay as a RLV command and, as such, can only clear RLV restrictions. If RLV restrictions were the only restrictions of the session, then the session will be closed, but some x-tensions also define pure LSL based restrictions.

===ping/!pong===

The ping/!pong mechanism exists so that relays can check presence and responsiveness of a controller. This was primarily meant to be used on relay wearer relog, in order to reactivate all restrictions so that sessions persist on relog if the controller still exists and is ready to continue the session.

''!pong'' cannot require auth and does not lock a session

We call ''ping message'' a message from the relay, having the following syntax:
ping,<controller_key>,ping,ping
We call ''!pong message'' a message from the controller, having the following syntax:
ping,<relay_key>,!pong

====Relay side====
*A relay SHOULD NOT send an acknowledgement in response to ''!pong''.
*A ping message can be sent any time by the relay to a known controller.
*On wearer relog, for each existing Locked session, the relay must send a ping message to the session controller.
*When a !pong message is received from a controller, if it was a reply to a previous ping message:
:#if the session RLV restrictions contain unsit and the avatar was sitting on some object when the restriction was applied, then the relay MUST force the avatar to sit back on the same object (if still existing);
:#the relay MUST make sure all restrictions belonging to the session are made active again.
*If a ping message is sent and is not answered by the controller, then the relay closes the session.

Note that the relay is responsible for storing restrictions and the key of the sit target across sessions, not the controller.

====Controller side====
*Unless it does not matter that the relay could close the session (or for another reason, the controller knows the relay will not close it), a controller SHOULD listen to ping messages and answer any ping message with a !pong message.
*A controller should ignore ping requests from relays it is not ready to handle.

Note controller don't have to poll for relay presence to resume a session but should just listen for ping messages instead. The relay should have stored all restrictions and handle sitting back to whatever furniture the relay wearer was tied up to.

Concerning the second bullet: for instance, if the controller is a furniture which is already in use by another relay wearer, it would be cause dysfunctions to let the pinging relay restore the restrictions without letting its wearer sit on the furniture. Or if the controller is not stateless and the state for the pinging relay has not been saved before, resuming the session from the initial state might be inconsistant.

===!version===
The purpose of this meta-command is to query the version of the RLVR protocol supported by a relay.

* !version opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !version with the version number of the RLVR protocol it supports ("1100" here, since ORG 0004 includes RLVR 1.100).

Note this is the most common command for a controller to scan for nearby relays, as non-ORG relays also accept this command and answer it the way described above.

===!implversion===
The purpose of this meta-command is to query the name and version of the relay implementation.

* !implversion opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !implversion with its implementation version string... which can be any string.

It is recommended this string includes the following elements:
* the relay name/brand/identifier,
* the version number of that relay name/brand/identifier,
* at the beginning, the string prefix "ORG=0004/"
The latter is convenient for checking for ORG compatibility using a command even non-ORG relay should understand.

===!x-orgversions===

This meta-command purpose it two-fold. First it allows a controlling device to ask a relay for the list of ORG x-tensions it supports and, second, similarily to !version, !x-orgversions can be used to know what version of ORG the relay complies to.

'''Example:'''
C<->R
-> query,rUUID,!x-orgversions
<- query,cUUID,!x-orgversions,ORG=0004/who=002/email=006

'''Requirements:'''
* !x-orgversions should always be accepted with no Auth required, it does not open a session or Lock one.
* The acknowledgement value in a reply to !x-orgversions is a "/"-list of items of the form <package>=<version>. The first <package> is always "ORG" (representing the core specification package of ORG relays), its version string is the version of the specification (4 digits). The other packages are ORG x-tension names, whose version string is 3 digits.
* If several incompatible versions of a same x-tension are supported, they must be listed ordered by version number. Ex: ORG=0004/who=002/email=005/email=006. If versions are backward compatible, only the last version should be reported.

'''Remarks:'''
* In a controller, it is however recommended to use !x-orgversions as soon as possible in order to avoid sending unsupported and useless metacommands later on.
* In the acknowledgement message, x-tension names are listed, not meta-command names (as one x-tension can have several meta-commands). Thus listed names do not include the prefix "!x-".

LSL Protocol/Restrained Love Open Relay Group/ORG Requirements/0004 draft

2011-06-27T15:19:01Z

Satomi Ahn: /* Protocol session */

{{ORG_Restrained_Life_Relay_Specs_TOC}}
STATUS: draft

VERSION: 0004

==Summary==

This page is a list of requirements for a relay or an in-world device to have the right to be called "ORG compliant". It is mostly about adding support for an ORG-centered informational metacommand and specifying Marine Kelley's RLVR protocol a bit more that it is now, while of course preserving full compatibility.

For a quick overview of the motivations and general working of this protocol and a few examples, we refer the reader to [[LSL_Protocol/Restrained_Love_Relay/Specification|the original specification page by Marine Kelley]].

If you are making furniture, traps, or other RLVR controllers and you are not interested in what [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] can offer, then you can stick with the original specification by Marine Kelley and still be compatible with [[LSL_Protocol/Restrained_Love_Relay/Comparison|ORG relays]]. However, to have the right to call your controller "ORG compatible", there are still a few light additional requirements such as:
* using only [[llRegionSayTo]] for communications with the relay,
* not spamming the RLVR channel with messages that do not belong to the protocol,
* and remain responsive to ping messages at every time if you want the session to remain locked.

If you are interested in [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|ORG x-tensions]], then you should also read the part about [[#!x-orgversions|!x-orgversions]].

If you are making a relay, sorry we are afraid you will have to read all this page.

==Definition of an ORG device==

A RLVR device is compliant with ORG specifications if it implements the consolidated RLVR protocol described below along with the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] it announces supporting.

Note in particular that
* the consolidated protocol is backward compatible with [[LSL_Protocol/Restrained_Love_Relay/Specification|Marine Kelley's RLVR protocol version 1.100]] but resolves most loose ends of that document;
* ORG relays handle controller messages whose second field is ffffffff-ffff-ffff-ffff-ffffffffffff exactly the same as if it was the key of the wearer (NULL_KEY is a wildcard);
* one-to-one chat messages (not using a wildcard) are sent by using [[llRegionSayTo]] LSL function;
* there is an additional meta-command, !x-orgversions for a relay to announce supported x-tensions;
* each supported x-tension can imply other supported metacommands, ORG x-tensions meta-command all having names starting with prefix "!x-";
* other proprietary metacommands with prefix "!_-" (replace "_" by any letter that is not "x") can be supported;

Supported x-tensions can constrain the core specification (this document) even more, but cannot alter it or make it less constraining unless as a result of the relay executing a meta-command of this x-tension sent by the controller. Thus, although the protocol is extensible, a controller can always rely on the fact an ORG relay abides by the requirements in this document until it asks the relay to do otherwise.

ORG devices may be advertised by the use of the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/ORG_Logo|ORG logo]] for advertising compliance with ORG requirements. ORG devices makers are encouraged to do so.

==Consolidated RLVR protocol==

=== Protocol Syntax ===
Summary of differences with original RLVR:
* we force use of llRegionSayTo,
* we explicitly forbid incorrect syntax on the relay channel
* the relay is supposed to ignore bad commands
* wildcards are supported

==== Definitions ====
* The '''Restrained Love Relay (RLVR) protocol''' implies two partners (SL objects): the '''relay''', attachment worn by the avatar commands are intended for, and a '''controller''', which sends commands to the relay.

* The goal of the protocol is to force the relay wearer to make perform actions and to toggle restrictions on their behavior. Both actions and restrictions can be enforced either through use of viewer hooks ([[LSL_Protocol/RestrainedLoveAPI|Restrained Love API]], or RLV) or through LSL scripting.

* Hence we distinguish between "'''RLV commands'''", starting with "@", which are commands following the syntax of the RLV API and which will ultimately be forwarded to the viewer, and "'''meta-commands'''", starting with "!", which are meant to be interpreted by LSL functions.

====Requirements====
RLVR protocol consists of messages exchanged between relay and controller
* on channel -1812221819 (called '''RLVR channel'''),
* using the LSL function [[llRegionSayTo]],
* all sent from the same prim of the controller or relay (within a [[#Protocol session|session]])
* and having the following syntax (non-terminal <c_msg> for controller messages/'''command messages''' and <r_msg> for relay messages/'''acknowledgement messages'''):

<c_msg> ::= IDENT "," KEY "," <commands>
<r_msg> ::= IDENT "," KEY "," <command> "," ACK
<commands> ::= <command> | <command> "|" <commands>
<command> ::= <rlvcommand> | <metacommand>
<rlvcommand> ::= "@" RLVCOMMAND
<metacommand> ::= "!" METACOMMANDNAME <metacommandarguments>
<metacommandarguments> ::= "" | "/" ARG <metacommandarguments>

where we explicit the different terminal tokens:
IDENT: any string without ","
KEY: any UUID
ACK: any string without ","
RLVCOMMAND: any string without ","
METACOMMANDNAME: any string without "/" and ","
ARG: any string without "/" and ","

* Relays can only send <r_msg>'s, and controllers <c_msg>'s. Nothing else is allowed on RLVR channel.
* In <c_msg>, KEY is always either the uuid of the relay wearer or ffffffff-ffff-ffff-ffff-ffffffffffff ('''wildcard''') if it is a message intended for all relays who can hear it.
* In <r_msg>, KEY is always the uuid of the controller.

====On the relay side only====
'''Further requirements:'''
*A relay MUST ignore any message on RLVR channel which is not a <c_msg> with KEY being either the key of the avatar wearing the relay or ffffffff-ffff-ffff-ffff-ffffffffffff.
Then, for every <command>:
* if <command> is neither a valid <rlvcommand> or <metacommand>, the relay must ignore it and process the next <command>'s;
* if <command> is a <rlvcommand> or a <metacommand>, the relay MUST send back to the controller a <r_msg> (see above) such that:
:*IDENT is the same as IDENT in the <c_msg> being processed,
:*<command> is the subcommand being processed
:*and ACK is a string called ''acknowledgement value''. By default the acknowledgement value is "ok" if the relay will execute the <command >, "ko" otherwise.

'''Remarks:'''
* Many meta-commands may have other acknowledgements than "ok" or "ko" (or none, for !pong). Their definitions supersede this specification.
* Note that unknown meta-commands cannot be executed and thus wil be acknowledged by "ko".
* Known meta-commands which are sent with not enough parameters or parameters with types incompatible with those in the definition known by the relay also cannot be executed and will also be acknowledged by "ko". (ex: the relay knows !x-who/key, but receives !x-who/integer/string).

===On executing commands===
Summary of differences with original RLVR:
* explanation on how to handle meta-commands with variable number of parameters,
* the relay knows commands in both core specification and x-tensions,
* clarification on multi-controller relays.

====Relay side====
'''Requirements:'''
* If a <rlvcommand> is acknowledged with value "ok", the relay ensures the viewer is affected the same way as if the LSL instruction llOwnerSay(<rlvcommand>) was executed by a script in a primitive that handles only one controller.
* When processing a <metacommand>, if the relay knows at least one definition of '!'+METACOMMANDNAME for which the received <metacommandarguments> provide enough parameters, then it will be handled according to the definition handling the most parameters among the latter. Extra parameters are ignored.
* A relays knows the following meta-command definitions:
:*[[#Core meta-commands and associated mechanisms|definitions listed in the core requirements]]
:*all definitions included in [[LSL_Protocol/Restrained_Love_Relay/Comparison|x-tensions]] announced by the relay.
* When acknowledging a <metacommand> by anything else than "ko", the relay commits itself to execute it.

'''Remarks:'''
* For first requirement, it must be understood that the reference behavior is that the relay would have if it had one controller per prim. However handling several controllers from one unique prim is possible but requires taking care that different controllers do not interfere with each other, releasing each other's restrictions, for instance.
* For the second requirement, the word "handled" means that if the meta-command with these parameters is known, then requirements in known definition cannot be ignored. Sometimes, this can imply that the meta-command cannot be refused, for instance.

====Controller side====
* The controller can send any command within allowed syntax.
* Only commands described in this specification and commands belonging to x-tensions announced by the relay are guaranteed to be understood by the relay. If not understood, the relay will just answer "ko", do nothing and skip to the next command.

===Protocol session===
Summary of differences with original RLVR:
* it is now clear when a session starts and stops (and what a session is!)
* it is clear when to expect interactive dialogs (and how to avoid spamming relay wearers with blue dialogs)
* no session for unreachable controllers (answer to ping is mandatory to ensure session persistence)

====Definitions====
* During an execution of the RLVR protocol, a relay and a controller establish a '''session''' together. A relay may manage several sessions with several controllers. Likewise, a controller could establish sessions with several relays.
* Restrictions on a relay wearer are relative to a session. So are most other variables (authorization state, key of the controller, ... ).
* A session is '''Opened''' whenever the relay accepts a RLVR command from a controller.
* A session is '''Closed''' (or '''released''') as soon as the relay forgets every variables and releases all restrictions pertaining to that session.
* A session is '''Locked''' whenever it holds active restrictions.
* A session is '''Authed''' if the controller has been allowed to control the relay (not only store some variables with no consequence). Once authed, no interactive "ask" dialog should pop up anymore concerning this session. Most commands should now normally be accepted (and maybe a few automatically rejected).
* A controller is called '''reachable''' if it can receive messages from the relay and can prove it by answering [[#ping/!pong|ping]] requests from the relay. By "can", it is meant by the method of communication agreed upon by the relay and controller (by default: chat messages sent on RLVR channel by llRegionSayTo). X-tensions such as email and delay can modify what is meant by reachable.

====Relay side requirements====
On closing sessions:
*Closing a session clears all RLV restrictions that belong only to that session, clears all session variables and disables all restrictions relative to that session. This MUST happen on the following events and no other:
:*on executing !release (received from the controller, or relay-triggered as in a safeword, see [[#!release]])
:*on noticing the controller is not reachable
:*on timeout, if the session is not Locked
*Sessions that are not locked MUST be closed after a reasonable timeout.

On interactive Auth:
*Unless specified otherwise (see !x-who), no command can trigger an interactive dialog unless the command requires an Authed session and the session is not already Authed.
*Relay implementations MAY require an authed session for all <rlvcommand>'s of the form @xxx=force, @xxx=add and @xxx=n, and for meta-commands whose specifications say it is allowed.
*Other RLV commands MUST automatically accepted or rejected by any relay.

On removing and adding restrictions:
* Commands that remove restrictions are always accepted (RLV @...=<channel_number>, @clear[=...] and @...=y/rem commands, !release, and !x-.../clear[/...] meta-commands).
* No restriction can be released unless as the result of one of the above commands, or of closing a session.
*@xxx=n/add <rlvcommand>'s, after being accepted, add a restriction and therefore Lock the session.
*Some meta-commands described in x-tensions can also add restrictions and therefore Lock the session.

Reachability:
*A relay MUST provide a mechanism for checking that every controlling device is reachable. It is not specified whether this checking process should be automatic or manually triggered.

====Controller side requirements====
* A controller MUST eventually close any Locked session using the meta-command !release.

In particular, non-portable controllers should not let a Locked relay wearer run free out of reach. Moreover, any controller should either react to some kind of event that is bound to happen (timer expiration being the most common) or provide a user interface for closing the session. It should be clear at least to the person who set the trap how the victim will be released.

==Core meta-commands and associated mechanisms==

An ORG device MUST at least support the meta-commands !release, !pong, !version, !implversion and !x-orgversions described below and implement their associated mechanisms.

Particular meta-commands definitions and mechanisms may override general requirements above.

===!release===
Sent by a controller, this command closes the session.

* !release obviously opens no session, requires no Auth and is not Locking.
* If there is an actual session to close !release MUST be accepted by the relay and acknowledeged by "ok".
* On accepting !release, the relay erases all data pertaining to the session and disables all restrictions of the session.
* When a relay decides to close a session on its own (user safeword, for instance) and it is not due to the controller being unreachable, the relay must send the following acknowledgement message:
release,<controller_key>,!release,ok

When receiving the latter message, the controller should act accordingly, for instance by resetting itself and making itself ready for the next session.

Note that !release is not the same as @clear. @clear is interpreted by the relay as a RLV command and, as such, can only clear RLV restrictions. If RLV restrictions were the only restrictions of the session, then the session will be closed, but some x-tensions also define pure LSL based restrictions.

===ping/!pong===

The ping/!pong mechanism exists so that relays can check presence and responsiveness of a controller. This was primarily meant to be used on relay wearer relog, in order to reactivate all restrictions so that sessions persist on relog if the controller still exists and is ready to continue the session.

''!pong'' cannot require auth and does not lock a session

We call ''ping message'' a message from the relay, having the following syntax:
ping,<controller_key>,ping,ping
We call ''!pong message'' a message from the controller, having the following syntax:
ping,<relay_key>,!pong

====Relay side====
*A relay SHOULD NOT send an acknowledgement in response to ''!pong''.
*A ping message can be sent any time by the relay to a known controller.
*On wearer relog, for each existing Locked session, the relay must send a ping message to the session controller.
*When a !pong message is received from a controller, if it was a reply to a previous ping message:
:#if the session RLV restrictions contain unsit and the avatar was sitting on some object when the restriction was applied, then the relay MUST force the avatar to sit back on the same object (if still existing);
:#the relay MUST make sure all restrictions belonging to the session are made active again.
*If a ping message is sent and is not answered by the controller, then the relay closes the session.

Note that the relay is responsible for storing restrictions and the key of the sit target across sessions, not the controller.

====Controller side====
*Unless it does not matter that the relay could close the session (or for another reason, the controller knows the relay will not close it), a controller SHOULD listen to ping messages and answer any ping message with a !pong message.
*A controller should ignore ping requests from relays it is not ready to handle.

Note controller don't have to poll for relay presence to resume a session but should just listen for ping messages instead. The relay should have stored all restrictions and handle sitting back to whatever furniture the relay wearer was tied up to.

Concerning the second bullet: for instance, if the controller is a furniture which is already in use by another relay wearer, it would be cause dysfunctions to let the pinging relay restore the restrictions without letting its wearer sit on the furniture. Or if the controller is not stateless and the state for the pinging relay has not been saved before, resuming the session from the initial state might be inconsistant.

===!version===
The purpose of this meta-command is to query the version of the RLVR protocol supported by a relay.

* !version opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !version with the version number of the RLVR protocol it supports ("1100" here, since ORG 0004 includes RLVR 1.100).

Note this is the most common command for a controller to scan for nearby relays, as non-ORG relays also accept this command and answer it the way described above.

===!implversion===
The purpose of this meta-command is to query the name and version of the relay implementation.

* !implversion opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !implversion with its implementation version string... which can be any string.

It is recommended this string includes the following elements:
* the relay name/brand/identifier,
* the version number of that relay name/brand/identifier,
* at the beginning, the string prefix "ORG=0004/"
The latter is convenient for checking for ORG compatibility using a command even non-ORG relay should understand.

===!x-orgversions===

This meta-command purpose it two-fold. First it allows a controlling device to ask a relay for the list of ORG x-tensions it supports and, second, similarily to !version, !x-orgversions can be used to know what version of ORG the relay complies to.

'''Example:'''
C<->R
-> query,rUUID,!x-orgversions
<- query,cUUID,!x-orgversions,ORG=0004/who=002/email=006

'''Requirements:'''
* !x-orgversions should always be accepted with no Auth required, it does not open a session or Lock one.
* The acknowledgement value in a reply to !x-orgversions is a "/"-list of items of the form <package>=<version>. The first <package> is always "ORG" (representing the core specification package of ORG relays), its version string is the version of the specification (4 digits). The other packages are ORG x-tension names, whose version string is 3 digits.
* If several incompatible versions of a same x-tension are supported, they must be listed ordered by version number. Ex: ORG=0004/who=002/email=005/email=006. If versions are backward compatible, only the last version should be reported.

'''Remarks:'''
* In a controller, it is however recommended to use !x-orgversions as soon as possible in order to avoid sending unsupported and useless metacommands later on.
* In the acknowledgement message, x-tension names are listed, not meta-command names (as one x-tension can have several meta-commands). Thus listed names do not include the prefix "!x-".

LSL Protocol/Restrained Love Open Relay Group/ORG Requirements/0004 draft

2011-06-27T15:15:50Z

Satomi Ahn: /* On executing commands */

{{ORG_Restrained_Life_Relay_Specs_TOC}}
STATUS: draft

VERSION: 0004

==Summary==

This page is a list of requirements for a relay or an in-world device to have the right to be called "ORG compliant". It is mostly about adding support for an ORG-centered informational metacommand and specifying Marine Kelley's RLVR protocol a bit more that it is now, while of course preserving full compatibility.

For a quick overview of the motivations and general working of this protocol and a few examples, we refer the reader to [[LSL_Protocol/Restrained_Love_Relay/Specification|the original specification page by Marine Kelley]].

If you are making furniture, traps, or other RLVR controllers and you are not interested in what [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] can offer, then you can stick with the original specification by Marine Kelley and still be compatible with [[LSL_Protocol/Restrained_Love_Relay/Comparison|ORG relays]]. However, to have the right to call your controller "ORG compatible", there are still a few light additional requirements such as:
* using only [[llRegionSayTo]] for communications with the relay,
* not spamming the RLVR channel with messages that do not belong to the protocol,
* and remain responsive to ping messages at every time if you want the session to remain locked.

If you are interested in [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|ORG x-tensions]], then you should also read the part about [[#!x-orgversions|!x-orgversions]].

If you are making a relay, sorry we are afraid you will have to read all this page.

==Definition of an ORG device==

A RLVR device is compliant with ORG specifications if it implements the consolidated RLVR protocol described below along with the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] it announces supporting.

Note in particular that
* the consolidated protocol is backward compatible with [[LSL_Protocol/Restrained_Love_Relay/Specification|Marine Kelley's RLVR protocol version 1.100]] but resolves most loose ends of that document;
* ORG relays handle controller messages whose second field is ffffffff-ffff-ffff-ffff-ffffffffffff exactly the same as if it was the key of the wearer (NULL_KEY is a wildcard);
* one-to-one chat messages (not using a wildcard) are sent by using [[llRegionSayTo]] LSL function;
* there is an additional meta-command, !x-orgversions for a relay to announce supported x-tensions;
* each supported x-tension can imply other supported metacommands, ORG x-tensions meta-command all having names starting with prefix "!x-";
* other proprietary metacommands with prefix "!_-" (replace "_" by any letter that is not "x") can be supported;

Supported x-tensions can constrain the core specification (this document) even more, but cannot alter it or make it less constraining unless as a result of the relay executing a meta-command of this x-tension sent by the controller. Thus, although the protocol is extensible, a controller can always rely on the fact an ORG relay abides by the requirements in this document until it asks the relay to do otherwise.

ORG devices may be advertised by the use of the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/ORG_Logo|ORG logo]] for advertising compliance with ORG requirements. ORG devices makers are encouraged to do so.

==Consolidated RLVR protocol==

=== Protocol Syntax ===
Summary of differences with original RLVR:
* we force use of llRegionSayTo,
* we explicitly forbid incorrect syntax on the relay channel
* the relay is supposed to ignore bad commands
* wildcards are supported

==== Definitions ====
* The '''Restrained Love Relay (RLVR) protocol''' implies two partners (SL objects): the '''relay''', attachment worn by the avatar commands are intended for, and a '''controller''', which sends commands to the relay.

* The goal of the protocol is to force the relay wearer to make perform actions and to toggle restrictions on their behavior. Both actions and restrictions can be enforced either through use of viewer hooks ([[LSL_Protocol/RestrainedLoveAPI|Restrained Love API]], or RLV) or through LSL scripting.

* Hence we distinguish between "'''RLV commands'''", starting with "@", which are commands following the syntax of the RLV API and which will ultimately be forwarded to the viewer, and "'''meta-commands'''", starting with "!", which are meant to be interpreted by LSL functions.

====Requirements====
RLVR protocol consists of messages exchanged between relay and controller
* on channel -1812221819 (called '''RLVR channel'''),
* using the LSL function [[llRegionSayTo]],
* all sent from the same prim of the controller or relay (within a [[#Protocol session|session]])
* and having the following syntax (non-terminal <c_msg> for controller messages/'''command messages''' and <r_msg> for relay messages/'''acknowledgement messages'''):

<c_msg> ::= IDENT "," KEY "," <commands>
<r_msg> ::= IDENT "," KEY "," <command> "," ACK
<commands> ::= <command> | <command> "|" <commands>
<command> ::= <rlvcommand> | <metacommand>
<rlvcommand> ::= "@" RLVCOMMAND
<metacommand> ::= "!" METACOMMANDNAME <metacommandarguments>
<metacommandarguments> ::= "" | "/" ARG <metacommandarguments>

where we explicit the different terminal tokens:
IDENT: any string without ","
KEY: any UUID
ACK: any string without ","
RLVCOMMAND: any string without ","
METACOMMANDNAME: any string without "/" and ","
ARG: any string without "/" and ","

* Relays can only send <r_msg>'s, and controllers <c_msg>'s. Nothing else is allowed on RLVR channel.
* In <c_msg>, KEY is always either the uuid of the relay wearer or ffffffff-ffff-ffff-ffff-ffffffffffff ('''wildcard''') if it is a message intended for all relays who can hear it.
* In <r_msg>, KEY is always the uuid of the controller.

====On the relay side only====
'''Further requirements:'''
*A relay MUST ignore any message on RLVR channel which is not a <c_msg> with KEY being either the key of the avatar wearing the relay or ffffffff-ffff-ffff-ffff-ffffffffffff.
Then, for every <command>:
* if <command> is neither a valid <rlvcommand> or <metacommand>, the relay must ignore it and process the next <command>'s;
* if <command> is a <rlvcommand> or a <metacommand>, the relay MUST send back to the controller a <r_msg> (see above) such that:
:*IDENT is the same as IDENT in the <c_msg> being processed,
:*<command> is the subcommand being processed
:*and ACK is a string called ''acknowledgement value''. By default the acknowledgement value is "ok" if the relay will execute the <command >, "ko" otherwise.

'''Remarks:'''
* Many meta-commands may have other acknowledgements than "ok" or "ko" (or none, for !pong). Their definitions supersede this specification.
* Note that unknown meta-commands cannot be executed and thus wil be acknowledged by "ko".
* Known meta-commands which are sent with not enough parameters or parameters with types incompatible with those in the definition known by the relay also cannot be executed and will also be acknowledged by "ko". (ex: the relay knows !x-who/key, but receives !x-who/integer/string).

===On executing commands===
Summary of differences with original RLVR:
* explanation on how to handle meta-commands with variable number of parameters,
* the relay knows commands in both core specification and x-tensions,
* clarification on multi-controller relays.

====Relay side====
'''Requirements:'''
* If a <rlvcommand> is acknowledged with value "ok", the relay ensures the viewer is affected the same way as if the LSL instruction llOwnerSay(<rlvcommand>) was executed by a script in a primitive that handles only one controller.
* When processing a <metacommand>, if the relay knows at least one definition of '!'+METACOMMANDNAME for which the received <metacommandarguments> provide enough parameters, then it will be handled according to the definition handling the most parameters among the latter. Extra parameters are ignored.
* A relays knows the following meta-command definitions:
:*[[#Core meta-commands and associated mechanisms|definitions listed in the core requirements]]
:*all definitions included in [[LSL_Protocol/Restrained_Love_Relay/Comparison|x-tensions]] announced by the relay.
* When acknowledging a <metacommand> by anything else than "ko", the relay commits itself to execute it.

'''Remarks:'''
* For first requirement, it must be understood that the reference behavior is that the relay would have if it had one controller per prim. However handling several controllers from one unique prim is possible but requires taking care that different controllers do not interfere with each other, releasing each other's restrictions, for instance.
* For the second requirement, the word "handled" means that if the meta-command with these parameters is known, then requirements in known definition cannot be ignored. Sometimes, this can imply that the meta-command cannot be refused, for instance.

====Controller side====
* The controller can send any command within allowed syntax.
* Only commands described in this specification and commands belonging to x-tensions announced by the relay are guaranteed to be understood by the relay. If not understood, the relay will just answer "ko", do nothing and skip to the next command.

===Protocol session===

====Definitions====
* During an execution of the RLVR protocol, a relay and a controller establish a '''session''' together. A relay may manage several sessions with several controllers. Likewise, a controller could establish sessions with several relays.
* Restrictions on a relay wearer are relative to a session. So are most other variables (authorization state, key of the controller, ... ).
* A session is '''Opened''' whenever the relay accepts a RLVR command from a controller.
* A session is '''Closed''' (or '''released''') as soon as the relay forgets every variables and releases all restrictions pertaining to that session.
* A session is '''Locked''' whenever it holds active restrictions.
* A session is '''Authed''' if the controller has been allowed to control the relay (not only store some variables with no consequence). Once authed, no interactive "ask" dialog should pop up anymore concerning this session. Most commands should now normally be accepted (and maybe a few automatically rejected).
* A controller is called '''reachable''' if it can receive messages from the relay and can prove it by answering [[#ping/!pong|ping]] requests from the relay. By "can", it is meant by the method of communication agreed upon by the relay and controller (by default: chat messages sent on RLVR channel by llRegionSayTo). X-tensions such as email and delay can modify what is meant by reachable.

====Relay side requirements====
On closing sessions:
*Closing a session clears all RLV restrictions that belong only to that session, clears all session variables and disables all restrictions relative to that session. This MUST happen on the following events and no other:
:*on executing !release (received from the controller, or relay-triggered as in a safeword, see [[#!release]])
:*on noticing the controller is not reachable
:*on timeout, if the session is not Locked
*Sessions that are not locked MUST be closed after a reasonable timeout.

On interactive Auth:
*Unless specified otherwise (see !x-who), no command can trigger an interactive dialog unless the command requires an Authed session and the session is not already Authed.
*Relay implementations MAY require an authed session for all <rlvcommand>'s of the form @xxx=force, @xxx=add and @xxx=n, and for meta-commands whose specifications say it is allowed.
*Other RLV commands MUST automatically accepted or rejected by any relay.

On removing and adding restrictions:
* Commands that remove restrictions are always accepted (RLV @...=<channel_number>, @clear[=...] and @...=y/rem commands, !release, and !x-.../clear[/...] meta-commands).
* No restriction can be released unless as the result of one of the above commands, or of closing a session.
*@xxx=n/add <rlvcommand>'s, after being accepted, add a restriction and therefore Lock the session.
*Some meta-commands described in x-tensions can also add restrictions and therefore Lock the session.

Reachability:
*A relay MUST provide a mechanism for checking that every controlling device is reachable. It is not specified whether this checking process should be automatic or manually triggered.

====Controller side requirements====
* A controller MUST eventually close any Locked session using the meta-command !release.

In particular, non-portable controllers should not let a Locked relay wearer run free out of reach. Moreover, any controller should either react to some kind of event that is bound to happen (timer expiration being the most common) or provide a user interface for closing the session. It should be clear at least to the person who set the trap how the victim will be released.

==Core meta-commands and associated mechanisms==

An ORG device MUST at least support the meta-commands !release, !pong, !version, !implversion and !x-orgversions described below and implement their associated mechanisms.

Particular meta-commands definitions and mechanisms may override general requirements above.

===!release===
Sent by a controller, this command closes the session.

* !release obviously opens no session, requires no Auth and is not Locking.
* If there is an actual session to close !release MUST be accepted by the relay and acknowledeged by "ok".
* On accepting !release, the relay erases all data pertaining to the session and disables all restrictions of the session.
* When a relay decides to close a session on its own (user safeword, for instance) and it is not due to the controller being unreachable, the relay must send the following acknowledgement message:
release,<controller_key>,!release,ok

When receiving the latter message, the controller should act accordingly, for instance by resetting itself and making itself ready for the next session.

Note that !release is not the same as @clear. @clear is interpreted by the relay as a RLV command and, as such, can only clear RLV restrictions. If RLV restrictions were the only restrictions of the session, then the session will be closed, but some x-tensions also define pure LSL based restrictions.

===ping/!pong===

The ping/!pong mechanism exists so that relays can check presence and responsiveness of a controller. This was primarily meant to be used on relay wearer relog, in order to reactivate all restrictions so that sessions persist on relog if the controller still exists and is ready to continue the session.

''!pong'' cannot require auth and does not lock a session

We call ''ping message'' a message from the relay, having the following syntax:
ping,<controller_key>,ping,ping
We call ''!pong message'' a message from the controller, having the following syntax:
ping,<relay_key>,!pong

====Relay side====
*A relay SHOULD NOT send an acknowledgement in response to ''!pong''.
*A ping message can be sent any time by the relay to a known controller.
*On wearer relog, for each existing Locked session, the relay must send a ping message to the session controller.
*When a !pong message is received from a controller, if it was a reply to a previous ping message:
:#if the session RLV restrictions contain unsit and the avatar was sitting on some object when the restriction was applied, then the relay MUST force the avatar to sit back on the same object (if still existing);
:#the relay MUST make sure all restrictions belonging to the session are made active again.
*If a ping message is sent and is not answered by the controller, then the relay closes the session.

Note that the relay is responsible for storing restrictions and the key of the sit target across sessions, not the controller.

====Controller side====
*Unless it does not matter that the relay could close the session (or for another reason, the controller knows the relay will not close it), a controller SHOULD listen to ping messages and answer any ping message with a !pong message.
*A controller should ignore ping requests from relays it is not ready to handle.

Note controller don't have to poll for relay presence to resume a session but should just listen for ping messages instead. The relay should have stored all restrictions and handle sitting back to whatever furniture the relay wearer was tied up to.

Concerning the second bullet: for instance, if the controller is a furniture which is already in use by another relay wearer, it would be cause dysfunctions to let the pinging relay restore the restrictions without letting its wearer sit on the furniture. Or if the controller is not stateless and the state for the pinging relay has not been saved before, resuming the session from the initial state might be inconsistant.

===!version===
The purpose of this meta-command is to query the version of the RLVR protocol supported by a relay.

* !version opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !version with the version number of the RLVR protocol it supports ("1100" here, since ORG 0004 includes RLVR 1.100).

Note this is the most common command for a controller to scan for nearby relays, as non-ORG relays also accept this command and answer it the way described above.

===!implversion===
The purpose of this meta-command is to query the name and version of the relay implementation.

* !implversion opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !implversion with its implementation version string... which can be any string.

It is recommended this string includes the following elements:
* the relay name/brand/identifier,
* the version number of that relay name/brand/identifier,
* at the beginning, the string prefix "ORG=0004/"
The latter is convenient for checking for ORG compatibility using a command even non-ORG relay should understand.

===!x-orgversions===

This meta-command purpose it two-fold. First it allows a controlling device to ask a relay for the list of ORG x-tensions it supports and, second, similarily to !version, !x-orgversions can be used to know what version of ORG the relay complies to.

'''Example:'''
C<->R
-> query,rUUID,!x-orgversions
<- query,cUUID,!x-orgversions,ORG=0004/who=002/email=006

'''Requirements:'''
* !x-orgversions should always be accepted with no Auth required, it does not open a session or Lock one.
* The acknowledgement value in a reply to !x-orgversions is a "/"-list of items of the form <package>=<version>. The first <package> is always "ORG" (representing the core specification package of ORG relays), its version string is the version of the specification (4 digits). The other packages are ORG x-tension names, whose version string is 3 digits.
* If several incompatible versions of a same x-tension are supported, they must be listed ordered by version number. Ex: ORG=0004/who=002/email=005/email=006. If versions are backward compatible, only the last version should be reported.

'''Remarks:'''
* In a controller, it is however recommended to use !x-orgversions as soon as possible in order to avoid sending unsupported and useless metacommands later on.
* In the acknowledgement message, x-tension names are listed, not meta-command names (as one x-tension can have several meta-commands). Thus listed names do not include the prefix "!x-".

LSL Protocol/Restrained Love Open Relay Group/ORG Requirements/0004 draft

2011-06-27T15:11:51Z

Satomi Ahn: /* Protocol Syntax */

{{ORG_Restrained_Life_Relay_Specs_TOC}}
STATUS: draft

VERSION: 0004

==Summary==

This page is a list of requirements for a relay or an in-world device to have the right to be called "ORG compliant". It is mostly about adding support for an ORG-centered informational metacommand and specifying Marine Kelley's RLVR protocol a bit more that it is now, while of course preserving full compatibility.

For a quick overview of the motivations and general working of this protocol and a few examples, we refer the reader to [[LSL_Protocol/Restrained_Love_Relay/Specification|the original specification page by Marine Kelley]].

If you are making furniture, traps, or other RLVR controllers and you are not interested in what [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] can offer, then you can stick with the original specification by Marine Kelley and still be compatible with [[LSL_Protocol/Restrained_Love_Relay/Comparison|ORG relays]]. However, to have the right to call your controller "ORG compatible", there are still a few light additional requirements such as:
* using only [[llRegionSayTo]] for communications with the relay,
* not spamming the RLVR channel with messages that do not belong to the protocol,
* and remain responsive to ping messages at every time if you want the session to remain locked.

If you are interested in [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|ORG x-tensions]], then you should also read the part about [[#!x-orgversions|!x-orgversions]].

If you are making a relay, sorry we are afraid you will have to read all this page.

==Definition of an ORG device==

A RLVR device is compliant with ORG specifications if it implements the consolidated RLVR protocol described below along with the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] it announces supporting.

Note in particular that
* the consolidated protocol is backward compatible with [[LSL_Protocol/Restrained_Love_Relay/Specification|Marine Kelley's RLVR protocol version 1.100]] but resolves most loose ends of that document;
* ORG relays handle controller messages whose second field is ffffffff-ffff-ffff-ffff-ffffffffffff exactly the same as if it was the key of the wearer (NULL_KEY is a wildcard);
* one-to-one chat messages (not using a wildcard) are sent by using [[llRegionSayTo]] LSL function;
* there is an additional meta-command, !x-orgversions for a relay to announce supported x-tensions;
* each supported x-tension can imply other supported metacommands, ORG x-tensions meta-command all having names starting with prefix "!x-";
* other proprietary metacommands with prefix "!_-" (replace "_" by any letter that is not "x") can be supported;

Supported x-tensions can constrain the core specification (this document) even more, but cannot alter it or make it less constraining unless as a result of the relay executing a meta-command of this x-tension sent by the controller. Thus, although the protocol is extensible, a controller can always rely on the fact an ORG relay abides by the requirements in this document until it asks the relay to do otherwise.

ORG devices may be advertised by the use of the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/ORG_Logo|ORG logo]] for advertising compliance with ORG requirements. ORG devices makers are encouraged to do so.

==Consolidated RLVR protocol==

=== Protocol Syntax ===
Summary of differences with original RLVR:
* we force use of llRegionSayTo,
* we explicitly forbid incorrect syntax on the relay channel
* the relay is supposed to ignore bad commands
* wildcards are supported

==== Definitions ====
* The '''Restrained Love Relay (RLVR) protocol''' implies two partners (SL objects): the '''relay''', attachment worn by the avatar commands are intended for, and a '''controller''', which sends commands to the relay.

* The goal of the protocol is to force the relay wearer to make perform actions and to toggle restrictions on their behavior. Both actions and restrictions can be enforced either through use of viewer hooks ([[LSL_Protocol/RestrainedLoveAPI|Restrained Love API]], or RLV) or through LSL scripting.

* Hence we distinguish between "'''RLV commands'''", starting with "@", which are commands following the syntax of the RLV API and which will ultimately be forwarded to the viewer, and "'''meta-commands'''", starting with "!", which are meant to be interpreted by LSL functions.

====Requirements====
RLVR protocol consists of messages exchanged between relay and controller
* on channel -1812221819 (called '''RLVR channel'''),
* using the LSL function [[llRegionSayTo]],
* all sent from the same prim of the controller or relay (within a [[#Protocol session|session]])
* and having the following syntax (non-terminal <c_msg> for controller messages/'''command messages''' and <r_msg> for relay messages/'''acknowledgement messages'''):

<c_msg> ::= IDENT "," KEY "," <commands>
<r_msg> ::= IDENT "," KEY "," <command> "," ACK
<commands> ::= <command> | <command> "|" <commands>
<command> ::= <rlvcommand> | <metacommand>
<rlvcommand> ::= "@" RLVCOMMAND
<metacommand> ::= "!" METACOMMANDNAME <metacommandarguments>
<metacommandarguments> ::= "" | "/" ARG <metacommandarguments>

where we explicit the different terminal tokens:
IDENT: any string without ","
KEY: any UUID
ACK: any string without ","
RLVCOMMAND: any string without ","
METACOMMANDNAME: any string without "/" and ","
ARG: any string without "/" and ","

* Relays can only send <r_msg>'s, and controllers <c_msg>'s. Nothing else is allowed on RLVR channel.
* In <c_msg>, KEY is always either the uuid of the relay wearer or ffffffff-ffff-ffff-ffff-ffffffffffff ('''wildcard''') if it is a message intended for all relays who can hear it.
* In <r_msg>, KEY is always the uuid of the controller.

====On the relay side only====
'''Further requirements:'''
*A relay MUST ignore any message on RLVR channel which is not a <c_msg> with KEY being either the key of the avatar wearing the relay or ffffffff-ffff-ffff-ffff-ffffffffffff.
Then, for every <command>:
* if <command> is neither a valid <rlvcommand> or <metacommand>, the relay must ignore it and process the next <command>'s;
* if <command> is a <rlvcommand> or a <metacommand>, the relay MUST send back to the controller a <r_msg> (see above) such that:
:*IDENT is the same as IDENT in the <c_msg> being processed,
:*<command> is the subcommand being processed
:*and ACK is a string called ''acknowledgement value''. By default the acknowledgement value is "ok" if the relay will execute the <command >, "ko" otherwise.

'''Remarks:'''
* Many meta-commands may have other acknowledgements than "ok" or "ko" (or none, for !pong). Their definitions supersede this specification.
* Note that unknown meta-commands cannot be executed and thus wil be acknowledged by "ko".
* Known meta-commands which are sent with not enough parameters or parameters with types incompatible with those in the definition known by the relay also cannot be executed and will also be acknowledged by "ko". (ex: the relay knows !x-who/key, but receives !x-who/integer/string).

===On executing commands===
====Relay side====
'''Requirements:'''
* If a <rlvcommand> is acknowledged with value "ok", the relay ensures the viewer is affected the same way as if the LSL instruction llOwnerSay(<rlvcommand>) was executed by a script in a primitive that handles only one controller.
* When processing a <metacommand>, if the relay knows at least one definition of '!'+METACOMMANDNAME for which the received <metacommandarguments> provide enough parameters, then it will be handled according to the definition handling the most parameters among the latter. Extra parameters are ignored.
* A relays knows the following meta-command definitions:
:*[[#Core meta-commands and associated mechanisms|definitions listed in the core requirements]]
:*all definitions included in [[LSL_Protocol/Restrained_Love_Relay/Comparison|x-tensions]] announced by the relay.
* When acknowledging a <metacommand> by anything else than "ko", the relay commits itself to execute it.

'''Remarks:'''
* For first requirement, it must be understood that the reference behavior is that the relay would have if it had one controller per prim. However handling several controllers from one unique prim is possible but requires taking care that different controllers do not interfere with each other, releasing each other's restrictions, for instance.
* For the second requirement, the word "handled" means that if the meta-command with these parameters is known, then requirements in known definition cannot be ignored. Sometimes, this can imply that the meta-command cannot be refused, for instance.

====Controller side====
* The controller can send any command within allowed syntax.
* Only commands described in this specification and commands belonging to x-tensions announced by the relay are guaranteed to be understood by the relay. If not understood, the relay will just answer "ko", do nothing and skip to the next command.

===Protocol session===

====Definitions====
* During an execution of the RLVR protocol, a relay and a controller establish a '''session''' together. A relay may manage several sessions with several controllers. Likewise, a controller could establish sessions with several relays.
* Restrictions on a relay wearer are relative to a session. So are most other variables (authorization state, key of the controller, ... ).
* A session is '''Opened''' whenever the relay accepts a RLVR command from a controller.
* A session is '''Closed''' (or '''released''') as soon as the relay forgets every variables and releases all restrictions pertaining to that session.
* A session is '''Locked''' whenever it holds active restrictions.
* A session is '''Authed''' if the controller has been allowed to control the relay (not only store some variables with no consequence). Once authed, no interactive "ask" dialog should pop up anymore concerning this session. Most commands should now normally be accepted (and maybe a few automatically rejected).
* A controller is called '''reachable''' if it can receive messages from the relay and can prove it by answering [[#ping/!pong|ping]] requests from the relay. By "can", it is meant by the method of communication agreed upon by the relay and controller (by default: chat messages sent on RLVR channel by llRegionSayTo). X-tensions such as email and delay can modify what is meant by reachable.

====Relay side requirements====
On closing sessions:
*Closing a session clears all RLV restrictions that belong only to that session, clears all session variables and disables all restrictions relative to that session. This MUST happen on the following events and no other:
:*on executing !release (received from the controller, or relay-triggered as in a safeword, see [[#!release]])
:*on noticing the controller is not reachable
:*on timeout, if the session is not Locked
*Sessions that are not locked MUST be closed after a reasonable timeout.

On interactive Auth:
*Unless specified otherwise (see !x-who), no command can trigger an interactive dialog unless the command requires an Authed session and the session is not already Authed.
*Relay implementations MAY require an authed session for all <rlvcommand>'s of the form @xxx=force, @xxx=add and @xxx=n, and for meta-commands whose specifications say it is allowed.
*Other RLV commands MUST automatically accepted or rejected by any relay.

On removing and adding restrictions:
* Commands that remove restrictions are always accepted (RLV @...=<channel_number>, @clear[=...] and @...=y/rem commands, !release, and !x-.../clear[/...] meta-commands).
* No restriction can be released unless as the result of one of the above commands, or of closing a session.
*@xxx=n/add <rlvcommand>'s, after being accepted, add a restriction and therefore Lock the session.
*Some meta-commands described in x-tensions can also add restrictions and therefore Lock the session.

Reachability:
*A relay MUST provide a mechanism for checking that every controlling device is reachable. It is not specified whether this checking process should be automatic or manually triggered.

====Controller side requirements====
* A controller MUST eventually close any Locked session using the meta-command !release.

In particular, non-portable controllers should not let a Locked relay wearer run free out of reach. Moreover, any controller should either react to some kind of event that is bound to happen (timer expiration being the most common) or provide a user interface for closing the session. It should be clear at least to the person who set the trap how the victim will be released.

==Core meta-commands and associated mechanisms==

An ORG device MUST at least support the meta-commands !release, !pong, !version, !implversion and !x-orgversions described below and implement their associated mechanisms.

Particular meta-commands definitions and mechanisms may override general requirements above.

===!release===
Sent by a controller, this command closes the session.

* !release obviously opens no session, requires no Auth and is not Locking.
* If there is an actual session to close !release MUST be accepted by the relay and acknowledeged by "ok".
* On accepting !release, the relay erases all data pertaining to the session and disables all restrictions of the session.
* When a relay decides to close a session on its own (user safeword, for instance) and it is not due to the controller being unreachable, the relay must send the following acknowledgement message:
release,<controller_key>,!release,ok

When receiving the latter message, the controller should act accordingly, for instance by resetting itself and making itself ready for the next session.

Note that !release is not the same as @clear. @clear is interpreted by the relay as a RLV command and, as such, can only clear RLV restrictions. If RLV restrictions were the only restrictions of the session, then the session will be closed, but some x-tensions also define pure LSL based restrictions.

===ping/!pong===

The ping/!pong mechanism exists so that relays can check presence and responsiveness of a controller. This was primarily meant to be used on relay wearer relog, in order to reactivate all restrictions so that sessions persist on relog if the controller still exists and is ready to continue the session.

''!pong'' cannot require auth and does not lock a session

We call ''ping message'' a message from the relay, having the following syntax:
ping,<controller_key>,ping,ping
We call ''!pong message'' a message from the controller, having the following syntax:
ping,<relay_key>,!pong

====Relay side====
*A relay SHOULD NOT send an acknowledgement in response to ''!pong''.
*A ping message can be sent any time by the relay to a known controller.
*On wearer relog, for each existing Locked session, the relay must send a ping message to the session controller.
*When a !pong message is received from a controller, if it was a reply to a previous ping message:
:#if the session RLV restrictions contain unsit and the avatar was sitting on some object when the restriction was applied, then the relay MUST force the avatar to sit back on the same object (if still existing);
:#the relay MUST make sure all restrictions belonging to the session are made active again.
*If a ping message is sent and is not answered by the controller, then the relay closes the session.

Note that the relay is responsible for storing restrictions and the key of the sit target across sessions, not the controller.

====Controller side====
*Unless it does not matter that the relay could close the session (or for another reason, the controller knows the relay will not close it), a controller SHOULD listen to ping messages and answer any ping message with a !pong message.
*A controller should ignore ping requests from relays it is not ready to handle.

Note controller don't have to poll for relay presence to resume a session but should just listen for ping messages instead. The relay should have stored all restrictions and handle sitting back to whatever furniture the relay wearer was tied up to.

Concerning the second bullet: for instance, if the controller is a furniture which is already in use by another relay wearer, it would be cause dysfunctions to let the pinging relay restore the restrictions without letting its wearer sit on the furniture. Or if the controller is not stateless and the state for the pinging relay has not been saved before, resuming the session from the initial state might be inconsistant.

===!version===
The purpose of this meta-command is to query the version of the RLVR protocol supported by a relay.

* !version opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !version with the version number of the RLVR protocol it supports ("1100" here, since ORG 0004 includes RLVR 1.100).

Note this is the most common command for a controller to scan for nearby relays, as non-ORG relays also accept this command and answer it the way described above.

===!implversion===
The purpose of this meta-command is to query the name and version of the relay implementation.

* !implversion opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !implversion with its implementation version string... which can be any string.

It is recommended this string includes the following elements:
* the relay name/brand/identifier,
* the version number of that relay name/brand/identifier,
* at the beginning, the string prefix "ORG=0004/"
The latter is convenient for checking for ORG compatibility using a command even non-ORG relay should understand.

===!x-orgversions===

This meta-command purpose it two-fold. First it allows a controlling device to ask a relay for the list of ORG x-tensions it supports and, second, similarily to !version, !x-orgversions can be used to know what version of ORG the relay complies to.

'''Example:'''
C<->R
-> query,rUUID,!x-orgversions
<- query,cUUID,!x-orgversions,ORG=0004/who=002/email=006

'''Requirements:'''
* !x-orgversions should always be accepted with no Auth required, it does not open a session or Lock one.
* The acknowledgement value in a reply to !x-orgversions is a "/"-list of items of the form <package>=<version>. The first <package> is always "ORG" (representing the core specification package of ORG relays), its version string is the version of the specification (4 digits). The other packages are ORG x-tension names, whose version string is 3 digits.
* If several incompatible versions of a same x-tension are supported, they must be listed ordered by version number. Ex: ORG=0004/who=002/email=005/email=006. If versions are backward compatible, only the last version should be reported.

'''Remarks:'''
* In a controller, it is however recommended to use !x-orgversions as soon as possible in order to avoid sending unsupported and useless metacommands later on.
* In the acknowledgement message, x-tension names are listed, not meta-command names (as one x-tension can have several meta-commands). Thus listed names do not include the prefix "!x-".

LSL Protocol/Restrained Love Open Relay Group/ORG Requirements/0004 draft

2011-06-27T15:00:32Z

Satomi Ahn:

{{ORG_Restrained_Life_Relay_Specs_TOC}}
STATUS: draft

VERSION: 0004

==Summary==

This page is a list of requirements for a relay or an in-world device to have the right to be called "ORG compliant". It is mostly about adding support for an ORG-centered informational metacommand and specifying Marine Kelley's RLVR protocol a bit more that it is now, while of course preserving full compatibility.

For a quick overview of the motivations and general working of this protocol and a few examples, we refer the reader to [[LSL_Protocol/Restrained_Love_Relay/Specification|the original specification page by Marine Kelley]].

If you are making furniture, traps, or other RLVR controllers and you are not interested in what [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] can offer, then you can stick with the original specification by Marine Kelley and still be compatible with [[LSL_Protocol/Restrained_Love_Relay/Comparison|ORG relays]]. However, to have the right to call your controller "ORG compatible", there are still a few light additional requirements such as:
* using only [[llRegionSayTo]] for communications with the relay,
* not spamming the RLVR channel with messages that do not belong to the protocol,
* and remain responsive to ping messages at every time if you want the session to remain locked.

If you are interested in [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|ORG x-tensions]], then you should also read the part about [[#!x-orgversions|!x-orgversions]].

If you are making a relay, sorry we are afraid you will have to read all this page.

==Definition of an ORG device==

A RLVR device is compliant with ORG specifications if it implements the consolidated RLVR protocol described below along with the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] it announces supporting.

Note in particular that
* the consolidated protocol is backward compatible with [[LSL_Protocol/Restrained_Love_Relay/Specification|Marine Kelley's RLVR protocol version 1.100]] but resolves most loose ends of that document;
* ORG relays handle controller messages whose second field is ffffffff-ffff-ffff-ffff-ffffffffffff exactly the same as if it was the key of the wearer (NULL_KEY is a wildcard);
* one-to-one chat messages (not using a wildcard) are sent by using [[llRegionSayTo]] LSL function;
* there is an additional meta-command, !x-orgversions for a relay to announce supported x-tensions;
* each supported x-tension can imply other supported metacommands, ORG x-tensions meta-command all having names starting with prefix "!x-";
* other proprietary metacommands with prefix "!_-" (replace "_" by any letter that is not "x") can be supported;

Supported x-tensions can constrain the core specification (this document) even more, but cannot alter it or make it less constraining unless as a result of the relay executing a meta-command of this x-tension sent by the controller. Thus, although the protocol is extensible, a controller can always rely on the fact an ORG relay abides by the requirements in this document until it asks the relay to do otherwise.

ORG devices may be advertised by the use of the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/ORG_Logo|ORG logo]] for advertising compliance with ORG requirements. ORG devices makers are encouraged to do so.

==Consolidated RLVR protocol==

=== Protocol Syntax ===

==== Definitions ====
* The '''Restrained Love Relay (RLVR) protocol''' implies two partners (SL objects): the '''relay''', attachment worn by the avatar commands are intended for, and a '''controller''', which sends commands to the relay.

* The goal of the protocol is to force the relay wearer to make perform actions and to toggle restrictions on their behavior. Both actions and restrictions can be enforced either through use of viewer hooks ([[LSL_Protocol/RestrainedLoveAPI|Restrained Love API]], or RLV) or through LSL scripting.

* Hence we distinguish between "'''RLV commands'''", starting with "@", which are commands following the syntax of the RLV API and which will ultimately be forwarded to the viewer, and "'''meta-commands'''", starting with "!", which are meant to be interpreted by LSL functions.

====Requirements====
RLVR protocol consists of messages exchanged between relay and controller
* on channel -1812221819 (called '''RLVR channel'''),
* using the LSL function [[llRegionSayTo]],
* all sent from the same prim of the controller or relay (within a [[#Protocol session|session]])
* and having the following syntax (non-terminal <c_msg> for controller messages/'''command messages''' and <r_msg> for relay messages/'''acknowledgement messages'''):

<c_msg> ::= IDENT "," KEY "," <commands>
<r_msg> ::= IDENT "," KEY "," <command> "," ACK
<commands> ::= <command> | <command> "|" <commands>
<command> ::= <rlvcommand> | <metacommand>
<rlvcommand> ::= "@" RLVCOMMAND
<metacommand> ::= "!" METACOMMANDNAME <metacommandarguments>
<metacommandarguments> ::= "" | "/" ARG <metacommandarguments>

where we explicit the different terminal tokens:
IDENT: any string without ","
KEY: any UUID
ACK: any string without ","
RLVCOMMAND: any string without ","
METACOMMANDNAME: any string without "/" and ","
ARG: any string without "/" and ","

* Relays can only send <r_msg>'s, and controllers <c_msg>'s. Nothing else is allowed on RLVR channel.
* In <c_msg>, KEY is always either the uuid of the relay wearer or ffffffff-ffff-ffff-ffff-ffffffffffff ('''wildcard''') if it is a message intended for all relays who can hear it.
* In <r_msg>, KEY is always the uuid of the controller.

====On the relay side only====
'''Further requirements:'''
*A relay MUST ignore any message on RLVR channel which is not a <c_msg> with KEY being either the key of the avatar wearing the relay or ffffffff-ffff-ffff-ffff-ffffffffffff.
Then, for every <command>:
* if <command> is neither a valid <rlvcommand> or <metacommand>, the relay must ignore it and process the next <command>'s;
* if <command> is a <rlvcommand> or a <metacommand>, the relay MUST send back to the controller a <r_msg> (see above) such that:
:*IDENT is the same as IDENT in the <c_msg> being processed,
:*<command> is the subcommand being processed
:*and ACK is a string called ''acknowledgement value''. By default the acknowledgement value is "ok" if the relay will execute the <command >, "ko" otherwise.

'''Remarks:'''
* Many meta-commands may have other acknowledgements than "ok" or "ko" (or none, for !pong). Their definitions supersede this specification.
* Note that unknown meta-commands cannot be executed and thus wil be acknowledged by "ko".
* Known meta-commands which are sent with not enough parameters or parameters with types incompatible with those in the definition known by the relay also cannot be executed and will also be acknowledged by "ko". (ex: the relay knows !x-who/key, but receives !x-who/integer/string).

===On executing commands===
====Relay side====
'''Requirements:'''
* If a <rlvcommand> is acknowledged with value "ok", the relay ensures the viewer is affected the same way as if the LSL instruction llOwnerSay(<rlvcommand>) was executed by a script in a primitive that handles only one controller.
* When processing a <metacommand>, if the relay knows at least one definition of '!'+METACOMMANDNAME for which the received <metacommandarguments> provide enough parameters, then it will be handled according to the definition handling the most parameters among the latter. Extra parameters are ignored.
* A relays knows the following meta-command definitions:
:*[[#Core meta-commands and associated mechanisms|definitions listed in the core requirements]]
:*all definitions included in [[LSL_Protocol/Restrained_Love_Relay/Comparison|x-tensions]] announced by the relay.
* When acknowledging a <metacommand> by anything else than "ko", the relay commits itself to execute it.

'''Remarks:'''
* For first requirement, it must be understood that the reference behavior is that the relay would have if it had one controller per prim. However handling several controllers from one unique prim is possible but requires taking care that different controllers do not interfere with each other, releasing each other's restrictions, for instance.
* For the second requirement, the word "handled" means that if the meta-command with these parameters is known, then requirements in known definition cannot be ignored. Sometimes, this can imply that the meta-command cannot be refused, for instance.

====Controller side====
* The controller can send any command within allowed syntax.
* Only commands described in this specification and commands belonging to x-tensions announced by the relay are guaranteed to be understood by the relay. If not understood, the relay will just answer "ko", do nothing and skip to the next command.

===Protocol session===

====Definitions====
* During an execution of the RLVR protocol, a relay and a controller establish a '''session''' together. A relay may manage several sessions with several controllers. Likewise, a controller could establish sessions with several relays.
* Restrictions on a relay wearer are relative to a session. So are most other variables (authorization state, key of the controller, ... ).
* A session is '''Opened''' whenever the relay accepts a RLVR command from a controller.
* A session is '''Closed''' (or '''released''') as soon as the relay forgets every variables and releases all restrictions pertaining to that session.
* A session is '''Locked''' whenever it holds active restrictions.
* A session is '''Authed''' if the controller has been allowed to control the relay (not only store some variables with no consequence). Once authed, no interactive "ask" dialog should pop up anymore concerning this session. Most commands should now normally be accepted (and maybe a few automatically rejected).
* A controller is called '''reachable''' if it can receive messages from the relay and can prove it by answering [[#ping/!pong|ping]] requests from the relay. By "can", it is meant by the method of communication agreed upon by the relay and controller (by default: chat messages sent on RLVR channel by llRegionSayTo). X-tensions such as email and delay can modify what is meant by reachable.

====Relay side requirements====
On closing sessions:
*Closing a session clears all RLV restrictions that belong only to that session, clears all session variables and disables all restrictions relative to that session. This MUST happen on the following events and no other:
:*on executing !release (received from the controller, or relay-triggered as in a safeword, see [[#!release]])
:*on noticing the controller is not reachable
:*on timeout, if the session is not Locked
*Sessions that are not locked MUST be closed after a reasonable timeout.

On interactive Auth:
*Unless specified otherwise (see !x-who), no command can trigger an interactive dialog unless the command requires an Authed session and the session is not already Authed.
*Relay implementations MAY require an authed session for all <rlvcommand>'s of the form @xxx=force, @xxx=add and @xxx=n, and for meta-commands whose specifications say it is allowed.
*Other RLV commands MUST automatically accepted or rejected by any relay.

On removing and adding restrictions:
* Commands that remove restrictions are always accepted (RLV @...=<channel_number>, @clear[=...] and @...=y/rem commands, !release, and !x-.../clear[/...] meta-commands).
* No restriction can be released unless as the result of one of the above commands, or of closing a session.
*@xxx=n/add <rlvcommand>'s, after being accepted, add a restriction and therefore Lock the session.
*Some meta-commands described in x-tensions can also add restrictions and therefore Lock the session.

Reachability:
*A relay MUST provide a mechanism for checking that every controlling device is reachable. It is not specified whether this checking process should be automatic or manually triggered.

====Controller side requirements====
* A controller MUST eventually close any Locked session using the meta-command !release.

In particular, non-portable controllers should not let a Locked relay wearer run free out of reach. Moreover, any controller should either react to some kind of event that is bound to happen (timer expiration being the most common) or provide a user interface for closing the session. It should be clear at least to the person who set the trap how the victim will be released.

==Core meta-commands and associated mechanisms==

An ORG device MUST at least support the meta-commands !release, !pong, !version, !implversion and !x-orgversions described below and implement their associated mechanisms.

Particular meta-commands definitions and mechanisms may override general requirements above.

===!release===
Sent by a controller, this command closes the session.

* !release obviously opens no session, requires no Auth and is not Locking.
* If there is an actual session to close !release MUST be accepted by the relay and acknowledeged by "ok".
* On accepting !release, the relay erases all data pertaining to the session and disables all restrictions of the session.
* When a relay decides to close a session on its own (user safeword, for instance) and it is not due to the controller being unreachable, the relay must send the following acknowledgement message:
release,<controller_key>,!release,ok

When receiving the latter message, the controller should act accordingly, for instance by resetting itself and making itself ready for the next session.

Note that !release is not the same as @clear. @clear is interpreted by the relay as a RLV command and, as such, can only clear RLV restrictions. If RLV restrictions were the only restrictions of the session, then the session will be closed, but some x-tensions also define pure LSL based restrictions.

===ping/!pong===

The ping/!pong mechanism exists so that relays can check presence and responsiveness of a controller. This was primarily meant to be used on relay wearer relog, in order to reactivate all restrictions so that sessions persist on relog if the controller still exists and is ready to continue the session.

''!pong'' cannot require auth and does not lock a session

We call ''ping message'' a message from the relay, having the following syntax:
ping,<controller_key>,ping,ping
We call ''!pong message'' a message from the controller, having the following syntax:
ping,<relay_key>,!pong

====Relay side====
*A relay SHOULD NOT send an acknowledgement in response to ''!pong''.
*A ping message can be sent any time by the relay to a known controller.
*On wearer relog, for each existing Locked session, the relay must send a ping message to the session controller.
*When a !pong message is received from a controller, if it was a reply to a previous ping message:
:#if the session RLV restrictions contain unsit and the avatar was sitting on some object when the restriction was applied, then the relay MUST force the avatar to sit back on the same object (if still existing);
:#the relay MUST make sure all restrictions belonging to the session are made active again.
*If a ping message is sent and is not answered by the controller, then the relay closes the session.

Note that the relay is responsible for storing restrictions and the key of the sit target across sessions, not the controller.

====Controller side====
*Unless it does not matter that the relay could close the session (or for another reason, the controller knows the relay will not close it), a controller SHOULD listen to ping messages and answer any ping message with a !pong message.
*A controller should ignore ping requests from relays it is not ready to handle.

Note controller don't have to poll for relay presence to resume a session but should just listen for ping messages instead. The relay should have stored all restrictions and handle sitting back to whatever furniture the relay wearer was tied up to.

Concerning the second bullet: for instance, if the controller is a furniture which is already in use by another relay wearer, it would be cause dysfunctions to let the pinging relay restore the restrictions without letting its wearer sit on the furniture. Or if the controller is not stateless and the state for the pinging relay has not been saved before, resuming the session from the initial state might be inconsistant.

===!version===
The purpose of this meta-command is to query the version of the RLVR protocol supported by a relay.

* !version opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !version with the version number of the RLVR protocol it supports ("1100" here, since ORG 0004 includes RLVR 1.100).

Note this is the most common command for a controller to scan for nearby relays, as non-ORG relays also accept this command and answer it the way described above.

===!implversion===
The purpose of this meta-command is to query the name and version of the relay implementation.

* !implversion opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !implversion with its implementation version string... which can be any string.

It is recommended this string includes the following elements:
* the relay name/brand/identifier,
* the version number of that relay name/brand/identifier,
* at the beginning, the string prefix "ORG=0004/"
The latter is convenient for checking for ORG compatibility using a command even non-ORG relay should understand.

===!x-orgversions===

This meta-command purpose it two-fold. First it allows a controlling device to ask a relay for the list of ORG x-tensions it supports and, second, similarily to !version, !x-orgversions can be used to know what version of ORG the relay complies to.

'''Example:'''
C<->R
-> query,rUUID,!x-orgversions
<- query,cUUID,!x-orgversions,ORG=0004/who=002/email=006

'''Requirements:'''
* !x-orgversions should always be accepted with no Auth required, it does not open a session or Lock one.
* The acknowledgement value in a reply to !x-orgversions is a "/"-list of items of the form <package>=<version>. The first <package> is always "ORG" (representing the core specification package of ORG relays), its version string is the version of the specification (4 digits). The other packages are ORG x-tension names, whose version string is 3 digits.
* If several incompatible versions of a same x-tension are supported, they must be listed ordered by version number. Ex: ORG=0004/who=002/email=005/email=006. If versions are backward compatible, only the last version should be reported.

'''Remarks:'''
* In a controller, it is however recommended to use !x-orgversions as soon as possible in order to avoid sending unsupported and useless metacommands later on.
* In the acknowledgement message, x-tension names are listed, not meta-command names (as one x-tension can have several meta-commands). Thus listed names do not include the prefix "!x-".

LSL Protocol/Restrained Love Open Relay Group/ORG Requirements/0004 draft

2011-06-27T14:55:48Z

Satomi Ahn: /* Protocol session */

{{ORG_Restrained_Life_Relay_Specs_TOC}}
STATUS: draft

VERSION: 0004

==Summary==

This page is a list of requirements for a relay or an in-world device to have the right to be called "ORG compliant". It is mostly about adding support for an ORG-centered informational metacommand and specifying Marine Kelley's RLVR protocol a bit more that it is now, while of course preserving full compatibility.

For a quick overview of the motivations and general working of this protocol and a few examples, we refer the reader to [[LSL_Protocol/Restrained_Love_Relay/Specification|the original specification page by Marine Kelley]].

If you are making furniture, traps, or other RLVR controllers and you are not interested in what [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] can offer, then you can stick with the original specification by Marine Kelley and still be compatible with [[LSL_Protocol/Restrained_Love_Relay/Comparison|ORG relays]]. However, to have the right to call your controller "ORG compatible", there are still a few light additional requirements such as:
* using only [[llRegionSayTo]] for communications with the relay,
* not spamming the RLVR channel with messages that do not belong to the protocol,
* and remain responsive to ping messages at every time if you want the session to remain locked.

If you are interested in [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|ORG x-tensions]], then you should also read the part about [[#!x-orgversions|!x-orgversions]].

If you are making a relay, sorry we are afraid you will have to read all this page.

==Definition of an ORG device==

A RLVR device is compliant with ORG specifications if it implements the consolidated RLVR protocol described below along with the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] it announces supporting.

Note in particular that
* the consolidated protocol is backward compatible with [[LSL_Protocol/Restrained_Love_Relay/Specification|Marine Kelley's RLVR protocol version 1.100]] but resolves most loose ends of that document;
* ORG relays handle controller messages whose second field is ffffffff-ffff-ffff-ffff-ffffffffffff exactly the same as if it was the key of the wearer (NULL_KEY is a wildcard);
* one-to-one chat messages (not using a wildcard) are sent by using [[llRegionSayTo]] LSL function;
* there is an additional meta-command, !x-orgversions for a relay to announce supported x-tensions;
* each supported x-tension can imply other supported metacommands, ORG x-tensions meta-command all having names starting with prefix "!x-";
* other proprietary metacommands with prefix "!_-" (replace "_" by any letter that is not "x") can be supported;

Supported x-tensions can constrain the core specification (this document) even more, but cannot alter it or make it less constraining unless as a result of the relay executing a meta-command of this x-tension sent by the controller. Thus, although the protocol is extensible, a controller can always rely on the fact an ORG relay abides by the requirements in this document until it asks the relay to do otherwise.

ORG devices may be advertised by the use of the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/ORG_Logo|ORG logo]] for advertising compliance with ORG requirements. ORG devices makers are encouraged to do so.

==Consolidated RLVR protocol==

=== Protocol Syntax ===

==== Definitions ====
* The '''Restrained Love Relay (RLVR) protocol''' implies two partners (SL objects): the '''relay''', attachment worn by the avatar commands are intended for, and a '''controller''', which sends commands to the relay.

* The goal of the protocol is to force the relay wearer to make perform actions and to toggle restrictions on their behavior. Both actions and restrictions can be enforced either through use of viewer hooks ([[LSL_Protocol/RestrainedLoveAPI|Restrained Love API]], or RLV) or through LSL scripting.

* Hence we distinguish between "'''RLV commands'''", starting with "@", which are commands following the syntax of the RLV API and which will ultimately be forwarded to the viewer, and "'''meta-commands'''", starting with "!", which are meant to be interpreted by LSL functions.

====Requirements====
RLVR protocol consists of messages exchanged between relay and controller
* on channel -1812221819 (called '''RLVR channel'''),
* using the LSL function [[llRegionSayTo]],
* all sent from the same prim of the controller or relay (within a [[#Protocol session|session]])
* and having the following syntax (non-terminal <c_msg> for controller messages/'''command messages''' and <r_msg> for relay messages/'''acknowledgement messages'''):

<c_msg> ::= IDENT "," KEY "," <commands>
<r_msg> ::= IDENT "," KEY "," <command> "," ACK
<commands> ::= <command> | <command> "|" <commands>
<command> ::= <rlvcommand> | <metacommand>
<rlvcommand> ::= "@" RLVCOMMAND
<metacommand> ::= "!" METACOMMANDNAME <metacommandarguments>
<metacommandarguments> ::= "" | "/" ARG <metacommandarguments>

where we explicit the different terminal tokens:
IDENT: any string without ","
KEY: any UUID
ACK: any string without ","
RLVCOMMAND: any string without ","
METACOMMANDNAME: any string without "/" and ","
ARG: any string without "/" and ","

* Relays can only send <r_msg>'s, and controllers <c_msg>'s. Nothing else is allowed on RLVR channel.
* In <c_msg>, KEY is always either the uuid of the relay wearer or ffffffff-ffff-ffff-ffff-ffffffffffff ('''wildcard''') if it is a message intended for all relays who can hear it.
* In <r_msg>, KEY is always the uuid of the controller.

====On the relay side only====
'''Further requirements:'''
*A relay MUST ignore any message on RLVR channel which is not a <c_msg> with KEY being either the key of the avatar wearing the relay or ffffffff-ffff-ffff-ffff-ffffffffffff.
Then, for every <command>:
* if <command> is neither a valid <rlvcommand> or <metacommand>, the relay must ignore it and process the next <command>'s;
* if <command> is a <rlvcommand> or a <metacommand>, the relay MUST send back to the controller a <r_msg> (see above) such that:
:*IDENT is the same as IDENT in the <c_msg> being processed,
:*<command> is the subcommand being processed
:*and ACK is a string called ''acknowledgement value''. By default the acknowledgement value is "ok" if the relay will execute the <command >, "ko" otherwise.

'''Remarks:'''
* Many meta-commands may have other acknowledgements than "ok" or "ko" (or none, for !pong). Their definitions supersede this specification.
* Note that unknown meta-commands cannot be executed and thus wil be acknowledged by "ko".
* Known meta-commands which are sent with not enough parameters or parameters with types incompatible with those in the definition known by the relay also cannot be executed and will also be acknowledged by "ko". (ex: the relay knows !x-who/key, but receives !x-who/integer/string).

===Protocol session===

====Definitions====
* During an execution of the RLVR protocol, a relay and a controller establish a '''session''' together. A relay may manage several sessions with several controllers. Likewise, a controller could establish sessions with several relays.
* Restrictions on a relay wearer are relative to a session. So are most other variables (authorization state, key of the controller, ... ).
* A session is '''Opened''' whenever the relay accepts a RLVR command from a controller.
* A session is '''Closed''' (or '''released''') as soon as the relay forgets every variables and releases all restrictions pertaining to that session.
* A session is '''Locked''' whenever it holds active restrictions.
* A session is '''Authed''' if the controller has been allowed to control the relay (not only store some variables with no consequence). Once authed, no interactive "ask" dialog should pop up anymore concerning this session. Most commands should now normally be accepted (and maybe a few automatically rejected).
* A controller is called '''reachable''' if it can receive messages from the relay and can prove it by answering [[#ping/!pong|ping]] requests from the relay. By "can", it is meant by the method of communication agreed upon by the relay and controller (by default: chat messages sent on RLVR channel by llRegionSayTo). X-tensions such as email and delay can modify what is meant by reachable.

====Relay side requirements====
On closing sessions:
*Closing a session clears all RLV restrictions that belong only to that session, clears all session variables and disables all restrictions relative to that session. This MUST happen on the following events and no other:
:*on executing !release (received from the controller, or relay-triggered as in a safeword, see [[#!release]])
:*on noticing the controller is not reachable
:*on timeout, if the session is not Locked
*Sessions that are not locked MUST be closed after a reasonable timeout.

On interactive Auth:
*Unless specified otherwise (see !x-who), no command can trigger an interactive dialog unless the command requires an Authed session and the session is not already Authed.
*Relay implementations MAY require an authed session for all <rlvcommand>'s of the form @xxx=force, @xxx=add and @xxx=n, and for meta-commands whose specifications say it is allowed.
*Other RLV commands MUST automatically accepted or rejected by any relay.

On removing and adding restrictions:
* Commands that remove restrictions are always accepted (RLV @...=<channel_number>, @clear[=...] and @...=y/rem commands, !release, and !x-.../clear[/...] meta-commands).
* No restriction can be released unless as the result of one of the above commands, or of closing a session.
*@xxx=n/add <rlvcommand>'s, after being accepted, add a restriction and therefore Lock the session.
*Some meta-commands described in x-tensions can also add restrictions and therefore Lock the session.

Reachability:
*A relay MUST provide a mechanism for checking that every controlling device is reachable. It is not specified whether this checking process should be automatic or manually triggered.

====Controller side requirements====
* A controller MUST eventually close any Locked session using the meta-command !release.

In particular, non-portable controllers should not let a Locked relay wearer run free out of reach. Moreover, any controller should either react to some kind of event that is bound to happen (timer expiration being the most common) or provide a user interface for closing the session. It should be clear at least to the person who set the trap how the victim will be released.

===Commands===
====Relay side requirements====
* If a <rlvcommand> is acknowledged with value "ok", the relay ensures the viewer is affected the same way as if the LSL instruction llOwnerSay(<rlvcommand>) was executed by a script in a primitive that handles only one controller.
* When processing a <metacommand>, if the relay knows at least one definition of '!'+METACOMMANDNAME for which the received <metacommandarguments> provide enough parameters, then it will be handled according to the definition handling the most parameters among the latter. Extra parameters are ignored.
* A relays knows the following meta-command definitions:
:*[[#Core meta-commands and associated mechanisms|definitions listed in the core requirements]]
:*all definitions included in [[LSL_Protocol/Restrained_Love_Relay/Comparison|x-tensions]] announced by the relay.
* When acknowledging a <metacommand> by anything else than "ko", the relay commits itself to execute it.

'''Remarks:'''
* For first requirement, it must be understood that the reference behavior is that the relay would have if it had one controller per prim. However handling several controllers from one unique prim is possible but requires taking care that different controllers do not interfere with each other, releasing each other's restrictions, for instance.
* For the second requirement, the word "handled" means that if the meta-command with these parameters is known, then requirements in known definition cannot be ignored. Sometimes, this can imply that the meta-command cannot be refused, for instance.

==Core meta-commands and associated mechanisms==

An ORG device MUST at least support the meta-commands !release, !pong, !version, !implversion and !x-orgversions described below and implement their associated mechanisms.

Particular meta-commands definitions and mechanisms may override general requirements above.

===!release===
Sent by a controller, this command closes the session.

* !release obviously opens no session, requires no Auth and is not Locking.
* If there is an actual session to close !release MUST be accepted by the relay and acknowledeged by "ok".
* On accepting !release, the relay erases all data pertaining to the session and disables all restrictions of the session.
* When a relay decides to close a session on its own (user safeword, for instance) and it is not due to the controller being unreachable, the relay must send the following acknowledgement message:
release,<controller_key>,!release,ok

When receiving the latter message, the controller should act accordingly, for instance by resetting itself and making itself ready for the next session.

Note that !release is not the same as @clear. @clear is interpreted by the relay as a RLV command and, as such, can only clear RLV restrictions. If RLV restrictions were the only restrictions of the session, then the session will be closed, but some x-tensions also define pure LSL based restrictions.

===ping/!pong===

The ping/!pong mechanism exists so that relays can check presence and responsiveness of a controller. This was primarily meant to be used on relay wearer relog, in order to reactivate all restrictions so that sessions persist on relog if the controller still exists and is ready to continue the session.

''!pong'' cannot require auth and does not lock a session

We call ''ping message'' a message from the relay, having the following syntax:
ping,<controller_key>,ping,ping
We call ''!pong message'' a message from the controller, having the following syntax:
ping,<relay_key>,!pong

====Relay side====
*A relay SHOULD NOT send an acknowledgement in response to ''!pong''.
*A ping message can be sent any time by the relay to a known controller.
*On wearer relog, for each existing Locked session, the relay must send a ping message to the session controller.
*When a !pong message is received from a controller, if it was a reply to a previous ping message:
:#if the session RLV restrictions contain unsit and the avatar was sitting on some object when the restriction was applied, then the relay MUST force the avatar to sit back on the same object (if still existing);
:#the relay MUST make sure all restrictions belonging to the session are made active again.
*If a ping message is sent and is not answered by the controller, then the relay closes the session.

Note that the relay is responsible for storing restrictions and the key of the sit target across sessions, not the controller.

====Controller side====
*Unless it does not matter that the relay could close the session (or for another reason, the controller knows the relay will not close it), a controller SHOULD listen to ping messages and answer any ping message with a !pong message.
*A controller should ignore ping requests from relays it is not ready to handle.

Note controller don't have to poll for relay presence to resume a session but should just listen for ping messages instead. The relay should have stored all restrictions and handle sitting back to whatever furniture the relay wearer was tied up to.

Concerning the second bullet: for instance, if the controller is a furniture which is already in use by another relay wearer, it would be cause dysfunctions to let the pinging relay restore the restrictions without letting its wearer sit on the furniture. Or if the controller is not stateless and the state for the pinging relay has not been saved before, resuming the session from the initial state might be inconsistant.

===!version===
The purpose of this meta-command is to query the version of the RLVR protocol supported by a relay.

* !version opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !version with the version number of the RLVR protocol it supports ("1100" here, since ORG 0004 includes RLVR 1.100).

Note this is the most common command for a controller to scan for nearby relays, as non-ORG relays also accept this command and answer it the way described above.

===!implversion===
The purpose of this meta-command is to query the name and version of the relay implementation.

* !implversion opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !implversion with its implementation version string... which can be any string.

It is recommended this string includes the following elements:
* the relay name/brand/identifier,
* the version number of that relay name/brand/identifier,
* at the beginning, the string prefix "ORG=0004/"
The latter is convenient for checking for ORG compatibility using a command even non-ORG relay should understand.

===!x-orgversions===

This meta-command purpose it two-fold. First it allows a controlling device to ask a relay for the list of ORG x-tensions it supports and, second, similarily to !version, !x-orgversions can be used to know what version of ORG the relay complies to.

'''Example:'''
C<->R
-> query,rUUID,!x-orgversions
<- query,cUUID,!x-orgversions,ORG=0004/who=002/email=006

'''Requirements:'''
* !x-orgversions should always be accepted with no Auth required, it does not open a session or Lock one.
* The acknowledgement value in a reply to !x-orgversions is a "/"-list of items of the form <package>=<version>. The first <package> is always "ORG" (representing the core specification package of ORG relays), its version string is the version of the specification (4 digits). The other packages are ORG x-tension names, whose version string is 3 digits.
* If several incompatible versions of a same x-tension are supported, they must be listed ordered by version number. Ex: ORG=0004/who=002/email=005/email=006. If versions are backward compatible, only the last version should be reported.

'''Remarks:'''
* In a controller, it is however recommended to use !x-orgversions as soon as possible in order to avoid sending unsupported and useless metacommands later on.
* In the acknowledgement message, x-tension names are listed, not meta-command names (as one x-tension can have several meta-commands). Thus listed names do not include the prefix "!x-".

LSL Protocol/Restrained Love Open Relay Group/ORG Requirements/0004 draft

2011-06-27T14:14:44Z

Satomi Ahn: /* On the relay side only */

{{ORG_Restrained_Life_Relay_Specs_TOC}}
STATUS: draft

VERSION: 0004

==Summary==

This page is a list of requirements for a relay or an in-world device to have the right to be called "ORG compliant". It is mostly about adding support for an ORG-centered informational metacommand and specifying Marine Kelley's RLVR protocol a bit more that it is now, while of course preserving full compatibility.

For a quick overview of the motivations and general working of this protocol and a few examples, we refer the reader to [[LSL_Protocol/Restrained_Love_Relay/Specification|the original specification page by Marine Kelley]].

If you are making furniture, traps, or other RLVR controllers and you are not interested in what [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] can offer, then you can stick with the original specification by Marine Kelley and still be compatible with [[LSL_Protocol/Restrained_Love_Relay/Comparison|ORG relays]]. However, to have the right to call your controller "ORG compatible", there are still a few light additional requirements such as:
* using only [[llRegionSayTo]] for communications with the relay,
* not spamming the RLVR channel with messages that do not belong to the protocol,
* and remain responsive to ping messages at every time if you want the session to remain locked.

If you are interested in [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|ORG x-tensions]], then you should also read the part about [[#!x-orgversions|!x-orgversions]].

If you are making a relay, sorry we are afraid you will have to read all this page.

==Definition of an ORG device==

A RLVR device is compliant with ORG specifications if it implements the consolidated RLVR protocol described below along with the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] it announces supporting.

Note in particular that
* the consolidated protocol is backward compatible with [[LSL_Protocol/Restrained_Love_Relay/Specification|Marine Kelley's RLVR protocol version 1.100]] but resolves most loose ends of that document;
* ORG relays handle controller messages whose second field is ffffffff-ffff-ffff-ffff-ffffffffffff exactly the same as if it was the key of the wearer (NULL_KEY is a wildcard);
* one-to-one chat messages (not using a wildcard) are sent by using [[llRegionSayTo]] LSL function;
* there is an additional meta-command, !x-orgversions for a relay to announce supported x-tensions;
* each supported x-tension can imply other supported metacommands, ORG x-tensions meta-command all having names starting with prefix "!x-";
* other proprietary metacommands with prefix "!_-" (replace "_" by any letter that is not "x") can be supported;

Supported x-tensions can constrain the core specification (this document) even more, but cannot alter it or make it less constraining unless as a result of the relay executing a meta-command of this x-tension sent by the controller. Thus, although the protocol is extensible, a controller can always rely on the fact an ORG relay abides by the requirements in this document until it asks the relay to do otherwise.

ORG devices may be advertised by the use of the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/ORG_Logo|ORG logo]] for advertising compliance with ORG requirements. ORG devices makers are encouraged to do so.

==Consolidated RLVR protocol==

=== Protocol Syntax ===

==== Definitions ====
* The '''Restrained Love Relay (RLVR) protocol''' implies two partners (SL objects): the '''relay''', attachment worn by the avatar commands are intended for, and a '''controller''', which sends commands to the relay.

* The goal of the protocol is to force the relay wearer to make perform actions and to toggle restrictions on their behavior. Both actions and restrictions can be enforced either through use of viewer hooks ([[LSL_Protocol/RestrainedLoveAPI|Restrained Love API]], or RLV) or through LSL scripting.

* Hence we distinguish between "'''RLV commands'''", starting with "@", which are commands following the syntax of the RLV API and which will ultimately be forwarded to the viewer, and "'''meta-commands'''", starting with "!", which are meant to be interpreted by LSL functions.

====Requirements====
RLVR protocol consists of messages exchanged between relay and controller
* on channel -1812221819 (called '''RLVR channel'''),
* using the LSL function [[llRegionSayTo]],
* all sent from the same prim of the controller or relay (within a [[#Protocol session|session]])
* and having the following syntax (non-terminal <c_msg> for controller messages/'''command messages''' and <r_msg> for relay messages/'''acknowledgement messages'''):

<c_msg> ::= IDENT "," KEY "," <commands>
<r_msg> ::= IDENT "," KEY "," <command> "," ACK
<commands> ::= <command> | <command> "|" <commands>
<command> ::= <rlvcommand> | <metacommand>
<rlvcommand> ::= "@" RLVCOMMAND
<metacommand> ::= "!" METACOMMANDNAME <metacommandarguments>
<metacommandarguments> ::= "" | "/" ARG <metacommandarguments>

where we explicit the different terminal tokens:
IDENT: any string without ","
KEY: any UUID
ACK: any string without ","
RLVCOMMAND: any string without ","
METACOMMANDNAME: any string without "/" and ","
ARG: any string without "/" and ","

* Relays can only send <r_msg>'s, and controllers <c_msg>'s. Nothing else is allowed on RLVR channel.
* In <c_msg>, KEY is always either the uuid of the relay wearer or ffffffff-ffff-ffff-ffff-ffffffffffff ('''wildcard''') if it is a message intended for all relays who can hear it.
* In <r_msg>, KEY is always the uuid of the controller.

====On the relay side only====
'''Further requirements:'''
*A relay MUST ignore any message on RLVR channel which is not a <c_msg> with KEY being either the key of the avatar wearing the relay or ffffffff-ffff-ffff-ffff-ffffffffffff.
Then, for every <command>:
* if <command> is neither a valid <rlvcommand> or <metacommand>, the relay must ignore it and process the next <command>'s;
* if <command> is a <rlvcommand> or a <metacommand>, the relay MUST send back to the controller a <r_msg> (see above) such that:
:*IDENT is the same as IDENT in the <c_msg> being processed,
:*<command> is the subcommand being processed
:*and ACK is a string called ''acknowledgement value''. By default the acknowledgement value is "ok" if the relay will execute the <command >, "ko" otherwise.

'''Remarks:'''
* Many meta-commands may have other acknowledgements than "ok" or "ko" (or none, for !pong). Their definitions supersede this specification.
* Note that unknown meta-commands cannot be executed and thus wil be acknowledged by "ko".
* Known meta-commands which are sent with not enough parameters or parameters with types incompatible with those in the definition known by the relay also cannot be executed and will also be acknowledged by "ko". (ex: the relay knows !x-who/key, but receives !x-who/integer/string).

===Protocol session===

====Definitions====
* During an execution of the RLVR protocol, a relay and a controller establish a '''session''' together. A relay may manage several sessions with several controllers. Likewise, a controller could establish sessions with several relays.
* Restrictions on a relay wearer are relative to a session. So are most other variables (authorization state, key of the controller, ... ).
* A session is '''Opened''' whenever the relay accepts a RLVR command from a controller.
* A session is '''Closed''' (or '''released''') as soon as the relay forgets every variables and releases all restrictions pertaining to that session.
* A session is '''Locked''' whenever it holds active restrictions.
* A session is '''Authed''' if the controller has been allowed to control the relay (not only store some variables with no consequence). Once authed, no interactive "ask" dialog should pop up anymore concerning this session. Most commands should now normally be accepted (and maybe a few automatically rejected).
* A controller is called '''reachable''' if it can receive messages from the relay and can prove it by answering ping requests from the relay. By "can", it is meant by the method of communication agreed upon by the relay and controller. By default the communication method is chat messages sent by llRegionSayTo. X-tensions such as email and delay can modify what is meant by reachable.

====Relay side requirements====
*Closing a session clears all RLV restrictions that belong only to that session, clears all session variables and disables all behaviors relative to that session.
*Sessions that are not locked MUST be released after a reasonable timeout.
*Relay implementations MAY require an authed session for all <rlvcommand>'s, except @xxx=<channel_number>, @clear[=xxx] and @xxx=y/rem commands, which MUST always be accepted.
*@xxx=n/add <rlvcommand>'s, after being accepted, add a restriction and therefore Lock the session.
*Some metacommands described in x-tensions can also add restrictions and therefore Lock the session.
*!release, !version, !implversion, !x-orgversions and !x-.../clear[/...] commands are always accepted.
*!pong reactivates an existing session but never requires further auth, provided it is sent by the device to which ping was sent. The relay MUST resend to the viewer all stored restrictions belonging to the controlling device if they are not already active.
*Unless specified otherwise (see !x-who), no command can trigger an interactive dialog unless
:* they require an Authed session
:* and no session is currently open or it is open but not Authed yet.
*When releasing a Locked session, a relay MUST release all restrictions belonging to the device controlling the session.
*On the following events, a relay MUST release a locked session:
:* when the relay notices the controller has become unreachable,
:* when the relay sends "release,<controller_key>,!release,ok" (due to acknowledging !release sent by the controller, or due to safewording triggered from the relay side).
*A relay MUST provide a mechanism for checking that every controlling device is reachable. It is not specified whether this checking process should be automatic or manually triggered.
*The absence of active restriction unlocks the session (and eventually releases it).
*A relay MUST remove restrictions from a session when (and only in these cases):
:* either the session controller specifically asks for the restriction to be released ("@restriction=y" "@restriction=rem", "@clear=restriction" for RLV restrictions, and "!x-restriction/clear/..." for LSL restrictions),
:* or the session closed (for instance !release coming from the device, or safeword).

===Commands===
====Relay side requirements====
* If a <rlvcommand> is acknowledged with value "ok", the relay ensures the viewer is affected the same way as if the LSL instruction llOwnerSay(<rlvcommand>) was executed by a script in a primitive that handles only one controller.
* When processing a <metacommand>, if the relay knows at least one definition of '!'+METACOMMANDNAME for which the received <metacommandarguments> provide enough parameters, then it will be handled according to the definition handling the most parameters among the latter. Extra parameters are ignored.
* A relays knows the following meta-command definitions:
:*[[#Core meta-commands and associated mechanisms|definitions listed in the core requirements]]
:*all definitions included in [[LSL_Protocol/Restrained_Love_Relay/Comparison|x-tensions]] announced by the relay.
* When acknowledging a <metacommand> by anything else than "ko", the relay commits itself to execute it.

'''Remarks:'''
* For first requirement, it must be understood that the reference behavior is that the relay would have if it had one controller per prim. However handling several controllers from one unique prim is possible but requires taking care that different controllers do not interfere with each other, releasing each other's restrictions, for instance.
* For the second requirement, the word "handled" means that if the meta-command with these parameters is known, then requirements in known definition cannot be ignored. Sometimes, this can imply that the meta-command cannot be refused, for instance.

==Core meta-commands and associated mechanisms==

An ORG device MUST at least support the meta-commands !release, !pong, !version, !implversion and !x-orgversions described below and implement their associated mechanisms.

Particular meta-commands definitions and mechanisms may override general requirements above.

===!release===
Sent by a controller, this command closes the session.

* !release obviously opens no session, requires no Auth and is not Locking.
* If there is an actual session to close !release MUST be accepted by the relay and acknowledeged by "ok".
* On accepting !release, the relay erases all data pertaining to the session and disables all restrictions of the session.
* When a relay decides to close a session on its own (user safeword, for instance) and it is not due to the controller being unreachable, the relay must send the following acknowledgement message:
release,<controller_key>,!release,ok

When receiving the latter message, the controller should act accordingly, for instance by resetting itself and making itself ready for the next session.

Note that !release is not the same as @clear. @clear is interpreted by the relay as a RLV command and, as such, can only clear RLV restrictions. If RLV restrictions were the only restrictions of the session, then the session will be closed, but some x-tensions also define pure LSL based restrictions.

===ping/!pong===

The ping/!pong mechanism exists so that relays can check presence and responsiveness of a controller. This was primarily meant to be used on relay wearer relog, in order to reactivate all restrictions so that sessions persist on relog if the controller still exists and is ready to continue the session.

''!pong'' cannot require auth and does not lock a session

We call ''ping message'' a message from the relay, having the following syntax:
ping,<controller_key>,ping,ping
We call ''!pong message'' a message from the controller, having the following syntax:
ping,<relay_key>,!pong

====Relay side====
*A relay SHOULD NOT send an acknowledgement in response to ''!pong''.
*A ping message can be sent any time by the relay to a known controller.
*On wearer relog, for each existing Locked session, the relay must send a ping message to the session controller.
*When a !pong message is received from a controller, if it was a reply to a previous ping message:
:#if the session RLV restrictions contain unsit and the avatar was sitting on some object when the restriction was applied, then the relay MUST force the avatar to sit back on the same object (if still existing);
:#the relay MUST make sure all restrictions belonging to the session are made active again.
*If a ping message is sent and is not answered by the controller, then the relay closes the session.

Note that the relay is responsible for storing restrictions and the key of the sit target across sessions, not the controller.

====Controller side====
*Unless it does not matter that the relay could close the session (or for another reason, the controller knows the relay will not close it), a controller SHOULD listen to ping messages and answer any ping message with a !pong message.
*A controller should ignore ping requests from relays it is not ready to handle.

Note controller don't have to poll for relay presence to resume a session but should just listen for ping messages instead. The relay should have stored all restrictions and handle sitting back to whatever furniture the relay wearer was tied up to.

Concerning the second bullet: for instance, if the controller is a furniture which is already in use by another relay wearer, it would be cause dysfunctions to let the pinging relay restore the restrictions without letting its wearer sit on the furniture. Or if the controller is not stateless and the state for the pinging relay has not been saved before, resuming the session from the initial state might be inconsistant.

===!version===
The purpose of this meta-command is to query the version of the RLVR protocol supported by a relay.

* !version opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !version with the version number of the RLVR protocol it supports ("1100" here, since ORG 0004 includes RLVR 1.100).

Note this is the most common command for a controller to scan for nearby relays, as non-ORG relays also accept this command and answer it the way described above.

===!implversion===
The purpose of this meta-command is to query the name and version of the relay implementation.

* !implversion opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !implversion with its implementation version string... which can be any string.

It is recommended this string includes the following elements:
* the relay name/brand/identifier,
* the version number of that relay name/brand/identifier,
* at the beginning, the string prefix "ORG=0004/"
The latter is convenient for checking for ORG compatibility using a command even non-ORG relay should understand.

===!x-orgversions===

This meta-command purpose it two-fold. First it allows a controlling device to ask a relay for the list of ORG x-tensions it supports and, second, similarily to !version, !x-orgversions can be used to know what version of ORG the relay complies to.

'''Example:'''
C<->R
-> query,rUUID,!x-orgversions
<- query,cUUID,!x-orgversions,ORG=0004/who=002/email=006

'''Requirements:'''
* !x-orgversions should always be accepted with no Auth required, it does not open a session or Lock one.
* The acknowledgement value in a reply to !x-orgversions is a "/"-list of items of the form <package>=<version>. The first <package> is always "ORG" (representing the core specification package of ORG relays), its version string is the version of the specification (4 digits). The other packages are ORG x-tension names, whose version string is 3 digits.
* If several incompatible versions of a same x-tension are supported, they must be listed ordered by version number. Ex: ORG=0004/who=002/email=005/email=006. If versions are backward compatible, only the last version should be reported.

'''Remarks:'''
* In a controller, it is however recommended to use !x-orgversions as soon as possible in order to avoid sending unsupported and useless metacommands later on.
* In the acknowledgement message, x-tension names are listed, not meta-command names (as one x-tension can have several meta-commands). Thus listed names do not include the prefix "!x-".

LSL Protocol/Restrained Love Open Relay Group/ORG Requirements/0004 draft

2011-06-27T14:13:42Z

Satomi Ahn: /* On the relay side only */

{{ORG_Restrained_Life_Relay_Specs_TOC}}
STATUS: draft

VERSION: 0004

==Summary==

This page is a list of requirements for a relay or an in-world device to have the right to be called "ORG compliant". It is mostly about adding support for an ORG-centered informational metacommand and specifying Marine Kelley's RLVR protocol a bit more that it is now, while of course preserving full compatibility.

For a quick overview of the motivations and general working of this protocol and a few examples, we refer the reader to [[LSL_Protocol/Restrained_Love_Relay/Specification|the original specification page by Marine Kelley]].

If you are making furniture, traps, or other RLVR controllers and you are not interested in what [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] can offer, then you can stick with the original specification by Marine Kelley and still be compatible with [[LSL_Protocol/Restrained_Love_Relay/Comparison|ORG relays]]. However, to have the right to call your controller "ORG compatible", there are still a few light additional requirements such as:
* using only [[llRegionSayTo]] for communications with the relay,
* not spamming the RLVR channel with messages that do not belong to the protocol,
* and remain responsive to ping messages at every time if you want the session to remain locked.

If you are interested in [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|ORG x-tensions]], then you should also read the part about [[#!x-orgversions|!x-orgversions]].

If you are making a relay, sorry we are afraid you will have to read all this page.

==Definition of an ORG device==

A RLVR device is compliant with ORG specifications if it implements the consolidated RLVR protocol described below along with the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] it announces supporting.

Note in particular that
* the consolidated protocol is backward compatible with [[LSL_Protocol/Restrained_Love_Relay/Specification|Marine Kelley's RLVR protocol version 1.100]] but resolves most loose ends of that document;
* ORG relays handle controller messages whose second field is ffffffff-ffff-ffff-ffff-ffffffffffff exactly the same as if it was the key of the wearer (NULL_KEY is a wildcard);
* one-to-one chat messages (not using a wildcard) are sent by using [[llRegionSayTo]] LSL function;
* there is an additional meta-command, !x-orgversions for a relay to announce supported x-tensions;
* each supported x-tension can imply other supported metacommands, ORG x-tensions meta-command all having names starting with prefix "!x-";
* other proprietary metacommands with prefix "!_-" (replace "_" by any letter that is not "x") can be supported;

Supported x-tensions can constrain the core specification (this document) even more, but cannot alter it or make it less constraining unless as a result of the relay executing a meta-command of this x-tension sent by the controller. Thus, although the protocol is extensible, a controller can always rely on the fact an ORG relay abides by the requirements in this document until it asks the relay to do otherwise.

ORG devices may be advertised by the use of the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/ORG_Logo|ORG logo]] for advertising compliance with ORG requirements. ORG devices makers are encouraged to do so.

==Consolidated RLVR protocol==

=== Protocol Syntax ===

==== Definitions ====
* The '''Restrained Love Relay (RLVR) protocol''' implies two partners (SL objects): the '''relay''', attachment worn by the avatar commands are intended for, and a '''controller''', which sends commands to the relay.

* The goal of the protocol is to force the relay wearer to make perform actions and to toggle restrictions on their behavior. Both actions and restrictions can be enforced either through use of viewer hooks ([[LSL_Protocol/RestrainedLoveAPI|Restrained Love API]], or RLV) or through LSL scripting.

* Hence we distinguish between "'''RLV commands'''", starting with "@", which are commands following the syntax of the RLV API and which will ultimately be forwarded to the viewer, and "'''meta-commands'''", starting with "!", which are meant to be interpreted by LSL functions.

====Requirements====
RLVR protocol consists of messages exchanged between relay and controller
* on channel -1812221819 (called '''RLVR channel'''),
* using the LSL function [[llRegionSayTo]],
* all sent from the same prim of the controller or relay (within a [[#Protocol session|session]])
* and having the following syntax (non-terminal <c_msg> for controller messages/'''command messages''' and <r_msg> for relay messages/'''acknowledgement messages'''):

<c_msg> ::= IDENT "," KEY "," <commands>
<r_msg> ::= IDENT "," KEY "," <command> "," ACK
<commands> ::= <command> | <command> "|" <commands>
<command> ::= <rlvcommand> | <metacommand>
<rlvcommand> ::= "@" RLVCOMMAND
<metacommand> ::= "!" METACOMMANDNAME <metacommandarguments>
<metacommandarguments> ::= "" | "/" ARG <metacommandarguments>

where we explicit the different terminal tokens:
IDENT: any string without ","
KEY: any UUID
ACK: any string without ","
RLVCOMMAND: any string without ","
METACOMMANDNAME: any string without "/" and ","
ARG: any string without "/" and ","

* Relays can only send <r_msg>'s, and controllers <c_msg>'s. Nothing else is allowed on RLVR channel.
* In <c_msg>, KEY is always either the uuid of the relay wearer or ffffffff-ffff-ffff-ffff-ffffffffffff ('''wildcard''') if it is a message intended for all relays who can hear it.
* In <r_msg>, KEY is always the uuid of the controller.

====On the relay side only====
'''Further requirements:'''
*A relay MUST ignore any message on RLVR channel which is not a <c_msg> with KEY being either the key of the avatar wearing the relay or ffffffff-ffff-ffff-ffff-ffffffffffff.
Then, for every <command>:
* if <command> is neither a valid <rlvcommand> or <metacommand>, the relay must ignore it and process the next <command>'s;
* if <command> is a <rlvcommand> or a <metacommand>, the relay MUST send back to the controller a <r_msg> (see above) such that:
:*IDENT is the same as IDENT in the <c_msg> being processed,
:*<command> is the subcommand being processed
:*and ACK is a string called ''acknowledgement value''. By default the acknowledgement value is "ok" if the relay will execute the <command >, "ko" otherwise.

'''Remarks:'''
* Many meta-commands may have other acknowledgements than "ok" or "ko" (or none, for !pong). Their definitions supersede this specification.

===Protocol session===

====Definitions====
* During an execution of the RLVR protocol, a relay and a controller establish a '''session''' together. A relay may manage several sessions with several controllers. Likewise, a controller could establish sessions with several relays.
* Restrictions on a relay wearer are relative to a session. So are most other variables (authorization state, key of the controller, ... ).
* A session is '''Opened''' whenever the relay accepts a RLVR command from a controller.
* A session is '''Closed''' (or '''released''') as soon as the relay forgets every variables and releases all restrictions pertaining to that session.
* A session is '''Locked''' whenever it holds active restrictions.
* A session is '''Authed''' if the controller has been allowed to control the relay (not only store some variables with no consequence). Once authed, no interactive "ask" dialog should pop up anymore concerning this session. Most commands should now normally be accepted (and maybe a few automatically rejected).
* A controller is called '''reachable''' if it can receive messages from the relay and can prove it by answering ping requests from the relay. By "can", it is meant by the method of communication agreed upon by the relay and controller. By default the communication method is chat messages sent by llRegionSayTo. X-tensions such as email and delay can modify what is meant by reachable.

====Relay side requirements====
*Closing a session clears all RLV restrictions that belong only to that session, clears all session variables and disables all behaviors relative to that session.
*Sessions that are not locked MUST be released after a reasonable timeout.
*Relay implementations MAY require an authed session for all <rlvcommand>'s, except @xxx=<channel_number>, @clear[=xxx] and @xxx=y/rem commands, which MUST always be accepted.
*@xxx=n/add <rlvcommand>'s, after being accepted, add a restriction and therefore Lock the session.
*Some metacommands described in x-tensions can also add restrictions and therefore Lock the session.
*!release, !version, !implversion, !x-orgversions and !x-.../clear[/...] commands are always accepted.
*!pong reactivates an existing session but never requires further auth, provided it is sent by the device to which ping was sent. The relay MUST resend to the viewer all stored restrictions belonging to the controlling device if they are not already active.
*Unless specified otherwise (see !x-who), no command can trigger an interactive dialog unless
:* they require an Authed session
:* and no session is currently open or it is open but not Authed yet.
*When releasing a Locked session, a relay MUST release all restrictions belonging to the device controlling the session.
*On the following events, a relay MUST release a locked session:
:* when the relay notices the controller has become unreachable,
:* when the relay sends "release,<controller_key>,!release,ok" (due to acknowledging !release sent by the controller, or due to safewording triggered from the relay side).
*A relay MUST provide a mechanism for checking that every controlling device is reachable. It is not specified whether this checking process should be automatic or manually triggered.
*The absence of active restriction unlocks the session (and eventually releases it).
*A relay MUST remove restrictions from a session when (and only in these cases):
:* either the session controller specifically asks for the restriction to be released ("@restriction=y" "@restriction=rem", "@clear=restriction" for RLV restrictions, and "!x-restriction/clear/..." for LSL restrictions),
:* or the session closed (for instance !release coming from the device, or safeword).

===Commands===
====Relay side requirements====
* If a <rlvcommand> is acknowledged with value "ok", the relay ensures the viewer is affected the same way as if the LSL instruction llOwnerSay(<rlvcommand>) was executed by a script in a primitive that handles only one controller.
* When processing a <metacommand>, if the relay knows at least one definition of '!'+METACOMMANDNAME for which the received <metacommandarguments> provide enough parameters, then it will be handled according to the definition handling the most parameters among the latter. Extra parameters are ignored.
* A relays knows the following meta-command definitions:
:*[[#Core meta-commands and associated mechanisms|definitions listed in the core requirements]]
:*all definitions included in [[LSL_Protocol/Restrained_Love_Relay/Comparison|x-tensions]] announced by the relay.
* When acknowledging a <metacommand> by anything else than "ko", the relay commits itself to execute it.

'''Remarks:'''
* For first requirement, it must be understood that the reference behavior is that the relay would have if it had one controller per prim. However handling several controllers from one unique prim is possible but requires taking care that different controllers do not interfere with each other, releasing each other's restrictions, for instance.
* For the second requirement, the word "handled" means that if the meta-command with these parameters is known, then requirements in known definition cannot be ignored. Sometimes, this can imply that the meta-command cannot be refused, for instance.

==Core meta-commands and associated mechanisms==

An ORG device MUST at least support the meta-commands !release, !pong, !version, !implversion and !x-orgversions described below and implement their associated mechanisms.

Particular meta-commands definitions and mechanisms may override general requirements above.

===!release===
Sent by a controller, this command closes the session.

* !release obviously opens no session, requires no Auth and is not Locking.
* If there is an actual session to close !release MUST be accepted by the relay and acknowledeged by "ok".
* On accepting !release, the relay erases all data pertaining to the session and disables all restrictions of the session.
* When a relay decides to close a session on its own (user safeword, for instance) and it is not due to the controller being unreachable, the relay must send the following acknowledgement message:
release,<controller_key>,!release,ok

When receiving the latter message, the controller should act accordingly, for instance by resetting itself and making itself ready for the next session.

Note that !release is not the same as @clear. @clear is interpreted by the relay as a RLV command and, as such, can only clear RLV restrictions. If RLV restrictions were the only restrictions of the session, then the session will be closed, but some x-tensions also define pure LSL based restrictions.

===ping/!pong===

The ping/!pong mechanism exists so that relays can check presence and responsiveness of a controller. This was primarily meant to be used on relay wearer relog, in order to reactivate all restrictions so that sessions persist on relog if the controller still exists and is ready to continue the session.

''!pong'' cannot require auth and does not lock a session

We call ''ping message'' a message from the relay, having the following syntax:
ping,<controller_key>,ping,ping
We call ''!pong message'' a message from the controller, having the following syntax:
ping,<relay_key>,!pong

====Relay side====
*A relay SHOULD NOT send an acknowledgement in response to ''!pong''.
*A ping message can be sent any time by the relay to a known controller.
*On wearer relog, for each existing Locked session, the relay must send a ping message to the session controller.
*When a !pong message is received from a controller, if it was a reply to a previous ping message:
:#if the session RLV restrictions contain unsit and the avatar was sitting on some object when the restriction was applied, then the relay MUST force the avatar to sit back on the same object (if still existing);
:#the relay MUST make sure all restrictions belonging to the session are made active again.
*If a ping message is sent and is not answered by the controller, then the relay closes the session.

Note that the relay is responsible for storing restrictions and the key of the sit target across sessions, not the controller.

====Controller side====
*Unless it does not matter that the relay could close the session (or for another reason, the controller knows the relay will not close it), a controller SHOULD listen to ping messages and answer any ping message with a !pong message.
*A controller should ignore ping requests from relays it is not ready to handle.

Note controller don't have to poll for relay presence to resume a session but should just listen for ping messages instead. The relay should have stored all restrictions and handle sitting back to whatever furniture the relay wearer was tied up to.

Concerning the second bullet: for instance, if the controller is a furniture which is already in use by another relay wearer, it would be cause dysfunctions to let the pinging relay restore the restrictions without letting its wearer sit on the furniture. Or if the controller is not stateless and the state for the pinging relay has not been saved before, resuming the session from the initial state might be inconsistant.

===!version===
The purpose of this meta-command is to query the version of the RLVR protocol supported by a relay.

* !version opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !version with the version number of the RLVR protocol it supports ("1100" here, since ORG 0004 includes RLVR 1.100).

Note this is the most common command for a controller to scan for nearby relays, as non-ORG relays also accept this command and answer it the way described above.

===!implversion===
The purpose of this meta-command is to query the name and version of the relay implementation.

* !implversion opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !implversion with its implementation version string... which can be any string.

It is recommended this string includes the following elements:
* the relay name/brand/identifier,
* the version number of that relay name/brand/identifier,
* at the beginning, the string prefix "ORG=0004/"
The latter is convenient for checking for ORG compatibility using a command even non-ORG relay should understand.

===!x-orgversions===

This meta-command purpose it two-fold. First it allows a controlling device to ask a relay for the list of ORG x-tensions it supports and, second, similarily to !version, !x-orgversions can be used to know what version of ORG the relay complies to.

'''Example:'''
C<->R
-> query,rUUID,!x-orgversions
<- query,cUUID,!x-orgversions,ORG=0004/who=002/email=006

'''Requirements:'''
* !x-orgversions should always be accepted with no Auth required, it does not open a session or Lock one.
* The acknowledgement value in a reply to !x-orgversions is a "/"-list of items of the form <package>=<version>. The first <package> is always "ORG" (representing the core specification package of ORG relays), its version string is the version of the specification (4 digits). The other packages are ORG x-tension names, whose version string is 3 digits.
* If several incompatible versions of a same x-tension are supported, they must be listed ordered by version number. Ex: ORG=0004/who=002/email=005/email=006. If versions are backward compatible, only the last version should be reported.

'''Remarks:'''
* In a controller, it is however recommended to use !x-orgversions as soon as possible in order to avoid sending unsupported and useless metacommands later on.
* In the acknowledgement message, x-tension names are listed, not meta-command names (as one x-tension can have several meta-commands). Thus listed names do not include the prefix "!x-".

LSL Protocol/Restrained Love Open Relay Group/ORG Requirements/0004 draft

2011-06-27T14:09:36Z

Satomi Ahn: /* Definitions */

{{ORG_Restrained_Life_Relay_Specs_TOC}}
STATUS: draft

VERSION: 0004

==Summary==

This page is a list of requirements for a relay or an in-world device to have the right to be called "ORG compliant". It is mostly about adding support for an ORG-centered informational metacommand and specifying Marine Kelley's RLVR protocol a bit more that it is now, while of course preserving full compatibility.

For a quick overview of the motivations and general working of this protocol and a few examples, we refer the reader to [[LSL_Protocol/Restrained_Love_Relay/Specification|the original specification page by Marine Kelley]].

If you are making furniture, traps, or other RLVR controllers and you are not interested in what [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] can offer, then you can stick with the original specification by Marine Kelley and still be compatible with [[LSL_Protocol/Restrained_Love_Relay/Comparison|ORG relays]]. However, to have the right to call your controller "ORG compatible", there are still a few light additional requirements such as:
* using only [[llRegionSayTo]] for communications with the relay,
* not spamming the RLVR channel with messages that do not belong to the protocol,
* and remain responsive to ping messages at every time if you want the session to remain locked.

If you are interested in [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|ORG x-tensions]], then you should also read the part about [[#!x-orgversions|!x-orgversions]].

If you are making a relay, sorry we are afraid you will have to read all this page.

==Definition of an ORG device==

A RLVR device is compliant with ORG specifications if it implements the consolidated RLVR protocol described below along with the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] it announces supporting.

Note in particular that
* the consolidated protocol is backward compatible with [[LSL_Protocol/Restrained_Love_Relay/Specification|Marine Kelley's RLVR protocol version 1.100]] but resolves most loose ends of that document;
* ORG relays handle controller messages whose second field is ffffffff-ffff-ffff-ffff-ffffffffffff exactly the same as if it was the key of the wearer (NULL_KEY is a wildcard);
* one-to-one chat messages (not using a wildcard) are sent by using [[llRegionSayTo]] LSL function;
* there is an additional meta-command, !x-orgversions for a relay to announce supported x-tensions;
* each supported x-tension can imply other supported metacommands, ORG x-tensions meta-command all having names starting with prefix "!x-";
* other proprietary metacommands with prefix "!_-" (replace "_" by any letter that is not "x") can be supported;

Supported x-tensions can constrain the core specification (this document) even more, but cannot alter it or make it less constraining unless as a result of the relay executing a meta-command of this x-tension sent by the controller. Thus, although the protocol is extensible, a controller can always rely on the fact an ORG relay abides by the requirements in this document until it asks the relay to do otherwise.

ORG devices may be advertised by the use of the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/ORG_Logo|ORG logo]] for advertising compliance with ORG requirements. ORG devices makers are encouraged to do so.

==Consolidated RLVR protocol==

=== Protocol Syntax ===

==== Definitions ====
* The '''Restrained Love Relay (RLVR) protocol''' implies two partners (SL objects): the '''relay''', attachment worn by the avatar commands are intended for, and a '''controller''', which sends commands to the relay.

* The goal of the protocol is to force the relay wearer to make perform actions and to toggle restrictions on their behavior. Both actions and restrictions can be enforced either through use of viewer hooks ([[LSL_Protocol/RestrainedLoveAPI|Restrained Love API]], or RLV) or through LSL scripting.

* Hence we distinguish between "'''RLV commands'''", starting with "@", which are commands following the syntax of the RLV API and which will ultimately be forwarded to the viewer, and "'''meta-commands'''", starting with "!", which are meant to be interpreted by LSL functions.

====Requirements====
RLVR protocol consists of messages exchanged between relay and controller
* on channel -1812221819 (called '''RLVR channel'''),
* using the LSL function [[llRegionSayTo]],
* all sent from the same prim of the controller or relay (within a [[#Protocol session|session]])
* and having the following syntax (non-terminal <c_msg> for controller messages/'''command messages''' and <r_msg> for relay messages/'''acknowledgement messages'''):

<c_msg> ::= IDENT "," KEY "," <commands>
<r_msg> ::= IDENT "," KEY "," <command> "," ACK
<commands> ::= <command> | <command> "|" <commands>
<command> ::= <rlvcommand> | <metacommand>
<rlvcommand> ::= "@" RLVCOMMAND
<metacommand> ::= "!" METACOMMANDNAME <metacommandarguments>
<metacommandarguments> ::= "" | "/" ARG <metacommandarguments>

where we explicit the different terminal tokens:
IDENT: any string without ","
KEY: any UUID
ACK: any string without ","
RLVCOMMAND: any string without ","
METACOMMANDNAME: any string without "/" and ","
ARG: any string without "/" and ","

* Relays can only send <r_msg>'s, and controllers <c_msg>'s. Nothing else is allowed on RLVR channel.
* In <c_msg>, KEY is always either the uuid of the relay wearer or ffffffff-ffff-ffff-ffff-ffffffffffff ('''wildcard''') if it is a message intended for all relays who can hear it.
* In <r_msg>, KEY is always the uuid of the controller.

====On the relay side only====
'''Further requirements:'''
*A relay MUST ignore any message on RLVR channel which is not a <c_msg> with KEY being either the key of the avatar wearing the relay or ffffffff-ffff-ffff-ffff-ffffffffffff.
Then, for every <command>:
* if <command> is neither a valid <rlvcommand> or <metacommand>, the relay must ignore it and process the next <command>'s;
* if <command> is a <rlvcommand> or a <metacommand>, the relay MUST send an acknowledgement message back to the controller.
* an acknowledgement message is a <r_msg> (see above) such that
:*IDENT is the same as IDENT in the <c_msg> being processed
:*<command> is the subcommand being processed
:*ACK is a string called ''acknowledgement value''. By default the acknowledgement value is "ok" if the relay will execute the <command >, "ko" otherwise;

'''Remarks:'''
* Many meta-commands may have other acknowledgements than "ok" or "ko" (or none, for !pong). Their definitions supersede this specification.
* Note that unknown meta-commands cannot be executed and thus wil be acknowledged by "ko".
* Known meta-commands which are sent with not enough parameters or parameters with types incompatible with those in the definition known by the relay also cannot be executed and will also be acknowledged by "ko". (ex: the relay knows !x-who/key, but receives !x-who/integer/string).

===Protocol session===

====Definitions====
* During an execution of the RLVR protocol, a relay and a controller establish a '''session''' together. A relay may manage several sessions with several controllers. Likewise, a controller could establish sessions with several relays.
* Restrictions on a relay wearer are relative to a session. So are most other variables (authorization state, key of the controller, ... ).
* A session is '''Opened''' whenever the relay accepts a RLVR command from a controller.
* A session is '''Closed''' (or '''released''') as soon as the relay forgets every variables and releases all restrictions pertaining to that session.
* A session is '''Locked''' whenever it holds active restrictions.
* A session is '''Authed''' if the controller has been allowed to control the relay (not only store some variables with no consequence). Once authed, no interactive "ask" dialog should pop up anymore concerning this session. Most commands should now normally be accepted (and maybe a few automatically rejected).
* A controller is called '''reachable''' if it can receive messages from the relay and can prove it by answering ping requests from the relay. By "can", it is meant by the method of communication agreed upon by the relay and controller. By default the communication method is chat messages sent by llRegionSayTo. X-tensions such as email and delay can modify what is meant by reachable.

====Relay side requirements====
*Closing a session clears all RLV restrictions that belong only to that session, clears all session variables and disables all behaviors relative to that session.
*Sessions that are not locked MUST be released after a reasonable timeout.
*Relay implementations MAY require an authed session for all <rlvcommand>'s, except @xxx=<channel_number>, @clear[=xxx] and @xxx=y/rem commands, which MUST always be accepted.
*@xxx=n/add <rlvcommand>'s, after being accepted, add a restriction and therefore Lock the session.
*Some metacommands described in x-tensions can also add restrictions and therefore Lock the session.
*!release, !version, !implversion, !x-orgversions and !x-.../clear[/...] commands are always accepted.
*!pong reactivates an existing session but never requires further auth, provided it is sent by the device to which ping was sent. The relay MUST resend to the viewer all stored restrictions belonging to the controlling device if they are not already active.
*Unless specified otherwise (see !x-who), no command can trigger an interactive dialog unless
:* they require an Authed session
:* and no session is currently open or it is open but not Authed yet.
*When releasing a Locked session, a relay MUST release all restrictions belonging to the device controlling the session.
*On the following events, a relay MUST release a locked session:
:* when the relay notices the controller has become unreachable,
:* when the relay sends "release,<controller_key>,!release,ok" (due to acknowledging !release sent by the controller, or due to safewording triggered from the relay side).
*A relay MUST provide a mechanism for checking that every controlling device is reachable. It is not specified whether this checking process should be automatic or manually triggered.
*The absence of active restriction unlocks the session (and eventually releases it).
*A relay MUST remove restrictions from a session when (and only in these cases):
:* either the session controller specifically asks for the restriction to be released ("@restriction=y" "@restriction=rem", "@clear=restriction" for RLV restrictions, and "!x-restriction/clear/..." for LSL restrictions),
:* or the session closed (for instance !release coming from the device, or safeword).

===Commands===
====Relay side requirements====
* If a <rlvcommand> is acknowledged with value "ok", the relay ensures the viewer is affected the same way as if the LSL instruction llOwnerSay(<rlvcommand>) was executed by a script in a primitive that handles only one controller.
* When processing a <metacommand>, if the relay knows at least one definition of '!'+METACOMMANDNAME for which the received <metacommandarguments> provide enough parameters, then it will be handled according to the definition handling the most parameters among the latter. Extra parameters are ignored.
* A relays knows the following meta-command definitions:
:*[[#Core meta-commands and associated mechanisms|definitions listed in the core requirements]]
:*all definitions included in [[LSL_Protocol/Restrained_Love_Relay/Comparison|x-tensions]] announced by the relay.
* When acknowledging a <metacommand> by anything else than "ko", the relay commits itself to execute it.

'''Remarks:'''
* For first requirement, it must be understood that the reference behavior is that the relay would have if it had one controller per prim. However handling several controllers from one unique prim is possible but requires taking care that different controllers do not interfere with each other, releasing each other's restrictions, for instance.
* For the second requirement, the word "handled" means that if the meta-command with these parameters is known, then requirements in known definition cannot be ignored. Sometimes, this can imply that the meta-command cannot be refused, for instance.

==Core meta-commands and associated mechanisms==

An ORG device MUST at least support the meta-commands !release, !pong, !version, !implversion and !x-orgversions described below and implement their associated mechanisms.

Particular meta-commands definitions and mechanisms may override general requirements above.

===!release===
Sent by a controller, this command closes the session.

* !release obviously opens no session, requires no Auth and is not Locking.
* If there is an actual session to close !release MUST be accepted by the relay and acknowledeged by "ok".
* On accepting !release, the relay erases all data pertaining to the session and disables all restrictions of the session.
* When a relay decides to close a session on its own (user safeword, for instance) and it is not due to the controller being unreachable, the relay must send the following acknowledgement message:
release,<controller_key>,!release,ok

When receiving the latter message, the controller should act accordingly, for instance by resetting itself and making itself ready for the next session.

Note that !release is not the same as @clear. @clear is interpreted by the relay as a RLV command and, as such, can only clear RLV restrictions. If RLV restrictions were the only restrictions of the session, then the session will be closed, but some x-tensions also define pure LSL based restrictions.

===ping/!pong===

The ping/!pong mechanism exists so that relays can check presence and responsiveness of a controller. This was primarily meant to be used on relay wearer relog, in order to reactivate all restrictions so that sessions persist on relog if the controller still exists and is ready to continue the session.

''!pong'' cannot require auth and does not lock a session

We call ''ping message'' a message from the relay, having the following syntax:
ping,<controller_key>,ping,ping
We call ''!pong message'' a message from the controller, having the following syntax:
ping,<relay_key>,!pong

====Relay side====
*A relay SHOULD NOT send an acknowledgement in response to ''!pong''.
*A ping message can be sent any time by the relay to a known controller.
*On wearer relog, for each existing Locked session, the relay must send a ping message to the session controller.
*When a !pong message is received from a controller, if it was a reply to a previous ping message:
:#if the session RLV restrictions contain unsit and the avatar was sitting on some object when the restriction was applied, then the relay MUST force the avatar to sit back on the same object (if still existing);
:#the relay MUST make sure all restrictions belonging to the session are made active again.
*If a ping message is sent and is not answered by the controller, then the relay closes the session.

Note that the relay is responsible for storing restrictions and the key of the sit target across sessions, not the controller.

====Controller side====
*Unless it does not matter that the relay could close the session (or for another reason, the controller knows the relay will not close it), a controller SHOULD listen to ping messages and answer any ping message with a !pong message.
*A controller should ignore ping requests from relays it is not ready to handle.

Note controller don't have to poll for relay presence to resume a session but should just listen for ping messages instead. The relay should have stored all restrictions and handle sitting back to whatever furniture the relay wearer was tied up to.

Concerning the second bullet: for instance, if the controller is a furniture which is already in use by another relay wearer, it would be cause dysfunctions to let the pinging relay restore the restrictions without letting its wearer sit on the furniture. Or if the controller is not stateless and the state for the pinging relay has not been saved before, resuming the session from the initial state might be inconsistant.

===!version===
The purpose of this meta-command is to query the version of the RLVR protocol supported by a relay.

* !version opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !version with the version number of the RLVR protocol it supports ("1100" here, since ORG 0004 includes RLVR 1.100).

Note this is the most common command for a controller to scan for nearby relays, as non-ORG relays also accept this command and answer it the way described above.

===!implversion===
The purpose of this meta-command is to query the name and version of the relay implementation.

* !implversion opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !implversion with its implementation version string... which can be any string.

It is recommended this string includes the following elements:
* the relay name/brand/identifier,
* the version number of that relay name/brand/identifier,
* at the beginning, the string prefix "ORG=0004/"
The latter is convenient for checking for ORG compatibility using a command even non-ORG relay should understand.

===!x-orgversions===

This meta-command purpose it two-fold. First it allows a controlling device to ask a relay for the list of ORG x-tensions it supports and, second, similarily to !version, !x-orgversions can be used to know what version of ORG the relay complies to.

'''Example:'''
C<->R
-> query,rUUID,!x-orgversions
<- query,cUUID,!x-orgversions,ORG=0004/who=002/email=006

'''Requirements:'''
* !x-orgversions should always be accepted with no Auth required, it does not open a session or Lock one.
* The acknowledgement value in a reply to !x-orgversions is a "/"-list of items of the form <package>=<version>. The first <package> is always "ORG" (representing the core specification package of ORG relays), its version string is the version of the specification (4 digits). The other packages are ORG x-tension names, whose version string is 3 digits.
* If several incompatible versions of a same x-tension are supported, they must be listed ordered by version number. Ex: ORG=0004/who=002/email=005/email=006. If versions are backward compatible, only the last version should be reported.

'''Remarks:'''
* In a controller, it is however recommended to use !x-orgversions as soon as possible in order to avoid sending unsupported and useless metacommands later on.
* In the acknowledgement message, x-tension names are listed, not meta-command names (as one x-tension can have several meta-commands). Thus listed names do not include the prefix "!x-".

LSL Protocol/Restrained Love Open Relay Group/ORG Requirements/0004 draft

2011-06-27T14:08:49Z

Satomi Ahn: /* Consolidated RLVR protocol */

{{ORG_Restrained_Life_Relay_Specs_TOC}}
STATUS: draft

VERSION: 0004

==Summary==

This page is a list of requirements for a relay or an in-world device to have the right to be called "ORG compliant". It is mostly about adding support for an ORG-centered informational metacommand and specifying Marine Kelley's RLVR protocol a bit more that it is now, while of course preserving full compatibility.

For a quick overview of the motivations and general working of this protocol and a few examples, we refer the reader to [[LSL_Protocol/Restrained_Love_Relay/Specification|the original specification page by Marine Kelley]].

If you are making furniture, traps, or other RLVR controllers and you are not interested in what [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] can offer, then you can stick with the original specification by Marine Kelley and still be compatible with [[LSL_Protocol/Restrained_Love_Relay/Comparison|ORG relays]]. However, to have the right to call your controller "ORG compatible", there are still a few light additional requirements such as:
* using only [[llRegionSayTo]] for communications with the relay,
* not spamming the RLVR channel with messages that do not belong to the protocol,
* and remain responsive to ping messages at every time if you want the session to remain locked.

If you are interested in [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|ORG x-tensions]], then you should also read the part about [[#!x-orgversions|!x-orgversions]].

If you are making a relay, sorry we are afraid you will have to read all this page.

==Definition of an ORG device==

A RLVR device is compliant with ORG specifications if it implements the consolidated RLVR protocol described below along with the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] it announces supporting.

Note in particular that
* the consolidated protocol is backward compatible with [[LSL_Protocol/Restrained_Love_Relay/Specification|Marine Kelley's RLVR protocol version 1.100]] but resolves most loose ends of that document;
* ORG relays handle controller messages whose second field is ffffffff-ffff-ffff-ffff-ffffffffffff exactly the same as if it was the key of the wearer (NULL_KEY is a wildcard);
* one-to-one chat messages (not using a wildcard) are sent by using [[llRegionSayTo]] LSL function;
* there is an additional meta-command, !x-orgversions for a relay to announce supported x-tensions;
* each supported x-tension can imply other supported metacommands, ORG x-tensions meta-command all having names starting with prefix "!x-";
* other proprietary metacommands with prefix "!_-" (replace "_" by any letter that is not "x") can be supported;

Supported x-tensions can constrain the core specification (this document) even more, but cannot alter it or make it less constraining unless as a result of the relay executing a meta-command of this x-tension sent by the controller. Thus, although the protocol is extensible, a controller can always rely on the fact an ORG relay abides by the requirements in this document until it asks the relay to do otherwise.

ORG devices may be advertised by the use of the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/ORG_Logo|ORG logo]] for advertising compliance with ORG requirements. ORG devices makers are encouraged to do so.

==Consolidated RLVR protocol==

=== Protocol Syntax ===

==== Definitions ====
* The '''Restrained Love Relay (RLVR) protocol''' implies two partners (SL objects): the '''relay''' worn by the avatar commands are intended for, and a '''controller''', which sends commands to the relay.

* The goal of the protocol is to force the relay wearer to make perform actions and to toggle restrictions on their behavior. Both actions and restrictions can be enforced either through use of viewer hooks ([[LSL_Protocol/RestrainedLoveAPI|Restrained Love API]], or RLV) or through LSL scripting.

* Hence we distinguish between "'''RLV commands'''", starting with "@", which are commands following the syntax of the RLV API and which will ultimately be forwarded to the viewer, and "'''meta-commands'''", starting with "!", which are meant to be interpreted by LSL functions.

====Requirements====
RLVR protocol consists of messages exchanged between relay and controller
* on channel -1812221819 (called '''RLVR channel'''),
* using the LSL function [[llRegionSayTo]],
* all sent from the same prim of the controller or relay (within a [[#Protocol session|session]])
* and having the following syntax (non-terminal <c_msg> for controller messages/'''command messages''' and <r_msg> for relay messages/'''acknowledgement messages'''):

<c_msg> ::= IDENT "," KEY "," <commands>
<r_msg> ::= IDENT "," KEY "," <command> "," ACK
<commands> ::= <command> | <command> "|" <commands>
<command> ::= <rlvcommand> | <metacommand>
<rlvcommand> ::= "@" RLVCOMMAND
<metacommand> ::= "!" METACOMMANDNAME <metacommandarguments>
<metacommandarguments> ::= "" | "/" ARG <metacommandarguments>

where we explicit the different terminal tokens:
IDENT: any string without ","
KEY: any UUID
ACK: any string without ","
RLVCOMMAND: any string without ","
METACOMMANDNAME: any string without "/" and ","
ARG: any string without "/" and ","

* Relays can only send <r_msg>'s, and controllers <c_msg>'s. Nothing else is allowed on RLVR channel.
* In <c_msg>, KEY is always either the uuid of the relay wearer or ffffffff-ffff-ffff-ffff-ffffffffffff ('''wildcard''') if it is a message intended for all relays who can hear it.
* In <r_msg>, KEY is always the uuid of the controller.

====On the relay side only====
'''Further requirements:'''
*A relay MUST ignore any message on RLVR channel which is not a <c_msg> with KEY being either the key of the avatar wearing the relay or ffffffff-ffff-ffff-ffff-ffffffffffff.
Then, for every <command>:
* if <command> is neither a valid <rlvcommand> or <metacommand>, the relay must ignore it and process the next <command>'s;
* if <command> is a <rlvcommand> or a <metacommand>, the relay MUST send an acknowledgement message back to the controller.
* an acknowledgement message is a <r_msg> (see above) such that
:*IDENT is the same as IDENT in the <c_msg> being processed
:*<command> is the subcommand being processed
:*ACK is a string called ''acknowledgement value''. By default the acknowledgement value is "ok" if the relay will execute the <command >, "ko" otherwise;

'''Remarks:'''
* Many meta-commands may have other acknowledgements than "ok" or "ko" (or none, for !pong). Their definitions supersede this specification.
* Note that unknown meta-commands cannot be executed and thus wil be acknowledged by "ko".
* Known meta-commands which are sent with not enough parameters or parameters with types incompatible with those in the definition known by the relay also cannot be executed and will also be acknowledged by "ko". (ex: the relay knows !x-who/key, but receives !x-who/integer/string).

===Protocol session===

====Definitions====
* During an execution of the RLVR protocol, a relay and a controller establish a '''session''' together. A relay may manage several sessions with several controllers. Likewise, a controller could establish sessions with several relays.
* Restrictions on a relay wearer are relative to a session. So are most other variables (authorization state, key of the controller, ... ).
* A session is '''Opened''' whenever the relay accepts a RLVR command from a controller.
* A session is '''Closed''' (or '''released''') as soon as the relay forgets every variables and releases all restrictions pertaining to that session.
* A session is '''Locked''' whenever it holds active restrictions.
* A session is '''Authed''' if the controller has been allowed to control the relay (not only store some variables with no consequence). Once authed, no interactive "ask" dialog should pop up anymore concerning this session. Most commands should now normally be accepted (and maybe a few automatically rejected).
* A controller is called '''reachable''' if it can receive messages from the relay and can prove it by answering ping requests from the relay. By "can", it is meant by the method of communication agreed upon by the relay and controller. By default the communication method is chat messages sent by llRegionSayTo. X-tensions such as email and delay can modify what is meant by reachable.

====Relay side requirements====
*Closing a session clears all RLV restrictions that belong only to that session, clears all session variables and disables all behaviors relative to that session.
*Sessions that are not locked MUST be released after a reasonable timeout.
*Relay implementations MAY require an authed session for all <rlvcommand>'s, except @xxx=<channel_number>, @clear[=xxx] and @xxx=y/rem commands, which MUST always be accepted.
*@xxx=n/add <rlvcommand>'s, after being accepted, add a restriction and therefore Lock the session.
*Some metacommands described in x-tensions can also add restrictions and therefore Lock the session.
*!release, !version, !implversion, !x-orgversions and !x-.../clear[/...] commands are always accepted.
*!pong reactivates an existing session but never requires further auth, provided it is sent by the device to which ping was sent. The relay MUST resend to the viewer all stored restrictions belonging to the controlling device if they are not already active.
*Unless specified otherwise (see !x-who), no command can trigger an interactive dialog unless
:* they require an Authed session
:* and no session is currently open or it is open but not Authed yet.
*When releasing a Locked session, a relay MUST release all restrictions belonging to the device controlling the session.
*On the following events, a relay MUST release a locked session:
:* when the relay notices the controller has become unreachable,
:* when the relay sends "release,<controller_key>,!release,ok" (due to acknowledging !release sent by the controller, or due to safewording triggered from the relay side).
*A relay MUST provide a mechanism for checking that every controlling device is reachable. It is not specified whether this checking process should be automatic or manually triggered.
*The absence of active restriction unlocks the session (and eventually releases it).
*A relay MUST remove restrictions from a session when (and only in these cases):
:* either the session controller specifically asks for the restriction to be released ("@restriction=y" "@restriction=rem", "@clear=restriction" for RLV restrictions, and "!x-restriction/clear/..." for LSL restrictions),
:* or the session closed (for instance !release coming from the device, or safeword).

===Commands===
====Relay side requirements====
* If a <rlvcommand> is acknowledged with value "ok", the relay ensures the viewer is affected the same way as if the LSL instruction llOwnerSay(<rlvcommand>) was executed by a script in a primitive that handles only one controller.
* When processing a <metacommand>, if the relay knows at least one definition of '!'+METACOMMANDNAME for which the received <metacommandarguments> provide enough parameters, then it will be handled according to the definition handling the most parameters among the latter. Extra parameters are ignored.
* A relays knows the following meta-command definitions:
:*[[#Core meta-commands and associated mechanisms|definitions listed in the core requirements]]
:*all definitions included in [[LSL_Protocol/Restrained_Love_Relay/Comparison|x-tensions]] announced by the relay.
* When acknowledging a <metacommand> by anything else than "ko", the relay commits itself to execute it.

'''Remarks:'''
* For first requirement, it must be understood that the reference behavior is that the relay would have if it had one controller per prim. However handling several controllers from one unique prim is possible but requires taking care that different controllers do not interfere with each other, releasing each other's restrictions, for instance.
* For the second requirement, the word "handled" means that if the meta-command with these parameters is known, then requirements in known definition cannot be ignored. Sometimes, this can imply that the meta-command cannot be refused, for instance.

==Core meta-commands and associated mechanisms==

An ORG device MUST at least support the meta-commands !release, !pong, !version, !implversion and !x-orgversions described below and implement their associated mechanisms.

Particular meta-commands definitions and mechanisms may override general requirements above.

===!release===
Sent by a controller, this command closes the session.

* !release obviously opens no session, requires no Auth and is not Locking.
* If there is an actual session to close !release MUST be accepted by the relay and acknowledeged by "ok".
* On accepting !release, the relay erases all data pertaining to the session and disables all restrictions of the session.
* When a relay decides to close a session on its own (user safeword, for instance) and it is not due to the controller being unreachable, the relay must send the following acknowledgement message:
release,<controller_key>,!release,ok

When receiving the latter message, the controller should act accordingly, for instance by resetting itself and making itself ready for the next session.

Note that !release is not the same as @clear. @clear is interpreted by the relay as a RLV command and, as such, can only clear RLV restrictions. If RLV restrictions were the only restrictions of the session, then the session will be closed, but some x-tensions also define pure LSL based restrictions.

===ping/!pong===

The ping/!pong mechanism exists so that relays can check presence and responsiveness of a controller. This was primarily meant to be used on relay wearer relog, in order to reactivate all restrictions so that sessions persist on relog if the controller still exists and is ready to continue the session.

''!pong'' cannot require auth and does not lock a session

We call ''ping message'' a message from the relay, having the following syntax:
ping,<controller_key>,ping,ping
We call ''!pong message'' a message from the controller, having the following syntax:
ping,<relay_key>,!pong

====Relay side====
*A relay SHOULD NOT send an acknowledgement in response to ''!pong''.
*A ping message can be sent any time by the relay to a known controller.
*On wearer relog, for each existing Locked session, the relay must send a ping message to the session controller.
*When a !pong message is received from a controller, if it was a reply to a previous ping message:
:#if the session RLV restrictions contain unsit and the avatar was sitting on some object when the restriction was applied, then the relay MUST force the avatar to sit back on the same object (if still existing);
:#the relay MUST make sure all restrictions belonging to the session are made active again.
*If a ping message is sent and is not answered by the controller, then the relay closes the session.

Note that the relay is responsible for storing restrictions and the key of the sit target across sessions, not the controller.

====Controller side====
*Unless it does not matter that the relay could close the session (or for another reason, the controller knows the relay will not close it), a controller SHOULD listen to ping messages and answer any ping message with a !pong message.
*A controller should ignore ping requests from relays it is not ready to handle.

Note controller don't have to poll for relay presence to resume a session but should just listen for ping messages instead. The relay should have stored all restrictions and handle sitting back to whatever furniture the relay wearer was tied up to.

Concerning the second bullet: for instance, if the controller is a furniture which is already in use by another relay wearer, it would be cause dysfunctions to let the pinging relay restore the restrictions without letting its wearer sit on the furniture. Or if the controller is not stateless and the state for the pinging relay has not been saved before, resuming the session from the initial state might be inconsistant.

===!version===
The purpose of this meta-command is to query the version of the RLVR protocol supported by a relay.

* !version opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !version with the version number of the RLVR protocol it supports ("1100" here, since ORG 0004 includes RLVR 1.100).

Note this is the most common command for a controller to scan for nearby relays, as non-ORG relays also accept this command and answer it the way described above.

===!implversion===
The purpose of this meta-command is to query the name and version of the relay implementation.

* !implversion opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !implversion with its implementation version string... which can be any string.

It is recommended this string includes the following elements:
* the relay name/brand/identifier,
* the version number of that relay name/brand/identifier,
* at the beginning, the string prefix "ORG=0004/"
The latter is convenient for checking for ORG compatibility using a command even non-ORG relay should understand.

===!x-orgversions===

This meta-command purpose it two-fold. First it allows a controlling device to ask a relay for the list of ORG x-tensions it supports and, second, similarily to !version, !x-orgversions can be used to know what version of ORG the relay complies to.

'''Example:'''
C<->R
-> query,rUUID,!x-orgversions
<- query,cUUID,!x-orgversions,ORG=0004/who=002/email=006

'''Requirements:'''
* !x-orgversions should always be accepted with no Auth required, it does not open a session or Lock one.
* The acknowledgement value in a reply to !x-orgversions is a "/"-list of items of the form <package>=<version>. The first <package> is always "ORG" (representing the core specification package of ORG relays), its version string is the version of the specification (4 digits). The other packages are ORG x-tension names, whose version string is 3 digits.
* If several incompatible versions of a same x-tension are supported, they must be listed ordered by version number. Ex: ORG=0004/who=002/email=005/email=006. If versions are backward compatible, only the last version should be reported.

'''Remarks:'''
* In a controller, it is however recommended to use !x-orgversions as soon as possible in order to avoid sending unsupported and useless metacommands later on.
* In the acknowledgement message, x-tension names are listed, not meta-command names (as one x-tension can have several meta-commands). Thus listed names do not include the prefix "!x-".

LSL Protocol/Restrained Love Open Relay Group/ORG Requirements/0004 draft

2011-06-27T14:06:41Z

Satomi Ahn: /* Protocol Syntax */

{{ORG_Restrained_Life_Relay_Specs_TOC}}
STATUS: draft

VERSION: 0004

==Summary==

This page is a list of requirements for a relay or an in-world device to have the right to be called "ORG compliant". It is mostly about adding support for an ORG-centered informational metacommand and specifying Marine Kelley's RLVR protocol a bit more that it is now, while of course preserving full compatibility.

For a quick overview of the motivations and general working of this protocol and a few examples, we refer the reader to [[LSL_Protocol/Restrained_Love_Relay/Specification|the original specification page by Marine Kelley]].

If you are making furniture, traps, or other RLVR controllers and you are not interested in what [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] can offer, then you can stick with the original specification by Marine Kelley and still be compatible with [[LSL_Protocol/Restrained_Love_Relay/Comparison|ORG relays]]. However, to have the right to call your controller "ORG compatible", there are still a few light additional requirements such as:
* using only [[llRegionSayTo]] for communications with the relay,
* not spamming the RLVR channel with messages that do not belong to the protocol,
* and remain responsive to ping messages at every time if you want the session to remain locked.

If you are interested in [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|ORG x-tensions]], then you should also read the part about [[#!x-orgversions|!x-orgversions]].

If you are making a relay, sorry we are afraid you will have to read all this page.

==Definition of an ORG device==

A RLVR device is compliant with ORG specifications if it implements the consolidated RLVR protocol described below along with the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] it announces supporting.

Note in particular that
* the consolidated protocol is backward compatible with [[LSL_Protocol/Restrained_Love_Relay/Specification|Marine Kelley's RLVR protocol version 1.100]] but resolves most loose ends of that document;
* ORG relays handle controller messages whose second field is ffffffff-ffff-ffff-ffff-ffffffffffff exactly the same as if it was the key of the wearer (NULL_KEY is a wildcard);
* one-to-one chat messages (not using a wildcard) are sent by using [[llRegionSayTo]] LSL function;
* there is an additional meta-command, !x-orgversions for a relay to announce supported x-tensions;
* each supported x-tension can imply other supported metacommands, ORG x-tensions meta-command all having names starting with prefix "!x-";
* other proprietary metacommands with prefix "!_-" (replace "_" by any letter that is not "x") can be supported;

Supported x-tensions can constrain the core specification (this document) even more, but cannot alter it or make it less constraining unless as a result of the relay executing a meta-command of this x-tension sent by the controller. Thus, although the protocol is extensible, a controller can always rely on the fact an ORG relay abides by the requirements in this document until it asks the relay to do otherwise.

ORG devices may be advertised by the use of the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/ORG_Logo|ORG logo]] for advertising compliance with ORG requirements. ORG devices makers are encouraged to do so.

==Consolidated RLVR protocol==

=== Protocol Syntax ===

==== Definitions ====
* The '''Restrained Love Relay (RLVR) protocol''' implies two partners (SL objects): the '''relay''' worn by the avatar commands are intended for, and a '''controller''', which sends commands to the relay.

* The goal of the protocol is to force the relay wearer to make perform actions and to toggle restrictions on their behavior. Both actions and restrictions can be enforced either through use of viewer hooks ([[LSL_Protocol/RestrainedLoveAPI|Restrained Love API]], or RLV) or through LSL scripting.

* Hence we distinguish between "'''RLV commands'''", starting with "@", which are commands following the syntax of the RLV API and which will ultimately be forwarded to the viewer, and "'''meta-commands'''", starting with "!", which are meant to be interpreted by LSL functions.

====Requirements====
RLVR protocol consists of messages exchanged between relay and controller
* on channel -1812221819 (called '''RLVR channel'''),
* using the LSL function [[llRegionSayTo]],
* all sent from the same prim of the controller or relay (within a session)
* and having the following syntax (non-terminal <c_msg> for controller messages/'''command messages''' and <r_msg> for relay messages/'''acknowledgement messages'''):

<c_msg> ::= IDENT "," KEY "," <commands>
<r_msg> ::= IDENT "," KEY "," <command> "," ACK
<commands> ::= <command> | <command> "|" <commands>
<command> ::= <rlvcommand> | <metacommand>
<rlvcommand> ::= "@" RLVCOMMAND
<metacommand> ::= "!" METACOMMANDNAME <metacommandarguments>
<metacommandarguments> ::= "" | "/" ARG <metacommandarguments>

where we explicit the different terminal tokens:
IDENT: any string without ","
KEY: any UUID
ACK: any string without ","
RLVCOMMAND: any string without ","
METACOMMANDNAME: any string without "/" and ","
ARG: any string without "/" and ","

* Relays can only send <r_msg>'s, and controllers <c_msg>'s. Nothing else is allowed on RLVR channel.
* In <c_msg>, KEY is always either the uuid of the relay wearer or ffffffff-ffff-ffff-ffff-ffffffffffff ('''wildcard''') if it is a message intended for all relays who can hear it.
* In <r_msg>, KEY is always the uuid of the controller.

====On the relay side only====
'''Further requirements:'''
*A relay MUST ignore any message on RLVR channel which is not a <c_msg> with KEY being either the key of the avatar wearing the relay or ffffffff-ffff-ffff-ffff-ffffffffffff.
Then, for every <command>:
* if <command> is neither a valid <rlvcommand> or <metacommand>, the relay must ignore it and process the next <command>'s;
* if <command> is a <rlvcommand> or a <metacommand>, the relay MUST send an acknowledgement message back to the controller.
* an acknowledgement message is a <r_msg> (see above) such that
:*IDENT is the same as IDENT in the <c_msg> being processed
:*<command> is the subcommand being processed
:*ACK is a string called ''acknowledgement value''. By default the acknowledgement value is "ok" if the relay will execute the <command >, "ko" otherwise;

'''Remarks:'''
* Many meta-commands may have other acknowledgements than "ok" or "ko" (or none, for !pong). Their definitions supersede this specification.
* Note that unknown meta-commands cannot be executed and thus wil be acknowledged by "ko".
* Known meta-commands which are sent with not enough parameters or parameters with types incompatible with those in the definition known by the relay also cannot be executed and will also be acknowledged by "ko". (ex: the relay knows !x-who/key, but receives !x-who/integer/string).

===The RLVR protocol session===

====Definitions====
* During an execution of the RLVR protocol, a relay and a controller establish a '''session''' together. A relay may manage several sessions with several controllers. Likewise, a controller could establish sessions with several relays.
* Restrictions on a relay wearer are relative to a session. So are most other variables (authorization state, key of the controller, ... ).
* A session is '''Opened''' whenever the relay accepts a RLVR command from a controller.
* A session is '''Closed''' (or '''released''') as soon as the relay forgets every variables and releases all restrictions pertaining to that session.
* A session is '''Locked''' whenever it holds active restrictions.
* A session is '''Authed''' if the controller has been allowed to control the relay (not only store some variables with no consequence). Once authed, no interactive "ask" dialog should pop up anymore concerning this session. Most commands should now normally be accepted (and maybe a few automatically rejected).
* A controller is called '''reachable''' if it can receive messages from the relay and can prove it by answering ping requests from the relay. By "can", it is meant by the method of communication agreed upon by the relay and controller. By default the communication method is chat messages sent by llRegionSayTo. X-tensions such as email and delay can modify what is meant by reachable.

====Relay side requirements====
*Closing a session clears all RLV restrictions that belong only to that session, clears all session variables and disables all behaviors relative to that session.
*Sessions that are not locked MUST be released after a reasonable timeout.
*Relay implementations MAY require an authed session for all <rlvcommand>'s, except @xxx=<channel_number>, @clear[=xxx] and @xxx=y/rem commands, which MUST always be accepted.
*@xxx=n/add <rlvcommand>'s, after being accepted, add a restriction and therefore Lock the session.
*Some metacommands described in x-tensions can also add restrictions and therefore Lock the session.
*!release, !version, !implversion, !x-orgversions and !x-.../clear[/...] commands are always accepted.
*!pong reactivates an existing session but never requires further auth, provided it is sent by the device to which ping was sent. The relay MUST resend to the viewer all stored restrictions belonging to the controlling device if they are not already active.
*Unless specified otherwise (see !x-who), no command can trigger an interactive dialog unless
:* they require an Authed session
:* and no session is currently open or it is open but not Authed yet.
*When releasing a Locked session, a relay MUST release all restrictions belonging to the device controlling the session.
*On the following events, a relay MUST release a locked session:
:* when the relay notices the controller has become unreachable,
:* when the relay sends "release,<controller_key>,!release,ok" (due to acknowledging !release sent by the controller, or due to safewording triggered from the relay side).
*A relay MUST provide a mechanism for checking that every controlling device is reachable. It is not specified whether this checking process should be automatic or manually triggered.
*The absence of active restriction unlocks the session (and eventually releases it).
*A relay MUST remove restrictions from a session when (and only in these cases):
:* either the session controller specifically asks for the restriction to be released ("@restriction=y" "@restriction=rem", "@clear=restriction" for RLV restrictions, and "!x-restriction/clear/..." for LSL restrictions),
:* or the session closed (for instance !release coming from the device, or safeword).

===Commands===
====Relay side requirements====
* If a <rlvcommand> is acknowledged with value "ok", the relay ensures the viewer is affected the same way as if the LSL instruction llOwnerSay(<rlvcommand>) was executed by a script in a primitive that handles only one controller.
* When processing a <metacommand>, if the relay knows at least one definition of '!'+METACOMMANDNAME for which the received <metacommandarguments> provide enough parameters, then it will be handled according to the definition handling the most parameters among the latter. Extra parameters are ignored.
* A relays knows the following meta-command definitions:
:*[[#Core meta-commands and associated mechanisms|definitions listed in the core requirements]]
:*all definitions included in [[LSL_Protocol/Restrained_Love_Relay/Comparison|x-tensions]] announced by the relay.
* When acknowledging a <metacommand> by anything else than "ko", the relay commits itself to execute it.

'''Remarks:'''
* For first requirement, it must be understood that the reference behavior is that the relay would have if it had one controller per prim. However handling several controllers from one unique prim is possible but requires taking care that different controllers do not interfere with each other, releasing each other's restrictions, for instance.
* For the second requirement, the word "handled" means that if the meta-command with these parameters is known, then requirements in known definition cannot be ignored. Sometimes, this can imply that the meta-command cannot be refused, for instance.

==Core meta-commands and associated mechanisms==

An ORG device MUST at least support the meta-commands !release, !pong, !version, !implversion and !x-orgversions described below and implement their associated mechanisms.

Particular meta-commands definitions and mechanisms may override general requirements above.

===!release===
Sent by a controller, this command closes the session.

* !release obviously opens no session, requires no Auth and is not Locking.
* If there is an actual session to close !release MUST be accepted by the relay and acknowledeged by "ok".
* On accepting !release, the relay erases all data pertaining to the session and disables all restrictions of the session.
* When a relay decides to close a session on its own (user safeword, for instance) and it is not due to the controller being unreachable, the relay must send the following acknowledgement message:
release,<controller_key>,!release,ok

When receiving the latter message, the controller should act accordingly, for instance by resetting itself and making itself ready for the next session.

Note that !release is not the same as @clear. @clear is interpreted by the relay as a RLV command and, as such, can only clear RLV restrictions. If RLV restrictions were the only restrictions of the session, then the session will be closed, but some x-tensions also define pure LSL based restrictions.

===ping/!pong===

The ping/!pong mechanism exists so that relays can check presence and responsiveness of a controller. This was primarily meant to be used on relay wearer relog, in order to reactivate all restrictions so that sessions persist on relog if the controller still exists and is ready to continue the session.

''!pong'' cannot require auth and does not lock a session

We call ''ping message'' a message from the relay, having the following syntax:
ping,<controller_key>,ping,ping
We call ''!pong message'' a message from the controller, having the following syntax:
ping,<relay_key>,!pong

====Relay side====
*A relay SHOULD NOT send an acknowledgement in response to ''!pong''.
*A ping message can be sent any time by the relay to a known controller.
*On wearer relog, for each existing Locked session, the relay must send a ping message to the session controller.
*When a !pong message is received from a controller, if it was a reply to a previous ping message:
:#if the session RLV restrictions contain unsit and the avatar was sitting on some object when the restriction was applied, then the relay MUST force the avatar to sit back on the same object (if still existing);
:#the relay MUST make sure all restrictions belonging to the session are made active again.
*If a ping message is sent and is not answered by the controller, then the relay closes the session.

Note that the relay is responsible for storing restrictions and the key of the sit target across sessions, not the controller.

====Controller side====
*Unless it does not matter that the relay could close the session (or for another reason, the controller knows the relay will not close it), a controller SHOULD listen to ping messages and answer any ping message with a !pong message.
*A controller should ignore ping requests from relays it is not ready to handle.

Note controller don't have to poll for relay presence to resume a session but should just listen for ping messages instead. The relay should have stored all restrictions and handle sitting back to whatever furniture the relay wearer was tied up to.

Concerning the second bullet: for instance, if the controller is a furniture which is already in use by another relay wearer, it would be cause dysfunctions to let the pinging relay restore the restrictions without letting its wearer sit on the furniture. Or if the controller is not stateless and the state for the pinging relay has not been saved before, resuming the session from the initial state might be inconsistant.

===!version===
The purpose of this meta-command is to query the version of the RLVR protocol supported by a relay.

* !version opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !version with the version number of the RLVR protocol it supports ("1100" here, since ORG 0004 includes RLVR 1.100).

Note this is the most common command for a controller to scan for nearby relays, as non-ORG relays also accept this command and answer it the way described above.

===!implversion===
The purpose of this meta-command is to query the name and version of the relay implementation.

* !implversion opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !implversion with its implementation version string... which can be any string.

It is recommended this string includes the following elements:
* the relay name/brand/identifier,
* the version number of that relay name/brand/identifier,
* at the beginning, the string prefix "ORG=0004/"
The latter is convenient for checking for ORG compatibility using a command even non-ORG relay should understand.

===!x-orgversions===

This meta-command purpose it two-fold. First it allows a controlling device to ask a relay for the list of ORG x-tensions it supports and, second, similarily to !version, !x-orgversions can be used to know what version of ORG the relay complies to.

'''Example:'''
C<->R
-> query,rUUID,!x-orgversions
<- query,cUUID,!x-orgversions,ORG=0004/who=002/email=006

'''Requirements:'''
* !x-orgversions should always be accepted with no Auth required, it does not open a session or Lock one.
* The acknowledgement value in a reply to !x-orgversions is a "/"-list of items of the form <package>=<version>. The first <package> is always "ORG" (representing the core specification package of ORG relays), its version string is the version of the specification (4 digits). The other packages are ORG x-tension names, whose version string is 3 digits.
* If several incompatible versions of a same x-tension are supported, they must be listed ordered by version number. Ex: ORG=0004/who=002/email=005/email=006. If versions are backward compatible, only the last version should be reported.

'''Remarks:'''
* In a controller, it is however recommended to use !x-orgversions as soon as possible in order to avoid sending unsupported and useless metacommands later on.
* In the acknowledgement message, x-tension names are listed, not meta-command names (as one x-tension can have several meta-commands). Thus listed names do not include the prefix "!x-".

LSL Protocol/Restrained Love Open Relay Group/ORG Requirements/0004 draft

2011-06-27T13:55:20Z

Satomi Ahn: /* Requirements on both sides */

{{ORG_Restrained_Life_Relay_Specs_TOC}}
STATUS: draft

VERSION: 0004

==Summary==

This page is a list of requirements for a relay or an in-world device to have the right to be called "ORG compliant". It is mostly about adding support for an ORG-centered informational metacommand and specifying Marine Kelley's RLVR protocol a bit more that it is now, while of course preserving full compatibility.

For a quick overview of the motivations and general working of this protocol and a few examples, we refer the reader to [[LSL_Protocol/Restrained_Love_Relay/Specification|the original specification page by Marine Kelley]].

If you are making furniture, traps, or other RLVR controllers and you are not interested in what [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] can offer, then you can stick with the original specification by Marine Kelley and still be compatible with [[LSL_Protocol/Restrained_Love_Relay/Comparison|ORG relays]]. However, to have the right to call your controller "ORG compatible", there are still a few light additional requirements such as:
* using only [[llRegionSayTo]] for communications with the relay,
* not spamming the RLVR channel with messages that do not belong to the protocol,
* and remain responsive to ping messages at every time if you want the session to remain locked.

If you are interested in [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|ORG x-tensions]], then you should also read the part about [[#!x-orgversions|!x-orgversions]].

If you are making a relay, sorry we are afraid you will have to read all this page.

==Definition of an ORG device==

A RLVR device is compliant with ORG specifications if it implements the consolidated RLVR protocol described below along with the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] it announces supporting.

Note in particular that
* the consolidated protocol is backward compatible with [[LSL_Protocol/Restrained_Love_Relay/Specification|Marine Kelley's RLVR protocol version 1.100]] but resolves most loose ends of that document;
* ORG relays handle controller messages whose second field is ffffffff-ffff-ffff-ffff-ffffffffffff exactly the same as if it was the key of the wearer (NULL_KEY is a wildcard);
* one-to-one chat messages (not using a wildcard) are sent by using [[llRegionSayTo]] LSL function;
* there is an additional meta-command, !x-orgversions for a relay to announce supported x-tensions;
* each supported x-tension can imply other supported metacommands, ORG x-tensions meta-command all having names starting with prefix "!x-";
* other proprietary metacommands with prefix "!_-" (replace "_" by any letter that is not "x") can be supported;

Supported x-tensions can constrain the core specification (this document) even more, but cannot alter it or make it less constraining unless as a result of the relay executing a meta-command of this x-tension sent by the controller. Thus, although the protocol is extensible, a controller can always rely on the fact an ORG relay abides by the requirements in this document until it asks the relay to do otherwise.

ORG devices may be advertised by the use of the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/ORG_Logo|ORG logo]] for advertising compliance with ORG requirements. ORG devices makers are encouraged to do so.

==Consolidated RLVR protocol==

=== Protocol Syntax ===

==== Definitions ====
* The '''Restrained Love Relay (RLVR) protocol''' implies two partners (SL objects): the '''relay''' worn by the avatar commands are intended for, and a '''controller''', which sends commands to the relay.

* The goal of the protocol is to force the relay wearer to make perform actions and to toggle restrictions on their behavior. Both actions and restrictions can be enforced either through use of viewer hooks ([[LSL_Protocol/RestrainedLoveAPI|Restrained Love API]], or RLV) or through LSL scripting.

* Hence we distinguish between "'''RLV commands'''", starting with "@", which are commands following the syntax of the RLV API and which will ultimately be forwarded to the viewer, and "'''meta-commands'''", starting with "!", which are meant to be interpreted by LSL functions.

More precisely:

* RLVR protocol consists of messages exchanged on channel -1812221819 (called '''RLVR channel''') using the LSL function [[llRegionSayTo]].
* A controller sends messages (commands) whose syntax is described by the non-terminal <c_msg>.
* A relay sends messages (acknowledgements) whose syntax is described by the non-terminal <r_msg>.

<c_msg> ::= IDENT "," KEY "," <commands>
<r_msg> ::= IDENT "," KEY "," <command> "," ACK
<commands> ::= <command> | <command> "|" <commands>
<command> ::= <rlvcommand> | <metacommand>
<rlvcommand> ::= "@" RLVCOMMAND
<metacommand> ::= "!" METACOMMANDNAME <metacommandarguments>
<metacommandarguments> ::= "" | "/" ARG <metacommandarguments>

where we explicit the different terminal tokens:
IDENT: any string without ","
KEY: any UUID
ACK: any string without ","
RLVCOMMAND: any string without ","
METACOMMANDNAME: any string without "/" and ","
ARG: any string without "/" and ","

====Requirements on both sides====
* Relays can only send <r_msg>'s, and controllers <c_msg>'s. Nothing else is allowed on RLVR channel.
* In <c_msg>, KEY is always either the uuid of relay wearer or ffffffff-ffff-ffff-ffff-ffffffffffff if it is a message intended for all relays who can hear it.
* In <r_msg>, KEY is always the uuid of the controller.

====On the relay side only====
'''Further requirements:'''
*A relay MUST ignore any message on RLVR channel which is not a <c_msg> with KEY being either the key of the avatar wearing the relay or ffffffff-ffff-ffff-ffff-ffffffffffff.
Then, for every <command>:
* if <command> is neither a valid <rlvcommand> or <metacommand>, the relay must ignore it and process the next <command>'s;
* if <command> is a <rlvcommand> or a <metacommand>, the relay MUST send an acknowledgement message back to the controller.
* an acknowledgement message is a <r_msg> (see above) such that
:*IDENT is the same as IDENT in the <c_msg> being processed
:*KEY is the key of the controller who sent the <c_msg>
:*<command> is the subcommand being processed
:*ACK is a string called ''acknowledgement value''. By default the acknowledgement value is "ok" if the relay will execute the <command >, "ko" otherwise;
* every acknowledgement or message sent by the relay to one given controlling device must be issued by the same prim (so that the controlling device can restrict its listener to one source key) using the LSL function [[llRegionSayTo]].

'''Remarks:'''
* Many meta-commands may have other acknowledgements than "ok" or "ko" (or none, for !pong). Their definitions supersede this specification.
* Note that unknown meta-commands cannot be executed and thus wil be acknowledged by "ko".
* Known meta-commands which are sent with not enough parameters or parameters with types incompatible with those in the definition known by the relay also cannot be executed and will also be acknowledged by "ko". (ex: the relay knows !x-who/key, but receives !x-who/integer/string).

===The RLVR protocol session===

====Definitions====
* During an execution of the RLVR protocol, a relay and a controller establish a '''session''' together. A relay may manage several sessions with several controllers. Likewise, a controller could establish sessions with several relays.
* Restrictions on a relay wearer are relative to a session. So are most other variables (authorization state, key of the controller, ... ).
* A session is '''Opened''' whenever the relay accepts a RLVR command from a controller.
* A session is '''Closed''' (or '''released''') as soon as the relay forgets every variables and releases all restrictions pertaining to that session.
* A session is '''Locked''' whenever it holds active restrictions.
* A session is '''Authed''' if the controller has been allowed to control the relay (not only store some variables with no consequence). Once authed, no interactive "ask" dialog should pop up anymore concerning this session. Most commands should now normally be accepted (and maybe a few automatically rejected).
* A controller is called '''reachable''' if it can receive messages from the relay and can prove it by answering ping requests from the relay. By "can", it is meant by the method of communication agreed upon by the relay and controller. By default the communication method is chat messages sent by llRegionSayTo. X-tensions such as email and delay can modify what is meant by reachable.

====Relay side requirements====
*Closing a session clears all RLV restrictions that belong only to that session, clears all session variables and disables all behaviors relative to that session.
*Sessions that are not locked MUST be released after a reasonable timeout.
*Relay implementations MAY require an authed session for all <rlvcommand>'s, except @xxx=<channel_number>, @clear[=xxx] and @xxx=y/rem commands, which MUST always be accepted.
*@xxx=n/add <rlvcommand>'s, after being accepted, add a restriction and therefore Lock the session.
*Some metacommands described in x-tensions can also add restrictions and therefore Lock the session.
*!release, !version, !implversion, !x-orgversions and !x-.../clear[/...] commands are always accepted.
*!pong reactivates an existing session but never requires further auth, provided it is sent by the device to which ping was sent. The relay MUST resend to the viewer all stored restrictions belonging to the controlling device if they are not already active.
*Unless specified otherwise (see !x-who), no command can trigger an interactive dialog unless
:* they require an Authed session
:* and no session is currently open or it is open but not Authed yet.
*When releasing a Locked session, a relay MUST release all restrictions belonging to the device controlling the session.
*On the following events, a relay MUST release a locked session:
:* when the relay notices the controller has become unreachable,
:* when the relay sends "release,<controller_key>,!release,ok" (due to acknowledging !release sent by the controller, or due to safewording triggered from the relay side).
*A relay MUST provide a mechanism for checking that every controlling device is reachable. It is not specified whether this checking process should be automatic or manually triggered.
*The absence of active restriction unlocks the session (and eventually releases it).
*A relay MUST remove restrictions from a session when (and only in these cases):
:* either the session controller specifically asks for the restriction to be released ("@restriction=y" "@restriction=rem", "@clear=restriction" for RLV restrictions, and "!x-restriction/clear/..." for LSL restrictions),
:* or the session closed (for instance !release coming from the device, or safeword).

===Commands===
====Relay side requirements====
* If a <rlvcommand> is acknowledged with value "ok", the relay ensures the viewer is affected the same way as if the LSL instruction llOwnerSay(<rlvcommand>) was executed by a script in a primitive that handles only one controller.
* When processing a <metacommand>, if the relay knows at least one definition of '!'+METACOMMANDNAME for which the received <metacommandarguments> provide enough parameters, then it will be handled according to the definition handling the most parameters among the latter. Extra parameters are ignored.
* A relays knows the following meta-command definitions:
:*[[#Core meta-commands and associated mechanisms|definitions listed in the core requirements]]
:*all definitions included in [[LSL_Protocol/Restrained_Love_Relay/Comparison|x-tensions]] announced by the relay.
* When acknowledging a <metacommand> by anything else than "ko", the relay commits itself to execute it.

'''Remarks:'''
* For first requirement, it must be understood that the reference behavior is that the relay would have if it had one controller per prim. However handling several controllers from one unique prim is possible but requires taking care that different controllers do not interfere with each other, releasing each other's restrictions, for instance.
* For the second requirement, the word "handled" means that if the meta-command with these parameters is known, then requirements in known definition cannot be ignored. Sometimes, this can imply that the meta-command cannot be refused, for instance.

==Core meta-commands and associated mechanisms==

An ORG device MUST at least support the meta-commands !release, !pong, !version, !implversion and !x-orgversions described below and implement their associated mechanisms.

Particular meta-commands definitions and mechanisms may override general requirements above.

===!release===
Sent by a controller, this command closes the session.

* !release obviously opens no session, requires no Auth and is not Locking.
* If there is an actual session to close !release MUST be accepted by the relay and acknowledeged by "ok".
* On accepting !release, the relay erases all data pertaining to the session and disables all restrictions of the session.
* When a relay decides to close a session on its own (user safeword, for instance) and it is not due to the controller being unreachable, the relay must send the following acknowledgement message:
release,<controller_key>,!release,ok

When receiving the latter message, the controller should act accordingly, for instance by resetting itself and making itself ready for the next session.

Note that !release is not the same as @clear. @clear is interpreted by the relay as a RLV command and, as such, can only clear RLV restrictions. If RLV restrictions were the only restrictions of the session, then the session will be closed, but some x-tensions also define pure LSL based restrictions.

===ping/!pong===

The ping/!pong mechanism exists so that relays can check presence and responsiveness of a controller. This was primarily meant to be used on relay wearer relog, in order to reactivate all restrictions so that sessions persist on relog if the controller still exists and is ready to continue the session.

''!pong'' cannot require auth and does not lock a session

We call ''ping message'' a message from the relay, having the following syntax:
ping,<controller_key>,ping,ping
We call ''!pong message'' a message from the controller, having the following syntax:
ping,<relay_key>,!pong

====Relay side====
*A relay SHOULD NOT send an acknowledgement in response to ''!pong''.
*A ping message can be sent any time by the relay to a known controller.
*On wearer relog, for each existing Locked session, the relay must send a ping message to the session controller.
*When a !pong message is received from a controller, if it was a reply to a previous ping message:
:#if the session RLV restrictions contain unsit and the avatar was sitting on some object when the restriction was applied, then the relay MUST force the avatar to sit back on the same object (if still existing);
:#the relay MUST make sure all restrictions belonging to the session are made active again.
*If a ping message is sent and is not answered by the controller, then the relay closes the session.

Note that the relay is responsible for storing restrictions and the key of the sit target across sessions, not the controller.

====Controller side====
*Unless it does not matter that the relay could close the session (or for another reason, the controller knows the relay will not close it), a controller SHOULD listen to ping messages and answer any ping message with a !pong message.
*A controller should ignore ping requests from relays it is not ready to handle.

Note controller don't have to poll for relay presence to resume a session but should just listen for ping messages instead. The relay should have stored all restrictions and handle sitting back to whatever furniture the relay wearer was tied up to.

Concerning the second bullet: for instance, if the controller is a furniture which is already in use by another relay wearer, it would be cause dysfunctions to let the pinging relay restore the restrictions without letting its wearer sit on the furniture. Or if the controller is not stateless and the state for the pinging relay has not been saved before, resuming the session from the initial state might be inconsistant.

===!version===
The purpose of this meta-command is to query the version of the RLVR protocol supported by a relay.

* !version opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !version with the version number of the RLVR protocol it supports ("1100" here, since ORG 0004 includes RLVR 1.100).

Note this is the most common command for a controller to scan for nearby relays, as non-ORG relays also accept this command and answer it the way described above.

===!implversion===
The purpose of this meta-command is to query the name and version of the relay implementation.

* !implversion opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !implversion with its implementation version string... which can be any string.

It is recommended this string includes the following elements:
* the relay name/brand/identifier,
* the version number of that relay name/brand/identifier,
* at the beginning, the string prefix "ORG=0004/"
The latter is convenient for checking for ORG compatibility using a command even non-ORG relay should understand.

===!x-orgversions===

This meta-command purpose it two-fold. First it allows a controlling device to ask a relay for the list of ORG x-tensions it supports and, second, similarily to !version, !x-orgversions can be used to know what version of ORG the relay complies to.

'''Example:'''
C<->R
-> query,rUUID,!x-orgversions
<- query,cUUID,!x-orgversions,ORG=0004/who=002/email=006

'''Requirements:'''
* !x-orgversions should always be accepted with no Auth required, it does not open a session or Lock one.
* The acknowledgement value in a reply to !x-orgversions is a "/"-list of items of the form <package>=<version>. The first <package> is always "ORG" (representing the core specification package of ORG relays), its version string is the version of the specification (4 digits). The other packages are ORG x-tension names, whose version string is 3 digits.
* If several incompatible versions of a same x-tension are supported, they must be listed ordered by version number. Ex: ORG=0004/who=002/email=005/email=006. If versions are backward compatible, only the last version should be reported.

'''Remarks:'''
* In a controller, it is however recommended to use !x-orgversions as soon as possible in order to avoid sending unsupported and useless metacommands later on.
* In the acknowledgement message, x-tension names are listed, not meta-command names (as one x-tension can have several meta-commands). Thus listed names do not include the prefix "!x-".

LSL Protocol/Restrained Love Open Relay Group/ORG Requirements/0004 draft

2011-06-27T13:52:58Z

Satomi Ahn: /* Consolidated RLVR protocol */

{{ORG_Restrained_Life_Relay_Specs_TOC}}
STATUS: draft

VERSION: 0004

==Summary==

This page is a list of requirements for a relay or an in-world device to have the right to be called "ORG compliant". It is mostly about adding support for an ORG-centered informational metacommand and specifying Marine Kelley's RLVR protocol a bit more that it is now, while of course preserving full compatibility.

For a quick overview of the motivations and general working of this protocol and a few examples, we refer the reader to [[LSL_Protocol/Restrained_Love_Relay/Specification|the original specification page by Marine Kelley]].

If you are making furniture, traps, or other RLVR controllers and you are not interested in what [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] can offer, then you can stick with the original specification by Marine Kelley and still be compatible with [[LSL_Protocol/Restrained_Love_Relay/Comparison|ORG relays]]. However, to have the right to call your controller "ORG compatible", there are still a few light additional requirements such as:
* using only [[llRegionSayTo]] for communications with the relay,
* not spamming the RLVR channel with messages that do not belong to the protocol,
* and remain responsive to ping messages at every time if you want the session to remain locked.

If you are interested in [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|ORG x-tensions]], then you should also read the part about [[#!x-orgversions|!x-orgversions]].

If you are making a relay, sorry we are afraid you will have to read all this page.

==Definition of an ORG device==

A RLVR device is compliant with ORG specifications if it implements the consolidated RLVR protocol described below along with the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] it announces supporting.

Note in particular that
* the consolidated protocol is backward compatible with [[LSL_Protocol/Restrained_Love_Relay/Specification|Marine Kelley's RLVR protocol version 1.100]] but resolves most loose ends of that document;
* ORG relays handle controller messages whose second field is ffffffff-ffff-ffff-ffff-ffffffffffff exactly the same as if it was the key of the wearer (NULL_KEY is a wildcard);
* one-to-one chat messages (not using a wildcard) are sent by using [[llRegionSayTo]] LSL function;
* there is an additional meta-command, !x-orgversions for a relay to announce supported x-tensions;
* each supported x-tension can imply other supported metacommands, ORG x-tensions meta-command all having names starting with prefix "!x-";
* other proprietary metacommands with prefix "!_-" (replace "_" by any letter that is not "x") can be supported;

Supported x-tensions can constrain the core specification (this document) even more, but cannot alter it or make it less constraining unless as a result of the relay executing a meta-command of this x-tension sent by the controller. Thus, although the protocol is extensible, a controller can always rely on the fact an ORG relay abides by the requirements in this document until it asks the relay to do otherwise.

ORG devices may be advertised by the use of the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/ORG_Logo|ORG logo]] for advertising compliance with ORG requirements. ORG devices makers are encouraged to do so.

==Consolidated RLVR protocol==

=== Protocol Syntax ===

==== Definitions ====
* The '''Restrained Love Relay (RLVR) protocol''' implies two partners (SL objects): the '''relay''' worn by the avatar commands are intended for, and a '''controller''', which sends commands to the relay.

* The goal of the protocol is to force the relay wearer to make perform actions and to toggle restrictions on their behavior. Both actions and restrictions can be enforced either through use of viewer hooks ([[LSL_Protocol/RestrainedLoveAPI|Restrained Love API]], or RLV) or through LSL scripting.

* Hence we distinguish between "'''RLV commands'''", starting with "@", which are commands following the syntax of the RLV API and which will ultimately be forwarded to the viewer, and "'''meta-commands'''", starting with "!", which are meant to be interpreted by LSL functions.

More precisely:

* RLVR protocol consists of messages exchanged on channel -1812221819 (called '''RLVR channel''') using the LSL function [[llRegionSayTo]].
* A controller sends messages (commands) whose syntax is described by the non-terminal <c_msg>.
* A relay sends messages (acknowledgements) whose syntax is described by the non-terminal <r_msg>.

<c_msg> ::= IDENT "," KEY "," <commands>
<r_msg> ::= IDENT "," KEY "," <command> "," ACK
<commands> ::= <command> | <command> "|" <commands>
<command> ::= <rlvcommand> | <metacommand>
<rlvcommand> ::= "@" RLVCOMMAND
<metacommand> ::= "!" METACOMMANDNAME <metacommandarguments>
<metacommandarguments> ::= "" | "/" ARG <metacommandarguments>

where we explicit the different terminal tokens:
IDENT: any string without ","
KEY: any UUID
ACK: any string without ","
RLVCOMMAND: any string without ","
METACOMMANDNAME: any string without "/" and ","
ARG: any string without "/" and ","

====Requirements on both sides====
* Relays can only send <r_msg>'s, and controllers <c_msg>'s. Nothing else is allowed on RLVR channel.
* KEY is always the uuid of the recipient of the message, or ffffffff-ffff-ffff-ffff-ffffffffffff if it is a message from a controller intended for all relays who can hear it.

====On the relay side only====
'''Further requirements:'''
*A relay MUST ignore any message on RLVR channel which is not a <c_msg> with KEY being either the key of the avatar wearing the relay or ffffffff-ffff-ffff-ffff-ffffffffffff.
Then, for every <command>:
* if <command> is neither a valid <rlvcommand> or <metacommand>, the relay must ignore it and process the next <command>'s;
* if <command> is a <rlvcommand> or a <metacommand>, the relay MUST send an acknowledgement message back to the controller.
* an acknowledgement message is a <r_msg> (see above) such that
:*IDENT is the same as IDENT in the <c_msg> being processed
:*KEY is the key of the controller who sent the <c_msg>
:*<command> is the subcommand being processed
:*ACK is a string called ''acknowledgement value''. By default the acknowledgement value is "ok" if the relay will execute the <command >, "ko" otherwise;
* every acknowledgement or message sent by the relay to one given controlling device must be issued by the same prim (so that the controlling device can restrict its listener to one source key) using the LSL function [[llRegionSayTo]].

'''Remarks:'''
* Many meta-commands may have other acknowledgements than "ok" or "ko" (or none, for !pong). Their definitions supersede this specification.
* Note that unknown meta-commands cannot be executed and thus wil be acknowledged by "ko".
* Known meta-commands which are sent with not enough parameters or parameters with types incompatible with those in the definition known by the relay also cannot be executed and will also be acknowledged by "ko". (ex: the relay knows !x-who/key, but receives !x-who/integer/string).

===The RLVR protocol session===

====Definitions====
* During an execution of the RLVR protocol, a relay and a controller establish a '''session''' together. A relay may manage several sessions with several controllers. Likewise, a controller could establish sessions with several relays.
* Restrictions on a relay wearer are relative to a session. So are most other variables (authorization state, key of the controller, ... ).
* A session is '''Opened''' whenever the relay accepts a RLVR command from a controller.
* A session is '''Closed''' (or '''released''') as soon as the relay forgets every variables and releases all restrictions pertaining to that session.
* A session is '''Locked''' whenever it holds active restrictions.
* A session is '''Authed''' if the controller has been allowed to control the relay (not only store some variables with no consequence). Once authed, no interactive "ask" dialog should pop up anymore concerning this session. Most commands should now normally be accepted (and maybe a few automatically rejected).
* A controller is called '''reachable''' if it can receive messages from the relay and can prove it by answering ping requests from the relay. By "can", it is meant by the method of communication agreed upon by the relay and controller. By default the communication method is chat messages sent by llRegionSayTo. X-tensions such as email and delay can modify what is meant by reachable.

====Relay side requirements====
*Closing a session clears all RLV restrictions that belong only to that session, clears all session variables and disables all behaviors relative to that session.
*Sessions that are not locked MUST be released after a reasonable timeout.
*Relay implementations MAY require an authed session for all <rlvcommand>'s, except @xxx=<channel_number>, @clear[=xxx] and @xxx=y/rem commands, which MUST always be accepted.
*@xxx=n/add <rlvcommand>'s, after being accepted, add a restriction and therefore Lock the session.
*Some metacommands described in x-tensions can also add restrictions and therefore Lock the session.
*!release, !version, !implversion, !x-orgversions and !x-.../clear[/...] commands are always accepted.
*!pong reactivates an existing session but never requires further auth, provided it is sent by the device to which ping was sent. The relay MUST resend to the viewer all stored restrictions belonging to the controlling device if they are not already active.
*Unless specified otherwise (see !x-who), no command can trigger an interactive dialog unless
:* they require an Authed session
:* and no session is currently open or it is open but not Authed yet.
*When releasing a Locked session, a relay MUST release all restrictions belonging to the device controlling the session.
*On the following events, a relay MUST release a locked session:
:* when the relay notices the controller has become unreachable,
:* when the relay sends "release,<controller_key>,!release,ok" (due to acknowledging !release sent by the controller, or due to safewording triggered from the relay side).
*A relay MUST provide a mechanism for checking that every controlling device is reachable. It is not specified whether this checking process should be automatic or manually triggered.
*The absence of active restriction unlocks the session (and eventually releases it).
*A relay MUST remove restrictions from a session when (and only in these cases):
:* either the session controller specifically asks for the restriction to be released ("@restriction=y" "@restriction=rem", "@clear=restriction" for RLV restrictions, and "!x-restriction/clear/..." for LSL restrictions),
:* or the session closed (for instance !release coming from the device, or safeword).

===Commands===
====Relay side requirements====
* If a <rlvcommand> is acknowledged with value "ok", the relay ensures the viewer is affected the same way as if the LSL instruction llOwnerSay(<rlvcommand>) was executed by a script in a primitive that handles only one controller.
* When processing a <metacommand>, if the relay knows at least one definition of '!'+METACOMMANDNAME for which the received <metacommandarguments> provide enough parameters, then it will be handled according to the definition handling the most parameters among the latter. Extra parameters are ignored.
* A relays knows the following meta-command definitions:
:*[[#Core meta-commands and associated mechanisms|definitions listed in the core requirements]]
:*all definitions included in [[LSL_Protocol/Restrained_Love_Relay/Comparison|x-tensions]] announced by the relay.
* When acknowledging a <metacommand> by anything else than "ko", the relay commits itself to execute it.

'''Remarks:'''
* For first requirement, it must be understood that the reference behavior is that the relay would have if it had one controller per prim. However handling several controllers from one unique prim is possible but requires taking care that different controllers do not interfere with each other, releasing each other's restrictions, for instance.
* For the second requirement, the word "handled" means that if the meta-command with these parameters is known, then requirements in known definition cannot be ignored. Sometimes, this can imply that the meta-command cannot be refused, for instance.

==Core meta-commands and associated mechanisms==

An ORG device MUST at least support the meta-commands !release, !pong, !version, !implversion and !x-orgversions described below and implement their associated mechanisms.

Particular meta-commands definitions and mechanisms may override general requirements above.

===!release===
Sent by a controller, this command closes the session.

* !release obviously opens no session, requires no Auth and is not Locking.
* If there is an actual session to close !release MUST be accepted by the relay and acknowledeged by "ok".
* On accepting !release, the relay erases all data pertaining to the session and disables all restrictions of the session.
* When a relay decides to close a session on its own (user safeword, for instance) and it is not due to the controller being unreachable, the relay must send the following acknowledgement message:
release,<controller_key>,!release,ok

When receiving the latter message, the controller should act accordingly, for instance by resetting itself and making itself ready for the next session.

Note that !release is not the same as @clear. @clear is interpreted by the relay as a RLV command and, as such, can only clear RLV restrictions. If RLV restrictions were the only restrictions of the session, then the session will be closed, but some x-tensions also define pure LSL based restrictions.

===ping/!pong===

The ping/!pong mechanism exists so that relays can check presence and responsiveness of a controller. This was primarily meant to be used on relay wearer relog, in order to reactivate all restrictions so that sessions persist on relog if the controller still exists and is ready to continue the session.

''!pong'' cannot require auth and does not lock a session

We call ''ping message'' a message from the relay, having the following syntax:
ping,<controller_key>,ping,ping
We call ''!pong message'' a message from the controller, having the following syntax:
ping,<relay_key>,!pong

====Relay side====
*A relay SHOULD NOT send an acknowledgement in response to ''!pong''.
*A ping message can be sent any time by the relay to a known controller.
*On wearer relog, for each existing Locked session, the relay must send a ping message to the session controller.
*When a !pong message is received from a controller, if it was a reply to a previous ping message:
:#if the session RLV restrictions contain unsit and the avatar was sitting on some object when the restriction was applied, then the relay MUST force the avatar to sit back on the same object (if still existing);
:#the relay MUST make sure all restrictions belonging to the session are made active again.
*If a ping message is sent and is not answered by the controller, then the relay closes the session.

Note that the relay is responsible for storing restrictions and the key of the sit target across sessions, not the controller.

====Controller side====
*Unless it does not matter that the relay could close the session (or for another reason, the controller knows the relay will not close it), a controller SHOULD listen to ping messages and answer any ping message with a !pong message.
*A controller should ignore ping requests from relays it is not ready to handle.

Note controller don't have to poll for relay presence to resume a session but should just listen for ping messages instead. The relay should have stored all restrictions and handle sitting back to whatever furniture the relay wearer was tied up to.

Concerning the second bullet: for instance, if the controller is a furniture which is already in use by another relay wearer, it would be cause dysfunctions to let the pinging relay restore the restrictions without letting its wearer sit on the furniture. Or if the controller is not stateless and the state for the pinging relay has not been saved before, resuming the session from the initial state might be inconsistant.

===!version===
The purpose of this meta-command is to query the version of the RLVR protocol supported by a relay.

* !version opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !version with the version number of the RLVR protocol it supports ("1100" here, since ORG 0004 includes RLVR 1.100).

Note this is the most common command for a controller to scan for nearby relays, as non-ORG relays also accept this command and answer it the way described above.

===!implversion===
The purpose of this meta-command is to query the name and version of the relay implementation.

* !implversion opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !implversion with its implementation version string... which can be any string.

It is recommended this string includes the following elements:
* the relay name/brand/identifier,
* the version number of that relay name/brand/identifier,
* at the beginning, the string prefix "ORG=0004/"
The latter is convenient for checking for ORG compatibility using a command even non-ORG relay should understand.

===!x-orgversions===

This meta-command purpose it two-fold. First it allows a controlling device to ask a relay for the list of ORG x-tensions it supports and, second, similarily to !version, !x-orgversions can be used to know what version of ORG the relay complies to.

'''Example:'''
C<->R
-> query,rUUID,!x-orgversions
<- query,cUUID,!x-orgversions,ORG=0004/who=002/email=006

'''Requirements:'''
* !x-orgversions should always be accepted with no Auth required, it does not open a session or Lock one.
* The acknowledgement value in a reply to !x-orgversions is a "/"-list of items of the form <package>=<version>. The first <package> is always "ORG" (representing the core specification package of ORG relays), its version string is the version of the specification (4 digits). The other packages are ORG x-tension names, whose version string is 3 digits.
* If several incompatible versions of a same x-tension are supported, they must be listed ordered by version number. Ex: ORG=0004/who=002/email=005/email=006. If versions are backward compatible, only the last version should be reported.

'''Remarks:'''
* In a controller, it is however recommended to use !x-orgversions as soon as possible in order to avoid sending unsupported and useless metacommands later on.
* In the acknowledgement message, x-tension names are listed, not meta-command names (as one x-tension can have several meta-commands). Thus listed names do not include the prefix "!x-".

LSL Protocol/Restrained Love Open Relay Group/ORG Requirements/0004 draft

2011-06-27T13:38:36Z

Satomi Ahn: /* Syntactical considerations */

{{ORG_Restrained_Life_Relay_Specs_TOC}}
STATUS: draft

VERSION: 0004

==Summary==

This page is a list of requirements for a relay or an in-world device to have the right to be called "ORG compliant". It is mostly about adding support for an ORG-centered informational metacommand and specifying Marine Kelley's RLVR protocol a bit more that it is now, while of course preserving full compatibility.

For a quick overview of the motivations and general working of this protocol and a few examples, we refer the reader to [[LSL_Protocol/Restrained_Love_Relay/Specification|the original specification page by Marine Kelley]].

If you are making furniture, traps, or other RLVR controllers and you are not interested in what [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] can offer, then you can stick with the original specification by Marine Kelley and still be compatible with [[LSL_Protocol/Restrained_Love_Relay/Comparison|ORG relays]]. However, to have the right to call your controller "ORG compatible", there are still a few light additional requirements such as:
* using only [[llRegionSayTo]] for communications with the relay,
* not spamming the RLVR channel with messages that do not belong to the protocol,
* and remain responsive to ping messages at every time if you want the session to remain locked.

If you are interested in [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|ORG x-tensions]], then you should also read the part about [[#!x-orgversions|!x-orgversions]].

If you are making a relay, sorry we are afraid you will have to read all this page.

==Definition of an ORG device==

A RLVR device is compliant with ORG specifications if it implements the consolidated RLVR protocol described below along with the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] it announces supporting.

Note in particular that
* the consolidated protocol is backward compatible with [[LSL_Protocol/Restrained_Love_Relay/Specification|Marine Kelley's RLVR protocol version 1.100]] but resolves most loose ends of that document;
* ORG relays handle controller messages whose second field is ffffffff-ffff-ffff-ffff-ffffffffffff exactly the same as if it was the key of the wearer (NULL_KEY is a wildcard);
* one-to-one chat messages (not using a wildcard) are sent by using [[llRegionSayTo]] LSL function;
* there is an additional meta-command, !x-orgversions for a relay to announce supported x-tensions;
* each supported x-tension can imply other supported metacommands, ORG x-tensions meta-command all having names starting with prefix "!x-";
* other proprietary metacommands with prefix "!_-" (replace "_" by any letter that is not "x") can be supported;

Supported x-tensions can constrain the core specification (this document) even more, but cannot alter it or make it less constraining unless as a result of the relay executing a meta-command of this x-tension sent by the controller. Thus, although the protocol is extensible, a controller can always rely on the fact an ORG relay abides by the requirements in this document until it asks the relay to do otherwise.

ORG devices may be advertised by the use of the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/ORG_Logo|ORG logo]] for advertising compliance with ORG requirements. ORG devices makers are encouraged to do so.

==Consolidated RLVR protocol==

=== A few definitions ===

* The '''Restrained Love Relay (RLVR) protocol''' implies two partners (SL objects): the '''relay''' worn by the avatar commands are intended for, and a '''controller''', which sends commands to the relay.

* During an execution of the RLVR protocol, a relay and a controller establish a '''session''' together. A relay may manage several sessions with several controllers. Likewise, a controller could establish sessions with several relays.

* The goal of the protocol is to force the relay wearer to make perform actions and to toggle restrictions on their behavior. Both actions and restrictions can be enforced either through use of viewer hooks ([[LSL_Protocol/RestrainedLoveAPI|Restrained Love API]], or RLV) or through LSL scripting.

* Hence we distinguish between "'''RLV commands'''", starting with "@", which are commands following the syntax of the RLV API and which will ultimately be forwarded to the viewer, and "'''meta-commands'''", starting with "!", which are meant to be interpreted by LSL functions.

* Restrictions on a relay wearer are relative to a session. So are most other variables (authorization state, key of the controller, ... ).

* A session is '''Opened''' whenever the relay accepts a RLVR command from a controller.

* A session is '''Closed''' (or '''released''') as soon as the relay forgets every variables and releases all restrictions pertaining to that session.

* A session is '''Locked''' whenever it holds active restrictions.

* A session is '''Authed''' if the controller has been allowed to control the relay (not only store some variables with no consequence). Once authed, no interactive "ask" dialog should pop up anymore concerning this session. Most commands should now normally be accepted (and maybe a few automatically rejected).

* A controller is called '''reachable''' if it can receive messages from the relay and can prove it by answering ping requests from the relay. By "can", it is meant by the method of communication agreed upon by the relay and controller. By default the communication method is chat messages sent by llRegionSayTo. X-tensions such as email and delay can modify what is meant by reachable.

===Protocol syntax and related notations===

* RLVR protocol consists of messages exchanged on channel -1812221819 (called '''RLVR channel''') using the LSL function [[llRegionSayTo]].
* A controller only sends messages (commands) whose syntax is described by the non-terminal <c_msg>.
* A relay only sends messages (acknowledgements) whose syntax is described by the non-terminal <r_msg>.
* No other message should be exchanged on this channel.

<c_msg> ::= IDENT "," KEY "," <commands>
<r_msg> ::= IDENT "," KEY "," <command> "," ACK
<commands> ::= <command> | <command> "|" <commands>
<command> ::= <rlvcommand> | <metacommand>
<rlvcommand> ::= "@" RLVCOMMAND
<metacommand> ::= "!" METACOMMANDNAME <metacommandarguments>
<metacommandarguments> ::= "" | "/" ARG <metacommandarguments>

where we explicit the different terminal tokens:
IDENT: any string without ","
KEY: any UUID
ACK: any string without ","
RLVCOMMAND: any string without ","
METACOMMANDNAME: any string without "/" and ","
ARG: any string without "/" and ","

===Relay requirements===
These requirements do apply by default but the behavior of the relay may be modified as a result of having executed some metacommand defined in an optional x-tension.

====Syntactical considerations====
'''Requirements:'''
*A relay MUST ignore any message on RLVR channel which is not a <c_msg> with KEY being either the key of the avatar wearing the relay or ffffffff-ffff-ffff-ffff-ffffffffffff.
Then, for every <command>:
* if <command> is neither a valid <rlvcommand> or <metacommand>, the relay must ignore it and process the next <command>'s;
* if <command> is a <rlvcommand> or a <metacommand>, the relay MUST send an acknowledgement message back to the controller.
* an acknowledgement message is a <r_msg> (see above) such that
:*IDENT is the same as IDENT in the <c_msg> being processed
:*KEY is the key of the controller who sent the <c_msg>
:*<command> is the subcommand being processed
:*ACK is a string called ''acknowledgement value''. By default the acknowledgement value is "ok" if the relay will execute the <command >, "ko" otherwise;
* every acknowledgement or message sent by the relay to one given controlling device must be issued by the same prim (so that the controlling device can restrict its listener to one source key) using the LSL function [[llRegionSayTo]].

'''Remarks:'''
* Many meta-commands may have other acknowledgements than "ok" or "ko" (or none, for !pong). Their definitions supersede this specification.
* Note that unknown meta-commands cannot be executed and thus wil be acknowledged by "ko".
* Known meta-commands which are sent with not enough parameters or parameters with types incompatible with those in the definition known by the relay also cannot be executed and will also be acknowledged by "ko". (ex: the relay knows !x-who/key, but receives !x-who/integer/string).

====Command handling====
'''Requirements:'''
* If a <rlvcommand> is acknowledged with value "ok", the relay ensures the viewer is affected the same way as if the LSL instruction llOwnerSay(<rlvcommand>) was executed by a script in a primitive that handles only one controller.
* When processing a <metacommand>, if the relay knows at least one definition of '!'+METACOMMANDNAME for which the received <metacommandarguments> provide enough parameters, then it will be handled according to the definition handling the most parameters among the latter. Extra parameters are ignored.
* A relays knows the following meta-command definitions:
:*[[#Core meta-commands and associated mechanisms|definitions listed in the core requirements]]
:*all definitions included in [[LSL_Protocol/Restrained_Love_Relay/Comparison|x-tensions]] announced by the relay.
* When acknowledging a <metacommand> by anything else than "ko", the relay commits itself to execute it.

'''Remarks:'''
* For first requirement, it must be understood that the reference behavior is that the relay would have if it had one controller per prim. However handling several controllers from one unique prim is possible but requires taking care that different controllers do not interfere with each other, releasing each other's restrictions, for instance.
* For the second requirement, the word "handled" means that if the meta-command with these parameters is known, then requirements in known definition cannot be ignored. Sometimes, this can imply that the meta-command cannot be refused, for instance.

====Session related requirements:====
*Closing a session clears all RLV restrictions that belong only to that session, clears all session variables and disables all behaviors relative to that session.
*Sessions that are not locked MUST be released after a reasonable timeout.
*Relay implementations MAY require an authed session for all <rlvcommand>'s, except @xxx=<channel_number>, @clear[=xxx] and @xxx=y/rem commands, which MUST always be accepted.
*@xxx=n/add <rlvcommand>'s, after being accepted, add a restriction and therefore Lock the session.
*Some metacommands described in x-tensions can also add restrictions and therefore Lock the session.
*!release, !version, !implversion, !x-orgversions and !x-.../clear[/...] commands are always accepted.
*!pong reactivates an existing session but never requires further auth, provided it is sent by the device to which ping was sent. The relay MUST resend to the viewer all stored restrictions belonging to the controlling device if they are not already active.
*Unless specified otherwise (see !x-who), no command can trigger an interactive dialog unless
:* they require an Authed session
:* and no session is currently open or it is open but not Authed yet.
*When releasing a Locked session, a relay MUST release all restrictions belonging to the device controlling the session.
*On the following events, a relay MUST release a locked session:
:* when the relay notices the controller has become unreachable,
:* wren the relay sends "release,<controller_key>,!release,ok" (due to acknowledging !release sent by the controller, or due to safewording triggered from the relay side).
*A relay MUST provide a mechanism for checking that every controlling device is reachable. It is not specified whether this checking process should be automatic or manually triggered.
*The absence of active restriction unlocks the session (and eventually releases it).
*A relay MUST remove restrictions from a session when (and only in these cases):
:* either the session controller specifically asks for the restriction to be released ("@restriction=y" "@restriction=rem", "@clear=restriction" for RLV restrictions, and "!x-restriction/clear/..." for LSL restrictions),
:* or the session closed (for instance !release coming from the device, or safeword).

===Controller requirements===
* A controller MUST not send anything on RLVR channel that is not a valid <c_msg>.
* A controller MUST, for each Locked session it controls, provide a mechanism that will unlock it in bounded time. (i.e.: either there is a menu that will release the victim, or there is a timer, or a menu should be able to start such a timer). At least one person MUST know what this mechanism is, and if it requires an action from someone else, be able to tell that other person what s/he has to do.

==Core meta-commands and associated mechanisms==

An ORG device MUST at least support the meta-commands !release, !pong, !version, !implversion and !x-orgversions described below and implement their associated mechanisms.

Particular meta-commands definitions and mechanisms may override general requirements above.

===!release===
Sent by a controller, this command closes the session.

* !release obviously opens no session, requires no Auth and is not Locking.
* If there is an actual session to close !release MUST be accepted by the relay and acknowledeged by "ok".
* On accepting !release, the relay erases all data pertaining to the session and disables all restrictions of the session.
* When a relay decides to close a session on its own (user safeword, for instance) and it is not due to the controller being unreachable, the relay must send the following acknowledgement message:
release,<controller_key>,!release,ok

When receiving the latter message, the controller should act accordingly, for instance by resetting itself and making itself ready for the next session.

Note that !release is not the same as @clear. @clear is interpreted by the relay as a RLV command and, as such, can only clear RLV restrictions. If RLV restrictions were the only restrictions of the session, then the session will be closed, but some x-tensions also define pure LSL based restrictions.

===ping/!pong===

The ping/!pong mechanism exists so that relays can check presence and responsiveness of a controller. This was primarily meant to be used on relay wearer relog, in order to reactivate all restrictions so that sessions persist on relog if the controller still exists and is ready to continue the session.

''!pong'' cannot require auth and does not lock a session

We call ''ping message'' a message from the relay, having the following syntax:
ping,<controller_key>,ping,ping
We call ''!pong message'' a message from the controller, having the following syntax:
ping,<relay_key>,!pong

====Relay side====
*A relay SHOULD NOT send an acknowledgement in response to ''!pong''.
*A ping message can be sent any time by the relay to a known controller.
*On wearer relog, for each existing Locked session, the relay must send a ping message to the session controller.
*When a !pong message is received from a controller, if it was a reply to a previous ping message:
:#if the session RLV restrictions contain unsit and the avatar was sitting on some object when the restriction was applied, then the relay MUST force the avatar to sit back on the same object (if still existing);
:#the relay MUST make sure all restrictions belonging to the session are made active again.
*If a ping message is sent and is not answered by the controller, then the relay closes the session.

Note that the relay is responsible for storing restrictions and the key of the sit target across sessions, not the controller.

====Controller side====
*Unless it does not matter that the relay could close the session (or for another reason, the controller knows the relay will not close it), a controller SHOULD listen to ping messages and answer any ping message with a !pong message.
*A controller should ignore ping requests from relays it is not ready to handle.

Note controller don't have to poll for relay presence to resume a session but should just listen for ping messages instead. The relay should have stored all restrictions and handle sitting back to whatever furniture the relay wearer was tied up to.

Concerning the second bullet: for instance, if the controller is a furniture which is already in use by another relay wearer, it would be cause dysfunctions to let the pinging relay restore the restrictions without letting its wearer sit on the furniture. Or if the controller is not stateless and the state for the pinging relay has not been saved before, resuming the session from the initial state might be inconsistant.

===!version===
The purpose of this meta-command is to query the version of the RLVR protocol supported by a relay.

* !version opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !version with the version number of the RLVR protocol it supports ("1100" here, since ORG 0004 includes RLVR 1.100).

Note this is the most common command for a controller to scan for nearby relays, as non-ORG relays also accept this command and answer it the way described above.

===!implversion===
The purpose of this meta-command is to query the name and version of the relay implementation.

* !implversion opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !implversion with its implementation version string... which can be any string.

It is recommended this string includes the following elements:
* the relay name/brand/identifier,
* the version number of that relay name/brand/identifier,
* at the beginning, the string prefix "ORG=0004/"
The latter is convenient for checking for ORG compatibility using a command even non-ORG relay should understand.

===!x-orgversions===

This meta-command purpose it two-fold. First it allows a controlling device to ask a relay for the list of ORG x-tensions it supports and, second, similarily to !version, !x-orgversions can be used to know what version of ORG the relay complies to.

'''Example:'''
C<->R
-> query,rUUID,!x-orgversions
<- query,cUUID,!x-orgversions,ORG=0004/who=002/email=006

'''Requirements:'''
* !x-orgversions should always be accepted with no Auth required, it does not open a session or Lock one.
* The acknowledgement value in a reply to !x-orgversions is a "/"-list of items of the form <package>=<version>. The first <package> is always "ORG" (representing the core specification package of ORG relays), its version string is the version of the specification (4 digits). The other packages are ORG x-tension names, whose version string is 3 digits.
* If several incompatible versions of a same x-tension are supported, they must be listed ordered by version number. Ex: ORG=0004/who=002/email=005/email=006. If versions are backward compatible, only the last version should be reported.

'''Remarks:'''
* In a controller, it is however recommended to use !x-orgversions as soon as possible in order to avoid sending unsupported and useless metacommands later on.
* In the acknowledgement message, x-tension names are listed, not meta-command names (as one x-tension can have several meta-commands). Thus listed names do not include the prefix "!x-".

LSL Protocol/Restrained Love Open Relay Group/ORG Requirements/0004 draft

2011-06-27T13:35:43Z

Satomi Ahn: /* Syntactical considerations */

{{ORG_Restrained_Life_Relay_Specs_TOC}}
STATUS: draft

VERSION: 0004

==Summary==

This page is a list of requirements for a relay or an in-world device to have the right to be called "ORG compliant". It is mostly about adding support for an ORG-centered informational metacommand and specifying Marine Kelley's RLVR protocol a bit more that it is now, while of course preserving full compatibility.

For a quick overview of the motivations and general working of this protocol and a few examples, we refer the reader to [[LSL_Protocol/Restrained_Love_Relay/Specification|the original specification page by Marine Kelley]].

If you are making furniture, traps, or other RLVR controllers and you are not interested in what [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] can offer, then you can stick with the original specification by Marine Kelley and still be compatible with [[LSL_Protocol/Restrained_Love_Relay/Comparison|ORG relays]]. However, to have the right to call your controller "ORG compatible", there are still a few light additional requirements such as:
* using only [[llRegionSayTo]] for communications with the relay,
* not spamming the RLVR channel with messages that do not belong to the protocol,
* and remain responsive to ping messages at every time if you want the session to remain locked.

If you are interested in [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|ORG x-tensions]], then you should also read the part about [[#!x-orgversions|!x-orgversions]].

If you are making a relay, sorry we are afraid you will have to read all this page.

==Definition of an ORG device==

A RLVR device is compliant with ORG specifications if it implements the consolidated RLVR protocol described below along with the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] it announces supporting.

Note in particular that
* the consolidated protocol is backward compatible with [[LSL_Protocol/Restrained_Love_Relay/Specification|Marine Kelley's RLVR protocol version 1.100]] but resolves most loose ends of that document;
* ORG relays handle controller messages whose second field is ffffffff-ffff-ffff-ffff-ffffffffffff exactly the same as if it was the key of the wearer (NULL_KEY is a wildcard);
* one-to-one chat messages (not using a wildcard) are sent by using [[llRegionSayTo]] LSL function;
* there is an additional meta-command, !x-orgversions for a relay to announce supported x-tensions;
* each supported x-tension can imply other supported metacommands, ORG x-tensions meta-command all having names starting with prefix "!x-";
* other proprietary metacommands with prefix "!_-" (replace "_" by any letter that is not "x") can be supported;

Supported x-tensions can constrain the core specification (this document) even more, but cannot alter it or make it less constraining unless as a result of the relay executing a meta-command of this x-tension sent by the controller. Thus, although the protocol is extensible, a controller can always rely on the fact an ORG relay abides by the requirements in this document until it asks the relay to do otherwise.

ORG devices may be advertised by the use of the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/ORG_Logo|ORG logo]] for advertising compliance with ORG requirements. ORG devices makers are encouraged to do so.

==Consolidated RLVR protocol==

=== A few definitions ===

* The '''Restrained Love Relay (RLVR) protocol''' implies two partners (SL objects): the '''relay''' worn by the avatar commands are intended for, and a '''controller''', which sends commands to the relay.

* During an execution of the RLVR protocol, a relay and a controller establish a '''session''' together. A relay may manage several sessions with several controllers. Likewise, a controller could establish sessions with several relays.

* The goal of the protocol is to force the relay wearer to make perform actions and to toggle restrictions on their behavior. Both actions and restrictions can be enforced either through use of viewer hooks ([[LSL_Protocol/RestrainedLoveAPI|Restrained Love API]], or RLV) or through LSL scripting.

* Hence we distinguish between "'''RLV commands'''", starting with "@", which are commands following the syntax of the RLV API and which will ultimately be forwarded to the viewer, and "'''meta-commands'''", starting with "!", which are meant to be interpreted by LSL functions.

* Restrictions on a relay wearer are relative to a session. So are most other variables (authorization state, key of the controller, ... ).

* A session is '''Opened''' whenever the relay accepts a RLVR command from a controller.

* A session is '''Closed''' (or '''released''') as soon as the relay forgets every variables and releases all restrictions pertaining to that session.

* A session is '''Locked''' whenever it holds active restrictions.

* A session is '''Authed''' if the controller has been allowed to control the relay (not only store some variables with no consequence). Once authed, no interactive "ask" dialog should pop up anymore concerning this session. Most commands should now normally be accepted (and maybe a few automatically rejected).

* A controller is called '''reachable''' if it can receive messages from the relay and can prove it by answering ping requests from the relay. By "can", it is meant by the method of communication agreed upon by the relay and controller. By default the communication method is chat messages sent by llRegionSayTo. X-tensions such as email and delay can modify what is meant by reachable.

===Protocol syntax and related notations===

* RLVR protocol consists of messages exchanged on channel -1812221819 (called '''RLVR channel''') using the LSL function [[llRegionSayTo]].
* A controller only sends messages (commands) whose syntax is described by the non-terminal <c_msg>.
* A relay only sends messages (acknowledgements) whose syntax is described by the non-terminal <r_msg>.
* No other message should be exchanged on this channel.

<c_msg> ::= IDENT "," KEY "," <commands>
<r_msg> ::= IDENT "," KEY "," <command> "," ACK
<commands> ::= <command> | <command> "|" <commands>
<command> ::= <rlvcommand> | <metacommand>
<rlvcommand> ::= "@" RLVCOMMAND
<metacommand> ::= "!" METACOMMANDNAME <metacommandarguments>
<metacommandarguments> ::= "" | "/" ARG <metacommandarguments>

where we explicit the different terminal tokens:
IDENT: any string without ","
KEY: any UUID
ACK: any string without ","
RLVCOMMAND: any string without ","
METACOMMANDNAME: any string without "/" and ","
ARG: any string without "/" and ","

===Relay requirements===
These requirements do apply by default but the behavior of the relay may be modified as a result of having executed some metacommand defined in an optional x-tension.

====Syntactical considerations====
'''Requirements:'''
*A relay MUST ignore any message on RLVR channel that is not a ","-list of 3 items and whose second item is not the key of the avatar wearing the relay or ffffffff-ffff-ffff-ffff-ffffffffffff.
When the relay receives a message meeting the above conditions and considering the 3rd item of the ","-list as a "|"-list of <command>s, then for every <command>:
* if the <command> is neither a valid <rlvcommand> or <metacommand>, the relay must ignore it and process the next <command>'s;
* if the <command> is a <rlvcommand> or a <metacommand>, the relay MUST send an acknowledgement message back to the controller.
* an acknowledgement message is a <r_msg> (see above) such that
:*IDENT is the same as IDENT in the <c_msg> being processed
:*KEY is the key of the controller who sent the <c_msg>
:*<command> is the subcommand being processed
:*ACK is a string called ''acknowledgement value''. By default the acknowledgement value is "ok" if the relay will execute the <command >, "ko" otherwise;
* every acknowledgement or message sent by the relay to one given controlling device must be issued by the same prim (so that the controlling device can restrict its listener to one source key) using the LSL function [[llRegionSayTo]].

'''Remarks:'''
* Many meta-commands may have other acknowledgements than "ok" or "ko" (or none, for !pong). Their definitions supersede this specification.
* Note that unknown meta-commands cannot be executed and thus wil be acknowledged by "ko".
* Known meta-commands which are sent with not enough parameters or parameters with types incompatible with those in the definition known by the relay also cannot be executed and will also be acknowledged by "ko". (ex: the relay knows !x-who/key, but receives !x-who/integer/string).

====Command handling====
'''Requirements:'''
* If a <rlvcommand> is acknowledged with value "ok", the relay ensures the viewer is affected the same way as if the LSL instruction llOwnerSay(<rlvcommand>) was executed by a script in a primitive that handles only one controller.
* When processing a <metacommand>, if the relay knows at least one definition of '!'+METACOMMANDNAME for which the received <metacommandarguments> provide enough parameters, then it will be handled according to the definition handling the most parameters among the latter. Extra parameters are ignored.
* A relays knows the following meta-command definitions:
:*[[#Core meta-commands and associated mechanisms|definitions listed in the core requirements]]
:*all definitions included in [[LSL_Protocol/Restrained_Love_Relay/Comparison|x-tensions]] announced by the relay.
* When acknowledging a <metacommand> by anything else than "ko", the relay commits itself to execute it.

'''Remarks:'''
* For first requirement, it must be understood that the reference behavior is that the relay would have if it had one controller per prim. However handling several controllers from one unique prim is possible but requires taking care that different controllers do not interfere with each other, releasing each other's restrictions, for instance.
* For the second requirement, the word "handled" means that if the meta-command with these parameters is known, then requirements in known definition cannot be ignored. Sometimes, this can imply that the meta-command cannot be refused, for instance.

====Session related requirements:====
*Closing a session clears all RLV restrictions that belong only to that session, clears all session variables and disables all behaviors relative to that session.
*Sessions that are not locked MUST be released after a reasonable timeout.
*Relay implementations MAY require an authed session for all <rlvcommand>'s, except @xxx=<channel_number>, @clear[=xxx] and @xxx=y/rem commands, which MUST always be accepted.
*@xxx=n/add <rlvcommand>'s, after being accepted, add a restriction and therefore Lock the session.
*Some metacommands described in x-tensions can also add restrictions and therefore Lock the session.
*!release, !version, !implversion, !x-orgversions and !x-.../clear[/...] commands are always accepted.
*!pong reactivates an existing session but never requires further auth, provided it is sent by the device to which ping was sent. The relay MUST resend to the viewer all stored restrictions belonging to the controlling device if they are not already active.
*Unless specified otherwise (see !x-who), no command can trigger an interactive dialog unless
:* they require an Authed session
:* and no session is currently open or it is open but not Authed yet.
*When releasing a Locked session, a relay MUST release all restrictions belonging to the device controlling the session.
*On the following events, a relay MUST release a locked session:
:* when the relay notices the controller has become unreachable,
:* wren the relay sends "release,<controller_key>,!release,ok" (due to acknowledging !release sent by the controller, or due to safewording triggered from the relay side).
*A relay MUST provide a mechanism for checking that every controlling device is reachable. It is not specified whether this checking process should be automatic or manually triggered.
*The absence of active restriction unlocks the session (and eventually releases it).
*A relay MUST remove restrictions from a session when (and only in these cases):
:* either the session controller specifically asks for the restriction to be released ("@restriction=y" "@restriction=rem", "@clear=restriction" for RLV restrictions, and "!x-restriction/clear/..." for LSL restrictions),
:* or the session closed (for instance !release coming from the device, or safeword).

===Controller requirements===
* A controller MUST not send anything on RLVR channel that is not a valid <c_msg>.
* A controller MUST, for each Locked session it controls, provide a mechanism that will unlock it in bounded time. (i.e.: either there is a menu that will release the victim, or there is a timer, or a menu should be able to start such a timer). At least one person MUST know what this mechanism is, and if it requires an action from someone else, be able to tell that other person what s/he has to do.

==Core meta-commands and associated mechanisms==

An ORG device MUST at least support the meta-commands !release, !pong, !version, !implversion and !x-orgversions described below and implement their associated mechanisms.

Particular meta-commands definitions and mechanisms may override general requirements above.

===!release===
Sent by a controller, this command closes the session.

* !release obviously opens no session, requires no Auth and is not Locking.
* If there is an actual session to close !release MUST be accepted by the relay and acknowledeged by "ok".
* On accepting !release, the relay erases all data pertaining to the session and disables all restrictions of the session.
* When a relay decides to close a session on its own (user safeword, for instance) and it is not due to the controller being unreachable, the relay must send the following acknowledgement message:
release,<controller_key>,!release,ok

When receiving the latter message, the controller should act accordingly, for instance by resetting itself and making itself ready for the next session.

Note that !release is not the same as @clear. @clear is interpreted by the relay as a RLV command and, as such, can only clear RLV restrictions. If RLV restrictions were the only restrictions of the session, then the session will be closed, but some x-tensions also define pure LSL based restrictions.

===ping/!pong===

The ping/!pong mechanism exists so that relays can check presence and responsiveness of a controller. This was primarily meant to be used on relay wearer relog, in order to reactivate all restrictions so that sessions persist on relog if the controller still exists and is ready to continue the session.

''!pong'' cannot require auth and does not lock a session

We call ''ping message'' a message from the relay, having the following syntax:
ping,<controller_key>,ping,ping
We call ''!pong message'' a message from the controller, having the following syntax:
ping,<relay_key>,!pong

====Relay side====
*A relay SHOULD NOT send an acknowledgement in response to ''!pong''.
*A ping message can be sent any time by the relay to a known controller.
*On wearer relog, for each existing Locked session, the relay must send a ping message to the session controller.
*When a !pong message is received from a controller, if it was a reply to a previous ping message:
:#if the session RLV restrictions contain unsit and the avatar was sitting on some object when the restriction was applied, then the relay MUST force the avatar to sit back on the same object (if still existing);
:#the relay MUST make sure all restrictions belonging to the session are made active again.
*If a ping message is sent and is not answered by the controller, then the relay closes the session.

Note that the relay is responsible for storing restrictions and the key of the sit target across sessions, not the controller.

====Controller side====
*Unless it does not matter that the relay could close the session (or for another reason, the controller knows the relay will not close it), a controller SHOULD listen to ping messages and answer any ping message with a !pong message.
*A controller should ignore ping requests from relays it is not ready to handle.

Note controller don't have to poll for relay presence to resume a session but should just listen for ping messages instead. The relay should have stored all restrictions and handle sitting back to whatever furniture the relay wearer was tied up to.

Concerning the second bullet: for instance, if the controller is a furniture which is already in use by another relay wearer, it would be cause dysfunctions to let the pinging relay restore the restrictions without letting its wearer sit on the furniture. Or if the controller is not stateless and the state for the pinging relay has not been saved before, resuming the session from the initial state might be inconsistant.

===!version===
The purpose of this meta-command is to query the version of the RLVR protocol supported by a relay.

* !version opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !version with the version number of the RLVR protocol it supports ("1100" here, since ORG 0004 includes RLVR 1.100).

Note this is the most common command for a controller to scan for nearby relays, as non-ORG relays also accept this command and answer it the way described above.

===!implversion===
The purpose of this meta-command is to query the name and version of the relay implementation.

* !implversion opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !implversion with its implementation version string... which can be any string.

It is recommended this string includes the following elements:
* the relay name/brand/identifier,
* the version number of that relay name/brand/identifier,
* at the beginning, the string prefix "ORG=0004/"
The latter is convenient for checking for ORG compatibility using a command even non-ORG relay should understand.

===!x-orgversions===

This meta-command purpose it two-fold. First it allows a controlling device to ask a relay for the list of ORG x-tensions it supports and, second, similarily to !version, !x-orgversions can be used to know what version of ORG the relay complies to.

'''Example:'''
C<->R
-> query,rUUID,!x-orgversions
<- query,cUUID,!x-orgversions,ORG=0004/who=002/email=006

'''Requirements:'''
* !x-orgversions should always be accepted with no Auth required, it does not open a session or Lock one.
* The acknowledgement value in a reply to !x-orgversions is a "/"-list of items of the form <package>=<version>. The first <package> is always "ORG" (representing the core specification package of ORG relays), its version string is the version of the specification (4 digits). The other packages are ORG x-tension names, whose version string is 3 digits.
* If several incompatible versions of a same x-tension are supported, they must be listed ordered by version number. Ex: ORG=0004/who=002/email=005/email=006. If versions are backward compatible, only the last version should be reported.

'''Remarks:'''
* In a controller, it is however recommended to use !x-orgversions as soon as possible in order to avoid sending unsupported and useless metacommands later on.
* In the acknowledgement message, x-tension names are listed, not meta-command names (as one x-tension can have several meta-commands). Thus listed names do not include the prefix "!x-".

LSL Protocol/Restrained Love Open Relay Group/ORG Requirements/0004 draft

2011-06-27T13:34:28Z

Satomi Ahn: /* Reminder of the protocol syntax and related notations */

{{ORG_Restrained_Life_Relay_Specs_TOC}}
STATUS: draft

VERSION: 0004

==Summary==

This page is a list of requirements for a relay or an in-world device to have the right to be called "ORG compliant". It is mostly about adding support for an ORG-centered informational metacommand and specifying Marine Kelley's RLVR protocol a bit more that it is now, while of course preserving full compatibility.

For a quick overview of the motivations and general working of this protocol and a few examples, we refer the reader to [[LSL_Protocol/Restrained_Love_Relay/Specification|the original specification page by Marine Kelley]].

If you are making furniture, traps, or other RLVR controllers and you are not interested in what [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] can offer, then you can stick with the original specification by Marine Kelley and still be compatible with [[LSL_Protocol/Restrained_Love_Relay/Comparison|ORG relays]]. However, to have the right to call your controller "ORG compatible", there are still a few light additional requirements such as:
* using only [[llRegionSayTo]] for communications with the relay,
* not spamming the RLVR channel with messages that do not belong to the protocol,
* and remain responsive to ping messages at every time if you want the session to remain locked.

If you are interested in [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|ORG x-tensions]], then you should also read the part about [[#!x-orgversions|!x-orgversions]].

If you are making a relay, sorry we are afraid you will have to read all this page.

==Definition of an ORG device==

A RLVR device is compliant with ORG specifications if it implements the consolidated RLVR protocol described below along with the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] it announces supporting.

Note in particular that
* the consolidated protocol is backward compatible with [[LSL_Protocol/Restrained_Love_Relay/Specification|Marine Kelley's RLVR protocol version 1.100]] but resolves most loose ends of that document;
* ORG relays handle controller messages whose second field is ffffffff-ffff-ffff-ffff-ffffffffffff exactly the same as if it was the key of the wearer (NULL_KEY is a wildcard);
* one-to-one chat messages (not using a wildcard) are sent by using [[llRegionSayTo]] LSL function;
* there is an additional meta-command, !x-orgversions for a relay to announce supported x-tensions;
* each supported x-tension can imply other supported metacommands, ORG x-tensions meta-command all having names starting with prefix "!x-";
* other proprietary metacommands with prefix "!_-" (replace "_" by any letter that is not "x") can be supported;

Supported x-tensions can constrain the core specification (this document) even more, but cannot alter it or make it less constraining unless as a result of the relay executing a meta-command of this x-tension sent by the controller. Thus, although the protocol is extensible, a controller can always rely on the fact an ORG relay abides by the requirements in this document until it asks the relay to do otherwise.

ORG devices may be advertised by the use of the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/ORG_Logo|ORG logo]] for advertising compliance with ORG requirements. ORG devices makers are encouraged to do so.

==Consolidated RLVR protocol==

=== A few definitions ===

* The '''Restrained Love Relay (RLVR) protocol''' implies two partners (SL objects): the '''relay''' worn by the avatar commands are intended for, and a '''controller''', which sends commands to the relay.

* During an execution of the RLVR protocol, a relay and a controller establish a '''session''' together. A relay may manage several sessions with several controllers. Likewise, a controller could establish sessions with several relays.

* The goal of the protocol is to force the relay wearer to make perform actions and to toggle restrictions on their behavior. Both actions and restrictions can be enforced either through use of viewer hooks ([[LSL_Protocol/RestrainedLoveAPI|Restrained Love API]], or RLV) or through LSL scripting.

* Hence we distinguish between "'''RLV commands'''", starting with "@", which are commands following the syntax of the RLV API and which will ultimately be forwarded to the viewer, and "'''meta-commands'''", starting with "!", which are meant to be interpreted by LSL functions.

* Restrictions on a relay wearer are relative to a session. So are most other variables (authorization state, key of the controller, ... ).

* A session is '''Opened''' whenever the relay accepts a RLVR command from a controller.

* A session is '''Closed''' (or '''released''') as soon as the relay forgets every variables and releases all restrictions pertaining to that session.

* A session is '''Locked''' whenever it holds active restrictions.

* A session is '''Authed''' if the controller has been allowed to control the relay (not only store some variables with no consequence). Once authed, no interactive "ask" dialog should pop up anymore concerning this session. Most commands should now normally be accepted (and maybe a few automatically rejected).

* A controller is called '''reachable''' if it can receive messages from the relay and can prove it by answering ping requests from the relay. By "can", it is meant by the method of communication agreed upon by the relay and controller. By default the communication method is chat messages sent by llRegionSayTo. X-tensions such as email and delay can modify what is meant by reachable.

===Protocol syntax and related notations===

* RLVR protocol consists of messages exchanged on channel -1812221819 (called '''RLVR channel''') using the LSL function [[llRegionSayTo]].
* A controller only sends messages (commands) whose syntax is described by the non-terminal <c_msg>.
* A relay only sends messages (acknowledgements) whose syntax is described by the non-terminal <r_msg>.
* No other message should be exchanged on this channel.

<c_msg> ::= IDENT "," KEY "," <commands>
<r_msg> ::= IDENT "," KEY "," <command> "," ACK
<commands> ::= <command> | <command> "|" <commands>
<command> ::= <rlvcommand> | <metacommand>
<rlvcommand> ::= "@" RLVCOMMAND
<metacommand> ::= "!" METACOMMANDNAME <metacommandarguments>
<metacommandarguments> ::= "" | "/" ARG <metacommandarguments>

where we explicit the different terminal tokens:
IDENT: any string without ","
KEY: any UUID
ACK: any string without ","
RLVCOMMAND: any string without ","
METACOMMANDNAME: any string without "/" and ","
ARG: any string without "/" and ","

===Relay requirements===
These requirements do apply by default but the behavior of the relay may be modified as a result of having executed some metacommand defined in an optional x-tension.

====Syntactical considerations====
'''Requirements:'''
*A relay MUST NOT send anything on RLVR channel that is not a valid <r_msg>.
*A relay MUST ignore any message on RLVR channel that is not a ","-list of 3 items and whose second item is not the key of the avatar wearing the relay or ffffffff-ffff-ffff-ffff-ffffffffffff.
When the relay receives a message meeting the above conditions and considering the 3rd item of the ","-list as a "|"-list of <command>s, then for every <command>:
* if the <command> is neither a valid <rlvcommand> or <metacommand>, the relay must ignore it and process the next <command>'s;
* if the <command> is a <rlvcommand> or a <metacommand>, the relay MUST send an acknowledgement message back to the controller.
* an acknowledgement message is a <r_msg> (see above) such that
:*IDENT is the same as IDENT in the <c_msg> being processed
:*KEY is the key of the controller who sent the <c_msg>
:*<command> is the subcommand being processed
:*ACK is a string called ''acknowledgement value''. By default the acknowledgement value is "ok" if the relay will execute the <command >, "ko" otherwise;
* every acknowledgement or message sent by the relay to one given controlling device must be issued by the same prim (so that the controlling device can restrict its listener to one source key) using the LSL function [[llRegionSayTo]].

'''Remarks:'''
* Many meta-commands may have other acknowledgements than "ok" or "ko" (or none, for !pong). Their definitions supersede this specification.
* Note that unknown meta-commands cannot be executed and thus wil be acknowledged by "ko".
* Known meta-commands which are sent with not enough parameters or parameters with types incompatible with those in the definition known by the relay also cannot be executed and will also be acknowledged by "ko". (ex: the relay knows !x-who/key, but receives !x-who/integer/string).

====Command handling====
'''Requirements:'''
* If a <rlvcommand> is acknowledged with value "ok", the relay ensures the viewer is affected the same way as if the LSL instruction llOwnerSay(<rlvcommand>) was executed by a script in a primitive that handles only one controller.
* When processing a <metacommand>, if the relay knows at least one definition of '!'+METACOMMANDNAME for which the received <metacommandarguments> provide enough parameters, then it will be handled according to the definition handling the most parameters among the latter. Extra parameters are ignored.
* A relays knows the following meta-command definitions:
:*[[#Core meta-commands and associated mechanisms|definitions listed in the core requirements]]
:*all definitions included in [[LSL_Protocol/Restrained_Love_Relay/Comparison|x-tensions]] announced by the relay.
* When acknowledging a <metacommand> by anything else than "ko", the relay commits itself to execute it.

'''Remarks:'''
* For first requirement, it must be understood that the reference behavior is that the relay would have if it had one controller per prim. However handling several controllers from one unique prim is possible but requires taking care that different controllers do not interfere with each other, releasing each other's restrictions, for instance.
* For the second requirement, the word "handled" means that if the meta-command with these parameters is known, then requirements in known definition cannot be ignored. Sometimes, this can imply that the meta-command cannot be refused, for instance.

====Session related requirements:====
*Closing a session clears all RLV restrictions that belong only to that session, clears all session variables and disables all behaviors relative to that session.
*Sessions that are not locked MUST be released after a reasonable timeout.
*Relay implementations MAY require an authed session for all <rlvcommand>'s, except @xxx=<channel_number>, @clear[=xxx] and @xxx=y/rem commands, which MUST always be accepted.
*@xxx=n/add <rlvcommand>'s, after being accepted, add a restriction and therefore Lock the session.
*Some metacommands described in x-tensions can also add restrictions and therefore Lock the session.
*!release, !version, !implversion, !x-orgversions and !x-.../clear[/...] commands are always accepted.
*!pong reactivates an existing session but never requires further auth, provided it is sent by the device to which ping was sent. The relay MUST resend to the viewer all stored restrictions belonging to the controlling device if they are not already active.
*Unless specified otherwise (see !x-who), no command can trigger an interactive dialog unless
:* they require an Authed session
:* and no session is currently open or it is open but not Authed yet.
*When releasing a Locked session, a relay MUST release all restrictions belonging to the device controlling the session.
*On the following events, a relay MUST release a locked session:
:* when the relay notices the controller has become unreachable,
:* wren the relay sends "release,<controller_key>,!release,ok" (due to acknowledging !release sent by the controller, or due to safewording triggered from the relay side).
*A relay MUST provide a mechanism for checking that every controlling device is reachable. It is not specified whether this checking process should be automatic or manually triggered.
*The absence of active restriction unlocks the session (and eventually releases it).
*A relay MUST remove restrictions from a session when (and only in these cases):
:* either the session controller specifically asks for the restriction to be released ("@restriction=y" "@restriction=rem", "@clear=restriction" for RLV restrictions, and "!x-restriction/clear/..." for LSL restrictions),
:* or the session closed (for instance !release coming from the device, or safeword).

===Controller requirements===
* A controller MUST not send anything on RLVR channel that is not a valid <c_msg>.
* A controller MUST, for each Locked session it controls, provide a mechanism that will unlock it in bounded time. (i.e.: either there is a menu that will release the victim, or there is a timer, or a menu should be able to start such a timer). At least one person MUST know what this mechanism is, and if it requires an action from someone else, be able to tell that other person what s/he has to do.

==Core meta-commands and associated mechanisms==

An ORG device MUST at least support the meta-commands !release, !pong, !version, !implversion and !x-orgversions described below and implement their associated mechanisms.

Particular meta-commands definitions and mechanisms may override general requirements above.

===!release===
Sent by a controller, this command closes the session.

* !release obviously opens no session, requires no Auth and is not Locking.
* If there is an actual session to close !release MUST be accepted by the relay and acknowledeged by "ok".
* On accepting !release, the relay erases all data pertaining to the session and disables all restrictions of the session.
* When a relay decides to close a session on its own (user safeword, for instance) and it is not due to the controller being unreachable, the relay must send the following acknowledgement message:
release,<controller_key>,!release,ok

When receiving the latter message, the controller should act accordingly, for instance by resetting itself and making itself ready for the next session.

Note that !release is not the same as @clear. @clear is interpreted by the relay as a RLV command and, as such, can only clear RLV restrictions. If RLV restrictions were the only restrictions of the session, then the session will be closed, but some x-tensions also define pure LSL based restrictions.

===ping/!pong===

The ping/!pong mechanism exists so that relays can check presence and responsiveness of a controller. This was primarily meant to be used on relay wearer relog, in order to reactivate all restrictions so that sessions persist on relog if the controller still exists and is ready to continue the session.

''!pong'' cannot require auth and does not lock a session

We call ''ping message'' a message from the relay, having the following syntax:
ping,<controller_key>,ping,ping
We call ''!pong message'' a message from the controller, having the following syntax:
ping,<relay_key>,!pong

====Relay side====
*A relay SHOULD NOT send an acknowledgement in response to ''!pong''.
*A ping message can be sent any time by the relay to a known controller.
*On wearer relog, for each existing Locked session, the relay must send a ping message to the session controller.
*When a !pong message is received from a controller, if it was a reply to a previous ping message:
:#if the session RLV restrictions contain unsit and the avatar was sitting on some object when the restriction was applied, then the relay MUST force the avatar to sit back on the same object (if still existing);
:#the relay MUST make sure all restrictions belonging to the session are made active again.
*If a ping message is sent and is not answered by the controller, then the relay closes the session.

Note that the relay is responsible for storing restrictions and the key of the sit target across sessions, not the controller.

====Controller side====
*Unless it does not matter that the relay could close the session (or for another reason, the controller knows the relay will not close it), a controller SHOULD listen to ping messages and answer any ping message with a !pong message.
*A controller should ignore ping requests from relays it is not ready to handle.

Note controller don't have to poll for relay presence to resume a session but should just listen for ping messages instead. The relay should have stored all restrictions and handle sitting back to whatever furniture the relay wearer was tied up to.

Concerning the second bullet: for instance, if the controller is a furniture which is already in use by another relay wearer, it would be cause dysfunctions to let the pinging relay restore the restrictions without letting its wearer sit on the furniture. Or if the controller is not stateless and the state for the pinging relay has not been saved before, resuming the session from the initial state might be inconsistant.

===!version===
The purpose of this meta-command is to query the version of the RLVR protocol supported by a relay.

* !version opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !version with the version number of the RLVR protocol it supports ("1100" here, since ORG 0004 includes RLVR 1.100).

Note this is the most common command for a controller to scan for nearby relays, as non-ORG relays also accept this command and answer it the way described above.

===!implversion===
The purpose of this meta-command is to query the name and version of the relay implementation.

* !implversion opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !implversion with its implementation version string... which can be any string.

It is recommended this string includes the following elements:
* the relay name/brand/identifier,
* the version number of that relay name/brand/identifier,
* at the beginning, the string prefix "ORG=0004/"
The latter is convenient for checking for ORG compatibility using a command even non-ORG relay should understand.

===!x-orgversions===

This meta-command purpose it two-fold. First it allows a controlling device to ask a relay for the list of ORG x-tensions it supports and, second, similarily to !version, !x-orgversions can be used to know what version of ORG the relay complies to.

'''Example:'''
C<->R
-> query,rUUID,!x-orgversions
<- query,cUUID,!x-orgversions,ORG=0004/who=002/email=006

'''Requirements:'''
* !x-orgversions should always be accepted with no Auth required, it does not open a session or Lock one.
* The acknowledgement value in a reply to !x-orgversions is a "/"-list of items of the form <package>=<version>. The first <package> is always "ORG" (representing the core specification package of ORG relays), its version string is the version of the specification (4 digits). The other packages are ORG x-tension names, whose version string is 3 digits.
* If several incompatible versions of a same x-tension are supported, they must be listed ordered by version number. Ex: ORG=0004/who=002/email=005/email=006. If versions are backward compatible, only the last version should be reported.

'''Remarks:'''
* In a controller, it is however recommended to use !x-orgversions as soon as possible in order to avoid sending unsupported and useless metacommands later on.
* In the acknowledgement message, x-tension names are listed, not meta-command names (as one x-tension can have several meta-commands). Thus listed names do not include the prefix "!x-".

LSL Protocol/Restrained Love Open Relay Group/ORG Requirements/0004 draft

2011-06-27T13:32:10Z

Satomi Ahn: /* Command handling */

{{ORG_Restrained_Life_Relay_Specs_TOC}}
STATUS: draft

VERSION: 0004

==Summary==

This page is a list of requirements for a relay or an in-world device to have the right to be called "ORG compliant". It is mostly about adding support for an ORG-centered informational metacommand and specifying Marine Kelley's RLVR protocol a bit more that it is now, while of course preserving full compatibility.

For a quick overview of the motivations and general working of this protocol and a few examples, we refer the reader to [[LSL_Protocol/Restrained_Love_Relay/Specification|the original specification page by Marine Kelley]].

If you are making furniture, traps, or other RLVR controllers and you are not interested in what [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] can offer, then you can stick with the original specification by Marine Kelley and still be compatible with [[LSL_Protocol/Restrained_Love_Relay/Comparison|ORG relays]]. However, to have the right to call your controller "ORG compatible", there are still a few light additional requirements such as:
* using only [[llRegionSayTo]] for communications with the relay,
* not spamming the RLVR channel with messages that do not belong to the protocol,
* and remain responsive to ping messages at every time if you want the session to remain locked.

If you are interested in [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|ORG x-tensions]], then you should also read the part about [[#!x-orgversions|!x-orgversions]].

If you are making a relay, sorry we are afraid you will have to read all this page.

==Definition of an ORG device==

A RLVR device is compliant with ORG specifications if it implements the consolidated RLVR protocol described below along with the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] it announces supporting.

Note in particular that
* the consolidated protocol is backward compatible with [[LSL_Protocol/Restrained_Love_Relay/Specification|Marine Kelley's RLVR protocol version 1.100]] but resolves most loose ends of that document;
* ORG relays handle controller messages whose second field is ffffffff-ffff-ffff-ffff-ffffffffffff exactly the same as if it was the key of the wearer (NULL_KEY is a wildcard);
* one-to-one chat messages (not using a wildcard) are sent by using [[llRegionSayTo]] LSL function;
* there is an additional meta-command, !x-orgversions for a relay to announce supported x-tensions;
* each supported x-tension can imply other supported metacommands, ORG x-tensions meta-command all having names starting with prefix "!x-";
* other proprietary metacommands with prefix "!_-" (replace "_" by any letter that is not "x") can be supported;

Supported x-tensions can constrain the core specification (this document) even more, but cannot alter it or make it less constraining unless as a result of the relay executing a meta-command of this x-tension sent by the controller. Thus, although the protocol is extensible, a controller can always rely on the fact an ORG relay abides by the requirements in this document until it asks the relay to do otherwise.

ORG devices may be advertised by the use of the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/ORG_Logo|ORG logo]] for advertising compliance with ORG requirements. ORG devices makers are encouraged to do so.

==Consolidated RLVR protocol==

=== A few definitions ===

* The '''Restrained Love Relay (RLVR) protocol''' implies two partners (SL objects): the '''relay''' worn by the avatar commands are intended for, and a '''controller''', which sends commands to the relay.

* During an execution of the RLVR protocol, a relay and a controller establish a '''session''' together. A relay may manage several sessions with several controllers. Likewise, a controller could establish sessions with several relays.

* The goal of the protocol is to force the relay wearer to make perform actions and to toggle restrictions on their behavior. Both actions and restrictions can be enforced either through use of viewer hooks ([[LSL_Protocol/RestrainedLoveAPI|Restrained Love API]], or RLV) or through LSL scripting.

* Hence we distinguish between "'''RLV commands'''", starting with "@", which are commands following the syntax of the RLV API and which will ultimately be forwarded to the viewer, and "'''meta-commands'''", starting with "!", which are meant to be interpreted by LSL functions.

* Restrictions on a relay wearer are relative to a session. So are most other variables (authorization state, key of the controller, ... ).

* A session is '''Opened''' whenever the relay accepts a RLVR command from a controller.

* A session is '''Closed''' (or '''released''') as soon as the relay forgets every variables and releases all restrictions pertaining to that session.

* A session is '''Locked''' whenever it holds active restrictions.

* A session is '''Authed''' if the controller has been allowed to control the relay (not only store some variables with no consequence). Once authed, no interactive "ask" dialog should pop up anymore concerning this session. Most commands should now normally be accepted (and maybe a few automatically rejected).

* A controller is called '''reachable''' if it can receive messages from the relay and can prove it by answering ping requests from the relay. By "can", it is meant by the method of communication agreed upon by the relay and controller. By default the communication method is chat messages sent by llRegionSayTo. X-tensions such as email and delay can modify what is meant by reachable.

===Reminder of the protocol syntax and related notations===

RLVR protocol consists of messages exchanged on channel -1812221819 (called '''RLVR channel''') using the LSL function [[llRegionSayTo]].

A controller only sends messages (commands) whose syntax is described by the non-terminal <c_msg>. A relay only sends messages (acknowledgements) whose syntax is described by the non-terminal <r_msg>.

<c_msg> ::= IDENT "," KEY "," <commands>
<r_msg> ::= IDENT "," KEY "," <command> "," ACK
<commands> ::= <command> | <command> "|" <commands>
<command> ::= <rlvcommand> | <metacommand>
<rlvcommand> ::= "@" RLVCOMMAND
<metacommand> ::= "!" METACOMMANDNAME <metacommandarguments>
<metacommandarguments> ::= "" | "/" ARG <metacommandarguments>

where we explicit the different terminal tokens:
IDENT: any string without ","
KEY: any UUID
ACK: any string without ","
RLVCOMMAND: any string without ","
METACOMMANDNAME: any string without "/" and ","
ARG: any string without "/" and ","

===Relay requirements===
These requirements do apply by default but the behavior of the relay may be modified as a result of having executed some metacommand defined in an optional x-tension.

====Syntactical considerations====
'''Requirements:'''
*A relay MUST NOT send anything on RLVR channel that is not a valid <r_msg>.
*A relay MUST ignore any message on RLVR channel that is not a ","-list of 3 items and whose second item is not the key of the avatar wearing the relay or ffffffff-ffff-ffff-ffff-ffffffffffff.
When the relay receives a message meeting the above conditions and considering the 3rd item of the ","-list as a "|"-list of <command>s, then for every <command>:
* if the <command> is neither a valid <rlvcommand> or <metacommand>, the relay must ignore it and process the next <command>'s;
* if the <command> is a <rlvcommand> or a <metacommand>, the relay MUST send an acknowledgement message back to the controller.
* an acknowledgement message is a <r_msg> (see above) such that
:*IDENT is the same as IDENT in the <c_msg> being processed
:*KEY is the key of the controller who sent the <c_msg>
:*<command> is the subcommand being processed
:*ACK is a string called ''acknowledgement value''. By default the acknowledgement value is "ok" if the relay will execute the <command >, "ko" otherwise;
* every acknowledgement or message sent by the relay to one given controlling device must be issued by the same prim (so that the controlling device can restrict its listener to one source key) using the LSL function [[llRegionSayTo]].

'''Remarks:'''
* Many meta-commands may have other acknowledgements than "ok" or "ko" (or none, for !pong). Their definitions supersede this specification.
* Note that unknown meta-commands cannot be executed and thus wil be acknowledged by "ko".
* Known meta-commands which are sent with not enough parameters or parameters with types incompatible with those in the definition known by the relay also cannot be executed and will also be acknowledged by "ko". (ex: the relay knows !x-who/key, but receives !x-who/integer/string).

====Command handling====
'''Requirements:'''
* If a <rlvcommand> is acknowledged with value "ok", the relay ensures the viewer is affected the same way as if the LSL instruction llOwnerSay(<rlvcommand>) was executed by a script in a primitive that handles only one controller.
* When processing a <metacommand>, if the relay knows at least one definition of '!'+METACOMMANDNAME for which the received <metacommandarguments> provide enough parameters, then it will be handled according to the definition handling the most parameters among the latter. Extra parameters are ignored.
* A relays knows the following meta-command definitions:
:*[[#Core meta-commands and associated mechanisms|definitions listed in the core requirements]]
:*all definitions included in [[LSL_Protocol/Restrained_Love_Relay/Comparison|x-tensions]] announced by the relay.
* When acknowledging a <metacommand> by anything else than "ko", the relay commits itself to execute it.

'''Remarks:'''
* For first requirement, it must be understood that the reference behavior is that the relay would have if it had one controller per prim. However handling several controllers from one unique prim is possible but requires taking care that different controllers do not interfere with each other, releasing each other's restrictions, for instance.
* For the second requirement, the word "handled" means that if the meta-command with these parameters is known, then requirements in known definition cannot be ignored. Sometimes, this can imply that the meta-command cannot be refused, for instance.

====Session related requirements:====
*Closing a session clears all RLV restrictions that belong only to that session, clears all session variables and disables all behaviors relative to that session.
*Sessions that are not locked MUST be released after a reasonable timeout.
*Relay implementations MAY require an authed session for all <rlvcommand>'s, except @xxx=<channel_number>, @clear[=xxx] and @xxx=y/rem commands, which MUST always be accepted.
*@xxx=n/add <rlvcommand>'s, after being accepted, add a restriction and therefore Lock the session.
*Some metacommands described in x-tensions can also add restrictions and therefore Lock the session.
*!release, !version, !implversion, !x-orgversions and !x-.../clear[/...] commands are always accepted.
*!pong reactivates an existing session but never requires further auth, provided it is sent by the device to which ping was sent. The relay MUST resend to the viewer all stored restrictions belonging to the controlling device if they are not already active.
*Unless specified otherwise (see !x-who), no command can trigger an interactive dialog unless
:* they require an Authed session
:* and no session is currently open or it is open but not Authed yet.
*When releasing a Locked session, a relay MUST release all restrictions belonging to the device controlling the session.
*On the following events, a relay MUST release a locked session:
:* when the relay notices the controller has become unreachable,
:* wren the relay sends "release,<controller_key>,!release,ok" (due to acknowledging !release sent by the controller, or due to safewording triggered from the relay side).
*A relay MUST provide a mechanism for checking that every controlling device is reachable. It is not specified whether this checking process should be automatic or manually triggered.
*The absence of active restriction unlocks the session (and eventually releases it).
*A relay MUST remove restrictions from a session when (and only in these cases):
:* either the session controller specifically asks for the restriction to be released ("@restriction=y" "@restriction=rem", "@clear=restriction" for RLV restrictions, and "!x-restriction/clear/..." for LSL restrictions),
:* or the session closed (for instance !release coming from the device, or safeword).

===Controller requirements===
* A controller MUST not send anything on RLVR channel that is not a valid <c_msg>.
* A controller MUST, for each Locked session it controls, provide a mechanism that will unlock it in bounded time. (i.e.: either there is a menu that will release the victim, or there is a timer, or a menu should be able to start such a timer). At least one person MUST know what this mechanism is, and if it requires an action from someone else, be able to tell that other person what s/he has to do.

==Core meta-commands and associated mechanisms==

An ORG device MUST at least support the meta-commands !release, !pong, !version, !implversion and !x-orgversions described below and implement their associated mechanisms.

Particular meta-commands definitions and mechanisms may override general requirements above.

===!release===
Sent by a controller, this command closes the session.

* !release obviously opens no session, requires no Auth and is not Locking.
* If there is an actual session to close !release MUST be accepted by the relay and acknowledeged by "ok".
* On accepting !release, the relay erases all data pertaining to the session and disables all restrictions of the session.
* When a relay decides to close a session on its own (user safeword, for instance) and it is not due to the controller being unreachable, the relay must send the following acknowledgement message:
release,<controller_key>,!release,ok

When receiving the latter message, the controller should act accordingly, for instance by resetting itself and making itself ready for the next session.

Note that !release is not the same as @clear. @clear is interpreted by the relay as a RLV command and, as such, can only clear RLV restrictions. If RLV restrictions were the only restrictions of the session, then the session will be closed, but some x-tensions also define pure LSL based restrictions.

===ping/!pong===

The ping/!pong mechanism exists so that relays can check presence and responsiveness of a controller. This was primarily meant to be used on relay wearer relog, in order to reactivate all restrictions so that sessions persist on relog if the controller still exists and is ready to continue the session.

''!pong'' cannot require auth and does not lock a session

We call ''ping message'' a message from the relay, having the following syntax:
ping,<controller_key>,ping,ping
We call ''!pong message'' a message from the controller, having the following syntax:
ping,<relay_key>,!pong

====Relay side====
*A relay SHOULD NOT send an acknowledgement in response to ''!pong''.
*A ping message can be sent any time by the relay to a known controller.
*On wearer relog, for each existing Locked session, the relay must send a ping message to the session controller.
*When a !pong message is received from a controller, if it was a reply to a previous ping message:
:#if the session RLV restrictions contain unsit and the avatar was sitting on some object when the restriction was applied, then the relay MUST force the avatar to sit back on the same object (if still existing);
:#the relay MUST make sure all restrictions belonging to the session are made active again.
*If a ping message is sent and is not answered by the controller, then the relay closes the session.

Note that the relay is responsible for storing restrictions and the key of the sit target across sessions, not the controller.

====Controller side====
*Unless it does not matter that the relay could close the session (or for another reason, the controller knows the relay will not close it), a controller SHOULD listen to ping messages and answer any ping message with a !pong message.
*A controller should ignore ping requests from relays it is not ready to handle.

Note controller don't have to poll for relay presence to resume a session but should just listen for ping messages instead. The relay should have stored all restrictions and handle sitting back to whatever furniture the relay wearer was tied up to.

Concerning the second bullet: for instance, if the controller is a furniture which is already in use by another relay wearer, it would be cause dysfunctions to let the pinging relay restore the restrictions without letting its wearer sit on the furniture. Or if the controller is not stateless and the state for the pinging relay has not been saved before, resuming the session from the initial state might be inconsistant.

===!version===
The purpose of this meta-command is to query the version of the RLVR protocol supported by a relay.

* !version opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !version with the version number of the RLVR protocol it supports ("1100" here, since ORG 0004 includes RLVR 1.100).

Note this is the most common command for a controller to scan for nearby relays, as non-ORG relays also accept this command and answer it the way described above.

===!implversion===
The purpose of this meta-command is to query the name and version of the relay implementation.

* !implversion opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !implversion with its implementation version string... which can be any string.

It is recommended this string includes the following elements:
* the relay name/brand/identifier,
* the version number of that relay name/brand/identifier,
* at the beginning, the string prefix "ORG=0004/"
The latter is convenient for checking for ORG compatibility using a command even non-ORG relay should understand.

===!x-orgversions===

This meta-command purpose it two-fold. First it allows a controlling device to ask a relay for the list of ORG x-tensions it supports and, second, similarily to !version, !x-orgversions can be used to know what version of ORG the relay complies to.

'''Example:'''
C<->R
-> query,rUUID,!x-orgversions
<- query,cUUID,!x-orgversions,ORG=0004/who=002/email=006

'''Requirements:'''
* !x-orgversions should always be accepted with no Auth required, it does not open a session or Lock one.
* The acknowledgement value in a reply to !x-orgversions is a "/"-list of items of the form <package>=<version>. The first <package> is always "ORG" (representing the core specification package of ORG relays), its version string is the version of the specification (4 digits). The other packages are ORG x-tension names, whose version string is 3 digits.
* If several incompatible versions of a same x-tension are supported, they must be listed ordered by version number. Ex: ORG=0004/who=002/email=005/email=006. If versions are backward compatible, only the last version should be reported.

'''Remarks:'''
* In a controller, it is however recommended to use !x-orgversions as soon as possible in order to avoid sending unsupported and useless metacommands later on.
* In the acknowledgement message, x-tension names are listed, not meta-command names (as one x-tension can have several meta-commands). Thus listed names do not include the prefix "!x-".

LSL Protocol/Restrained Love Open Relay Group/ORG Requirements/0004 draft

2011-06-27T13:31:05Z

Satomi Ahn: /* Command handling */

{{ORG_Restrained_Life_Relay_Specs_TOC}}
STATUS: draft

VERSION: 0004

==Summary==

This page is a list of requirements for a relay or an in-world device to have the right to be called "ORG compliant". It is mostly about adding support for an ORG-centered informational metacommand and specifying Marine Kelley's RLVR protocol a bit more that it is now, while of course preserving full compatibility.

For a quick overview of the motivations and general working of this protocol and a few examples, we refer the reader to [[LSL_Protocol/Restrained_Love_Relay/Specification|the original specification page by Marine Kelley]].

If you are making furniture, traps, or other RLVR controllers and you are not interested in what [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] can offer, then you can stick with the original specification by Marine Kelley and still be compatible with [[LSL_Protocol/Restrained_Love_Relay/Comparison|ORG relays]]. However, to have the right to call your controller "ORG compatible", there are still a few light additional requirements such as:
* using only [[llRegionSayTo]] for communications with the relay,
* not spamming the RLVR channel with messages that do not belong to the protocol,
* and remain responsive to ping messages at every time if you want the session to remain locked.

If you are interested in [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|ORG x-tensions]], then you should also read the part about [[#!x-orgversions|!x-orgversions]].

If you are making a relay, sorry we are afraid you will have to read all this page.

==Definition of an ORG device==

A RLVR device is compliant with ORG specifications if it implements the consolidated RLVR protocol described below along with the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] it announces supporting.

Note in particular that
* the consolidated protocol is backward compatible with [[LSL_Protocol/Restrained_Love_Relay/Specification|Marine Kelley's RLVR protocol version 1.100]] but resolves most loose ends of that document;
* ORG relays handle controller messages whose second field is ffffffff-ffff-ffff-ffff-ffffffffffff exactly the same as if it was the key of the wearer (NULL_KEY is a wildcard);
* one-to-one chat messages (not using a wildcard) are sent by using [[llRegionSayTo]] LSL function;
* there is an additional meta-command, !x-orgversions for a relay to announce supported x-tensions;
* each supported x-tension can imply other supported metacommands, ORG x-tensions meta-command all having names starting with prefix "!x-";
* other proprietary metacommands with prefix "!_-" (replace "_" by any letter that is not "x") can be supported;

Supported x-tensions can constrain the core specification (this document) even more, but cannot alter it or make it less constraining unless as a result of the relay executing a meta-command of this x-tension sent by the controller. Thus, although the protocol is extensible, a controller can always rely on the fact an ORG relay abides by the requirements in this document until it asks the relay to do otherwise.

ORG devices may be advertised by the use of the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/ORG_Logo|ORG logo]] for advertising compliance with ORG requirements. ORG devices makers are encouraged to do so.

==Consolidated RLVR protocol==

=== A few definitions ===

* The '''Restrained Love Relay (RLVR) protocol''' implies two partners (SL objects): the '''relay''' worn by the avatar commands are intended for, and a '''controller''', which sends commands to the relay.

* During an execution of the RLVR protocol, a relay and a controller establish a '''session''' together. A relay may manage several sessions with several controllers. Likewise, a controller could establish sessions with several relays.

* The goal of the protocol is to force the relay wearer to make perform actions and to toggle restrictions on their behavior. Both actions and restrictions can be enforced either through use of viewer hooks ([[LSL_Protocol/RestrainedLoveAPI|Restrained Love API]], or RLV) or through LSL scripting.

* Hence we distinguish between "'''RLV commands'''", starting with "@", which are commands following the syntax of the RLV API and which will ultimately be forwarded to the viewer, and "'''meta-commands'''", starting with "!", which are meant to be interpreted by LSL functions.

* Restrictions on a relay wearer are relative to a session. So are most other variables (authorization state, key of the controller, ... ).

* A session is '''Opened''' whenever the relay accepts a RLVR command from a controller.

* A session is '''Closed''' (or '''released''') as soon as the relay forgets every variables and releases all restrictions pertaining to that session.

* A session is '''Locked''' whenever it holds active restrictions.

* A session is '''Authed''' if the controller has been allowed to control the relay (not only store some variables with no consequence). Once authed, no interactive "ask" dialog should pop up anymore concerning this session. Most commands should now normally be accepted (and maybe a few automatically rejected).

* A controller is called '''reachable''' if it can receive messages from the relay and can prove it by answering ping requests from the relay. By "can", it is meant by the method of communication agreed upon by the relay and controller. By default the communication method is chat messages sent by llRegionSayTo. X-tensions such as email and delay can modify what is meant by reachable.

===Reminder of the protocol syntax and related notations===

RLVR protocol consists of messages exchanged on channel -1812221819 (called '''RLVR channel''') using the LSL function [[llRegionSayTo]].

A controller only sends messages (commands) whose syntax is described by the non-terminal <c_msg>. A relay only sends messages (acknowledgements) whose syntax is described by the non-terminal <r_msg>.

<c_msg> ::= IDENT "," KEY "," <commands>
<r_msg> ::= IDENT "," KEY "," <command> "," ACK
<commands> ::= <command> | <command> "|" <commands>
<command> ::= <rlvcommand> | <metacommand>
<rlvcommand> ::= "@" RLVCOMMAND
<metacommand> ::= "!" METACOMMANDNAME <metacommandarguments>
<metacommandarguments> ::= "" | "/" ARG <metacommandarguments>

where we explicit the different terminal tokens:
IDENT: any string without ","
KEY: any UUID
ACK: any string without ","
RLVCOMMAND: any string without ","
METACOMMANDNAME: any string without "/" and ","
ARG: any string without "/" and ","

===Relay requirements===
These requirements do apply by default but the behavior of the relay may be modified as a result of having executed some metacommand defined in an optional x-tension.

====Syntactical considerations====
'''Requirements:'''
*A relay MUST NOT send anything on RLVR channel that is not a valid <r_msg>.
*A relay MUST ignore any message on RLVR channel that is not a ","-list of 3 items and whose second item is not the key of the avatar wearing the relay or ffffffff-ffff-ffff-ffff-ffffffffffff.
When the relay receives a message meeting the above conditions and considering the 3rd item of the ","-list as a "|"-list of <command>s, then for every <command>:
* if the <command> is neither a valid <rlvcommand> or <metacommand>, the relay must ignore it and process the next <command>'s;
* if the <command> is a <rlvcommand> or a <metacommand>, the relay MUST send an acknowledgement message back to the controller.
* an acknowledgement message is a <r_msg> (see above) such that
:*IDENT is the same as IDENT in the <c_msg> being processed
:*KEY is the key of the controller who sent the <c_msg>
:*<command> is the subcommand being processed
:*ACK is a string called ''acknowledgement value''. By default the acknowledgement value is "ok" if the relay will execute the <command >, "ko" otherwise;
* every acknowledgement or message sent by the relay to one given controlling device must be issued by the same prim (so that the controlling device can restrict its listener to one source key) using the LSL function [[llRegionSayTo]].

'''Remarks:'''
* Many meta-commands may have other acknowledgements than "ok" or "ko" (or none, for !pong). Their definitions supersede this specification.
* Note that unknown meta-commands cannot be executed and thus wil be acknowledged by "ko".
* Known meta-commands which are sent with not enough parameters or parameters with types incompatible with those in the definition known by the relay also cannot be executed and will also be acknowledged by "ko". (ex: the relay knows !x-who/key, but receives !x-who/integer/string).

====Command handling====
'''Requirements:'''
* If a <rlvcommand> is acknowledged with value "ok", the relay ensures the viewer is affected the same way as if the LSL instruction llOwnerSay(<rlvcommand>) was executed by a script in a primitive that handles only one controller.
* When processing a <metacommand>, if the relay knows at least one definition of '!'+METACOMMANDNAME for which the received <metacommandarguments> provide enough parameters, then it will be handled according to the definition handling the most parameters among the latter. Extra parameters are ignored.
* A relays knows the following meta-command definitions:
:*[[#Core meta-commands and associated mechanisms|definitions listed in the core requirements]]
:*all definitions included in x-tensions announced by the relay.
* When acknowledging a <metacommand> by anything else than "ko", the relay commits itself to execute it.

'''Remarks:'''
* For first requirement, it must be understood that the reference behavior is that the relay would have if it had one controller per prim. However handling several controllers from one unique prim is possible but requires taking care that different controllers do not interfere with each other, releasing each other's restrictions, for instance.
* For the second requirement, the word "handled" means that if the meta-command with these parameters is known, then requirements in known definition cannot be ignored. Sometimes, this can imply that the meta-command cannot be refused, for instance.

====Session related requirements:====
*Closing a session clears all RLV restrictions that belong only to that session, clears all session variables and disables all behaviors relative to that session.
*Sessions that are not locked MUST be released after a reasonable timeout.
*Relay implementations MAY require an authed session for all <rlvcommand>'s, except @xxx=<channel_number>, @clear[=xxx] and @xxx=y/rem commands, which MUST always be accepted.
*@xxx=n/add <rlvcommand>'s, after being accepted, add a restriction and therefore Lock the session.
*Some metacommands described in x-tensions can also add restrictions and therefore Lock the session.
*!release, !version, !implversion, !x-orgversions and !x-.../clear[/...] commands are always accepted.
*!pong reactivates an existing session but never requires further auth, provided it is sent by the device to which ping was sent. The relay MUST resend to the viewer all stored restrictions belonging to the controlling device if they are not already active.
*Unless specified otherwise (see !x-who), no command can trigger an interactive dialog unless
:* they require an Authed session
:* and no session is currently open or it is open but not Authed yet.
*When releasing a Locked session, a relay MUST release all restrictions belonging to the device controlling the session.
*On the following events, a relay MUST release a locked session:
:* when the relay notices the controller has become unreachable,
:* wren the relay sends "release,<controller_key>,!release,ok" (due to acknowledging !release sent by the controller, or due to safewording triggered from the relay side).
*A relay MUST provide a mechanism for checking that every controlling device is reachable. It is not specified whether this checking process should be automatic or manually triggered.
*The absence of active restriction unlocks the session (and eventually releases it).
*A relay MUST remove restrictions from a session when (and only in these cases):
:* either the session controller specifically asks for the restriction to be released ("@restriction=y" "@restriction=rem", "@clear=restriction" for RLV restrictions, and "!x-restriction/clear/..." for LSL restrictions),
:* or the session closed (for instance !release coming from the device, or safeword).

===Controller requirements===
* A controller MUST not send anything on RLVR channel that is not a valid <c_msg>.
* A controller MUST, for each Locked session it controls, provide a mechanism that will unlock it in bounded time. (i.e.: either there is a menu that will release the victim, or there is a timer, or a menu should be able to start such a timer). At least one person MUST know what this mechanism is, and if it requires an action from someone else, be able to tell that other person what s/he has to do.

==Core meta-commands and associated mechanisms==

An ORG device MUST at least support the meta-commands !release, !pong, !version, !implversion and !x-orgversions described below and implement their associated mechanisms.

Particular meta-commands definitions and mechanisms may override general requirements above.

===!release===
Sent by a controller, this command closes the session.

* !release obviously opens no session, requires no Auth and is not Locking.
* If there is an actual session to close !release MUST be accepted by the relay and acknowledeged by "ok".
* On accepting !release, the relay erases all data pertaining to the session and disables all restrictions of the session.
* When a relay decides to close a session on its own (user safeword, for instance) and it is not due to the controller being unreachable, the relay must send the following acknowledgement message:
release,<controller_key>,!release,ok

When receiving the latter message, the controller should act accordingly, for instance by resetting itself and making itself ready for the next session.

Note that !release is not the same as @clear. @clear is interpreted by the relay as a RLV command and, as such, can only clear RLV restrictions. If RLV restrictions were the only restrictions of the session, then the session will be closed, but some x-tensions also define pure LSL based restrictions.

===ping/!pong===

The ping/!pong mechanism exists so that relays can check presence and responsiveness of a controller. This was primarily meant to be used on relay wearer relog, in order to reactivate all restrictions so that sessions persist on relog if the controller still exists and is ready to continue the session.

''!pong'' cannot require auth and does not lock a session

We call ''ping message'' a message from the relay, having the following syntax:
ping,<controller_key>,ping,ping
We call ''!pong message'' a message from the controller, having the following syntax:
ping,<relay_key>,!pong

====Relay side====
*A relay SHOULD NOT send an acknowledgement in response to ''!pong''.
*A ping message can be sent any time by the relay to a known controller.
*On wearer relog, for each existing Locked session, the relay must send a ping message to the session controller.
*When a !pong message is received from a controller, if it was a reply to a previous ping message:
:#if the session RLV restrictions contain unsit and the avatar was sitting on some object when the restriction was applied, then the relay MUST force the avatar to sit back on the same object (if still existing);
:#the relay MUST make sure all restrictions belonging to the session are made active again.
*If a ping message is sent and is not answered by the controller, then the relay closes the session.

Note that the relay is responsible for storing restrictions and the key of the sit target across sessions, not the controller.

====Controller side====
*Unless it does not matter that the relay could close the session (or for another reason, the controller knows the relay will not close it), a controller SHOULD listen to ping messages and answer any ping message with a !pong message.
*A controller should ignore ping requests from relays it is not ready to handle.

Note controller don't have to poll for relay presence to resume a session but should just listen for ping messages instead. The relay should have stored all restrictions and handle sitting back to whatever furniture the relay wearer was tied up to.

Concerning the second bullet: for instance, if the controller is a furniture which is already in use by another relay wearer, it would be cause dysfunctions to let the pinging relay restore the restrictions without letting its wearer sit on the furniture. Or if the controller is not stateless and the state for the pinging relay has not been saved before, resuming the session from the initial state might be inconsistant.

===!version===
The purpose of this meta-command is to query the version of the RLVR protocol supported by a relay.

* !version opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !version with the version number of the RLVR protocol it supports ("1100" here, since ORG 0004 includes RLVR 1.100).

Note this is the most common command for a controller to scan for nearby relays, as non-ORG relays also accept this command and answer it the way described above.

===!implversion===
The purpose of this meta-command is to query the name and version of the relay implementation.

* !implversion opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !implversion with its implementation version string... which can be any string.

It is recommended this string includes the following elements:
* the relay name/brand/identifier,
* the version number of that relay name/brand/identifier,
* at the beginning, the string prefix "ORG=0004/"
The latter is convenient for checking for ORG compatibility using a command even non-ORG relay should understand.

===!x-orgversions===

This meta-command purpose it two-fold. First it allows a controlling device to ask a relay for the list of ORG x-tensions it supports and, second, similarily to !version, !x-orgversions can be used to know what version of ORG the relay complies to.

'''Example:'''
C<->R
-> query,rUUID,!x-orgversions
<- query,cUUID,!x-orgversions,ORG=0004/who=002/email=006

'''Requirements:'''
* !x-orgversions should always be accepted with no Auth required, it does not open a session or Lock one.
* The acknowledgement value in a reply to !x-orgversions is a "/"-list of items of the form <package>=<version>. The first <package> is always "ORG" (representing the core specification package of ORG relays), its version string is the version of the specification (4 digits). The other packages are ORG x-tension names, whose version string is 3 digits.
* If several incompatible versions of a same x-tension are supported, they must be listed ordered by version number. Ex: ORG=0004/who=002/email=005/email=006. If versions are backward compatible, only the last version should be reported.

'''Remarks:'''
* In a controller, it is however recommended to use !x-orgversions as soon as possible in order to avoid sending unsupported and useless metacommands later on.
* In the acknowledgement message, x-tension names are listed, not meta-command names (as one x-tension can have several meta-commands). Thus listed names do not include the prefix "!x-".

LSL Protocol/Restrained Love Open Relay Group/ORG Requirements/0004 draft

2011-06-27T13:26:27Z

Satomi Ahn: /* !x-orgversions */

{{ORG_Restrained_Life_Relay_Specs_TOC}}
STATUS: draft

VERSION: 0004

==Summary==

This page is a list of requirements for a relay or an in-world device to have the right to be called "ORG compliant". It is mostly about adding support for an ORG-centered informational metacommand and specifying Marine Kelley's RLVR protocol a bit more that it is now, while of course preserving full compatibility.

For a quick overview of the motivations and general working of this protocol and a few examples, we refer the reader to [[LSL_Protocol/Restrained_Love_Relay/Specification|the original specification page by Marine Kelley]].

If you are making furniture, traps, or other RLVR controllers and you are not interested in what [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] can offer, then you can stick with the original specification by Marine Kelley and still be compatible with [[LSL_Protocol/Restrained_Love_Relay/Comparison|ORG relays]]. However, to have the right to call your controller "ORG compatible", there are still a few light additional requirements such as:
* using only [[llRegionSayTo]] for communications with the relay,
* not spamming the RLVR channel with messages that do not belong to the protocol,
* and remain responsive to ping messages at every time if you want the session to remain locked.

If you are interested in [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|ORG x-tensions]], then you should also read the part about [[#!x-orgversions|!x-orgversions]].

If you are making a relay, sorry we are afraid you will have to read all this page.

==Definition of an ORG device==

A RLVR device is compliant with ORG specifications if it implements the consolidated RLVR protocol described below along with the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] it announces supporting.

Note in particular that
* the consolidated protocol is backward compatible with [[LSL_Protocol/Restrained_Love_Relay/Specification|Marine Kelley's RLVR protocol version 1.100]] but resolves most loose ends of that document;
* ORG relays handle controller messages whose second field is ffffffff-ffff-ffff-ffff-ffffffffffff exactly the same as if it was the key of the wearer (NULL_KEY is a wildcard);
* one-to-one chat messages (not using a wildcard) are sent by using [[llRegionSayTo]] LSL function;
* there is an additional meta-command, !x-orgversions for a relay to announce supported x-tensions;
* each supported x-tension can imply other supported metacommands, ORG x-tensions meta-command all having names starting with prefix "!x-";
* other proprietary metacommands with prefix "!_-" (replace "_" by any letter that is not "x") can be supported;

Supported x-tensions can constrain the core specification (this document) even more, but cannot alter it or make it less constraining unless as a result of the relay executing a meta-command of this x-tension sent by the controller. Thus, although the protocol is extensible, a controller can always rely on the fact an ORG relay abides by the requirements in this document until it asks the relay to do otherwise.

ORG devices may be advertised by the use of the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/ORG_Logo|ORG logo]] for advertising compliance with ORG requirements. ORG devices makers are encouraged to do so.

==Consolidated RLVR protocol==

=== A few definitions ===

* The '''Restrained Love Relay (RLVR) protocol''' implies two partners (SL objects): the '''relay''' worn by the avatar commands are intended for, and a '''controller''', which sends commands to the relay.

* During an execution of the RLVR protocol, a relay and a controller establish a '''session''' together. A relay may manage several sessions with several controllers. Likewise, a controller could establish sessions with several relays.

* The goal of the protocol is to force the relay wearer to make perform actions and to toggle restrictions on their behavior. Both actions and restrictions can be enforced either through use of viewer hooks ([[LSL_Protocol/RestrainedLoveAPI|Restrained Love API]], or RLV) or through LSL scripting.

* Hence we distinguish between "'''RLV commands'''", starting with "@", which are commands following the syntax of the RLV API and which will ultimately be forwarded to the viewer, and "'''meta-commands'''", starting with "!", which are meant to be interpreted by LSL functions.

* Restrictions on a relay wearer are relative to a session. So are most other variables (authorization state, key of the controller, ... ).

* A session is '''Opened''' whenever the relay accepts a RLVR command from a controller.

* A session is '''Closed''' (or '''released''') as soon as the relay forgets every variables and releases all restrictions pertaining to that session.

* A session is '''Locked''' whenever it holds active restrictions.

* A session is '''Authed''' if the controller has been allowed to control the relay (not only store some variables with no consequence). Once authed, no interactive "ask" dialog should pop up anymore concerning this session. Most commands should now normally be accepted (and maybe a few automatically rejected).

* A controller is called '''reachable''' if it can receive messages from the relay and can prove it by answering ping requests from the relay. By "can", it is meant by the method of communication agreed upon by the relay and controller. By default the communication method is chat messages sent by llRegionSayTo. X-tensions such as email and delay can modify what is meant by reachable.

===Reminder of the protocol syntax and related notations===

RLVR protocol consists of messages exchanged on channel -1812221819 (called '''RLVR channel''') using the LSL function [[llRegionSayTo]].

A controller only sends messages (commands) whose syntax is described by the non-terminal <c_msg>. A relay only sends messages (acknowledgements) whose syntax is described by the non-terminal <r_msg>.

<c_msg> ::= IDENT "," KEY "," <commands>
<r_msg> ::= IDENT "," KEY "," <command> "," ACK
<commands> ::= <command> | <command> "|" <commands>
<command> ::= <rlvcommand> | <metacommand>
<rlvcommand> ::= "@" RLVCOMMAND
<metacommand> ::= "!" METACOMMANDNAME <metacommandarguments>
<metacommandarguments> ::= "" | "/" ARG <metacommandarguments>

where we explicit the different terminal tokens:
IDENT: any string without ","
KEY: any UUID
ACK: any string without ","
RLVCOMMAND: any string without ","
METACOMMANDNAME: any string without "/" and ","
ARG: any string without "/" and ","

===Relay requirements===
These requirements do apply by default but the behavior of the relay may be modified as a result of having executed some metacommand defined in an optional x-tension.

====Syntactical considerations====
'''Requirements:'''
*A relay MUST NOT send anything on RLVR channel that is not a valid <r_msg>.
*A relay MUST ignore any message on RLVR channel that is not a ","-list of 3 items and whose second item is not the key of the avatar wearing the relay or ffffffff-ffff-ffff-ffff-ffffffffffff.
When the relay receives a message meeting the above conditions and considering the 3rd item of the ","-list as a "|"-list of <command>s, then for every <command>:
* if the <command> is neither a valid <rlvcommand> or <metacommand>, the relay must ignore it and process the next <command>'s;
* if the <command> is a <rlvcommand> or a <metacommand>, the relay MUST send an acknowledgement message back to the controller.
* an acknowledgement message is a <r_msg> (see above) such that
:*IDENT is the same as IDENT in the <c_msg> being processed
:*KEY is the key of the controller who sent the <c_msg>
:*<command> is the subcommand being processed
:*ACK is a string called ''acknowledgement value''. By default the acknowledgement value is "ok" if the relay will execute the <command >, "ko" otherwise;
* every acknowledgement or message sent by the relay to one given controlling device must be issued by the same prim (so that the controlling device can restrict its listener to one source key) using the LSL function [[llRegionSayTo]].

'''Remarks:'''
* Many meta-commands may have other acknowledgements than "ok" or "ko" (or none, for !pong). Their definitions supersede this specification.
* Note that unknown meta-commands cannot be executed and thus wil be acknowledged by "ko".
* Known meta-commands which are sent with not enough parameters or parameters with types incompatible with those in the definition known by the relay also cannot be executed and will also be acknowledged by "ko". (ex: the relay knows !x-who/key, but receives !x-who/integer/string).

====Command handling====
'''Requirements:'''
* If a <rlvcommand> is acknowledged with value "ok", the relay ensures the viewer is affected the same way as if the LSL instruction llOwnerSay(<rlvcommand>) was executed by a script in a primitive that handles only one controller.
* When processing a <metacommand>, if the relay knows at least one definition of '!'+METACOMMANDNAME for which the received <metacommandarguments> provide enough parameters, then it will be handled according to the definition handling the most parameters among the latter. Extra parameters are ignored.
* When acknowledging a <metacommand> by anything else than "ko", the relay commits itself to execute it.

'''Remarks:'''
* For first requirement, it must be understood that the reference behavior is that the relay would have if it had one controller per prim. However handling several controllers from one unique prim is possible but requires taking care that different controllers do not interfere with each other, releasing each other's restrictions, for instance.
* For the second requirement, the word "handled" means that if the meta-command with these parameters is known, then requirements in known definition cannot be ignored. Sometimes, this can imply that the meta-command cannot be refused, for instance.

====Session related requirements:====
*Closing a session clears all RLV restrictions that belong only to that session, clears all session variables and disables all behaviors relative to that session.
*Sessions that are not locked MUST be released after a reasonable timeout.
*Relay implementations MAY require an authed session for all <rlvcommand>'s, except @xxx=<channel_number>, @clear[=xxx] and @xxx=y/rem commands, which MUST always be accepted.
*@xxx=n/add <rlvcommand>'s, after being accepted, add a restriction and therefore Lock the session.
*Some metacommands described in x-tensions can also add restrictions and therefore Lock the session.
*!release, !version, !implversion, !x-orgversions and !x-.../clear[/...] commands are always accepted.
*!pong reactivates an existing session but never requires further auth, provided it is sent by the device to which ping was sent. The relay MUST resend to the viewer all stored restrictions belonging to the controlling device if they are not already active.
*Unless specified otherwise (see !x-who), no command can trigger an interactive dialog unless
:* they require an Authed session
:* and no session is currently open or it is open but not Authed yet.
*When releasing a Locked session, a relay MUST release all restrictions belonging to the device controlling the session.
*On the following events, a relay MUST release a locked session:
:* when the relay notices the controller has become unreachable,
:* wren the relay sends "release,<controller_key>,!release,ok" (due to acknowledging !release sent by the controller, or due to safewording triggered from the relay side).
*A relay MUST provide a mechanism for checking that every controlling device is reachable. It is not specified whether this checking process should be automatic or manually triggered.
*The absence of active restriction unlocks the session (and eventually releases it).
*A relay MUST remove restrictions from a session when (and only in these cases):
:* either the session controller specifically asks for the restriction to be released ("@restriction=y" "@restriction=rem", "@clear=restriction" for RLV restrictions, and "!x-restriction/clear/..." for LSL restrictions),
:* or the session closed (for instance !release coming from the device, or safeword).

===Controller requirements===
* A controller MUST not send anything on RLVR channel that is not a valid <c_msg>.
* A controller MUST, for each Locked session it controls, provide a mechanism that will unlock it in bounded time. (i.e.: either there is a menu that will release the victim, or there is a timer, or a menu should be able to start such a timer). At least one person MUST know what this mechanism is, and if it requires an action from someone else, be able to tell that other person what s/he has to do.

==Core meta-commands and associated mechanisms==

An ORG device MUST at least support the meta-commands !release, !pong, !version, !implversion and !x-orgversions described below and implement their associated mechanisms.

Particular meta-commands definitions and mechanisms may override general requirements above.

===!release===
Sent by a controller, this command closes the session.

* !release obviously opens no session, requires no Auth and is not Locking.
* If there is an actual session to close !release MUST be accepted by the relay and acknowledeged by "ok".
* On accepting !release, the relay erases all data pertaining to the session and disables all restrictions of the session.
* When a relay decides to close a session on its own (user safeword, for instance) and it is not due to the controller being unreachable, the relay must send the following acknowledgement message:
release,<controller_key>,!release,ok

When receiving the latter message, the controller should act accordingly, for instance by resetting itself and making itself ready for the next session.

Note that !release is not the same as @clear. @clear is interpreted by the relay as a RLV command and, as such, can only clear RLV restrictions. If RLV restrictions were the only restrictions of the session, then the session will be closed, but some x-tensions also define pure LSL based restrictions.

===ping/!pong===

The ping/!pong mechanism exists so that relays can check presence and responsiveness of a controller. This was primarily meant to be used on relay wearer relog, in order to reactivate all restrictions so that sessions persist on relog if the controller still exists and is ready to continue the session.

''!pong'' cannot require auth and does not lock a session

We call ''ping message'' a message from the relay, having the following syntax:
ping,<controller_key>,ping,ping
We call ''!pong message'' a message from the controller, having the following syntax:
ping,<relay_key>,!pong

====Relay side====
*A relay SHOULD NOT send an acknowledgement in response to ''!pong''.
*A ping message can be sent any time by the relay to a known controller.
*On wearer relog, for each existing Locked session, the relay must send a ping message to the session controller.
*When a !pong message is received from a controller, if it was a reply to a previous ping message:
:#if the session RLV restrictions contain unsit and the avatar was sitting on some object when the restriction was applied, then the relay MUST force the avatar to sit back on the same object (if still existing);
:#the relay MUST make sure all restrictions belonging to the session are made active again.
*If a ping message is sent and is not answered by the controller, then the relay closes the session.

Note that the relay is responsible for storing restrictions and the key of the sit target across sessions, not the controller.

====Controller side====
*Unless it does not matter that the relay could close the session (or for another reason, the controller knows the relay will not close it), a controller SHOULD listen to ping messages and answer any ping message with a !pong message.
*A controller should ignore ping requests from relays it is not ready to handle.

Note controller don't have to poll for relay presence to resume a session but should just listen for ping messages instead. The relay should have stored all restrictions and handle sitting back to whatever furniture the relay wearer was tied up to.

Concerning the second bullet: for instance, if the controller is a furniture which is already in use by another relay wearer, it would be cause dysfunctions to let the pinging relay restore the restrictions without letting its wearer sit on the furniture. Or if the controller is not stateless and the state for the pinging relay has not been saved before, resuming the session from the initial state might be inconsistant.

===!version===
The purpose of this meta-command is to query the version of the RLVR protocol supported by a relay.

* !version opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !version with the version number of the RLVR protocol it supports ("1100" here, since ORG 0004 includes RLVR 1.100).

Note this is the most common command for a controller to scan for nearby relays, as non-ORG relays also accept this command and answer it the way described above.

===!implversion===
The purpose of this meta-command is to query the name and version of the relay implementation.

* !implversion opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !implversion with its implementation version string... which can be any string.

It is recommended this string includes the following elements:
* the relay name/brand/identifier,
* the version number of that relay name/brand/identifier,
* at the beginning, the string prefix "ORG=0004/"
The latter is convenient for checking for ORG compatibility using a command even non-ORG relay should understand.

===!x-orgversions===

This meta-command purpose it two-fold. First it allows a controlling device to ask a relay for the list of ORG x-tensions it supports and, second, similarily to !version, !x-orgversions can be used to know what version of ORG the relay complies to.

'''Example:'''
C<->R
-> query,rUUID,!x-orgversions
<- query,cUUID,!x-orgversions,ORG=0004/who=002/email=006

'''Requirements:'''
* !x-orgversions should always be accepted with no Auth required, it does not open a session or Lock one.
* The acknowledgement value in a reply to !x-orgversions is a "/"-list of items of the form <package>=<version>. The first <package> is always "ORG" (representing the core specification package of ORG relays), its version string is the version of the specification (4 digits). The other packages are ORG x-tension names, whose version string is 3 digits.
* If several incompatible versions of a same x-tension are supported, they must be listed ordered by version number. Ex: ORG=0004/who=002/email=005/email=006. If versions are backward compatible, only the last version should be reported.

'''Remarks:'''
* In a controller, it is however recommended to use !x-orgversions as soon as possible in order to avoid sending unsupported and useless metacommands later on.
* In the acknowledgement message, x-tension names are listed, not meta-command names (as one x-tension can have several meta-commands). Thus listed names do not include the prefix "!x-".

LSL Protocol/Restrained Love Open Relay Group/ORG Requirements/0004 draft

2011-06-27T13:25:27Z

Satomi Ahn: /* !x-orgversions */

{{ORG_Restrained_Life_Relay_Specs_TOC}}
STATUS: draft

VERSION: 0004

==Summary==

This page is a list of requirements for a relay or an in-world device to have the right to be called "ORG compliant". It is mostly about adding support for an ORG-centered informational metacommand and specifying Marine Kelley's RLVR protocol a bit more that it is now, while of course preserving full compatibility.

For a quick overview of the motivations and general working of this protocol and a few examples, we refer the reader to [[LSL_Protocol/Restrained_Love_Relay/Specification|the original specification page by Marine Kelley]].

If you are making furniture, traps, or other RLVR controllers and you are not interested in what [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] can offer, then you can stick with the original specification by Marine Kelley and still be compatible with [[LSL_Protocol/Restrained_Love_Relay/Comparison|ORG relays]]. However, to have the right to call your controller "ORG compatible", there are still a few light additional requirements such as:
* using only [[llRegionSayTo]] for communications with the relay,
* not spamming the RLVR channel with messages that do not belong to the protocol,
* and remain responsive to ping messages at every time if you want the session to remain locked.

If you are interested in [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|ORG x-tensions]], then you should also read the part about [[#!x-orgversions|!x-orgversions]].

If you are making a relay, sorry we are afraid you will have to read all this page.

==Definition of an ORG device==

A RLVR device is compliant with ORG specifications if it implements the consolidated RLVR protocol described below along with the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] it announces supporting.

Note in particular that
* the consolidated protocol is backward compatible with [[LSL_Protocol/Restrained_Love_Relay/Specification|Marine Kelley's RLVR protocol version 1.100]] but resolves most loose ends of that document;
* ORG relays handle controller messages whose second field is ffffffff-ffff-ffff-ffff-ffffffffffff exactly the same as if it was the key of the wearer (NULL_KEY is a wildcard);
* one-to-one chat messages (not using a wildcard) are sent by using [[llRegionSayTo]] LSL function;
* there is an additional meta-command, !x-orgversions for a relay to announce supported x-tensions;
* each supported x-tension can imply other supported metacommands, ORG x-tensions meta-command all having names starting with prefix "!x-";
* other proprietary metacommands with prefix "!_-" (replace "_" by any letter that is not "x") can be supported;

Supported x-tensions can constrain the core specification (this document) even more, but cannot alter it or make it less constraining unless as a result of the relay executing a meta-command of this x-tension sent by the controller. Thus, although the protocol is extensible, a controller can always rely on the fact an ORG relay abides by the requirements in this document until it asks the relay to do otherwise.

ORG devices may be advertised by the use of the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/ORG_Logo|ORG logo]] for advertising compliance with ORG requirements. ORG devices makers are encouraged to do so.

==Consolidated RLVR protocol==

=== A few definitions ===

* The '''Restrained Love Relay (RLVR) protocol''' implies two partners (SL objects): the '''relay''' worn by the avatar commands are intended for, and a '''controller''', which sends commands to the relay.

* During an execution of the RLVR protocol, a relay and a controller establish a '''session''' together. A relay may manage several sessions with several controllers. Likewise, a controller could establish sessions with several relays.

* The goal of the protocol is to force the relay wearer to make perform actions and to toggle restrictions on their behavior. Both actions and restrictions can be enforced either through use of viewer hooks ([[LSL_Protocol/RestrainedLoveAPI|Restrained Love API]], or RLV) or through LSL scripting.

* Hence we distinguish between "'''RLV commands'''", starting with "@", which are commands following the syntax of the RLV API and which will ultimately be forwarded to the viewer, and "'''meta-commands'''", starting with "!", which are meant to be interpreted by LSL functions.

* Restrictions on a relay wearer are relative to a session. So are most other variables (authorization state, key of the controller, ... ).

* A session is '''Opened''' whenever the relay accepts a RLVR command from a controller.

* A session is '''Closed''' (or '''released''') as soon as the relay forgets every variables and releases all restrictions pertaining to that session.

* A session is '''Locked''' whenever it holds active restrictions.

* A session is '''Authed''' if the controller has been allowed to control the relay (not only store some variables with no consequence). Once authed, no interactive "ask" dialog should pop up anymore concerning this session. Most commands should now normally be accepted (and maybe a few automatically rejected).

* A controller is called '''reachable''' if it can receive messages from the relay and can prove it by answering ping requests from the relay. By "can", it is meant by the method of communication agreed upon by the relay and controller. By default the communication method is chat messages sent by llRegionSayTo. X-tensions such as email and delay can modify what is meant by reachable.

===Reminder of the protocol syntax and related notations===

RLVR protocol consists of messages exchanged on channel -1812221819 (called '''RLVR channel''') using the LSL function [[llRegionSayTo]].

A controller only sends messages (commands) whose syntax is described by the non-terminal <c_msg>. A relay only sends messages (acknowledgements) whose syntax is described by the non-terminal <r_msg>.

<c_msg> ::= IDENT "," KEY "," <commands>
<r_msg> ::= IDENT "," KEY "," <command> "," ACK
<commands> ::= <command> | <command> "|" <commands>
<command> ::= <rlvcommand> | <metacommand>
<rlvcommand> ::= "@" RLVCOMMAND
<metacommand> ::= "!" METACOMMANDNAME <metacommandarguments>
<metacommandarguments> ::= "" | "/" ARG <metacommandarguments>

where we explicit the different terminal tokens:
IDENT: any string without ","
KEY: any UUID
ACK: any string without ","
RLVCOMMAND: any string without ","
METACOMMANDNAME: any string without "/" and ","
ARG: any string without "/" and ","

===Relay requirements===
These requirements do apply by default but the behavior of the relay may be modified as a result of having executed some metacommand defined in an optional x-tension.

====Syntactical considerations====
'''Requirements:'''
*A relay MUST NOT send anything on RLVR channel that is not a valid <r_msg>.
*A relay MUST ignore any message on RLVR channel that is not a ","-list of 3 items and whose second item is not the key of the avatar wearing the relay or ffffffff-ffff-ffff-ffff-ffffffffffff.
When the relay receives a message meeting the above conditions and considering the 3rd item of the ","-list as a "|"-list of <command>s, then for every <command>:
* if the <command> is neither a valid <rlvcommand> or <metacommand>, the relay must ignore it and process the next <command>'s;
* if the <command> is a <rlvcommand> or a <metacommand>, the relay MUST send an acknowledgement message back to the controller.
* an acknowledgement message is a <r_msg> (see above) such that
:*IDENT is the same as IDENT in the <c_msg> being processed
:*KEY is the key of the controller who sent the <c_msg>
:*<command> is the subcommand being processed
:*ACK is a string called ''acknowledgement value''. By default the acknowledgement value is "ok" if the relay will execute the <command >, "ko" otherwise;
* every acknowledgement or message sent by the relay to one given controlling device must be issued by the same prim (so that the controlling device can restrict its listener to one source key) using the LSL function [[llRegionSayTo]].

'''Remarks:'''
* Many meta-commands may have other acknowledgements than "ok" or "ko" (or none, for !pong). Their definitions supersede this specification.
* Note that unknown meta-commands cannot be executed and thus wil be acknowledged by "ko".
* Known meta-commands which are sent with not enough parameters or parameters with types incompatible with those in the definition known by the relay also cannot be executed and will also be acknowledged by "ko". (ex: the relay knows !x-who/key, but receives !x-who/integer/string).

====Command handling====
'''Requirements:'''
* If a <rlvcommand> is acknowledged with value "ok", the relay ensures the viewer is affected the same way as if the LSL instruction llOwnerSay(<rlvcommand>) was executed by a script in a primitive that handles only one controller.
* When processing a <metacommand>, if the relay knows at least one definition of '!'+METACOMMANDNAME for which the received <metacommandarguments> provide enough parameters, then it will be handled according to the definition handling the most parameters among the latter. Extra parameters are ignored.
* When acknowledging a <metacommand> by anything else than "ko", the relay commits itself to execute it.

'''Remarks:'''
* For first requirement, it must be understood that the reference behavior is that the relay would have if it had one controller per prim. However handling several controllers from one unique prim is possible but requires taking care that different controllers do not interfere with each other, releasing each other's restrictions, for instance.
* For the second requirement, the word "handled" means that if the meta-command with these parameters is known, then requirements in known definition cannot be ignored. Sometimes, this can imply that the meta-command cannot be refused, for instance.

====Session related requirements:====
*Closing a session clears all RLV restrictions that belong only to that session, clears all session variables and disables all behaviors relative to that session.
*Sessions that are not locked MUST be released after a reasonable timeout.
*Relay implementations MAY require an authed session for all <rlvcommand>'s, except @xxx=<channel_number>, @clear[=xxx] and @xxx=y/rem commands, which MUST always be accepted.
*@xxx=n/add <rlvcommand>'s, after being accepted, add a restriction and therefore Lock the session.
*Some metacommands described in x-tensions can also add restrictions and therefore Lock the session.
*!release, !version, !implversion, !x-orgversions and !x-.../clear[/...] commands are always accepted.
*!pong reactivates an existing session but never requires further auth, provided it is sent by the device to which ping was sent. The relay MUST resend to the viewer all stored restrictions belonging to the controlling device if they are not already active.
*Unless specified otherwise (see !x-who), no command can trigger an interactive dialog unless
:* they require an Authed session
:* and no session is currently open or it is open but not Authed yet.
*When releasing a Locked session, a relay MUST release all restrictions belonging to the device controlling the session.
*On the following events, a relay MUST release a locked session:
:* when the relay notices the controller has become unreachable,
:* wren the relay sends "release,<controller_key>,!release,ok" (due to acknowledging !release sent by the controller, or due to safewording triggered from the relay side).
*A relay MUST provide a mechanism for checking that every controlling device is reachable. It is not specified whether this checking process should be automatic or manually triggered.
*The absence of active restriction unlocks the session (and eventually releases it).
*A relay MUST remove restrictions from a session when (and only in these cases):
:* either the session controller specifically asks for the restriction to be released ("@restriction=y" "@restriction=rem", "@clear=restriction" for RLV restrictions, and "!x-restriction/clear/..." for LSL restrictions),
:* or the session closed (for instance !release coming from the device, or safeword).

===Controller requirements===
* A controller MUST not send anything on RLVR channel that is not a valid <c_msg>.
* A controller MUST, for each Locked session it controls, provide a mechanism that will unlock it in bounded time. (i.e.: either there is a menu that will release the victim, or there is a timer, or a menu should be able to start such a timer). At least one person MUST know what this mechanism is, and if it requires an action from someone else, be able to tell that other person what s/he has to do.

==Core meta-commands and associated mechanisms==

An ORG device MUST at least support the meta-commands !release, !pong, !version, !implversion and !x-orgversions described below and implement their associated mechanisms.

Particular meta-commands definitions and mechanisms may override general requirements above.

===!release===
Sent by a controller, this command closes the session.

* !release obviously opens no session, requires no Auth and is not Locking.
* If there is an actual session to close !release MUST be accepted by the relay and acknowledeged by "ok".
* On accepting !release, the relay erases all data pertaining to the session and disables all restrictions of the session.
* When a relay decides to close a session on its own (user safeword, for instance) and it is not due to the controller being unreachable, the relay must send the following acknowledgement message:
release,<controller_key>,!release,ok

When receiving the latter message, the controller should act accordingly, for instance by resetting itself and making itself ready for the next session.

Note that !release is not the same as @clear. @clear is interpreted by the relay as a RLV command and, as such, can only clear RLV restrictions. If RLV restrictions were the only restrictions of the session, then the session will be closed, but some x-tensions also define pure LSL based restrictions.

===ping/!pong===

The ping/!pong mechanism exists so that relays can check presence and responsiveness of a controller. This was primarily meant to be used on relay wearer relog, in order to reactivate all restrictions so that sessions persist on relog if the controller still exists and is ready to continue the session.

''!pong'' cannot require auth and does not lock a session

We call ''ping message'' a message from the relay, having the following syntax:
ping,<controller_key>,ping,ping
We call ''!pong message'' a message from the controller, having the following syntax:
ping,<relay_key>,!pong

====Relay side====
*A relay SHOULD NOT send an acknowledgement in response to ''!pong''.
*A ping message can be sent any time by the relay to a known controller.
*On wearer relog, for each existing Locked session, the relay must send a ping message to the session controller.
*When a !pong message is received from a controller, if it was a reply to a previous ping message:
:#if the session RLV restrictions contain unsit and the avatar was sitting on some object when the restriction was applied, then the relay MUST force the avatar to sit back on the same object (if still existing);
:#the relay MUST make sure all restrictions belonging to the session are made active again.
*If a ping message is sent and is not answered by the controller, then the relay closes the session.

Note that the relay is responsible for storing restrictions and the key of the sit target across sessions, not the controller.

====Controller side====
*Unless it does not matter that the relay could close the session (or for another reason, the controller knows the relay will not close it), a controller SHOULD listen to ping messages and answer any ping message with a !pong message.
*A controller should ignore ping requests from relays it is not ready to handle.

Note controller don't have to poll for relay presence to resume a session but should just listen for ping messages instead. The relay should have stored all restrictions and handle sitting back to whatever furniture the relay wearer was tied up to.

Concerning the second bullet: for instance, if the controller is a furniture which is already in use by another relay wearer, it would be cause dysfunctions to let the pinging relay restore the restrictions without letting its wearer sit on the furniture. Or if the controller is not stateless and the state for the pinging relay has not been saved before, resuming the session from the initial state might be inconsistant.

===!version===
The purpose of this meta-command is to query the version of the RLVR protocol supported by a relay.

* !version opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !version with the version number of the RLVR protocol it supports ("1100" here, since ORG 0004 includes RLVR 1.100).

Note this is the most common command for a controller to scan for nearby relays, as non-ORG relays also accept this command and answer it the way described above.

===!implversion===
The purpose of this meta-command is to query the name and version of the relay implementation.

* !implversion opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !implversion with its implementation version string... which can be any string.

It is recommended this string includes the following elements:
* the relay name/brand/identifier,
* the version number of that relay name/brand/identifier,
* at the beginning, the string prefix "ORG=0004/"
The latter is convenient for checking for ORG compatibility using a command even non-ORG relay should understand.

===!x-orgversions===

This meta-command purpose it two-fold. First it allows a controlling device to ask a relay for the list of ORG x-tensions it supports and, second, similarily to !version, !x-orgversions can be used to know what version of ORG the relay complies to.

Example:
C<->R
-> query,rUUID,!x-orgversions
<- query,cUUID,!x-orgversions,ORG=0004/who=002/email=006

* !x-orgversions should always be accepted with no Auth required, it does not open a session or Lock one.
* The acknowledgement value in a reply to !x-orgversions is a "/"-list of items of the form <package>=<version>. The first <package> is always "ORG" (representing the core specification package of ORG relays), its version string is the version of the specification (4 digits). The other packages are ORG x-tension names, whose version string is 3 digits.
* If several incompatible versions of a same x-tension are supported, they must be listed ordered by version number. Ex: ORG=0004/who=002/email=005/email=006. If versions are backward compatible, only the last version should be reported.

'''Remarks:'''
* In a controller, it is however recommended to use !x-orgversions as soon as possible in order to avoid sending unsupported and useless metacommands later on.
* In the acknowledgement message, x-tension names are listed, not meta-command names (as one x-tension can have several meta-commands). Thus listed names do not include the prefix "!x-".

LSL Protocol/Restrained Love Open Relay Group/ORG Requirements/0004 draft

2011-06-27T13:17:24Z

Satomi Ahn: /* Controller side */

{{ORG_Restrained_Life_Relay_Specs_TOC}}
STATUS: draft

VERSION: 0004

==Summary==

This page is a list of requirements for a relay or an in-world device to have the right to be called "ORG compliant". It is mostly about adding support for an ORG-centered informational metacommand and specifying Marine Kelley's RLVR protocol a bit more that it is now, while of course preserving full compatibility.

For a quick overview of the motivations and general working of this protocol and a few examples, we refer the reader to [[LSL_Protocol/Restrained_Love_Relay/Specification|the original specification page by Marine Kelley]].

If you are making furniture, traps, or other RLVR controllers and you are not interested in what [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] can offer, then you can stick with the original specification by Marine Kelley and still be compatible with [[LSL_Protocol/Restrained_Love_Relay/Comparison|ORG relays]]. However, to have the right to call your controller "ORG compatible", there are still a few light additional requirements such as:
* using only [[llRegionSayTo]] for communications with the relay,
* not spamming the RLVR channel with messages that do not belong to the protocol,
* and remain responsive to ping messages at every time if you want the session to remain locked.

If you are interested in [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|ORG x-tensions]], then you should also read the part about [[#!x-orgversions|!x-orgversions]].

If you are making a relay, sorry we are afraid you will have to read all this page.

==Definition of an ORG device==

A RLVR device is compliant with ORG specifications if it implements the consolidated RLVR protocol described below along with the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] it announces supporting.

Note in particular that
* the consolidated protocol is backward compatible with [[LSL_Protocol/Restrained_Love_Relay/Specification|Marine Kelley's RLVR protocol version 1.100]] but resolves most loose ends of that document;
* ORG relays handle controller messages whose second field is ffffffff-ffff-ffff-ffff-ffffffffffff exactly the same as if it was the key of the wearer (NULL_KEY is a wildcard);
* one-to-one chat messages (not using a wildcard) are sent by using [[llRegionSayTo]] LSL function;
* there is an additional meta-command, !x-orgversions for a relay to announce supported x-tensions;
* each supported x-tension can imply other supported metacommands, ORG x-tensions meta-command all having names starting with prefix "!x-";
* other proprietary metacommands with prefix "!_-" (replace "_" by any letter that is not "x") can be supported;

Supported x-tensions can constrain the core specification (this document) even more, but cannot alter it or make it less constraining unless as a result of the relay executing a meta-command of this x-tension sent by the controller. Thus, although the protocol is extensible, a controller can always rely on the fact an ORG relay abides by the requirements in this document until it asks the relay to do otherwise.

ORG devices may be advertised by the use of the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/ORG_Logo|ORG logo]] for advertising compliance with ORG requirements. ORG devices makers are encouraged to do so.

==Consolidated RLVR protocol==

=== A few definitions ===

* The '''Restrained Love Relay (RLVR) protocol''' implies two partners (SL objects): the '''relay''' worn by the avatar commands are intended for, and a '''controller''', which sends commands to the relay.

* During an execution of the RLVR protocol, a relay and a controller establish a '''session''' together. A relay may manage several sessions with several controllers. Likewise, a controller could establish sessions with several relays.

* The goal of the protocol is to force the relay wearer to make perform actions and to toggle restrictions on their behavior. Both actions and restrictions can be enforced either through use of viewer hooks ([[LSL_Protocol/RestrainedLoveAPI|Restrained Love API]], or RLV) or through LSL scripting.

* Hence we distinguish between "'''RLV commands'''", starting with "@", which are commands following the syntax of the RLV API and which will ultimately be forwarded to the viewer, and "'''meta-commands'''", starting with "!", which are meant to be interpreted by LSL functions.

* Restrictions on a relay wearer are relative to a session. So are most other variables (authorization state, key of the controller, ... ).

* A session is '''Opened''' whenever the relay accepts a RLVR command from a controller.

* A session is '''Closed''' (or '''released''') as soon as the relay forgets every variables and releases all restrictions pertaining to that session.

* A session is '''Locked''' whenever it holds active restrictions.

* A session is '''Authed''' if the controller has been allowed to control the relay (not only store some variables with no consequence). Once authed, no interactive "ask" dialog should pop up anymore concerning this session. Most commands should now normally be accepted (and maybe a few automatically rejected).

* A controller is called '''reachable''' if it can receive messages from the relay and can prove it by answering ping requests from the relay. By "can", it is meant by the method of communication agreed upon by the relay and controller. By default the communication method is chat messages sent by llRegionSayTo. X-tensions such as email and delay can modify what is meant by reachable.

===Reminder of the protocol syntax and related notations===

RLVR protocol consists of messages exchanged on channel -1812221819 (called '''RLVR channel''') using the LSL function [[llRegionSayTo]].

A controller only sends messages (commands) whose syntax is described by the non-terminal <c_msg>. A relay only sends messages (acknowledgements) whose syntax is described by the non-terminal <r_msg>.

<c_msg> ::= IDENT "," KEY "," <commands>
<r_msg> ::= IDENT "," KEY "," <command> "," ACK
<commands> ::= <command> | <command> "|" <commands>
<command> ::= <rlvcommand> | <metacommand>
<rlvcommand> ::= "@" RLVCOMMAND
<metacommand> ::= "!" METACOMMANDNAME <metacommandarguments>
<metacommandarguments> ::= "" | "/" ARG <metacommandarguments>

where we explicit the different terminal tokens:
IDENT: any string without ","
KEY: any UUID
ACK: any string without ","
RLVCOMMAND: any string without ","
METACOMMANDNAME: any string without "/" and ","
ARG: any string without "/" and ","

===Relay requirements===
These requirements do apply by default but the behavior of the relay may be modified as a result of having executed some metacommand defined in an optional x-tension.

====Syntactical considerations====
'''Requirements:'''
*A relay MUST NOT send anything on RLVR channel that is not a valid <r_msg>.
*A relay MUST ignore any message on RLVR channel that is not a ","-list of 3 items and whose second item is not the key of the avatar wearing the relay or ffffffff-ffff-ffff-ffff-ffffffffffff.
When the relay receives a message meeting the above conditions and considering the 3rd item of the ","-list as a "|"-list of <command>s, then for every <command>:
* if the <command> is neither a valid <rlvcommand> or <metacommand>, the relay must ignore it and process the next <command>'s;
* if the <command> is a <rlvcommand> or a <metacommand>, the relay MUST send an acknowledgement message back to the controller.
* an acknowledgement message is a <r_msg> (see above) such that
:*IDENT is the same as IDENT in the <c_msg> being processed
:*KEY is the key of the controller who sent the <c_msg>
:*<command> is the subcommand being processed
:*ACK is a string called ''acknowledgement value''. By default the acknowledgement value is "ok" if the relay will execute the <command >, "ko" otherwise;
* every acknowledgement or message sent by the relay to one given controlling device must be issued by the same prim (so that the controlling device can restrict its listener to one source key) using the LSL function [[llRegionSayTo]].

'''Remarks:'''
* Many meta-commands may have other acknowledgements than "ok" or "ko" (or none, for !pong). Their definitions supersede this specification.
* Note that unknown meta-commands cannot be executed and thus wil be acknowledged by "ko".
* Known meta-commands which are sent with not enough parameters or parameters with types incompatible with those in the definition known by the relay also cannot be executed and will also be acknowledged by "ko". (ex: the relay knows !x-who/key, but receives !x-who/integer/string).

====Command handling====
'''Requirements:'''
* If a <rlvcommand> is acknowledged with value "ok", the relay ensures the viewer is affected the same way as if the LSL instruction llOwnerSay(<rlvcommand>) was executed by a script in a primitive that handles only one controller.
* When processing a <metacommand>, if the relay knows at least one definition of '!'+METACOMMANDNAME for which the received <metacommandarguments> provide enough parameters, then it will be handled according to the definition handling the most parameters among the latter. Extra parameters are ignored.
* When acknowledging a <metacommand> by anything else than "ko", the relay commits itself to execute it.

'''Remarks:'''
* For first requirement, it must be understood that the reference behavior is that the relay would have if it had one controller per prim. However handling several controllers from one unique prim is possible but requires taking care that different controllers do not interfere with each other, releasing each other's restrictions, for instance.
* For the second requirement, the word "handled" means that if the meta-command with these parameters is known, then requirements in known definition cannot be ignored. Sometimes, this can imply that the meta-command cannot be refused, for instance.

====Session related requirements:====
*Closing a session clears all RLV restrictions that belong only to that session, clears all session variables and disables all behaviors relative to that session.
*Sessions that are not locked MUST be released after a reasonable timeout.
*Relay implementations MAY require an authed session for all <rlvcommand>'s, except @xxx=<channel_number>, @clear[=xxx] and @xxx=y/rem commands, which MUST always be accepted.
*@xxx=n/add <rlvcommand>'s, after being accepted, add a restriction and therefore Lock the session.
*Some metacommands described in x-tensions can also add restrictions and therefore Lock the session.
*!release, !version, !implversion, !x-orgversions and !x-.../clear[/...] commands are always accepted.
*!pong reactivates an existing session but never requires further auth, provided it is sent by the device to which ping was sent. The relay MUST resend to the viewer all stored restrictions belonging to the controlling device if they are not already active.
*Unless specified otherwise (see !x-who), no command can trigger an interactive dialog unless
:* they require an Authed session
:* and no session is currently open or it is open but not Authed yet.
*When releasing a Locked session, a relay MUST release all restrictions belonging to the device controlling the session.
*On the following events, a relay MUST release a locked session:
:* when the relay notices the controller has become unreachable,
:* wren the relay sends "release,<controller_key>,!release,ok" (due to acknowledging !release sent by the controller, or due to safewording triggered from the relay side).
*A relay MUST provide a mechanism for checking that every controlling device is reachable. It is not specified whether this checking process should be automatic or manually triggered.
*The absence of active restriction unlocks the session (and eventually releases it).
*A relay MUST remove restrictions from a session when (and only in these cases):
:* either the session controller specifically asks for the restriction to be released ("@restriction=y" "@restriction=rem", "@clear=restriction" for RLV restrictions, and "!x-restriction/clear/..." for LSL restrictions),
:* or the session closed (for instance !release coming from the device, or safeword).

===Controller requirements===
* A controller MUST not send anything on RLVR channel that is not a valid <c_msg>.
* A controller MUST, for each Locked session it controls, provide a mechanism that will unlock it in bounded time. (i.e.: either there is a menu that will release the victim, or there is a timer, or a menu should be able to start such a timer). At least one person MUST know what this mechanism is, and if it requires an action from someone else, be able to tell that other person what s/he has to do.

==Core meta-commands and associated mechanisms==

An ORG device MUST at least support the meta-commands !release, !pong, !version, !implversion and !x-orgversions described below and implement their associated mechanisms.

Particular meta-commands definitions and mechanisms may override general requirements above.

===!release===
Sent by a controller, this command closes the session.

* !release obviously opens no session, requires no Auth and is not Locking.
* If there is an actual session to close !release MUST be accepted by the relay and acknowledeged by "ok".
* On accepting !release, the relay erases all data pertaining to the session and disables all restrictions of the session.
* When a relay decides to close a session on its own (user safeword, for instance) and it is not due to the controller being unreachable, the relay must send the following acknowledgement message:
release,<controller_key>,!release,ok

When receiving the latter message, the controller should act accordingly, for instance by resetting itself and making itself ready for the next session.

Note that !release is not the same as @clear. @clear is interpreted by the relay as a RLV command and, as such, can only clear RLV restrictions. If RLV restrictions were the only restrictions of the session, then the session will be closed, but some x-tensions also define pure LSL based restrictions.

===ping/!pong===

The ping/!pong mechanism exists so that relays can check presence and responsiveness of a controller. This was primarily meant to be used on relay wearer relog, in order to reactivate all restrictions so that sessions persist on relog if the controller still exists and is ready to continue the session.

''!pong'' cannot require auth and does not lock a session

We call ''ping message'' a message from the relay, having the following syntax:
ping,<controller_key>,ping,ping
We call ''!pong message'' a message from the controller, having the following syntax:
ping,<relay_key>,!pong

====Relay side====
*A relay SHOULD NOT send an acknowledgement in response to ''!pong''.
*A ping message can be sent any time by the relay to a known controller.
*On wearer relog, for each existing Locked session, the relay must send a ping message to the session controller.
*When a !pong message is received from a controller, if it was a reply to a previous ping message:
:#if the session RLV restrictions contain unsit and the avatar was sitting on some object when the restriction was applied, then the relay MUST force the avatar to sit back on the same object (if still existing);
:#the relay MUST make sure all restrictions belonging to the session are made active again.
*If a ping message is sent and is not answered by the controller, then the relay closes the session.

Note that the relay is responsible for storing restrictions and the key of the sit target across sessions, not the controller.

====Controller side====
*Unless it does not matter that the relay could close the session (or for another reason, the controller knows the relay will not close it), a controller SHOULD listen to ping messages and answer any ping message with a !pong message.
*A controller should ignore ping requests from relays it is not ready to handle.

Note controller don't have to poll for relay presence to resume a session but should just listen for ping messages instead. The relay should have stored all restrictions and handle sitting back to whatever furniture the relay wearer was tied up to.

Concerning the second bullet: for instance, if the controller is a furniture which is already in use by another relay wearer, it would be cause dysfunctions to let the pinging relay restore the restrictions without letting its wearer sit on the furniture. Or if the controller is not stateless and the state for the pinging relay has not been saved before, resuming the session from the initial state might be inconsistant.

===!version===
The purpose of this meta-command is to query the version of the RLVR protocol supported by a relay.

* !version opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !version with the version number of the RLVR protocol it supports ("1100" here, since ORG 0004 includes RLVR 1.100).

Note this is the most common command for a controller to scan for nearby relays, as non-ORG relays also accept this command and answer it the way described above.

===!implversion===
The purpose of this meta-command is to query the name and version of the relay implementation.

* !implversion opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !implversion with its implementation version string... which can be any string.

It is recommended this string includes the following elements:
* the relay name/brand/identifier,
* the version number of that relay name/brand/identifier,
* at the beginning, the string prefix "ORG=0004/"
The latter is convenient for checking for ORG compatibility using a command even non-ORG relay should understand.

===!x-orgversions===

This meta-command purpose it two-fold. First it allows a controlling device to ask a relay for the list of ORG x-tensions it supports, second it is similar to !version in RLVR protocol, as its reply gives the versions of the ORG core specification and ORG x-tensions that are implemented in the relay.

C<->R
-> query,rUUID,!x-orgversions
<- query,cUUID,!x-orgversions,ORG=0004/who=002/email=006

The acknowledgement string of the relay is a list separated by "/" whose items are of the form <package>=<version>. The first package is "ORG", the core specification of ORG relays, its version string is the version of the specification (4 digits). The other packages are ORG x-tension names (not meta-command names, as one x-tension can require several metacommands, thus the name does not include the prefix "!x-"), whose version string is 3 digits.

''Requirements for a relay:''
* The support of this metacommand is mandatory for an ORG relay.
* It is also required that the list of packages in the !x-orgversions reply includes the package "ORG" and the exact list of supported optional x-tensions.
* If several incompatible versions of an x-tension are supported, they must be listed ordered by version number. Ex: ORG=0004/who=002/email=005/email=006. If versions are backward compatible, it is necessary to report only the last one.

''Requirements for a controlling device:'' None. It is however recommended to use !x-orgversions when it makes sense for avoiding sending unsupported and useless metacommands later.

LSL Protocol/Restrained Love Open Relay Group/ORG Requirements/0004 draft

2011-06-27T13:14:03Z

Satomi Ahn: /* Relay side */

{{ORG_Restrained_Life_Relay_Specs_TOC}}
STATUS: draft

VERSION: 0004

==Summary==

This page is a list of requirements for a relay or an in-world device to have the right to be called "ORG compliant". It is mostly about adding support for an ORG-centered informational metacommand and specifying Marine Kelley's RLVR protocol a bit more that it is now, while of course preserving full compatibility.

For a quick overview of the motivations and general working of this protocol and a few examples, we refer the reader to [[LSL_Protocol/Restrained_Love_Relay/Specification|the original specification page by Marine Kelley]].

If you are making furniture, traps, or other RLVR controllers and you are not interested in what [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] can offer, then you can stick with the original specification by Marine Kelley and still be compatible with [[LSL_Protocol/Restrained_Love_Relay/Comparison|ORG relays]]. However, to have the right to call your controller "ORG compatible", there are still a few light additional requirements such as:
* using only [[llRegionSayTo]] for communications with the relay,
* not spamming the RLVR channel with messages that do not belong to the protocol,
* and remain responsive to ping messages at every time if you want the session to remain locked.

If you are interested in [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|ORG x-tensions]], then you should also read the part about [[#!x-orgversions|!x-orgversions]].

If you are making a relay, sorry we are afraid you will have to read all this page.

==Definition of an ORG device==

A RLVR device is compliant with ORG specifications if it implements the consolidated RLVR protocol described below along with the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] it announces supporting.

Note in particular that
* the consolidated protocol is backward compatible with [[LSL_Protocol/Restrained_Love_Relay/Specification|Marine Kelley's RLVR protocol version 1.100]] but resolves most loose ends of that document;
* ORG relays handle controller messages whose second field is ffffffff-ffff-ffff-ffff-ffffffffffff exactly the same as if it was the key of the wearer (NULL_KEY is a wildcard);
* one-to-one chat messages (not using a wildcard) are sent by using [[llRegionSayTo]] LSL function;
* there is an additional meta-command, !x-orgversions for a relay to announce supported x-tensions;
* each supported x-tension can imply other supported metacommands, ORG x-tensions meta-command all having names starting with prefix "!x-";
* other proprietary metacommands with prefix "!_-" (replace "_" by any letter that is not "x") can be supported;

Supported x-tensions can constrain the core specification (this document) even more, but cannot alter it or make it less constraining unless as a result of the relay executing a meta-command of this x-tension sent by the controller. Thus, although the protocol is extensible, a controller can always rely on the fact an ORG relay abides by the requirements in this document until it asks the relay to do otherwise.

ORG devices may be advertised by the use of the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/ORG_Logo|ORG logo]] for advertising compliance with ORG requirements. ORG devices makers are encouraged to do so.

==Consolidated RLVR protocol==

=== A few definitions ===

* The '''Restrained Love Relay (RLVR) protocol''' implies two partners (SL objects): the '''relay''' worn by the avatar commands are intended for, and a '''controller''', which sends commands to the relay.

* During an execution of the RLVR protocol, a relay and a controller establish a '''session''' together. A relay may manage several sessions with several controllers. Likewise, a controller could establish sessions with several relays.

* The goal of the protocol is to force the relay wearer to make perform actions and to toggle restrictions on their behavior. Both actions and restrictions can be enforced either through use of viewer hooks ([[LSL_Protocol/RestrainedLoveAPI|Restrained Love API]], or RLV) or through LSL scripting.

* Hence we distinguish between "'''RLV commands'''", starting with "@", which are commands following the syntax of the RLV API and which will ultimately be forwarded to the viewer, and "'''meta-commands'''", starting with "!", which are meant to be interpreted by LSL functions.

* Restrictions on a relay wearer are relative to a session. So are most other variables (authorization state, key of the controller, ... ).

* A session is '''Opened''' whenever the relay accepts a RLVR command from a controller.

* A session is '''Closed''' (or '''released''') as soon as the relay forgets every variables and releases all restrictions pertaining to that session.

* A session is '''Locked''' whenever it holds active restrictions.

* A session is '''Authed''' if the controller has been allowed to control the relay (not only store some variables with no consequence). Once authed, no interactive "ask" dialog should pop up anymore concerning this session. Most commands should now normally be accepted (and maybe a few automatically rejected).

* A controller is called '''reachable''' if it can receive messages from the relay and can prove it by answering ping requests from the relay. By "can", it is meant by the method of communication agreed upon by the relay and controller. By default the communication method is chat messages sent by llRegionSayTo. X-tensions such as email and delay can modify what is meant by reachable.

===Reminder of the protocol syntax and related notations===

RLVR protocol consists of messages exchanged on channel -1812221819 (called '''RLVR channel''') using the LSL function [[llRegionSayTo]].

A controller only sends messages (commands) whose syntax is described by the non-terminal <c_msg>. A relay only sends messages (acknowledgements) whose syntax is described by the non-terminal <r_msg>.

<c_msg> ::= IDENT "," KEY "," <commands>
<r_msg> ::= IDENT "," KEY "," <command> "," ACK
<commands> ::= <command> | <command> "|" <commands>
<command> ::= <rlvcommand> | <metacommand>
<rlvcommand> ::= "@" RLVCOMMAND
<metacommand> ::= "!" METACOMMANDNAME <metacommandarguments>
<metacommandarguments> ::= "" | "/" ARG <metacommandarguments>

where we explicit the different terminal tokens:
IDENT: any string without ","
KEY: any UUID
ACK: any string without ","
RLVCOMMAND: any string without ","
METACOMMANDNAME: any string without "/" and ","
ARG: any string without "/" and ","

===Relay requirements===
These requirements do apply by default but the behavior of the relay may be modified as a result of having executed some metacommand defined in an optional x-tension.

====Syntactical considerations====
'''Requirements:'''
*A relay MUST NOT send anything on RLVR channel that is not a valid <r_msg>.
*A relay MUST ignore any message on RLVR channel that is not a ","-list of 3 items and whose second item is not the key of the avatar wearing the relay or ffffffff-ffff-ffff-ffff-ffffffffffff.
When the relay receives a message meeting the above conditions and considering the 3rd item of the ","-list as a "|"-list of <command>s, then for every <command>:
* if the <command> is neither a valid <rlvcommand> or <metacommand>, the relay must ignore it and process the next <command>'s;
* if the <command> is a <rlvcommand> or a <metacommand>, the relay MUST send an acknowledgement message back to the controller.
* an acknowledgement message is a <r_msg> (see above) such that
:*IDENT is the same as IDENT in the <c_msg> being processed
:*KEY is the key of the controller who sent the <c_msg>
:*<command> is the subcommand being processed
:*ACK is a string called ''acknowledgement value''. By default the acknowledgement value is "ok" if the relay will execute the <command >, "ko" otherwise;
* every acknowledgement or message sent by the relay to one given controlling device must be issued by the same prim (so that the controlling device can restrict its listener to one source key) using the LSL function [[llRegionSayTo]].

'''Remarks:'''
* Many meta-commands may have other acknowledgements than "ok" or "ko" (or none, for !pong). Their definitions supersede this specification.
* Note that unknown meta-commands cannot be executed and thus wil be acknowledged by "ko".
* Known meta-commands which are sent with not enough parameters or parameters with types incompatible with those in the definition known by the relay also cannot be executed and will also be acknowledged by "ko". (ex: the relay knows !x-who/key, but receives !x-who/integer/string).

====Command handling====
'''Requirements:'''
* If a <rlvcommand> is acknowledged with value "ok", the relay ensures the viewer is affected the same way as if the LSL instruction llOwnerSay(<rlvcommand>) was executed by a script in a primitive that handles only one controller.
* When processing a <metacommand>, if the relay knows at least one definition of '!'+METACOMMANDNAME for which the received <metacommandarguments> provide enough parameters, then it will be handled according to the definition handling the most parameters among the latter. Extra parameters are ignored.
* When acknowledging a <metacommand> by anything else than "ko", the relay commits itself to execute it.

'''Remarks:'''
* For first requirement, it must be understood that the reference behavior is that the relay would have if it had one controller per prim. However handling several controllers from one unique prim is possible but requires taking care that different controllers do not interfere with each other, releasing each other's restrictions, for instance.
* For the second requirement, the word "handled" means that if the meta-command with these parameters is known, then requirements in known definition cannot be ignored. Sometimes, this can imply that the meta-command cannot be refused, for instance.

====Session related requirements:====
*Closing a session clears all RLV restrictions that belong only to that session, clears all session variables and disables all behaviors relative to that session.
*Sessions that are not locked MUST be released after a reasonable timeout.
*Relay implementations MAY require an authed session for all <rlvcommand>'s, except @xxx=<channel_number>, @clear[=xxx] and @xxx=y/rem commands, which MUST always be accepted.
*@xxx=n/add <rlvcommand>'s, after being accepted, add a restriction and therefore Lock the session.
*Some metacommands described in x-tensions can also add restrictions and therefore Lock the session.
*!release, !version, !implversion, !x-orgversions and !x-.../clear[/...] commands are always accepted.
*!pong reactivates an existing session but never requires further auth, provided it is sent by the device to which ping was sent. The relay MUST resend to the viewer all stored restrictions belonging to the controlling device if they are not already active.
*Unless specified otherwise (see !x-who), no command can trigger an interactive dialog unless
:* they require an Authed session
:* and no session is currently open or it is open but not Authed yet.
*When releasing a Locked session, a relay MUST release all restrictions belonging to the device controlling the session.
*On the following events, a relay MUST release a locked session:
:* when the relay notices the controller has become unreachable,
:* wren the relay sends "release,<controller_key>,!release,ok" (due to acknowledging !release sent by the controller, or due to safewording triggered from the relay side).
*A relay MUST provide a mechanism for checking that every controlling device is reachable. It is not specified whether this checking process should be automatic or manually triggered.
*The absence of active restriction unlocks the session (and eventually releases it).
*A relay MUST remove restrictions from a session when (and only in these cases):
:* either the session controller specifically asks for the restriction to be released ("@restriction=y" "@restriction=rem", "@clear=restriction" for RLV restrictions, and "!x-restriction/clear/..." for LSL restrictions),
:* or the session closed (for instance !release coming from the device, or safeword).

===Controller requirements===
* A controller MUST not send anything on RLVR channel that is not a valid <c_msg>.
* A controller MUST, for each Locked session it controls, provide a mechanism that will unlock it in bounded time. (i.e.: either there is a menu that will release the victim, or there is a timer, or a menu should be able to start such a timer). At least one person MUST know what this mechanism is, and if it requires an action from someone else, be able to tell that other person what s/he has to do.

==Core meta-commands and associated mechanisms==

An ORG device MUST at least support the meta-commands !release, !pong, !version, !implversion and !x-orgversions described below and implement their associated mechanisms.

Particular meta-commands definitions and mechanisms may override general requirements above.

===!release===
Sent by a controller, this command closes the session.

* !release obviously opens no session, requires no Auth and is not Locking.
* If there is an actual session to close !release MUST be accepted by the relay and acknowledeged by "ok".
* On accepting !release, the relay erases all data pertaining to the session and disables all restrictions of the session.
* When a relay decides to close a session on its own (user safeword, for instance) and it is not due to the controller being unreachable, the relay must send the following acknowledgement message:
release,<controller_key>,!release,ok

When receiving the latter message, the controller should act accordingly, for instance by resetting itself and making itself ready for the next session.

Note that !release is not the same as @clear. @clear is interpreted by the relay as a RLV command and, as such, can only clear RLV restrictions. If RLV restrictions were the only restrictions of the session, then the session will be closed, but some x-tensions also define pure LSL based restrictions.

===ping/!pong===

The ping/!pong mechanism exists so that relays can check presence and responsiveness of a controller. This was primarily meant to be used on relay wearer relog, in order to reactivate all restrictions so that sessions persist on relog if the controller still exists and is ready to continue the session.

''!pong'' cannot require auth and does not lock a session

We call ''ping message'' a message from the relay, having the following syntax:
ping,<controller_key>,ping,ping
We call ''!pong message'' a message from the controller, having the following syntax:
ping,<relay_key>,!pong

====Relay side====
*A relay SHOULD NOT send an acknowledgement in response to ''!pong''.
*A ping message can be sent any time by the relay to a known controller.
*On wearer relog, for each existing Locked session, the relay must send a ping message to the session controller.
*When a !pong message is received from a controller, if it was a reply to a previous ping message:
:#if the session RLV restrictions contain unsit and the avatar was sitting on some object when the restriction was applied, then the relay MUST force the avatar to sit back on the same object (if still existing);
:#the relay MUST make sure all restrictions belonging to the session are made active again.
*If a ping message is sent and is not answered by the controller, then the relay closes the session.

Note that the relay is responsible for storing restrictions and the key of the sit target across sessions, not the controller.

====Controller side====
*Unless it does not matter that the relay could close the session (or for another reason, the controller knows the relay will not close it), a controller SHOULD listen to ping messages and answer any ping message with a !pong message.
*A controller should ignore ping requests from relays it is not ready to handle.

For instance, if the controller is a furniture which is already in use by another relay wearer, it would be inconsistant to let the pinging relay restore the restrictions without letting its wearer sit on the furniture. Or if the controller is not stateless and the state for the pinging relay has not been saved before, resuming the session from the initial state might be inconsistant.

===!version===
The purpose of this meta-command is to query the version of the RLVR protocol supported by a relay.

* !version opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !version with the version number of the RLVR protocol it supports ("1100" here, since ORG 0004 includes RLVR 1.100).

Note this is the most common command for a controller to scan for nearby relays, as non-ORG relays also accept this command and answer it the way described above.

===!implversion===
The purpose of this meta-command is to query the name and version of the relay implementation.

* !implversion opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !implversion with its implementation version string... which can be any string.

It is recommended this string includes the following elements:
* the relay name/brand/identifier,
* the version number of that relay name/brand/identifier,
* at the beginning, the string prefix "ORG=0004/"
The latter is convenient for checking for ORG compatibility using a command even non-ORG relay should understand.

===!x-orgversions===

This meta-command purpose it two-fold. First it allows a controlling device to ask a relay for the list of ORG x-tensions it supports, second it is similar to !version in RLVR protocol, as its reply gives the versions of the ORG core specification and ORG x-tensions that are implemented in the relay.

C<->R
-> query,rUUID,!x-orgversions
<- query,cUUID,!x-orgversions,ORG=0004/who=002/email=006

The acknowledgement string of the relay is a list separated by "/" whose items are of the form <package>=<version>. The first package is "ORG", the core specification of ORG relays, its version string is the version of the specification (4 digits). The other packages are ORG x-tension names (not meta-command names, as one x-tension can require several metacommands, thus the name does not include the prefix "!x-"), whose version string is 3 digits.

''Requirements for a relay:''
* The support of this metacommand is mandatory for an ORG relay.
* It is also required that the list of packages in the !x-orgversions reply includes the package "ORG" and the exact list of supported optional x-tensions.
* If several incompatible versions of an x-tension are supported, they must be listed ordered by version number. Ex: ORG=0004/who=002/email=005/email=006. If versions are backward compatible, it is necessary to report only the last one.

''Requirements for a controlling device:'' None. It is however recommended to use !x-orgversions when it makes sense for avoiding sending unsupported and useless metacommands later.

LSL Protocol/Restrained Love Open Relay Group/ORG Requirements/0004 draft

2011-06-27T13:12:35Z

Satomi Ahn: /* Relay side */

{{ORG_Restrained_Life_Relay_Specs_TOC}}
STATUS: draft

VERSION: 0004

==Summary==

This page is a list of requirements for a relay or an in-world device to have the right to be called "ORG compliant". It is mostly about adding support for an ORG-centered informational metacommand and specifying Marine Kelley's RLVR protocol a bit more that it is now, while of course preserving full compatibility.

For a quick overview of the motivations and general working of this protocol and a few examples, we refer the reader to [[LSL_Protocol/Restrained_Love_Relay/Specification|the original specification page by Marine Kelley]].

If you are making furniture, traps, or other RLVR controllers and you are not interested in what [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] can offer, then you can stick with the original specification by Marine Kelley and still be compatible with [[LSL_Protocol/Restrained_Love_Relay/Comparison|ORG relays]]. However, to have the right to call your controller "ORG compatible", there are still a few light additional requirements such as:
* using only [[llRegionSayTo]] for communications with the relay,
* not spamming the RLVR channel with messages that do not belong to the protocol,
* and remain responsive to ping messages at every time if you want the session to remain locked.

If you are interested in [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|ORG x-tensions]], then you should also read the part about [[#!x-orgversions|!x-orgversions]].

If you are making a relay, sorry we are afraid you will have to read all this page.

==Definition of an ORG device==

A RLVR device is compliant with ORG specifications if it implements the consolidated RLVR protocol described below along with the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] it announces supporting.

Note in particular that
* the consolidated protocol is backward compatible with [[LSL_Protocol/Restrained_Love_Relay/Specification|Marine Kelley's RLVR protocol version 1.100]] but resolves most loose ends of that document;
* ORG relays handle controller messages whose second field is ffffffff-ffff-ffff-ffff-ffffffffffff exactly the same as if it was the key of the wearer (NULL_KEY is a wildcard);
* one-to-one chat messages (not using a wildcard) are sent by using [[llRegionSayTo]] LSL function;
* there is an additional meta-command, !x-orgversions for a relay to announce supported x-tensions;
* each supported x-tension can imply other supported metacommands, ORG x-tensions meta-command all having names starting with prefix "!x-";
* other proprietary metacommands with prefix "!_-" (replace "_" by any letter that is not "x") can be supported;

Supported x-tensions can constrain the core specification (this document) even more, but cannot alter it or make it less constraining unless as a result of the relay executing a meta-command of this x-tension sent by the controller. Thus, although the protocol is extensible, a controller can always rely on the fact an ORG relay abides by the requirements in this document until it asks the relay to do otherwise.

ORG devices may be advertised by the use of the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/ORG_Logo|ORG logo]] for advertising compliance with ORG requirements. ORG devices makers are encouraged to do so.

==Consolidated RLVR protocol==

=== A few definitions ===

* The '''Restrained Love Relay (RLVR) protocol''' implies two partners (SL objects): the '''relay''' worn by the avatar commands are intended for, and a '''controller''', which sends commands to the relay.

* During an execution of the RLVR protocol, a relay and a controller establish a '''session''' together. A relay may manage several sessions with several controllers. Likewise, a controller could establish sessions with several relays.

* The goal of the protocol is to force the relay wearer to make perform actions and to toggle restrictions on their behavior. Both actions and restrictions can be enforced either through use of viewer hooks ([[LSL_Protocol/RestrainedLoveAPI|Restrained Love API]], or RLV) or through LSL scripting.

* Hence we distinguish between "'''RLV commands'''", starting with "@", which are commands following the syntax of the RLV API and which will ultimately be forwarded to the viewer, and "'''meta-commands'''", starting with "!", which are meant to be interpreted by LSL functions.

* Restrictions on a relay wearer are relative to a session. So are most other variables (authorization state, key of the controller, ... ).

* A session is '''Opened''' whenever the relay accepts a RLVR command from a controller.

* A session is '''Closed''' (or '''released''') as soon as the relay forgets every variables and releases all restrictions pertaining to that session.

* A session is '''Locked''' whenever it holds active restrictions.

* A session is '''Authed''' if the controller has been allowed to control the relay (not only store some variables with no consequence). Once authed, no interactive "ask" dialog should pop up anymore concerning this session. Most commands should now normally be accepted (and maybe a few automatically rejected).

* A controller is called '''reachable''' if it can receive messages from the relay and can prove it by answering ping requests from the relay. By "can", it is meant by the method of communication agreed upon by the relay and controller. By default the communication method is chat messages sent by llRegionSayTo. X-tensions such as email and delay can modify what is meant by reachable.

===Reminder of the protocol syntax and related notations===

RLVR protocol consists of messages exchanged on channel -1812221819 (called '''RLVR channel''') using the LSL function [[llRegionSayTo]].

A controller only sends messages (commands) whose syntax is described by the non-terminal <c_msg>. A relay only sends messages (acknowledgements) whose syntax is described by the non-terminal <r_msg>.

<c_msg> ::= IDENT "," KEY "," <commands>
<r_msg> ::= IDENT "," KEY "," <command> "," ACK
<commands> ::= <command> | <command> "|" <commands>
<command> ::= <rlvcommand> | <metacommand>
<rlvcommand> ::= "@" RLVCOMMAND
<metacommand> ::= "!" METACOMMANDNAME <metacommandarguments>
<metacommandarguments> ::= "" | "/" ARG <metacommandarguments>

where we explicit the different terminal tokens:
IDENT: any string without ","
KEY: any UUID
ACK: any string without ","
RLVCOMMAND: any string without ","
METACOMMANDNAME: any string without "/" and ","
ARG: any string without "/" and ","

===Relay requirements===
These requirements do apply by default but the behavior of the relay may be modified as a result of having executed some metacommand defined in an optional x-tension.

====Syntactical considerations====
'''Requirements:'''
*A relay MUST NOT send anything on RLVR channel that is not a valid <r_msg>.
*A relay MUST ignore any message on RLVR channel that is not a ","-list of 3 items and whose second item is not the key of the avatar wearing the relay or ffffffff-ffff-ffff-ffff-ffffffffffff.
When the relay receives a message meeting the above conditions and considering the 3rd item of the ","-list as a "|"-list of <command>s, then for every <command>:
* if the <command> is neither a valid <rlvcommand> or <metacommand>, the relay must ignore it and process the next <command>'s;
* if the <command> is a <rlvcommand> or a <metacommand>, the relay MUST send an acknowledgement message back to the controller.
* an acknowledgement message is a <r_msg> (see above) such that
:*IDENT is the same as IDENT in the <c_msg> being processed
:*KEY is the key of the controller who sent the <c_msg>
:*<command> is the subcommand being processed
:*ACK is a string called ''acknowledgement value''. By default the acknowledgement value is "ok" if the relay will execute the <command >, "ko" otherwise;
* every acknowledgement or message sent by the relay to one given controlling device must be issued by the same prim (so that the controlling device can restrict its listener to one source key) using the LSL function [[llRegionSayTo]].

'''Remarks:'''
* Many meta-commands may have other acknowledgements than "ok" or "ko" (or none, for !pong). Their definitions supersede this specification.
* Note that unknown meta-commands cannot be executed and thus wil be acknowledged by "ko".
* Known meta-commands which are sent with not enough parameters or parameters with types incompatible with those in the definition known by the relay also cannot be executed and will also be acknowledged by "ko". (ex: the relay knows !x-who/key, but receives !x-who/integer/string).

====Command handling====
'''Requirements:'''
* If a <rlvcommand> is acknowledged with value "ok", the relay ensures the viewer is affected the same way as if the LSL instruction llOwnerSay(<rlvcommand>) was executed by a script in a primitive that handles only one controller.
* When processing a <metacommand>, if the relay knows at least one definition of '!'+METACOMMANDNAME for which the received <metacommandarguments> provide enough parameters, then it will be handled according to the definition handling the most parameters among the latter. Extra parameters are ignored.
* When acknowledging a <metacommand> by anything else than "ko", the relay commits itself to execute it.

'''Remarks:'''
* For first requirement, it must be understood that the reference behavior is that the relay would have if it had one controller per prim. However handling several controllers from one unique prim is possible but requires taking care that different controllers do not interfere with each other, releasing each other's restrictions, for instance.
* For the second requirement, the word "handled" means that if the meta-command with these parameters is known, then requirements in known definition cannot be ignored. Sometimes, this can imply that the meta-command cannot be refused, for instance.

====Session related requirements:====
*Closing a session clears all RLV restrictions that belong only to that session, clears all session variables and disables all behaviors relative to that session.
*Sessions that are not locked MUST be released after a reasonable timeout.
*Relay implementations MAY require an authed session for all <rlvcommand>'s, except @xxx=<channel_number>, @clear[=xxx] and @xxx=y/rem commands, which MUST always be accepted.
*@xxx=n/add <rlvcommand>'s, after being accepted, add a restriction and therefore Lock the session.
*Some metacommands described in x-tensions can also add restrictions and therefore Lock the session.
*!release, !version, !implversion, !x-orgversions and !x-.../clear[/...] commands are always accepted.
*!pong reactivates an existing session but never requires further auth, provided it is sent by the device to which ping was sent. The relay MUST resend to the viewer all stored restrictions belonging to the controlling device if they are not already active.
*Unless specified otherwise (see !x-who), no command can trigger an interactive dialog unless
:* they require an Authed session
:* and no session is currently open or it is open but not Authed yet.
*When releasing a Locked session, a relay MUST release all restrictions belonging to the device controlling the session.
*On the following events, a relay MUST release a locked session:
:* when the relay notices the controller has become unreachable,
:* wren the relay sends "release,<controller_key>,!release,ok" (due to acknowledging !release sent by the controller, or due to safewording triggered from the relay side).
*A relay MUST provide a mechanism for checking that every controlling device is reachable. It is not specified whether this checking process should be automatic or manually triggered.
*The absence of active restriction unlocks the session (and eventually releases it).
*A relay MUST remove restrictions from a session when (and only in these cases):
:* either the session controller specifically asks for the restriction to be released ("@restriction=y" "@restriction=rem", "@clear=restriction" for RLV restrictions, and "!x-restriction/clear/..." for LSL restrictions),
:* or the session closed (for instance !release coming from the device, or safeword).

===Controller requirements===
* A controller MUST not send anything on RLVR channel that is not a valid <c_msg>.
* A controller MUST, for each Locked session it controls, provide a mechanism that will unlock it in bounded time. (i.e.: either there is a menu that will release the victim, or there is a timer, or a menu should be able to start such a timer). At least one person MUST know what this mechanism is, and if it requires an action from someone else, be able to tell that other person what s/he has to do.

==Core meta-commands and associated mechanisms==

An ORG device MUST at least support the meta-commands !release, !pong, !version, !implversion and !x-orgversions described below and implement their associated mechanisms.

Particular meta-commands definitions and mechanisms may override general requirements above.

===!release===
Sent by a controller, this command closes the session.

* !release obviously opens no session, requires no Auth and is not Locking.
* If there is an actual session to close !release MUST be accepted by the relay and acknowledeged by "ok".
* On accepting !release, the relay erases all data pertaining to the session and disables all restrictions of the session.
* When a relay decides to close a session on its own (user safeword, for instance) and it is not due to the controller being unreachable, the relay must send the following acknowledgement message:
release,<controller_key>,!release,ok

When receiving the latter message, the controller should act accordingly, for instance by resetting itself and making itself ready for the next session.

Note that !release is not the same as @clear. @clear is interpreted by the relay as a RLV command and, as such, can only clear RLV restrictions. If RLV restrictions were the only restrictions of the session, then the session will be closed, but some x-tensions also define pure LSL based restrictions.

===ping/!pong===

The ping/!pong mechanism exists so that relays can check presence and responsiveness of a controller. This was primarily meant to be used on relay wearer relog, in order to reactivate all restrictions so that sessions persist on relog if the controller still exists and is ready to continue the session.

''!pong'' cannot require auth and does not lock a session

We call ''ping message'' a message from the relay, having the following syntax:
ping,<controller_key>,ping,ping
We call ''!pong message'' a message from the controller, having the following syntax:
ping,<relay_key>,!pong

====Relay side====
*A relay SHOULD NOT send an acknowledgement in response to ''!pong''.
*A ping message can be sent any time by the relay to a known controller.
*On wearer relog, for each existing Locked session, the relay must send a ping message to the session controller.
*When a !pong message is received from a controller, if it was a reply to a previous ping message:
:#if the session RLV restrictions contain unsit and the avatar was sitting on some object when the restriction was applied, then the relay MUST force the avatar to sit back on the same object (if still existing);
:#the relay MUST make sure all restrictions belonging to the session are made active again.
*If a ping message is sent and is not answered by the controller, then the relay closes the session.

====Controller side====
*Unless it does not matter that the relay could close the session (or for another reason, the controller knows the relay will not close it), a controller SHOULD listen to ping messages and answer any ping message with a !pong message.
*A controller should ignore ping requests from relays it is not ready to handle.

For instance, if the controller is a furniture which is already in use by another relay wearer, it would be inconsistant to let the pinging relay restore the restrictions without letting its wearer sit on the furniture. Or if the controller is not stateless and the state for the pinging relay has not been saved before, resuming the session from the initial state might be inconsistant.

===!version===
The purpose of this meta-command is to query the version of the RLVR protocol supported by a relay.

* !version opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !version with the version number of the RLVR protocol it supports ("1100" here, since ORG 0004 includes RLVR 1.100).

Note this is the most common command for a controller to scan for nearby relays, as non-ORG relays also accept this command and answer it the way described above.

===!implversion===
The purpose of this meta-command is to query the name and version of the relay implementation.

* !implversion opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !implversion with its implementation version string... which can be any string.

It is recommended this string includes the following elements:
* the relay name/brand/identifier,
* the version number of that relay name/brand/identifier,
* at the beginning, the string prefix "ORG=0004/"
The latter is convenient for checking for ORG compatibility using a command even non-ORG relay should understand.

===!x-orgversions===

This meta-command purpose it two-fold. First it allows a controlling device to ask a relay for the list of ORG x-tensions it supports, second it is similar to !version in RLVR protocol, as its reply gives the versions of the ORG core specification and ORG x-tensions that are implemented in the relay.

C<->R
-> query,rUUID,!x-orgversions
<- query,cUUID,!x-orgversions,ORG=0004/who=002/email=006

The acknowledgement string of the relay is a list separated by "/" whose items are of the form <package>=<version>. The first package is "ORG", the core specification of ORG relays, its version string is the version of the specification (4 digits). The other packages are ORG x-tension names (not meta-command names, as one x-tension can require several metacommands, thus the name does not include the prefix "!x-"), whose version string is 3 digits.

''Requirements for a relay:''
* The support of this metacommand is mandatory for an ORG relay.
* It is also required that the list of packages in the !x-orgversions reply includes the package "ORG" and the exact list of supported optional x-tensions.
* If several incompatible versions of an x-tension are supported, they must be listed ordered by version number. Ex: ORG=0004/who=002/email=005/email=006. If versions are backward compatible, it is necessary to report only the last one.

''Requirements for a controlling device:'' None. It is however recommended to use !x-orgversions when it makes sense for avoiding sending unsupported and useless metacommands later.

LSL Protocol/Restrained Love Open Relay Group/ORG Requirements/0004 draft

2011-06-27T13:11:44Z

Satomi Ahn: /* Core meta-commands and associated mechanisms */

{{ORG_Restrained_Life_Relay_Specs_TOC}}
STATUS: draft

VERSION: 0004

==Summary==

This page is a list of requirements for a relay or an in-world device to have the right to be called "ORG compliant". It is mostly about adding support for an ORG-centered informational metacommand and specifying Marine Kelley's RLVR protocol a bit more that it is now, while of course preserving full compatibility.

For a quick overview of the motivations and general working of this protocol and a few examples, we refer the reader to [[LSL_Protocol/Restrained_Love_Relay/Specification|the original specification page by Marine Kelley]].

If you are making furniture, traps, or other RLVR controllers and you are not interested in what [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] can offer, then you can stick with the original specification by Marine Kelley and still be compatible with [[LSL_Protocol/Restrained_Love_Relay/Comparison|ORG relays]]. However, to have the right to call your controller "ORG compatible", there are still a few light additional requirements such as:
* using only [[llRegionSayTo]] for communications with the relay,
* not spamming the RLVR channel with messages that do not belong to the protocol,
* and remain responsive to ping messages at every time if you want the session to remain locked.

If you are interested in [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|ORG x-tensions]], then you should also read the part about [[#!x-orgversions|!x-orgversions]].

If you are making a relay, sorry we are afraid you will have to read all this page.

==Definition of an ORG device==

A RLVR device is compliant with ORG specifications if it implements the consolidated RLVR protocol described below along with the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] it announces supporting.

Note in particular that
* the consolidated protocol is backward compatible with [[LSL_Protocol/Restrained_Love_Relay/Specification|Marine Kelley's RLVR protocol version 1.100]] but resolves most loose ends of that document;
* ORG relays handle controller messages whose second field is ffffffff-ffff-ffff-ffff-ffffffffffff exactly the same as if it was the key of the wearer (NULL_KEY is a wildcard);
* one-to-one chat messages (not using a wildcard) are sent by using [[llRegionSayTo]] LSL function;
* there is an additional meta-command, !x-orgversions for a relay to announce supported x-tensions;
* each supported x-tension can imply other supported metacommands, ORG x-tensions meta-command all having names starting with prefix "!x-";
* other proprietary metacommands with prefix "!_-" (replace "_" by any letter that is not "x") can be supported;

Supported x-tensions can constrain the core specification (this document) even more, but cannot alter it or make it less constraining unless as a result of the relay executing a meta-command of this x-tension sent by the controller. Thus, although the protocol is extensible, a controller can always rely on the fact an ORG relay abides by the requirements in this document until it asks the relay to do otherwise.

ORG devices may be advertised by the use of the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/ORG_Logo|ORG logo]] for advertising compliance with ORG requirements. ORG devices makers are encouraged to do so.

==Consolidated RLVR protocol==

=== A few definitions ===

* The '''Restrained Love Relay (RLVR) protocol''' implies two partners (SL objects): the '''relay''' worn by the avatar commands are intended for, and a '''controller''', which sends commands to the relay.

* During an execution of the RLVR protocol, a relay and a controller establish a '''session''' together. A relay may manage several sessions with several controllers. Likewise, a controller could establish sessions with several relays.

* The goal of the protocol is to force the relay wearer to make perform actions and to toggle restrictions on their behavior. Both actions and restrictions can be enforced either through use of viewer hooks ([[LSL_Protocol/RestrainedLoveAPI|Restrained Love API]], or RLV) or through LSL scripting.

* Hence we distinguish between "'''RLV commands'''", starting with "@", which are commands following the syntax of the RLV API and which will ultimately be forwarded to the viewer, and "'''meta-commands'''", starting with "!", which are meant to be interpreted by LSL functions.

* Restrictions on a relay wearer are relative to a session. So are most other variables (authorization state, key of the controller, ... ).

* A session is '''Opened''' whenever the relay accepts a RLVR command from a controller.

* A session is '''Closed''' (or '''released''') as soon as the relay forgets every variables and releases all restrictions pertaining to that session.

* A session is '''Locked''' whenever it holds active restrictions.

* A session is '''Authed''' if the controller has been allowed to control the relay (not only store some variables with no consequence). Once authed, no interactive "ask" dialog should pop up anymore concerning this session. Most commands should now normally be accepted (and maybe a few automatically rejected).

* A controller is called '''reachable''' if it can receive messages from the relay and can prove it by answering ping requests from the relay. By "can", it is meant by the method of communication agreed upon by the relay and controller. By default the communication method is chat messages sent by llRegionSayTo. X-tensions such as email and delay can modify what is meant by reachable.

===Reminder of the protocol syntax and related notations===

RLVR protocol consists of messages exchanged on channel -1812221819 (called '''RLVR channel''') using the LSL function [[llRegionSayTo]].

A controller only sends messages (commands) whose syntax is described by the non-terminal <c_msg>. A relay only sends messages (acknowledgements) whose syntax is described by the non-terminal <r_msg>.

<c_msg> ::= IDENT "," KEY "," <commands>
<r_msg> ::= IDENT "," KEY "," <command> "," ACK
<commands> ::= <command> | <command> "|" <commands>
<command> ::= <rlvcommand> | <metacommand>
<rlvcommand> ::= "@" RLVCOMMAND
<metacommand> ::= "!" METACOMMANDNAME <metacommandarguments>
<metacommandarguments> ::= "" | "/" ARG <metacommandarguments>

where we explicit the different terminal tokens:
IDENT: any string without ","
KEY: any UUID
ACK: any string without ","
RLVCOMMAND: any string without ","
METACOMMANDNAME: any string without "/" and ","
ARG: any string without "/" and ","

===Relay requirements===
These requirements do apply by default but the behavior of the relay may be modified as a result of having executed some metacommand defined in an optional x-tension.

====Syntactical considerations====
'''Requirements:'''
*A relay MUST NOT send anything on RLVR channel that is not a valid <r_msg>.
*A relay MUST ignore any message on RLVR channel that is not a ","-list of 3 items and whose second item is not the key of the avatar wearing the relay or ffffffff-ffff-ffff-ffff-ffffffffffff.
When the relay receives a message meeting the above conditions and considering the 3rd item of the ","-list as a "|"-list of <command>s, then for every <command>:
* if the <command> is neither a valid <rlvcommand> or <metacommand>, the relay must ignore it and process the next <command>'s;
* if the <command> is a <rlvcommand> or a <metacommand>, the relay MUST send an acknowledgement message back to the controller.
* an acknowledgement message is a <r_msg> (see above) such that
:*IDENT is the same as IDENT in the <c_msg> being processed
:*KEY is the key of the controller who sent the <c_msg>
:*<command> is the subcommand being processed
:*ACK is a string called ''acknowledgement value''. By default the acknowledgement value is "ok" if the relay will execute the <command >, "ko" otherwise;
* every acknowledgement or message sent by the relay to one given controlling device must be issued by the same prim (so that the controlling device can restrict its listener to one source key) using the LSL function [[llRegionSayTo]].

'''Remarks:'''
* Many meta-commands may have other acknowledgements than "ok" or "ko" (or none, for !pong). Their definitions supersede this specification.
* Note that unknown meta-commands cannot be executed and thus wil be acknowledged by "ko".
* Known meta-commands which are sent with not enough parameters or parameters with types incompatible with those in the definition known by the relay also cannot be executed and will also be acknowledged by "ko". (ex: the relay knows !x-who/key, but receives !x-who/integer/string).

====Command handling====
'''Requirements:'''
* If a <rlvcommand> is acknowledged with value "ok", the relay ensures the viewer is affected the same way as if the LSL instruction llOwnerSay(<rlvcommand>) was executed by a script in a primitive that handles only one controller.
* When processing a <metacommand>, if the relay knows at least one definition of '!'+METACOMMANDNAME for which the received <metacommandarguments> provide enough parameters, then it will be handled according to the definition handling the most parameters among the latter. Extra parameters are ignored.
* When acknowledging a <metacommand> by anything else than "ko", the relay commits itself to execute it.

'''Remarks:'''
* For first requirement, it must be understood that the reference behavior is that the relay would have if it had one controller per prim. However handling several controllers from one unique prim is possible but requires taking care that different controllers do not interfere with each other, releasing each other's restrictions, for instance.
* For the second requirement, the word "handled" means that if the meta-command with these parameters is known, then requirements in known definition cannot be ignored. Sometimes, this can imply that the meta-command cannot be refused, for instance.

====Session related requirements:====
*Closing a session clears all RLV restrictions that belong only to that session, clears all session variables and disables all behaviors relative to that session.
*Sessions that are not locked MUST be released after a reasonable timeout.
*Relay implementations MAY require an authed session for all <rlvcommand>'s, except @xxx=<channel_number>, @clear[=xxx] and @xxx=y/rem commands, which MUST always be accepted.
*@xxx=n/add <rlvcommand>'s, after being accepted, add a restriction and therefore Lock the session.
*Some metacommands described in x-tensions can also add restrictions and therefore Lock the session.
*!release, !version, !implversion, !x-orgversions and !x-.../clear[/...] commands are always accepted.
*!pong reactivates an existing session but never requires further auth, provided it is sent by the device to which ping was sent. The relay MUST resend to the viewer all stored restrictions belonging to the controlling device if they are not already active.
*Unless specified otherwise (see !x-who), no command can trigger an interactive dialog unless
:* they require an Authed session
:* and no session is currently open or it is open but not Authed yet.
*When releasing a Locked session, a relay MUST release all restrictions belonging to the device controlling the session.
*On the following events, a relay MUST release a locked session:
:* when the relay notices the controller has become unreachable,
:* wren the relay sends "release,<controller_key>,!release,ok" (due to acknowledging !release sent by the controller, or due to safewording triggered from the relay side).
*A relay MUST provide a mechanism for checking that every controlling device is reachable. It is not specified whether this checking process should be automatic or manually triggered.
*The absence of active restriction unlocks the session (and eventually releases it).
*A relay MUST remove restrictions from a session when (and only in these cases):
:* either the session controller specifically asks for the restriction to be released ("@restriction=y" "@restriction=rem", "@clear=restriction" for RLV restrictions, and "!x-restriction/clear/..." for LSL restrictions),
:* or the session closed (for instance !release coming from the device, or safeword).

===Controller requirements===
* A controller MUST not send anything on RLVR channel that is not a valid <c_msg>.
* A controller MUST, for each Locked session it controls, provide a mechanism that will unlock it in bounded time. (i.e.: either there is a menu that will release the victim, or there is a timer, or a menu should be able to start such a timer). At least one person MUST know what this mechanism is, and if it requires an action from someone else, be able to tell that other person what s/he has to do.

==Core meta-commands and associated mechanisms==

An ORG device MUST at least support the meta-commands !release, !pong, !version, !implversion and !x-orgversions described below and implement their associated mechanisms.

Particular meta-commands definitions and mechanisms may override general requirements above.

===!release===
Sent by a controller, this command closes the session.

* !release obviously opens no session, requires no Auth and is not Locking.
* If there is an actual session to close !release MUST be accepted by the relay and acknowledeged by "ok".
* On accepting !release, the relay erases all data pertaining to the session and disables all restrictions of the session.
* When a relay decides to close a session on its own (user safeword, for instance) and it is not due to the controller being unreachable, the relay must send the following acknowledgement message:
release,<controller_key>,!release,ok

When receiving the latter message, the controller should act accordingly, for instance by resetting itself and making itself ready for the next session.

Note that !release is not the same as @clear. @clear is interpreted by the relay as a RLV command and, as such, can only clear RLV restrictions. If RLV restrictions were the only restrictions of the session, then the session will be closed, but some x-tensions also define pure LSL based restrictions.

===ping/!pong===

The ping/!pong mechanism exists so that relays can check presence and responsiveness of a controller. This was primarily meant to be used on relay wearer relog, in order to reactivate all restrictions so that sessions persist on relog if the controller still exists and is ready to continue the session.

''!pong'' cannot require auth and does not lock a session

We call ''ping message'' a message from the relay, having the following syntax:
ping,<controller_key>,ping,ping
We call ''!pong message'' a message from the controller, having the following syntax:
ping,<relay_key>,!pong

====Relay side====
*A relay SHOULD NOT send an acknowledgement in response to ''!pong''.
*A ping message can be sent any time by the relay to a known controller (in contrary to other acknowlegement messages that are always replies to controller commands).
*On wearer relog, for each existing Locked session, the relay must send a ping message to the session controller.
*When a !pong message is received from a controller, if it was a reply to a previous ping message:
:#if the session RLV restrictions contain unsit and the avatar was sitting on some object when the restriction was applied, then the relay MUST force the avatar to sit back on the same object (if still existing);
:#the relay MUST make sure all restrictions belonging to the session are made active again.
*If a ping message is sent and is not answered by the controller, then the relay closes the session.

====Controller side====
*Unless it does not matter that the relay could close the session (or for another reason, the controller knows the relay will not close it), a controller SHOULD listen to ping messages and answer any ping message with a !pong message.
*A controller should ignore ping requests from relays it is not ready to handle.

For instance, if the controller is a furniture which is already in use by another relay wearer, it would be inconsistant to let the pinging relay restore the restrictions without letting its wearer sit on the furniture. Or if the controller is not stateless and the state for the pinging relay has not been saved before, resuming the session from the initial state might be inconsistant.

===!version===
The purpose of this meta-command is to query the version of the RLVR protocol supported by a relay.

* !version opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !version with the version number of the RLVR protocol it supports ("1100" here, since ORG 0004 includes RLVR 1.100).

Note this is the most common command for a controller to scan for nearby relays, as non-ORG relays also accept this command and answer it the way described above.

===!implversion===
The purpose of this meta-command is to query the name and version of the relay implementation.

* !implversion opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !implversion with its implementation version string... which can be any string.

It is recommended this string includes the following elements:
* the relay name/brand/identifier,
* the version number of that relay name/brand/identifier,
* at the beginning, the string prefix "ORG=0004/"
The latter is convenient for checking for ORG compatibility using a command even non-ORG relay should understand.

===!x-orgversions===

This meta-command purpose it two-fold. First it allows a controlling device to ask a relay for the list of ORG x-tensions it supports, second it is similar to !version in RLVR protocol, as its reply gives the versions of the ORG core specification and ORG x-tensions that are implemented in the relay.

C<->R
-> query,rUUID,!x-orgversions
<- query,cUUID,!x-orgversions,ORG=0004/who=002/email=006

The acknowledgement string of the relay is a list separated by "/" whose items are of the form <package>=<version>. The first package is "ORG", the core specification of ORG relays, its version string is the version of the specification (4 digits). The other packages are ORG x-tension names (not meta-command names, as one x-tension can require several metacommands, thus the name does not include the prefix "!x-"), whose version string is 3 digits.

''Requirements for a relay:''
* The support of this metacommand is mandatory for an ORG relay.
* It is also required that the list of packages in the !x-orgversions reply includes the package "ORG" and the exact list of supported optional x-tensions.
* If several incompatible versions of an x-tension are supported, they must be listed ordered by version number. Ex: ORG=0004/who=002/email=005/email=006. If versions are backward compatible, it is necessary to report only the last one.

''Requirements for a controlling device:'' None. It is however recommended to use !x-orgversions when it makes sense for avoiding sending unsupported and useless metacommands later.

LSL Protocol/Restrained Love Open Relay Group/ORG Requirements/0004 draft

2011-06-27T13:10:44Z

Satomi Ahn: /* Core meta-commands */

{{ORG_Restrained_Life_Relay_Specs_TOC}}
STATUS: draft

VERSION: 0004

==Summary==

This page is a list of requirements for a relay or an in-world device to have the right to be called "ORG compliant". It is mostly about adding support for an ORG-centered informational metacommand and specifying Marine Kelley's RLVR protocol a bit more that it is now, while of course preserving full compatibility.

For a quick overview of the motivations and general working of this protocol and a few examples, we refer the reader to [[LSL_Protocol/Restrained_Love_Relay/Specification|the original specification page by Marine Kelley]].

If you are making furniture, traps, or other RLVR controllers and you are not interested in what [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] can offer, then you can stick with the original specification by Marine Kelley and still be compatible with [[LSL_Protocol/Restrained_Love_Relay/Comparison|ORG relays]]. However, to have the right to call your controller "ORG compatible", there are still a few light additional requirements such as:
* using only [[llRegionSayTo]] for communications with the relay,
* not spamming the RLVR channel with messages that do not belong to the protocol,
* and remain responsive to ping messages at every time if you want the session to remain locked.

If you are interested in [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|ORG x-tensions]], then you should also read the part about [[#!x-orgversions|!x-orgversions]].

If you are making a relay, sorry we are afraid you will have to read all this page.

==Definition of an ORG device==

A RLVR device is compliant with ORG specifications if it implements the consolidated RLVR protocol described below along with the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/x-tensions|optional ORG x-tensions]] it announces supporting.

Note in particular that
* the consolidated protocol is backward compatible with [[LSL_Protocol/Restrained_Love_Relay/Specification|Marine Kelley's RLVR protocol version 1.100]] but resolves most loose ends of that document;
* ORG relays handle controller messages whose second field is ffffffff-ffff-ffff-ffff-ffffffffffff exactly the same as if it was the key of the wearer (NULL_KEY is a wildcard);
* one-to-one chat messages (not using a wildcard) are sent by using [[llRegionSayTo]] LSL function;
* there is an additional meta-command, !x-orgversions for a relay to announce supported x-tensions;
* each supported x-tension can imply other supported metacommands, ORG x-tensions meta-command all having names starting with prefix "!x-";
* other proprietary metacommands with prefix "!_-" (replace "_" by any letter that is not "x") can be supported;

Supported x-tensions can constrain the core specification (this document) even more, but cannot alter it or make it less constraining unless as a result of the relay executing a meta-command of this x-tension sent by the controller. Thus, although the protocol is extensible, a controller can always rely on the fact an ORG relay abides by the requirements in this document until it asks the relay to do otherwise.

ORG devices may be advertised by the use of the [[LSL_Protocol/Restrained_Love_Open_Relay_Group/ORG_Logo|ORG logo]] for advertising compliance with ORG requirements. ORG devices makers are encouraged to do so.

==Consolidated RLVR protocol==

=== A few definitions ===

* The '''Restrained Love Relay (RLVR) protocol''' implies two partners (SL objects): the '''relay''' worn by the avatar commands are intended for, and a '''controller''', which sends commands to the relay.

* During an execution of the RLVR protocol, a relay and a controller establish a '''session''' together. A relay may manage several sessions with several controllers. Likewise, a controller could establish sessions with several relays.

* The goal of the protocol is to force the relay wearer to make perform actions and to toggle restrictions on their behavior. Both actions and restrictions can be enforced either through use of viewer hooks ([[LSL_Protocol/RestrainedLoveAPI|Restrained Love API]], or RLV) or through LSL scripting.

* Hence we distinguish between "'''RLV commands'''", starting with "@", which are commands following the syntax of the RLV API and which will ultimately be forwarded to the viewer, and "'''meta-commands'''", starting with "!", which are meant to be interpreted by LSL functions.

* Restrictions on a relay wearer are relative to a session. So are most other variables (authorization state, key of the controller, ... ).

* A session is '''Opened''' whenever the relay accepts a RLVR command from a controller.

* A session is '''Closed''' (or '''released''') as soon as the relay forgets every variables and releases all restrictions pertaining to that session.

* A session is '''Locked''' whenever it holds active restrictions.

* A session is '''Authed''' if the controller has been allowed to control the relay (not only store some variables with no consequence). Once authed, no interactive "ask" dialog should pop up anymore concerning this session. Most commands should now normally be accepted (and maybe a few automatically rejected).

* A controller is called '''reachable''' if it can receive messages from the relay and can prove it by answering ping requests from the relay. By "can", it is meant by the method of communication agreed upon by the relay and controller. By default the communication method is chat messages sent by llRegionSayTo. X-tensions such as email and delay can modify what is meant by reachable.

===Reminder of the protocol syntax and related notations===

RLVR protocol consists of messages exchanged on channel -1812221819 (called '''RLVR channel''') using the LSL function [[llRegionSayTo]].

A controller only sends messages (commands) whose syntax is described by the non-terminal <c_msg>. A relay only sends messages (acknowledgements) whose syntax is described by the non-terminal <r_msg>.

<c_msg> ::= IDENT "," KEY "," <commands>
<r_msg> ::= IDENT "," KEY "," <command> "," ACK
<commands> ::= <command> | <command> "|" <commands>
<command> ::= <rlvcommand> | <metacommand>
<rlvcommand> ::= "@" RLVCOMMAND
<metacommand> ::= "!" METACOMMANDNAME <metacommandarguments>
<metacommandarguments> ::= "" | "/" ARG <metacommandarguments>

where we explicit the different terminal tokens:
IDENT: any string without ","
KEY: any UUID
ACK: any string without ","
RLVCOMMAND: any string without ","
METACOMMANDNAME: any string without "/" and ","
ARG: any string without "/" and ","

===Relay requirements===
These requirements do apply by default but the behavior of the relay may be modified as a result of having executed some metacommand defined in an optional x-tension.

====Syntactical considerations====
'''Requirements:'''
*A relay MUST NOT send anything on RLVR channel that is not a valid <r_msg>.
*A relay MUST ignore any message on RLVR channel that is not a ","-list of 3 items and whose second item is not the key of the avatar wearing the relay or ffffffff-ffff-ffff-ffff-ffffffffffff.
When the relay receives a message meeting the above conditions and considering the 3rd item of the ","-list as a "|"-list of <command>s, then for every <command>:
* if the <command> is neither a valid <rlvcommand> or <metacommand>, the relay must ignore it and process the next <command>'s;
* if the <command> is a <rlvcommand> or a <metacommand>, the relay MUST send an acknowledgement message back to the controller.
* an acknowledgement message is a <r_msg> (see above) such that
:*IDENT is the same as IDENT in the <c_msg> being processed
:*KEY is the key of the controller who sent the <c_msg>
:*<command> is the subcommand being processed
:*ACK is a string called ''acknowledgement value''. By default the acknowledgement value is "ok" if the relay will execute the <command >, "ko" otherwise;
* every acknowledgement or message sent by the relay to one given controlling device must be issued by the same prim (so that the controlling device can restrict its listener to one source key) using the LSL function [[llRegionSayTo]].

'''Remarks:'''
* Many meta-commands may have other acknowledgements than "ok" or "ko" (or none, for !pong). Their definitions supersede this specification.
* Note that unknown meta-commands cannot be executed and thus wil be acknowledged by "ko".
* Known meta-commands which are sent with not enough parameters or parameters with types incompatible with those in the definition known by the relay also cannot be executed and will also be acknowledged by "ko". (ex: the relay knows !x-who/key, but receives !x-who/integer/string).

====Command handling====
'''Requirements:'''
* If a <rlvcommand> is acknowledged with value "ok", the relay ensures the viewer is affected the same way as if the LSL instruction llOwnerSay(<rlvcommand>) was executed by a script in a primitive that handles only one controller.
* When processing a <metacommand>, if the relay knows at least one definition of '!'+METACOMMANDNAME for which the received <metacommandarguments> provide enough parameters, then it will be handled according to the definition handling the most parameters among the latter. Extra parameters are ignored.
* When acknowledging a <metacommand> by anything else than "ko", the relay commits itself to execute it.

'''Remarks:'''
* For first requirement, it must be understood that the reference behavior is that the relay would have if it had one controller per prim. However handling several controllers from one unique prim is possible but requires taking care that different controllers do not interfere with each other, releasing each other's restrictions, for instance.
* For the second requirement, the word "handled" means that if the meta-command with these parameters is known, then requirements in known definition cannot be ignored. Sometimes, this can imply that the meta-command cannot be refused, for instance.

====Session related requirements:====
*Closing a session clears all RLV restrictions that belong only to that session, clears all session variables and disables all behaviors relative to that session.
*Sessions that are not locked MUST be released after a reasonable timeout.
*Relay implementations MAY require an authed session for all <rlvcommand>'s, except @xxx=<channel_number>, @clear[=xxx] and @xxx=y/rem commands, which MUST always be accepted.
*@xxx=n/add <rlvcommand>'s, after being accepted, add a restriction and therefore Lock the session.
*Some metacommands described in x-tensions can also add restrictions and therefore Lock the session.
*!release, !version, !implversion, !x-orgversions and !x-.../clear[/...] commands are always accepted.
*!pong reactivates an existing session but never requires further auth, provided it is sent by the device to which ping was sent. The relay MUST resend to the viewer all stored restrictions belonging to the controlling device if they are not already active.
*Unless specified otherwise (see !x-who), no command can trigger an interactive dialog unless
:* they require an Authed session
:* and no session is currently open or it is open but not Authed yet.
*When releasing a Locked session, a relay MUST release all restrictions belonging to the device controlling the session.
*On the following events, a relay MUST release a locked session:
:* when the relay notices the controller has become unreachable,
:* wren the relay sends "release,<controller_key>,!release,ok" (due to acknowledging !release sent by the controller, or due to safewording triggered from the relay side).
*A relay MUST provide a mechanism for checking that every controlling device is reachable. It is not specified whether this checking process should be automatic or manually triggered.
*The absence of active restriction unlocks the session (and eventually releases it).
*A relay MUST remove restrictions from a session when (and only in these cases):
:* either the session controller specifically asks for the restriction to be released ("@restriction=y" "@restriction=rem", "@clear=restriction" for RLV restrictions, and "!x-restriction/clear/..." for LSL restrictions),
:* or the session closed (for instance !release coming from the device, or safeword).

===Controller requirements===
* A controller MUST not send anything on RLVR channel that is not a valid <c_msg>.
* A controller MUST, for each Locked session it controls, provide a mechanism that will unlock it in bounded time. (i.e.: either there is a menu that will release the victim, or there is a timer, or a menu should be able to start such a timer). At least one person MUST know what this mechanism is, and if it requires an action from someone else, be able to tell that other person what s/he has to do.

==Core meta-commands and associated mechanisms==

An ORG relay MUST at least support the meta-commands !release, !pong, !version, !implversion and !x-orgversions described below and implement their associated mechanisms.

Particular meta-commands definitions and mechanisms may override general requirements above.

===!release===
Sent by a controller, this command closes the session.

* !release obviously opens no session, requires no Auth and is not Locking.
* If there is an actual session to close !release MUST be accepted by the relay and acknowledeged by "ok".
* On accepting !release, the relay erases all data pertaining to the session and disables all restrictions of the session.
* When a relay decides to close a session on its own (user safeword, for instance) and it is not due to the controller being unreachable, the relay must send the following acknowledgement message:
release,<controller_key>,!release,ok

When receiving the latter message, the controller should act accordingly, for instance by resetting itself and making itself ready for the next session.

Note that !release is not the same as @clear. @clear is interpreted by the relay as a RLV command and, as such, can only clear RLV restrictions. If RLV restrictions were the only restrictions of the session, then the session will be closed, but some x-tensions also define pure LSL based restrictions.

===ping/!pong===

The ping/!pong mechanism exists so that relays can check presence and responsiveness of a controller. This was primarily meant to be used on relay wearer relog, in order to reactivate all restrictions so that sessions persist on relog if the controller still exists and is ready to continue the session.

''!pong'' cannot require auth and does not lock a session

We call ''ping message'' a message from the relay, having the following syntax:
ping,<controller_key>,ping,ping
We call ''!pong message'' a message from the controller, having the following syntax:
ping,<relay_key>,!pong

====Relay side====
*A relay SHOULD NOT send an acknowledgement in response to ''!pong''.
*A ping message can be sent any time by the relay to a known controller (in contrary to other acknowlegement messages that are always replies to controller commands).
*On wearer relog, for each existing Locked session, the relay must send a ping message to the session controller.
*When a !pong message is received from a controller, if it was a reply to a previous ping message:
:#if the session RLV restrictions contain unsit and the avatar was sitting on some object when the restriction was applied, then the relay MUST force the avatar to sit back on the same object (if still existing);
:#the relay MUST make sure all restrictions belonging to the session are made active again.
*If a ping message is sent and is not answered by the controller, then the relay closes the session.

====Controller side====
*Unless it does not matter that the relay could close the session (or for another reason, the controller knows the relay will not close it), a controller SHOULD listen to ping messages and answer any ping message with a !pong message.
*A controller should ignore ping requests from relays it is not ready to handle.

For instance, if the controller is a furniture which is already in use by another relay wearer, it would be inconsistant to let the pinging relay restore the restrictions without letting its wearer sit on the furniture. Or if the controller is not stateless and the state for the pinging relay has not been saved before, resuming the session from the initial state might be inconsistant.

===!version===
The purpose of this meta-command is to query the version of the RLVR protocol supported by a relay.

* !version opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !version with the version number of the RLVR protocol it supports ("1100" here, since ORG 0004 includes RLVR 1.100).

Note this is the most common command for a controller to scan for nearby relays, as non-ORG relays also accept this command and answer it the way described above.

===!implversion===
The purpose of this meta-command is to query the name and version of the relay implementation.

* !implversion opens no session (and requires no auth, neither can lock a session)
* A relay MUST always acknowledge !implversion with its implementation version string... which can be any string.

It is recommended this string includes the following elements:
* the relay name/brand/identifier,
* the version number of that relay name/brand/identifier,
* at the beginning, the string prefix "ORG=0004/"
The latter is convenient for checking for ORG compatibility using a command even non-ORG relay should understand.

===!x-orgversions===

This meta-command purpose it two-fold. First it allows a controlling device to ask a relay for the list of ORG x-tensions it supports, second it is similar to !version in RLVR protocol, as its reply gives the versions of the ORG core specification and ORG x-tensions that are implemented in the relay.

C<->R
-> query,rUUID,!x-orgversions
<- query,cUUID,!x-orgversions,ORG=0004/who=002/email=006

The acknowledgement string of the relay is a list separated by "/" whose items are of the form <package>=<version>. The first package is "ORG", the core specification of ORG relays, its version string is the version of the specification (4 digits). The other packages are ORG x-tension names (not meta-command names, as one x-tension can require several metacommands, thus the name does not include the prefix "!x-"), whose version string is 3 digits.

''Requirements for a relay:''
* The support of this metacommand is mandatory for an ORG relay.
* It is also required that the list of packages in the !x-orgversions reply includes the package "ORG" and the exact list of supported optional x-tensions.
* If several incompatible versions of an x-tension are supported, they must be listed ordered by version number. Ex: ORG=0004/who=002/email=005/email=006. If versions are backward compatible, it is necessary to report only the last one.

''Requirements for a controlling device:'' None. It is however recommended to use !x-orgversions when it makes sense for avoiding sending unsupported and useless metacommands later.