LSL Protocol/Restrained Love Open Relay Group/email

!x-pollemail

STATUS: draft

VERSION: 006

MANDATORY DEPENDENCIES: key

RECOMMENDED: autoforward, sensor

COMMANDS:

• !x-pollemail: commands the relay to start polling emails. (!x-pollemail/clear makes it stop)

IMPLEMENTATIONS

Relay side:

• Version 005 in Satomi's Multi-Relay HUD 0.93
• Version 005 in Dahlia's multirelay >=0.39
• Version 006 in Dahlia's multirelay >=1.2.15

Controller side:

• Version 005 in Satomi's Witchy Remote 1.1beta2
• Version 005 in Dahlia's anythingRLV >=2.97
• Version 006 in Dahlia's anythingRLV >=3.7

DESCRIPTION: This x-tension makes it possible to control relays gridwide (relay in one sim, controller in another one) by using email as a communication channel instead of usual chat on RLVR channel.

Presentation of e-mails

Emails exchanged between relay and controller need to follow a common format.

The topic must be:

ORG encapsulated RLVR protocol,<protocol version>,<session_key>

Where the protocol version if the version of the x-tension, and the session key is a secret shared by both relay and controlling device.

ex:  ORG encapsulated RLVR protocol,006,a586c562-bf27-b7db-e36e-822d0a9ba02a

The session key will usually be created within a prior session, using !x-key as defined in key, but it is also possible for the controller to generate and send a new key in the first email message. In the latter case, a new session is created that will use this key in all further messages.

The body of the mail contains one or several lines with the same syntax as used in the RLVR protocol, without the field with the recipient UUID.

From the controller:

<command ident>,<list of RLVR commands and metacommands separated by '|'>

From the relay:

<command ident>,<commands or metacommand the relay is answering to>,<ack value>

Note that in conjunction with autoforward, the following is also possible from the relay:

<channel number>,<forwarded viewer reply>

Example of initialization between a controller C and the relay R

In the following exchange, the controller C and the relay R negotiates a secret UUID key which will be the key of the session. The exchange is done using llRegionSayTo() to keep the key secret (k(R) is the UUID key of the wearer of the relay and k(C) the UUID key of the controller).

1 C--RLVR--> R    secret_key,k(R),!x-key/a586c562-bf27-b7db-e36e-822d0a9ba02a
2 C<-RLVR--- R    secret_key,k(C),!x-key/a586c562-bf27-b7db-e36e-822d0a9ba02a,ok

Then C can start an email session using !x-pollemail as follows:

1 C--RLVR--> R    blah,k(R),!x-pollemail
2 C<-RLVR--- R    blah,k(C),!x-pollemail,ok

Without secret key, the answer for !x-pollemail must be a "ko". There are no exceptions. Then the session can continue by email using the subject "ORG encapsulated RLVR protocol,006,a586c562-bf27-b7db-e36e-822d0a9ba02a".

1 -e>     bleh,<anything>
2 <e-     bleh,<anything>,<ack>
...

Remark

• The autoforward and sensor x-tensions are not required: a controller does not necessarily need to send @getxxx or @notify commands, or to scan for objects or avatars. The autoforward and the sensor x-tensions may be used also for a simwide control (i.e. a chat session with the controller and the relay distant of more than 100m).

Ending the email session between a controller C and the relay R

To end up an email session, the commands !x-takeover and !x-pollemail/clear may be used.

1 C--RLVR--> R   back_to_chat,k(R),!x-takeover/a586c562-bf27-b7db-e36e-822d0a9ba02a
2 C<-RLVR--- R   back_to_chat,k(C),!x-takeover/a586c562-bf27-b7db-e36e-822d0a9ba02a,ok

Note that in the above exchange, the controller C is not necessarily the first controller; the above commands can also be interpreted as a kind of handover.

It is also possible to use !x-pollemail/clear as follows (by email or by chat):

1 C------> R   back_to_chat,k(R),!x-pollemail/clear
2 C<------ R   back_to_chat,k(C),!x-pollemail/clear,ok

Remarks

• The commands using the secret session key must use llRegionSayTo(): !x-key and !x-takeover
• This behaviour of !x-takeover is already in the version 002 of the x-tension key.

Testing controller's presence

For garbage collection purposes, be it on relog, or on regular basis, R might want to check if C is still active. The ping mechanism can be used here.

<e-    ping,ping,ping
-e>    ping,!pong

The important thing is that the relay remembers it was an email session after relog.

C can check R's presence by sending any valid message, as acknowledgement by R is required for every RLVR message from C. If the only purpose of the message is presience verification, the following scenario is recommended:

-e>    blah,!x-pollemail
<e-    blah,!x-pollemail,ok

Handover

!x-handover/K/n should work like in chat sessions (with the semantics that the session is transfered to the object of key K, chatting on standard RLVR channel).

Handing over to another object while remaining in e-mail mode, doesn't however require any special step. The following scenario can be used:

1 - assume C has a session with R, using key k(S)
2 - C gives k(S) to another object C' via any preferred medium
3 - now  C' can continue e-mailing with S, using key k(S) (and can use the "C has a new key" scenario)

Handing over to oneself can also be used to switch back to chat mode.