Tool Discovery Protocol
This protocol is used by the
TrustNet HUD Avatar Scanner (supported starting at version 0.50) to discover "tools", that is, various scripts that can target avatars to perform a function. The idea is to use the scanner to select an avatar from the list by clicking on it, and then pass the selection to an external tool. This is intended to integrate with tools like security orbs, weapons that target a specific avatar, etc.
Protocol
The object that wishes to implement the protocol must listen on channel 0x44470001 (or 1145503745 in decimal).
The text sent on the channel to the object implementing the protocol has a base format of
llList2CSV([version, target_key, command]). Additional data is arguments to the command.
| Field | Type | Description |
| version | integer | Protocol version number. Currently always 1. |
| target_key | key | Object key the message is destined to. If NULL_KEY, then destined to all the objects that hear it. |
| command | string | Command (see list below) |
If the object implementing this protocol supports some sort of access control (for example, can only be used by its owner) it should ignore completely commands coming from objects owned by avatars that won't be able to use it.
Discovery
The first stage of the protocol is the discovery process. The scanner sends the "discover" command, and all the objects wishing to appear on the menu must reply as quickly as possible. The reply to this command must be sent to the specified channel, which is randomly generated.
| Field | Type | Description |
| version | integer | Protocol version number. Currently always 1. |
| target_key | key | NULL_KEY |
| command | string | "discover" |
| reply_channel | integer | Channel where to send the reply. Will be randomly generated. |
Discovery Reply
The reply must be in the format of llList2CSV([version, name, priority]) sent to the channel indicated in the "discover" command.
| Field | Type | Description |
| version | integer | Protocol version number. Currently always 1. |
| name | string | Name of the function the object replying performs. Must 24 characters or less, or the reply will be ignored. Must be unique. |
| priority | integer | Number from 1 to 10, indicating the importance of this function. Higher numbers have higher priority. If there are enough objects replying that they can't fit in the llDialog list (more than 12), the lowest priority entry will be dropped to make room for a new one. The TrustNet Avatar Scanner internally gives a higher priority to objects owned by the scanner's owner. |
The name sent must be unique, as it is what will be displayed on the llDialog button. Only one function per object will be accepted.
Command Execution Request
If the tool is chosen to perform its function, then an execute command will be sent to the channel, with this format:
| Field | Type | Description |
| version | integer | Protocol version number. Currently always 1. |
| target_key | key | Object's key |
| command | string | "execute" |
| avatar_key | key | Key of the avatar that was selected |
| avatar_name | string | Name of the avatar that was selected |
The object should respond to this by performing whatever action it does on the avatar. If multiple actions may be performed, it should present them to the scanner's owner (obtained with llGetOwnerKey in the listen event) using llDialog.
Versioning
In order to make it easier to extend the protocol if needed, all commands are prefixed with a version number. An object implementing the protocol should check the version number it just received, and if it doesn't recognize the version, the preferred action is to ignore the command completely.
Protocol Example
This is the timeline of the events that would happen when the full protocol is played out.
1. Scanner sends llList2CSV([version, NULL_KEY, "discovery", channel_num]) to channel 0x44470001.
2. Object replies with llList2CSV([version, "Test Object", 5]) sent to channel channel_num.
3. If "Test Object" is selected on the dialog, scanner sends llList2CSV([version, objects_key, "execute", avatar_key, avatar_name]) to channel 0x44470001.
4. Object performs the action on avatar avatar_key.
Example Source
This is the source for a script that would be detected by the scanner, and be possible to use with it.
// Example of Tool Discovery protocol, by Dale Glass
// Channel where the announcement request will be sent
integer g_announce_channel = 0x44470001;
// Name the object will have in the tools list. Must be unique
string g_name = "Test";
// Priority, 1-10. Larger number = higher priority
integer g_priority = 5;
// Protocol version we speak
integer g_protocol_version = 1;
default {
state_entry() {
llListen(g_announce_channel, "", NULL_KEY, "");
}
listen(integer channel, string obj_name, key id, string str) {
list tmp = llCSV2List(str);
integer version = llList2Integer(tmp,0);
key dest_key = llList2Key(tmp,1);
string command = llList2String(tmp,2);
if ( version != g_protocol_version ) return;
if ( (dest_key != llGetKey()) && (dest_key != NULL_KEY) ) return;
if ( command == "discover" ) {
integer reply_chan = llList2Integer(tmp,3);
llSay(reply_chan, llList2CSV([g_protocol_version, g_name, g_priority]));
llOwnerSay("Replied to announcement request from " + obj_name);
} else if ( command == "execute" ) {
key av_key = llList2Key(tmp,3);
string av_name = llList2String(tmp,4);
// Perform our action
llInstantMessage(av_key, "Test!");
llOwnerSay("Executed command on " + av_name + " (" + (string)av_key + ")");
} else {
llOwnerSay("Unknown command: " + command);
}
}
}
Protocol Exchange