LSL Wiki : exchangeTrustNet

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