TrustNet API
TrustNet is an attempt to replace the ratings system in SL with something better. A complete explanation of how it works can be found here:
http://daleglass.wordpress.com/trustnet/
This is the complete API available to other people. Any unexplained functionality (you can tell for example by skipped command numbers) is either unavailable in the API, not stable enough, not generally useful, or deprecated.
HTTP Module
The HTTP module is the actual part doing requests with
llHTTPRequest to the TrustNet server. To reduce server load and improve performance using the cache (explained below) is strongly encouraged. This function is done by two scripts,
http and
http_controller. Both are absolutely required to perform the function. The first one handles the actual HTTP requests, and the other deals with the formatting.
Constant | Integer | String | Key | Description |
TN_HTTP_EXPLAIN | 0x44472902 | Agent's name | Agent's key | Returns a human-readable string (don't try to parse it, format is subject to change) that explains why the specified agent has the rating it does. Output may be cut to prevent script crashes due to memory exhaustion. |
TN_HTTP_FLUSH | 0x44472904 | none | none | Requests aren't done immediately. The HTTP module will delay a request and attempt to convert multiple commands into one llHTTPRequest. This command requests the HTTP to do the pending requests now. This is useful if you're using TrustNet for something like a door, which runs a check for a single agent, and where waiting for more to appear is most likely useless. |
TN_HTTP_GET_RATING | 0x44472906 | llList2CSV([agent_name, rating_type, link_num]) | Agent's key | Retrieves the rating_type rating for the specified agent. The link_num argument specifies to which prim to send the reply. This is provided as convenience for scanner objects that use a prim per agent. |
TN_HTTP_LOGIN | 0x44472903 | none | none | Logs into the TrustNet system. This is required before any other commands work. No credentials are required, authentication is done against your key. |
TN_HTTP_RATE | 0x4447290b | llList2CSV([agent_name, rating_type, score]) | Agent's key | Submits a rating for the indicated agent. The rating type is a string and a table of them can be found below. The score is an integer. Allowed values are -1, 0 and 1. A rating will remove any previous ones. 0 removes any previous rating. |
TN_HTTP_SEARCH | 0x44472907 | rating type | none | Returns a human-readable string (don't parse it) containing a list of avatars with the best ratings of the requested type. This will for example return the best scripters from your net. |
List of currently recognized rating types
Rating | Description |
behavior | Are they nice to have around or not? A positive rating here implies a certain amount of trust. If you rate somebody's behavior positively, their ratings will affect the scores you get |
scripting | Scripting ability |
building | Building ability |
avatars | Avatar making ability (not appearance) |
Cache Module
Since requesting things takes time, and for some purposes the same request might be likely to be made repeatedly, a cache module is provided. Its use is strongly encouraged, unless you absolutely don't needed it. An example of when you could choose not to use it is when you're using TrustNet on something like a door, where checks are made against single agents very infrequently.
Constant | Integer | String | Key | Description |
TN_CACHE_FLUSH | 0x44473103 | none | none | Clears the cache completely |
TN_CACHE_GET | 0x44473100 | llList2CSV([agent_name, rating_type, link_num]) | Agent's key | Same as TN_HTTP_GET_RATING, only if it's found in the cache you get the result a lot faster |
TN_CACHE_SET | 0x44473101 | llList2CSV([rating_type, score]) | Agent's key | Stores a rating in the cache. Overrides a previous rating if any. Ignored if the rating type is wrong (see TN_CACHE_SET_RATING_TYPE below). This is generally not necessary in normal usage. |
TN_CACHE_SET_RATING_TYPE | 0x44473106 | rating type | none | The current cache implementation only caches scores of one type. The rest are passed through. If the rating you're primarily working with is not 'behavior' then you should call this to make the cache more useful. Calling it will clear the cache. If this defect is fixed, this command will be silently ignored. |
TN_CACHE_STATS | 0x44473102 | none | none | Dumps cache statistics using llOwnerSay. May be helpful during development. |
Client Events
These messages are going to be sent to the client script. This is how confirmations, replies, and errors are reported. They are sent to LINK_THIS, that is, the same module where the TrustNet scripts are. Many of them may be ignored.
Constant | Integer | String | Key | Description |
TN_CLIENT_CONNECTING | 0x4447300b | none | none | HTTP module is connecting to the server. Will happen after a TN_HTTP_LOGIN. May be ignored. |
TN_CLIENT_DOWNLOAD_DONE | 0x4447300c | none | none | Retrieval of ratings is complete. This happens once per ratings "bunch", not per requested rating. May be ignored. |
TN_CLIENT_ERROR | 0x44473007 | Error message | none | Error message from the server, in a human-readable format. Will be received if something goes wrong, such as a request being incorrectly formatted. |
TN_CLIENT_EXPLAIN | 0x44473008 | Message | none | Reply to TN_HTTP_EXPLAIN, formatted for human readability. Should not be parsed in any way, format may change unpredictably. |
TN_CLIENT_LOGGING_IN | 0x4447300a | none | none | HTTP module is performing a login. Will happen after a TN_HTTP_LOGIN. May be ignored. |
TN_CLIENT_LOGIN_ERROR | 0x44473006 | Error message | none | Received if a login attempt fails. This may be due to an expired subscription, server problems, or your version being too old. |
TN_CLIENT_LOGIN_OK | 0x44473005 | Login message | none | Received when a login is successfully completed. Detecting this is mandatory. Most commands will be silently ignored until a login is completed. |
TN_CLIENT_NO_RATINGS | 0x44473011 | none | none | Notification from the server informing the user that they haven't given any ratings yet. That means that no scores can be calculated. For that reason, using commands like TN_HTTP_GET_RATING and TN_CACHE_GET is strongly discouraged until you submit ratings to the server. |
TN_CLIENT_NOTICE | 0x44473009 | Notice | none | General message from the server to the user. May contain notices about future downtime, etc. May be received at any time. May be ignored. |
TN_CLIENT_RATING | 0x44473000 | llList2CSV(rating_type, rating) | Agent's key | Result of a TN_HTTP_GET_RATING. |
TN_CLIENT_SEARCH | 0x4447300f | Message | none | Result of a TN_HTTP_SEARCH query. Formatted for human readability. |
TN_CLIENT_STATS_QUEUED | 0x44473001 | Count | none | How many pieces of data (rating requests, rating submissions, etc) are currently waiting to be sent. |
TN_CLIENT_STATS_TRANSMITTING | 0x44473003 | Count | none | How many pieces of data are currently being transmitted |
TN_CLIENT_SUBSCRIPTION_EXPIRING | 0x4447300e | none | none | Notification from the server informing the user that their subscription is expiring (currently, less than a week left). Will be received during login. It is recommended that you check for this in at least one object to avoid surprises. |
TN_CLIENT_UPLOAD_DONE | 0x4447300d | none | none | Ratings were accepted by the server. This happens once per ratings "bunch", not per requested rating. May be ignored. |
Code Examples
Explain
This example demonstrates how to make an object that waits for somebody to click it, then does a TN_HTTP_EXPLAIN request for the agent that clicked it, and produces the output.
// Example TrustNet script by Dale Glass
// Demonstrates the TN_HTTP_EXPLAIN TrustNet command
integer TN_HTTP_LOGIN = 0x44472903;
integer TN_HTTP_EXPLAIN = 0x44472902;
integer TN_CLIENT_LOGIN_OK = 0x44473005;
integer TN_CLIENT_LOGIN_ERROR = 0x44473006;
integer TN_CLIENT_EXPLAIN = 0x44473008;
default {
state_entry() {
// Start a login
llMessageLinked(LINK_THIS, TN_HTTP_LOGIN, "", NULL_KEY);
llSetText("Logging in...", <0,0,1>, 1.0);
}
link_message(integer sender_num, integer num, string str, key id) {
if( num == TN_CLIENT_LOGIN_OK ) {
// Login completed, everything went fine
state running;
} else if ( num == TN_CLIENT_LOGIN_ERROR ) {
// Login failed. Here we could perhaps retry after a delay.
llOwnerSay("Login failed!\n" + str);
llSetText("Login failed", <1,0,0>, 1.0);
}
}
}
state running {
state_entry() {
llSetText("Ready. Click me!", <0,0,1>, 1.0);
}
touch_start(integer count) {
llSetText("Requesting...", <0,0,1>, 1.0);
// Request an explanation of the score from the server
llMessageLinked(LINK_THIS, TN_HTTP_EXPLAIN, llDetectedName(0), llDetectedKey(0));
}
link_message(integer sender_num, integer num, string str, key id) {
if ( num == TN_CLIENT_EXPLAIN ) {
// Explanation received
llWhisper(0, str);
}
}
}
Get Rating
// Example TrustNet script by Dale Glass
// Demonstrates the TN_HTTP_GET_RATING TrustNet command.
//
// This is a more complete example with code for handling
// common events.
integer TN_HTTP_LOGIN = 0x44472903;
integer TN_HTTP_GET_RATING = 0x44472906;
integer TN_CLIENT_RATING = 0x44473000;
integer TN_CLIENT_LOGIN_OK = 0x44473005;
integer TN_CLIENT_LOGIN_ERROR = 0x44473006;
integer TN_CLIENT_SUBSCRIPTION_EXPIRING = 0x4447300e;
integer TN_CLIENT_ERROR = 0x44473007;
integer TN_CLIENT_NOTICE = 0x44473009;
integer TN_CLIENT_LOGGING_IN = 0x4447300a;
integer TN_CLIENT_CONNECTING = 0x4447300b;
handle_common(integer num, string str, key id) {
if ( num == TN_CLIENT_NOTICE ) {
llOwnerSay("Notice: " + str);
} else if ( num == TN_CLIENT_ERROR ) {
llOwnerSay("Error: " + str);
}
}
default {
state_entry() {
// Start a login
llMessageLinked(LINK_THIS, TN_HTTP_LOGIN, "", NULL_KEY);
llSetText("", <0,0,1>, 1.0);
}
link_message(integer sender_num, integer num, string str, key id) {
if( num == TN_CLIENT_LOGIN_OK ) {
// Login completed, everything went fine
if ( str != "" ) {
// Display login message, if there is one
llOwnerSay(str);
}
state running;
} else if ( num == TN_CLIENT_LOGIN_ERROR ) {
// Login failed. Here we could perhaps retry after a delay.
llOwnerSay("Login failed!\n" + str);
llSetText("Login failed", <1,0,0>, 1.0);
} else if ( num == TN_CLIENT_SUBSCRIPTION_EXPIRING ) {
llOwnerSay("Your TrustNet API subscription is expiring");
} else if ( num == TN_CLIENT_CONNECTING ) {
llSetText("Connecting...", <0,0,1>, 1.0);
} else if ( num == TN_CLIENT_LOGGING_IN ) {
llSetText("Logging in...", <0,0,1>, 1.0);
} else {
handle_common(num, str, id);
}
}
}
state running {
state_entry() {
llSetText("Ready. Click me!", <0,0,1>, 1.0);
}
touch_start(integer count) {
llSetText("Requesting...", <0,0,1>, 1.0);
// Request an score from the server
llMessageLinked(LINK_THIS, TN_HTTP_GET_RATING,
llList2CSV([llDetectedName(0), "behavior", llGetLinkNumber()]),
llDetectedKey(0));
}
link_message(integer sender_num, integer num, string str, key id) {
if ( num == TN_CLIENT_RATING ) {
// Explanation received
list result = llCSV2List(str);
string rating_type = llList2String(result,0);
float score = llList2Float(result,1);
llSetText("", <0,0,0>, 0.0);
llWhisper(0, llKey2Name(id) + "'s " + rating_type + " score is " + (string)score);
} else {
handle_common(num, str, id);
}
}
}
Protocol Exchange