Difference between revisions of "LlRequestURL"

From Second Life Wiki
Jump to navigation Jump to search
(Maybe 5 per 3 seconds?)
(Resetting a script releases URLs, so no need to formally release them before llResetScript())
Line 13: Line 13:
**Use [[CHANGED_REGION_START]] to detect this so new URL can be requested.
**Use [[CHANGED_REGION_START]] to detect this so new URL can be requested.
*The number of available URLs is a limited resource, that is to say, a script can only have so many open URLs. See [[LSL http_server#Resource Limitations]] for details.
*The number of available URLs is a limited resource, that is to say, a script can only have so many open URLs. See [[LSL http_server#Resource Limitations]] for details.
*When abandoning a URL, always release it with [[llReleaseURL]], otherwise it will leak.
*When abandoning a URL, release it with [[llReleaseURL]], to avoid leaks. Resetting the script, or deleting the prim will also suffice to release URLs.
{{LSL Tip|Never ever forget to release a URL again which you have requested! URLs are region resources just like prims. If you take them all you can get into big trouble with the sim owner and/or estate managers.}}
 
|constants
|constants
|examples=
|examples=
Line 22: Line 22:
key urlRequestId;
key urlRequestId;
key selfCheckRequestId;
key selfCheckRequestId;
reset_script()
{
    llReleaseURL(url);
    llResetScript();
}


request_url()
request_url()
Line 45: Line 39:
     // However this is just a demo script...
     // However this is just a demo script...


     reset_script();
     llResetScript();
}
}


Line 52: Line 46:
     on_rez(integer start_param)
     on_rez(integer start_param)
     {
     {
         reset_script();
         llResetScript();
     }
     }


Line 58: Line 52:
     {
     {
         if (change & (CHANGED_OWNER | CHANGED_INVENTORY))
         if (change & (CHANGED_OWNER | CHANGED_INVENTORY))
             reset_script();
             llResetScript();


         if (change & (CHANGED_REGION | CHANGED_REGION_START | CHANGED_TELEPORT))
         if (change & (CHANGED_REGION | CHANGED_REGION_START | CHANGED_TELEPORT))

Revision as of 16:14, 12 December 2015

Summary

Function: key llRequestURL( );

Requests one HTTP:// url for use by this object. The http_request event is triggered with the result of the request. HTTP-in uses port 12046.
Returns a handle (a key) used for identifying the result of the request in the http_request event.

Caveats

  • HTTP-in uses port 12046.
  • Use of this function is throttled. Although it has no forced sleep time, too many requests (5 ish) in a short period will cause all further requests to be denied until the script stops requesting urls for at least 1 second. Using an llSleep of 0.6 seconds or greater between each request will prevent you from being throttled.
  • When a region is (re)started all HTTP server URLs are automatically released and invalidated.
  • The number of available URLs is a limited resource, that is to say, a script can only have so many open URLs. See LSL http_server#Resource Limitations for details.
  • When abandoning a URL, release it with llReleaseURL, to avoid leaks. Resetting the script, or deleting the prim will also suffice to release URLs.

Important Issues

~ All Issues ~ Search JIRA for related Bugs
   llRequestURL silently failing on simulator restart

Examples

This script requests a new URL after region restart:

string url;
key urlRequestId;
key selfCheckRequestId;

request_url()
{
    llReleaseURL(url);
    url = "";

    urlRequestId = llRequestURL();
}

throw_exception(string inputString)
{
    key owner = llGetOwner();
    llInstantMessage(owner, inputString);

    // yeah, bad way to handle exceptions by restarting.
    // However this is just a demo script...

    llResetScript();
}

default
{
    on_rez(integer start_param)
    {
        llResetScript();
    }

    changed(integer change)
    {
        if (change & (CHANGED_OWNER | CHANGED_INVENTORY))
            llResetScript();

        if (change & (CHANGED_REGION | CHANGED_REGION_START | CHANGED_TELEPORT))
            request_url();
    }

    state_entry()
    {
        request_url();
    }

    http_request(key id, string method, string body)
    {
        integer responseStatus = 400;
        string responseBody = "Unsupported method";

        if (method == URL_REQUEST_DENIED)
            throw_exception("The following error occurred while attempting to get a free URL for this device:\n \n" + body);

        else if (method == URL_REQUEST_GRANTED)
        {
            url = body;
            key owner = llGetOwner();
            llLoadURL(owner, "Click to visit my URL!", url);

            // check every 5 mins for dropped URL
            llSetTimerEvent(300.0);
        }
        else if (method == "GET")
        {
            responseStatus = 200;
            responseBody = "Hello world!";
        }
        // else if (method == "POST") ...;
        // else if (method == "PUT") ...;
        // else if (method == "DELETE") { responseStatus = 403; responseBody = "forbidden"; }

        llHTTPResponse(id, responseStatus, responseBody);
    }

    http_response(key id, integer status, list metaData, string body)
    {
        if (id == selfCheckRequestId)
        {
            // If you're not usually doing this,
            // now is a good time to get used to doing it!
            selfCheckRequestId = NULL_KEY;

            if (status != 200)
                request_url();
        }

        else if (id == NULL_KEY)
            throw_exception("Too many HTTP requests too fast!");
    }

    timer()
    {
        selfCheckRequestId = llHTTPRequest(url,
                                [HTTP_METHOD, "GET",
                                    HTTP_VERBOSE_THROTTLE, FALSE,
                                    HTTP_BODY_MAXLENGTH, 16384],
                                "");
    }
}

It's important to keep in mind that if you request another URL, that the old one will not be released, it will remain active. The following script drives home this point.

Try the following code ONLY if you can use all your URLs on your land. Removing the prim/script will release all URLs previous assigned.

// WARNING:
//
//      This script is only for proof-of-concept (demo purposes).
//      DO NOT use it if you don't have the sim owners and/or
//      estate managers OK to test this script.
//      This script can possibly block HTTP communication from and to the sim.
//      ...bringing down all networked vendors and/or similar machines.
//
//      This script allocates all available URLs.
//      Deleting the script and/or derezzing the object containing the script,
//      will release all previously taken URLs.


default
{
    state_entry()
    {
        llRequestURL();
    }

    http_request(key id, string method, string body)
    {
        if (method == URL_REQUEST_DENIED)
            llSetText("No free URLs!", <1.0, 0.0, 0.0>, 1.0);

        else if (method == URL_REQUEST_GRANTED)
        {
            llSetText( (string)llGetFreeURLs() + " URLs left\n" + body, <1.0, 1.0, 1.0>, 1.0);

            llRequestURL();
        }
        else if (method == "GET")
            llHTTPResponse(id, 200, "Hello there!");
    }
}

This script will, as you can see, use all URLs available on your land because it does not remove the old URLs before requesting a new one.

Just store the old URL in a global variable and release it with llReleaseURL.

Notes

Another comment on resilient programming: getting a global resource, an HTTP listener in this case, should always be considered an operation that can fail for transitory reasons (as well as permanent ones). In this case, LSL folds retryable and permanent errors into the same error status and there's no opportunity for a script writer to distinguish the two cases. But a reasonable way to handle this is sleeping with limited retries before failing hard in the LSL code.
Monty Linden

See Also

Functions

•  llRequestSecureURL
•  llGetFreeURLs
•  llReleaseURL
•  llHTTPResponse
•  llGetHTTPHeader

Articles

•  LSL http server

Deep Notes

History

All Issues

~ Search JIRA for related Issues
   llRequestURL silently failing on simulator restart

Signature

function key llRequestURL();