LlHTTPRequest

From Second Life Wiki
Revision as of 12:05, 1 October 2007 by Siann Beck (Talk | contribs)

Jump to: navigation, search

Summary

Function: key llHTTPRequest( string url, list <span title="HTTP request parameters in the format
[ parameter1, value1, parameter2, value2, . . . parameterN, valueN]" style="border-bottom:1px dotted; cursor:help;">parameters
, string body );</span>

Sends an HTTP request to the specified URL with the body of the request and parameters.
Returns a key that is a handle identifying the HTTP request made.

• string url A valid HTTP/HTTPS URL.
• list parameters HTTP request parameters in the format
[ parameter1, value1, parameter2, value2, . . . parameterN, valueN]
• string body Contents of the request.
Flag Parameter(s) Default Parameter Value(s) Description
HTTP_METHOD 0 [string method] ["GET"] "GET", "POST", "PUT" and "DELETE"
HTTP_MIMETYPE 1 [string MIME_type] ["text/plain;charset=utf-8"] text/* MIME types should specify a charset. To emulate HTML forms use application/x-www-form-urlencoded. This allows you to set the body to a properly escaped (llEscapeURL) sequence of <name,value> pairs in the form var=value&var2=value2 and have them automatically parsed by web frameworks.
MIME types must be specified in the format: type/subtype[;option=value]
Some valid examples are
"text/html"
"text/plain;charset=utf-8"
"application/xhtml+xml"
"application/json"
"application/x-www-form-urlencoded"
"application/rss+xml"
"multipart/mixed; boundary="---1234567890---""
HTTP_BODY_MAXLENGTH 2 [integer length] [2048] Sets the maximum (UTF-8 encoded) byte length of the HTTP response body. The maximum that can be set depends upon which VM is used.
HTTP_VERIFY_CERT 3 [integer verify] [TRUE] If TRUE, the server SSL certificate must be verifiable using one of the standard certificate authorities[1] when making HTTPS requests. If FALSE, any server SSL certificate will be accepted.
HTTP_VERBOSE_THROTTLE 4 [integer noisy] [TRUE] If TRUE, shout error messages to DEBUG_CHANNEL if the outgoing request rate exceeds the server limit. If FALSE, the error messages are suppressed (llHTTPRequest will still return NULL_KEY).
HTTP_CUSTOM_HEADER 5 [string name, string value] NA Add an extra custom HTTP header to the request. The first string is the name of the parameter to change, e.g. "Pragma", and the second string is the value, e.g. "no-cache". Up to 8 custom headers may be configured per request, and each header's combined name+value length must be no greater than 253 characters. Note that certain headers, such as the default headers, are blocked for security reasons.
HTTP_PRAGMA_NO_CACHE 6 [integer send_header] [TRUE] Sends "Pragma: no-cache" header (TRUE), or does not send a "Pragma" header (FALSE).
HTTP_USER_AGENT 7 [string user agent value] [(none)] The user agent value is appended to the one generated by LSL itself. It should follow the syntax from the HTTP standard like: "My-Script-Name/1.0 (Mozilla compatible)".

Note: Spaces are not allowed in HTTP User Agent token values, so "My Script Name/1.0" will produce a script error; change the spaces to hyphens ("-")

Note: this constant is not yet available in all deployed server versions

HTTP_ACCEPT 8 [string MIME_type] ["text/plain;charset=utf-8"] HTTP_ACCEPT parameters can be passed to limit the number of mime types that are sent in the Accept: header of the HTTP request. Specified mime types may include character set and q parameters. This parameter may be specified multiple times.

The specified mime type must be one already recognized by llHTTPRequest. These include any text/ mime type, or the following application mime types: “application/xhtml+xml”, “application/atom+xml”, “application/json”, “application/xml”, “application/llsd+xml”, “application/x-javascript”, “application/javascript”, “application/x-www-form-urlencoded”, or “application/rss+xml”.

The Content-Type header in the response is checked against the specified HTTP_ACCEPT parameters. If the value of the header is not in the list of acceptable mime types, llHTTPRequest will return 415 as a result code and the body will be "Unsupported or unknown Content-Type."

Headers sent by the simulator.
Header Description Example data
X-SecondLife-Shard The environment the object is in. "Production" is the main grid and "Testing" is the preview grid Production
X-SecondLife-Object-Name The name of the object containing the script Object
X-SecondLife-Object-Key The key of the object containing the script 01234567-89ab-cdef-0123-456789abcdef
X-SecondLife-Region The name of the region the object is in, along with the global coordinates of the region's south-west corner Jin Ho (264448, 233984)
X-SecondLife-Local-Position The position of the object within the region (173.009827, 75.551231, 60.950001)
X-SecondLife-Local-Rotation The rotation of the object containing the script 0.000000, 0.000000, 0.000000, 1.000000
X-SecondLife-Local-Velocity The velocity of the object 0.000000, 0.000000, 0.000000
X-SecondLife-Owner-Name Name of the owner of the object Zeb Wyler
X-SecondLife-Owner-Key UUID of the owner of the object 01234567-89ab-cdef-0123-456789abcdef

Caveats

  • Cannot be used to load textures or images from the internet, for more information see Web Textures.
  • If the accessed site is relying on the LSL script to report L$ transactions, then it must check the X-SecondLife-Shard header to see if the script is running on the beta grid.
  • The response body is limited to 2048 bytes; if it is longer it will be truncated.
All Issues ~ Search JIRA for related Bugs

Examples

key http_request_id;

default
{
    state_entry()
    {
        http_request_id = llHTTPRequest("url", [], "");
    }

    http_response(key request_id, integer status, list metadata, string body)
    {
        if (request_id == http_request_id)
        {
            llSetText(body, <0,0,1>, 1);
        }
    }
}

Notes

If for some reason while using llHTTPRequest/http_response you are unable to parse a known good RSS feed or some other form of web contents, you will need to work around it outside of SecondLife. This is unlikely to change in the near future since checking the headers requires more overhead at the simulator level.

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. "HTTP_X_SECONDLIFE_OBJECT_NAME."

See Also

Events

•  http_response

Functions

•  llEscapeURL
•  llUnescapeURL

Articles

•  Simulator IP Addresses

Deep Notes

Search JIRA for related Issues

Footnotes

  1. ^ A list of acceptable certificate authorities can be found at SCR-473.

Signature

function key llHTTPRequest( string url, list parameters, string body );