Difference between revisions of "LSL Protocol/Restrained Love Open Relay Group/sensor"

From Second Life Wiki
Jump to: navigation, search
 
(27 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
{{ ORG Restrained Life Relay Specs TOC }}
 
= sensor =
 
= sensor =
  
 
STATUS: draft
 
STATUS: draft
  
version: 001
+
version: 002
 +
 
 +
''version 001 implemented in Dahlia's multirelay 1.2.14 and anythingRLV3.6RC8''
 +
 
 +
* A unique command !x-sensor allowing to do remote llSensor()
 +
 
 +
* The main difference between 001 and 002 is the use of llEscapeURL()/llUnEscapeURL() to encode strings.
  
 
==Description of !x-sensor==
 
==Description of !x-sensor==
  
 +
=== '''(DEPRECATED)''' Syntax with optional parameter full===
  
===Syntax===
+
The parameters are the same as for the LSL command llSensor(string name, key id, integer type, float range, float arc), with an additional optional parameter "full".
  
The parameters are the same as for the LSL command llSensor(string name, key id, integer type, float range, float arc). The ack contains a list of uuid keys, or nosensor if nothing is detected. No other ack is possible.
+
* The acknowledgment of receipt contains a non empty list of uuid keys without the parameter "full".
 +
 
 +
* With the additional parameter, the list of uuid keys is followed by the list of the lengths of the names and the last item of the list is the concatenation of these names.  The null key 00000000-0000-0000-0000-000000000000 must be returned if nothing is detected.
 +
 
 +
* Example of acknowledgment of receipt with the parameter "full":
 +
''97116a5b-686b-64a9-a086-cae72a95ce6b,ccb7ce46-eec4-e790-9995-47d789adfe49,l1,l2,Object1Object2''
 +
i.e. two uuid keys, two integers which are the lengths of the strings Object1 and Object2 and the concatenation of Object1 and Object2.
 +
 
 +
* The source must be previously accepted by the relay to avoid a bad use of this command; a griefer for example could use it, together with the wildcard, to cause lag in a sim. Even if the command !x-sensor is not a restriction to be saved. So "ko" must be returned in that case.
 +
 
 +
No other acknowledgment of receipt is possible.
  
 
Two examples with
 
Two examples with
* C being the RLV controller
+
* C being the RLV controller which is a grabber (i.e. it already sent a restriction to the relay, accepted by the relay)
 
* R being the RLV relay
 
* R being the RLV relay
  
  C-->R  !x-sensor/name/id/type/range/arc
+
  C-->R  sensor,!x-sensor//nullkey/3/20.0/3.141593
  C<--R  !x-sensor/name/id/type/range/arc,97116a5b-686b-64a9-a086-cae72a95ce6b,ccb7ce46-eec4-e790-9995-47d789adfe49
+
  C<--R  sensor,!x-sensor//nullkey/3/20.0/3.141593,97116a5b-686b-64a9-a086-cae72a95ce6b,ccb7ce46-eec4-e790-9995-47d789adfe49,
  
  C-->R  !x-sensor/name/id/type/range/arc
+
  C-->R  sensor,!x-sensor//nullkey/3/20.0/3.141593
  C<--R  !x-sensor/name/id/type/range/arc,nosensor
+
  C<--R  sensor,!x-sensor//nullkey/3/20.0/3.141593,00000000-0000-0000-0000-000000000000
  
* Is it possible to detect 00000000-0000-0000-0000-000000000000 ? If not, maybe the ack nosensor could be replaced by 00000000-0000-0000-0000-000000000000. Or maybe by the wildcard = ffffffff-ffff-ffff-ffff-ffffffffffff ?
+
C-->R  sensor,!x-sensor//nullkey/3/20.0/3.141593/full
 +
C<--R  sensor,!x-sensor//nullkey/3/20.0/3.141593/full,97116a5b-686b-64a9-a086-cae72a95ce6b,ccb7ce46-eec4-e790-9995-47d789adfe49,l1,l2,Object1Object2
 +
 
 +
C-->R  sensor,!x-sensor//nullkey/3/20.0/3.141593/full
 +
C<--R  sensor,!x-sensor//nullkey/3/20.0/3.141593/full,00000000-0000-0000-0000-000000000000,0,
 +
 
 +
* C being any RLV source not yet accepted by the relay
 +
* R being the RLV relay
 +
 
 +
C-->R  sensor,!x-sensor//nullkey/3/20.0/3.141593
 +
C<--R  sensor,!x-sensor//nullkey/3/20.0/3.141593,ko
 +
 
 +
C-->R  sensor,!x-sensor//nullkey/3/20.0/3.141593/full
 +
C<--R  sensor,!x-sensor//nullkey/3/20.0/3.141593/full,ko
 +
 
 +
=== Syntax with optional parameter name===
 +
 
 +
The parameters are the same as for the LSL command llSensor(string name, key id, integer type, float range, float arc), with an additional optional parameter "name".
 +
 
 +
* The acknowledgment of receipt contains a non empty list of uuid keys without the parameter "name".
 +
 
 +
* With the additional parameter, the list of uuid keys is followed by the list of the names '''which must be escaped using llEscapeURL()'''.  The null key 00000000-0000-0000-0000-000000000000 must be returned if nothing is detected.
 +
 
 +
* Example of acknowledgment of receipt with the parameter "name":
 +
''97116a5b-686b-64a9-a086-cae72a95ce6b,ccb7ce46-eec4-e790-9995-47d789adfe49,Object1,Object2''
 +
i.e. a list consisiting of the two uuid keys, and the two strings Object1 and Object2.
 +
 
 +
* The source must be previously accepted by the relay to avoid a bad use of this command; a griefer for example could use it, together with the wildcard, to cause lag in a sim. Even if the command !x-sensor is not a restriction to be saved. So "ko" must be returned in that case.
 +
 
 +
No other acknowledgment of receipt is possible.
 +
 
 +
Two examples with
 +
* C being the RLV controller which is a grabber (i.e. it already sent a restriction to the relay, accepted by the relay)
 +
* R being the RLV relay
 +
 
 +
C-->R  sensor,!x-sensor//nullkey/3/20.0/3.141593
 +
C<--R  sensor,!x-sensor//nullkey/3/20.0/3.141593,97116a5b-686b-64a9-a086-cae72a95ce6b,ccb7ce46-eec4-e790-9995-47d789adfe49,
 +
 
 +
C-->R  sensor,!x-sensor//nullkey/3/20.0/3.141593
 +
C<--R  sensor,!x-sensor//nullkey/3/20.0/3.141593,00000000-0000-0000-0000-000000000000
 +
 
 +
C-->R  sensor,!x-sensor//nullkey/3/20.0/3.141593/name
 +
C<--R  sensor,!x-sensor//nullkey/3/20.0/3.141593/name,97116a5b-686b-64a9-a086-cae72a95ce6b,ccb7ce46-eec4-e790-9995-47d789adfe49,Object1,Object2
 +
 
 +
C-->R  sensor,!x-sensor//nullkey/3/20.0/3.141593/name
 +
C<--R  sensor,!x-sensor//nullkey/3/20.0/3.141593/name,00000000-0000-0000-0000-000000000000,
 +
 
 +
* C being any RLV source not yet accepted by the relay
 +
* R being the RLV relay
 +
 
 +
C-->R  sensor,!x-sensor//nullkey/3/20.0/3.141593
 +
C<--R  sensor,!x-sensor//nullkey/3/20.0/3.141593,ko
 +
 
 +
C-->R  sensor,!x-sensor//nullkey/3/20.0/3.141593/name
 +
C<--R  sensor,!x-sensor//nullkey/3/20.0/3.141593/name,ko
  
 
===Semantics===
 
===Semantics===
 
   
 
   
The effect of this command is that the relay performs a llSensor() with the given parameters, and sends the result as a (possibly empty) list of keys separated by a comma to the grabber in the ack using llRegionSayTo().  
+
The effect of this command is that the relay executes a llSensor() with the given parameters, and sends the result as a list of UUID keys separated by a comma to the source in the acknowledgment of receipt using llRegionSayTo().  
  
 
===Remarks===
 
===Remarks===
  
*Before sending this kind of command, the grabber must check by !x-orgversions the presence of 'sensor=' in the ack of this command.
+
*Before sending this kind of command, the source must check by !x-orgversions the presence of 'sensor=' in the acknowledgment of receipt of this command.
 +
 
 +
*The maximal possible length of the acknowledgment of receipt is 16*36+15=591<1023. It remains 432 characters for the command !x-sensor/name/id/type/range/arc, more precisely !x-sensor = 9 characters, /////, = 6 characters, id = 36 characters, range = 8 characters maximum, arc = 8 characters (example: 3.141593) maximum, type = 31 characters maximum, so it remains 334 characters for 'name' without the additional parameter "name".
  
*The maximal length of the message is 16*36+15=591<1023. It remains 432 characters for '!x-sensor/name/id/type/range/arc,' !x-sensor = 9 characters, /////, = 6 characters, id = 36 characters, range = 8 characters, arc = 8 characters (example: 3.141593), type = 31 characters maximum (?!), so it remains 334 characters for 'name'.  
+
*The additional parameter "name" is designed to being used in gridwide mode using !x-email or !x-pollemail, when llKey2Name() cannot be used by the controller to get the names of the UUIDs keys returned by !x-sensor. The maximal length of an email being 4096 characters, there should not be any problem; Names may contain commas or slashs. It is why they must be escaped using llEscapeURL().
  
*!x-sensor enables to use llSensor(), e.g. for a forcesit command or to force to follow an object or an avatar, when the captured avatar is more than 100m away.
+
*!x-sensor enables to use llSensor(), e.g. for a forcesit command or for forcing to follow an object or an avatar or for identifying avatars, when the captured avatar is more than 100m away. It also enables to perform a scan with the relay, not the source, as center.

Latest revision as of 05:27, 26 September 2011

sensor

STATUS: draft

version: 002

version 001 implemented in Dahlia's multirelay 1.2.14 and anythingRLV3.6RC8

  • A unique command !x-sensor allowing to do remote llSensor()
  • The main difference between 001 and 002 is the use of llEscapeURL()/llUnEscapeURL() to encode strings.

Description of !x-sensor

(DEPRECATED) Syntax with optional parameter full

The parameters are the same as for the LSL command llSensor(string name, key id, integer type, float range, float arc), with an additional optional parameter "full".

  • The acknowledgment of receipt contains a non empty list of uuid keys without the parameter "full".
  • With the additional parameter, the list of uuid keys is followed by the list of the lengths of the names and the last item of the list is the concatenation of these names. The null key 00000000-0000-0000-0000-000000000000 must be returned if nothing is detected.
  • Example of acknowledgment of receipt with the parameter "full":
97116a5b-686b-64a9-a086-cae72a95ce6b,ccb7ce46-eec4-e790-9995-47d789adfe49,l1,l2,Object1Object2

i.e. two uuid keys, two integers which are the lengths of the strings Object1 and Object2 and the concatenation of Object1 and Object2.

  • The source must be previously accepted by the relay to avoid a bad use of this command; a griefer for example could use it, together with the wildcard, to cause lag in a sim. Even if the command !x-sensor is not a restriction to be saved. So "ko" must be returned in that case.

No other acknowledgment of receipt is possible.

Two examples with

  • C being the RLV controller which is a grabber (i.e. it already sent a restriction to the relay, accepted by the relay)
  • R being the RLV relay
C-->R  sensor,!x-sensor//nullkey/3/20.0/3.141593
C<--R  sensor,!x-sensor//nullkey/3/20.0/3.141593,97116a5b-686b-64a9-a086-cae72a95ce6b,ccb7ce46-eec4-e790-9995-47d789adfe49,
C-->R  sensor,!x-sensor//nullkey/3/20.0/3.141593
C<--R  sensor,!x-sensor//nullkey/3/20.0/3.141593,00000000-0000-0000-0000-000000000000
C-->R  sensor,!x-sensor//nullkey/3/20.0/3.141593/full
C<--R  sensor,!x-sensor//nullkey/3/20.0/3.141593/full,97116a5b-686b-64a9-a086-cae72a95ce6b,ccb7ce46-eec4-e790-9995-47d789adfe49,l1,l2,Object1Object2
C-->R  sensor,!x-sensor//nullkey/3/20.0/3.141593/full
C<--R  sensor,!x-sensor//nullkey/3/20.0/3.141593/full,00000000-0000-0000-0000-000000000000,0,
  • C being any RLV source not yet accepted by the relay
  • R being the RLV relay
C-->R  sensor,!x-sensor//nullkey/3/20.0/3.141593
C<--R  sensor,!x-sensor//nullkey/3/20.0/3.141593,ko
C-->R  sensor,!x-sensor//nullkey/3/20.0/3.141593/full
C<--R  sensor,!x-sensor//nullkey/3/20.0/3.141593/full,ko

Syntax with optional parameter name

The parameters are the same as for the LSL command llSensor(string name, key id, integer type, float range, float arc), with an additional optional parameter "name".

  • The acknowledgment of receipt contains a non empty list of uuid keys without the parameter "name".
  • With the additional parameter, the list of uuid keys is followed by the list of the names which must be escaped using llEscapeURL(). The null key 00000000-0000-0000-0000-000000000000 must be returned if nothing is detected.
  • Example of acknowledgment of receipt with the parameter "name":
97116a5b-686b-64a9-a086-cae72a95ce6b,ccb7ce46-eec4-e790-9995-47d789adfe49,Object1,Object2

i.e. a list consisiting of the two uuid keys, and the two strings Object1 and Object2.

  • The source must be previously accepted by the relay to avoid a bad use of this command; a griefer for example could use it, together with the wildcard, to cause lag in a sim. Even if the command !x-sensor is not a restriction to be saved. So "ko" must be returned in that case.

No other acknowledgment of receipt is possible.

Two examples with

  • C being the RLV controller which is a grabber (i.e. it already sent a restriction to the relay, accepted by the relay)
  • R being the RLV relay
C-->R  sensor,!x-sensor//nullkey/3/20.0/3.141593
C<--R  sensor,!x-sensor//nullkey/3/20.0/3.141593,97116a5b-686b-64a9-a086-cae72a95ce6b,ccb7ce46-eec4-e790-9995-47d789adfe49,
C-->R  sensor,!x-sensor//nullkey/3/20.0/3.141593
C<--R  sensor,!x-sensor//nullkey/3/20.0/3.141593,00000000-0000-0000-0000-000000000000
C-->R  sensor,!x-sensor//nullkey/3/20.0/3.141593/name
C<--R  sensor,!x-sensor//nullkey/3/20.0/3.141593/name,97116a5b-686b-64a9-a086-cae72a95ce6b,ccb7ce46-eec4-e790-9995-47d789adfe49,Object1,Object2
C-->R  sensor,!x-sensor//nullkey/3/20.0/3.141593/name
C<--R  sensor,!x-sensor//nullkey/3/20.0/3.141593/name,00000000-0000-0000-0000-000000000000,
  • C being any RLV source not yet accepted by the relay
  • R being the RLV relay
C-->R  sensor,!x-sensor//nullkey/3/20.0/3.141593
C<--R  sensor,!x-sensor//nullkey/3/20.0/3.141593,ko
C-->R  sensor,!x-sensor//nullkey/3/20.0/3.141593/name
C<--R  sensor,!x-sensor//nullkey/3/20.0/3.141593/name,ko

Semantics

The effect of this command is that the relay executes a llSensor() with the given parameters, and sends the result as a list of UUID keys separated by a comma to the source in the acknowledgment of receipt using llRegionSayTo().

Remarks

  • Before sending this kind of command, the source must check by !x-orgversions the presence of 'sensor=' in the acknowledgment of receipt of this command.
  • The maximal possible length of the acknowledgment of receipt is 16*36+15=591<1023. It remains 432 characters for the command !x-sensor/name/id/type/range/arc, more precisely !x-sensor = 9 characters, /////, = 6 characters, id = 36 characters, range = 8 characters maximum, arc = 8 characters (example: 3.141593) maximum, type = 31 characters maximum, so it remains 334 characters for 'name' without the additional parameter "name".
  • The additional parameter "name" is designed to being used in gridwide mode using !x-email or !x-pollemail, when llKey2Name() cannot be used by the controller to get the names of the UUIDs keys returned by !x-sensor. The maximal length of an email being 4096 characters, there should not be any problem; Names may contain commas or slashs. It is why they must be escaped using llEscapeURL().
  • !x-sensor enables to use llSensor(), e.g. for a forcesit command or for forcing to follow an object or an avatar or for identifying avatars, when the captured avatar is more than 100m away. It also enables to perform a scan with the relay, not the source, as center.