Introduction

This is the counterpart to llHTTPRequest. While llHTTPRequest enables LSL scripts to request data from HTTP-accessible sources, HTTP-in enables outside sources to request data from LSL scripts in Second Life. The key difference is that llHTTPRequest exchanges data when the script in SL wants; HTTP-in allows outside sources to determine when they need to communicate with LSL scripts in SL.

Prior to HTTP-in, similar functionality could be achieved by polling with llHTTPRequest, llEmail and XML-RPC. All three are cumbersome and the latter two have serious scalability bottlenecks.

Functions

llRequestURL

Requests one HTTP:// url for use by the script. The http_requestevent is triggered with the result of the request. HTTP-in uses port 12046.Returns a key that is the handle used for identifying the result in the http_requestevent.

llRequestSecureURL

Requests one HTTPS:// (SSL) url for use by the script. The http_requestevent is triggered with the result of the request. HTTPS-in uses port 12043.Returns a key that is the handle used for identifying the result in the http_requestevent.

Returns an empty string if the header is not found or if the headers can no longer be accessed. Headers can only be accessed before llHTTPResponse is called and with-in the first 30 seconds after the http_requestevent is queued.

Generated Headers

These headers are automatically generated by the simulator, they were not actually sent by the requesting client. They supply information about the request to make parsing easier.

CGI environments may place the headers into variables by capitalizing the entire name, replacing dashes with underscores, and prefixing the name with "HTTP_", e.g. "x-secondlife-object-name" becomes "HTTP_X_SECONDLIFE_OBJECT_NAME".

HTTP header names are case insensitive [1]. Some ISPs may modify the case of header names, as was seen in BUG-5094.

URL Lifetime Limitations

URLs are temporary!

URLs will be lost in the following cases, all detectable by the script events listed with them.

On region cross or TP(attachments): changedevent, CHANGED_REGION and CHANGED_TELEPORT. Testing this have it has been found that teleports within a region DO NOT cause a URL to be lost, therefore, you do not need to request a new URL on CHANGED_TELEPORT, because CHANGED_REGION will handle a teleport to a different region. If you choose to request a URL after a teleport, it is recommended to release the old URL to be sure you don't have too many used. (Stone Tremont Aug 8th 2010)

The SilverDay ObjectDNS is an easy to use dns-mapping-service with many configurable options (password protection, write protection, etc.) and an optional web-interface. The LSL scripts are available here on the wiki (LSL-Script Library/Silverday ObjectDNS).

Resource Limitations

There are a limited number of URLs available in each region, split by land ownership exactly like prim limits.

Use llGetFreeURLs to get the exact number of available URLs for the script.

The number of allowed URLs is the same as the number of allowed prims on the parcel the object is over.

Object owner does not matter, all objects over a parcel will use the resource pool for that parcel.

Like prims, all the parcels owned by the same owner and in the same region share the same pool of resources.

If you have two parcels in a region that each support 100 URLs, then you could use all 200 in object(s) on a single parcel.

Vehicles will use the url resources from the parcel they are over until the cross a parcel border.

Specifically this prevents anyone from breaking your vending machine by sitting on it and making it a 'vehicle'.

When any object using URL resources with a resident sitting on it crosses a parcel boundary the resources will switch to the first sitting resident with enough resources. If no sitting agents have enough resources then the resources from the parcel being moved onto will be used. If even then there are not enough resources to use then the vehicle will be blocked from moving.

In short we do everything we can to find a pool to host the resources needed by the vehicle, but will block movement if we can't.

Parcel Sale: When a parcel is sold such that it changes the total available URLs in the region for either resident (seller or buyer) such that more URLs are being used than are available some objects will be returned.

The objects returned will be from youngest object to oldest object of those using URLs in each category in order of object category: Temporary, Other, Group, Owner, Selected/Sat upon.

The only time objects are possibly returned is when parcels change owner, and only if more resources are being used than allowed.

Other Limitations

Size of headers of requests will be limited to 255 bytes per header, not total.

The size of responses to requests is not currently limited, but this is subject to review during testing.

By default the content type of the returned data is always "text/plain; charset=utf-8", this however can be changed via llSetContentType for all subsequent responses via llHTTPResponse.

There is a cap of 64 in flight requests per script. This is based on the maximum number of pending events in LSL. After hitting the 64 request limit, the simulator cap server returns "503 Service Unavailable" to the inbound request.

We may throttle the rate we accept hits at the CAP server level as well. This is possible, but has not yet been decided.