XMLHttpRequest - Vircadia API Docs

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 (`100` – `599`). 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.

Value	Name	Description
`0`	NoError	No error.
`1`	ConnectionRefusedError	The server refused the connection.
`2`	RemoteHostClosedError	The server closed the connection.
`3`	HostNotFoundError	Host name not found.
`4`	TimeoutError	Connection timed out
`5`	OperationCanceledError	Operation canceled by XMLHttpRequest.abort.
`6`	SslHandshakeFailedError	SSL/TLS handshake failed.
`7`	TemporaryNetworkFailureError	Temporarily disconnected from the network.
`8`	NetworkSessionFailedError	Disconnection from the network.
`9`	BackgroundRequestNotAllowedError	Background request not allowed.
`10`	TooManyRedirectsError	Too many redirects.
`11`	InsecureRedirectError	Redirect from secure to insecure protocol.
`101`	ProxyConnectionRefusedError	Connection to proxy server refused.
`102`	ProxyConnectionClosedError	Proxy server closed the connection.
`103`	ProxyNotFoundError	Proxy host name not found.
`104`	ProxyTimeoutError	Proxy connection timed out.
`105`	ProxyAuthenticationRequiredError	Proxy requires authentication.
`201`	ContentAccessDenied	Access denied.
`202`	ContentOperationNotPermittedError	Operation not permitted.
`203`	ContentNotFoundError	Content not found.
`204`	AuthenticationRequiredError	Authentication required.
`205`	ContentReSendError	Resend failed.
`206`	ContentConflictError	Resource state conflict.
`207`	ContentGoneError	Resource no longer available.
`401`	InternalServerError	Internal server error.
`402`	OperationNotImplementedError	Operation not supported.
`403`	ServiceUnavailableError	Request not able to be handled at this time.
`301`	ProtocolUnknownError	Protocol unknown.
`302`	ProtocolInvalidOperationError	Operation invalid fro protocol.
`99`	UnknownNetworkError	Unknown network-related error.
`199`	UnknownProxyError	Unknown proxy-related error.
`299`	UnknownContentError	Unknown content-related error.
`399`	ProtocolFailure	Protocol error.
`499`	UnknownServerError	Unknown server response error.

ReadyState
Type: number

The state of an XMLHttpRequest.

Value	Name	Description
`0`	UNSENT	Request has been created; XMLHttpRequest.open not called yet.
`1`	OPENED	XMLHttpRequest.open has been called.
`2`	HEADERS_RECEIVED	XMLHttpRequest.send has been called; headers and status are available.
`3`	LOADING	Downloading; XMLHttpRequest.responseText has partial data.
`4`	DONE	Operation 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).