XMLHttpRequest

Description

Supported Script Types:

  • Interface Scripts
  • Client Entity Scripts
  • Avatar Scripts
  • Server Entity Scripts
  • Assignment Client Scripts
Provides a means to interact with web servers. It is a near-complete implementation of the XMLHttpRequest API described in the Mozilla docs: https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest.

Create using new XMLHttpRequest(...).

Properties

Name Type Summary
response *

The response data. Read-only.

responseText string

The response data as text. Read-only.

responseType string

The response type required or received (e.g., "text", "json", "arraybuffer", ...).

status number

The HTTP response status code (100599). Read-only.

statusText string

The HTTP response status text. Read-only.

readyState XMLHttpRequest.ReadyState

The status of the request. Read-only.

errorCode XMLHttpRequest.NetworkError

The network result of the request: including, 0 (NoError) if there was no error, 4 (TimeoutError) if the request timed out. Read-only.

timeout number

The time a request can take before timing out, in ms.

UNSENT XMLHttpRequest.ReadyState

Request has been created; XMLHttpRequest.open not called yet. Read-only.

OPENED XMLHttpRequest.ReadyState

XMLHttpRequest.open has been called. Read-only.

HEADERS_RECEIVED XMLHttpRequest.ReadyState

XMLHttpRequest.send has been called; headers and status are available. Read-only.

LOADING XMLHttpRequest.ReadyState

Downloading; XMLHttpRequest.responseText has partial data. Read-only.

DONE XMLHttpRequest.ReadyState

Operation complete. Read-only.

ontimeout XMLHttpRequest~onTimeoutCallback

Function called when the request times out.

Note: This is called in addition to any function set for onreadystatechange.

onreadystatechange XMLHttpRequest~onReadyStateChangeCallback

Function called when the request's ready state changes.

Constructor
new XMLHttpRequest( )

Examples

Get a web page's HTML.

var URL = "https://www.highfidelity.com/";

var req = new XMLHttpRequest();
req.onreadystatechange = function () {
    if (req.readyState === req.DONE) {
        if (req.status === 200) {
            print("Success");
            print("Content type:", req.getResponseHeader("content-type"));
            print("Content:", req.responseText.slice(0, 100), "...");

        } else {
            print("Error", req.status, req.statusText);
        }

        req = null;
    }
};

req.open("GET", URL);
req.send();

Get a web page's HTML — alternative method.

var URL = "https://www.highfidelity.com/";

var req = new XMLHttpRequest();
req.requestComplete.connect(function () {
    if (req.status === 200) {
        print("Success");
        print("Content type:", req.getResponseHeader("content-type"));
        print("Content:", req.responseText.slice(0, 100), "...");

    } else {
        print("Error", req.status, req.statusText);
    }

    req = null;
});

req.open("GET", URL);
req.send();

Methods

Name Return Value Summary
abort None

Aborts the request.

getAllResponseHeaders string

Gets the response headers.

getResponseHeader string

Gets a response header.

open None

Initializes a request.

send None

Sends the request to the server.

setRequestHeader None

Sets the value of an HTTP request header. Must be called after XMLHttpRequest.open but before XMLHttpRequest.send;

Signals

Name Summary
requestComplete

Triggered when the request is complete — with or without error (incl. timeout).

Type Definitions

NetworkError
Type: number

The type of network error.

ValueNameDescription
0NoErrorNo error.
1ConnectionRefusedErrorThe server refused the connection.
2RemoteHostClosedErrorThe server closed the connection.
3HostNotFoundErrorHost name not found.
4TimeoutErrorConnection timed out
5OperationCanceledErrorOperation canceled by XMLHttpRequest.abort.
6SslHandshakeFailedErrorSSL/TLS handshake failed.
7TemporaryNetworkFailureErrorTemporarily disconnected from the network.
8NetworkSessionFailedErrorDisconnection from the network.
9BackgroundRequestNotAllowedErrorBackground request not allowed.
10TooManyRedirectsErrorToo many redirects.
11InsecureRedirectErrorRedirect from secure to insecure protocol.
101ProxyConnectionRefusedErrorConnection to proxy server refused.
102ProxyConnectionClosedErrorProxy server closed the connection.
103ProxyNotFoundErrorProxy host name not found.
104ProxyTimeoutErrorProxy connection timed out.
105ProxyAuthenticationRequiredErrorProxy requires authentication.
201ContentAccessDeniedAccess denied.
202ContentOperationNotPermittedErrorOperation not permitted.
203ContentNotFoundErrorContent not found.
204AuthenticationRequiredErrorAuthentication required.
205ContentReSendErrorResend failed.
206ContentConflictErrorResource state conflict.
207ContentGoneErrorResource no longer available.
401InternalServerErrorInternal server error.
402OperationNotImplementedErrorOperation not supported.
403ServiceUnavailableErrorRequest not able to be handled at this time.
301ProtocolUnknownErrorProtocol unknown.
302ProtocolInvalidOperationErrorOperation invalid fro protocol.
99UnknownNetworkErrorUnknown network-related error.
199UnknownProxyErrorUnknown proxy-related error.
299UnknownContentErrorUnknown content-related error.
399ProtocolFailureProtocol error.
499UnknownServerErrorUnknown server response error.
ReadyState
Type: number

The state of an XMLHttpRequest.

ValueNameDescription
0UNSENTRequest has been created; XMLHttpRequest.open not called yet.
1OPENEDXMLHttpRequest.open has been called.
2HEADERS_RECEIVEDXMLHttpRequest.send has been called; headers and status are available.
3LOADINGDownloading; XMLHttpRequest.responseText has partial data.
4DONEOperation complete.
onReadyStateChangeCallback( )
Type: function

Called when the request's ready state changes.

onTimeoutCallback( )
Type: function

Called when the request times out.

Method Details

(static) abort( )

Aborts the request.

(static) getAllResponseHeaders( ) → {string}
Returns: The response headers, separated by "\n" characters.

Gets the response headers.

(static) getResponseHeader( name ) → {string}
Returns: The response header.

Gets a response header.

Parameters

Name Type Description
name string

-

(static) open( method, url, asyncopt, usernameopt, passwordopt )

Initializes a request.

Parameters

Name Type Attributes Default Value Description
method string

The HTTP request method to use, e.g., "GET", "POST", "PUT", or "DELETE".

url string

The URL to send the request to.

async boolean <optional>
true

true if the method returns without waiting for the response, false if the method returns only once the request is complete.

username string <optional>
""

User name for authentication.

password string <optional>
""

Password for authentication.

(static) send( dataopt )

Sends the request to the server.

Parameters

Name Type Attributes Description
data * <optional>

The data to send.

(static) setRequestHeader( name, value )

Sets the value of an HTTP request header. Must be called after XMLHttpRequest.open but before XMLHttpRequest.send;

Parameters

Name Type Description
name string

The name of the header to set.

value string

The value of the header.

Signal Details

requestComplete( )
Returns: Signal

Triggered when the request is complete — with or without error (incl. timeout).