The XMLHTTPRequest class represents a HTTP request. More...

Public Member Functions
boolean	abort ()
	Abort an asynchronous request if it already has been sent. More...

boolean	addRequestHeader (String name, String value)
	Add a HTTP header to the request to be sent. More...

String	getAllResponseHeaders ()
	Get all response headers as a string. More...

String	getResponseHeader (String name)
	Get the value of the specified response header. More...

boolean	open (String method, String url, boolean async=false, String user="", String passwd="")
	Initialize a HTTP request. More...

boolean	send (String content="")
	Send the request to the HTTP server. More...

void	setCAInfo (String pemFile, int options)
	Set one or more certificates to verify the peer if using HTTPS. More...

XMLHTTPRequest	XMLHTTPRequest (String proxy="", int proxyPort=3128, String proxyUser="", String proxyPasswd="")
	Create a new XMLHTTPRequest object. More...

XMLHTTPRequest	XMLHTTPRequest (bool useProxySetting=true)
	Create a new XMLHTTPRequest object with option to switch off the query mechanism for proxy settings. More...

Public Attributes
boolean	canAsync
	Flag indicating whether asynchronous requests are possible on the used plattform. More...

boolean	canProxy
	Flag indicating whether the implementation on the used plattform allows the direct specifying of a proxy server. More...

int	COMPLETED
	The constant 4 for XMLHTTPRequest.readyState. More...

int	FileSizeHint
	Optional File size indicator for sending pure sequential files. More...

int	INTERACTIVE
	The constant 3 for XMLHTTPRequest.readyState. More...

int	NOTSENT
	The constant 1 for XMLHTTPRequest.readyState. More...

int	readyState
	The current state of the asynchronous request. More...

Var	response
	The response received from the HTTP server or null if no response is received. More...

File	responseFile
	An optional writable file for streaming a large response. More...

String	responseType
	Preferred output format of the response property (optional). More...

int	SENT
	The constant 2 for XMLHTTPRequest.readyState. More...

int	status
	The HTTP status code of the request. More...

String	statusText
	The HTTP status text of the request. More...

int	UNINITIALIZED
	The constant 0 for XMLHTTPRequest.readyState. More...

int	VERIFYHOST
	Constant for CA Certificate verification if using HTTPS. More...

int	VERIFYPEER
	Constant for CA Certificate verification if using HTTPS. More...

Detailed Description

The XMLHTTPRequest class represents a HTTP request.

Though the name of this class traditionally refers to XML, it can be used to transfer arbitrary strings or binary data. The interface is based on the definition of the class IXMLHTTPRequest from MSXML. As http-library the libcurl is used. To send a HTTP request the following steps are needed:

Creating an instance of this class.
Initializing the request via open(). Possibly also adding header data by means of addRequestHeader().
Sending the request via send().
In case of asynchronous request checking for completion of the request operation via XMLHTTPRequest.readyState.
Evaluating the result via e.g. XMLHTTPRequest.status, XMLHTTPRequest.response and getAllResponseHeaders().

See SOAP Client using DOM for a detailed example using XMLHTTPRequest.

Example:: // synchron
var xmlHttp = new XMLHTTPRequest();
var async = false;
var url = "https://developers.mdocs.si/soap/";
xmlHttp.open("GET", url + "?wsdl", async);
xmlHttp.send();
util.out(xmlHttp.response);

Example:: // asynchron
var xmlHttp = new XMLHTTPRequest();
var async = true;
var url = "http://localhost:11001/";
xmlHttp.open("GET", url + "?wsdl", async);
xmlHttp.send();
while(xmlHttp.status != xmlHttp.COMPLETED) {
util.sleep(500); // sleep 500 ms
}
util.out(xmlHttp.response);

Note

The XMLHTTPRequest is able to use a proxy configuration. The server searches the proxy settings in the following order (priority)

Specification in the constructor function s. XMLHTTPRequest(String proxy, int proxyPort, String proxyUser, String proxyPasswd)
Global specification in the documents.ini
On Windows systems: Internet Explorer proxy configuration for the current user
On Windows systems: Default WinHTTP proxy configuration from the registry.

If you want to be sure, that no proxy must be used, then use the constructor function XMLHTTPRequest(bool useProxySetting) with useProxySetting = false

Since: DOCUMENTS 4.0

Constructor & Destructor Documentation

◆ XMLHTTPRequest() [1/2]

XMLHTTPRequest XMLHTTPRequest::XMLHTTPRequest	(	String	proxy = `""`,
		int	proxyPort = `3128`,
		String	proxyUser = `""`,
		String	proxyPasswd = `""`
	)

Create a new XMLHTTPRequest object.

Parameters

proxy	Optional string value specifying the hostname of the proxy server being resolvable by the nameserver. On windows OS: If this parameter is not specified, the windows proxy configuration will be used. E.g. the proxy server specified in Internet Explorer is used in the registry.
proxyPort	Optional number of the port on which the proxy accepts requests.
proxyUser	Optional string value specifying the desired login name for the proxy
proxyPasswd	Optional string value specifying the password for logging in to the proxy

Note: On windows OS: If no proxy is specified as first parameter, the proxy settings of the Internet Explorer and and the WinHTTP configuration will be checked, and a defined proxy setting will be used.

Since: DOCUMENTS 4.0; DOCUMENTS 5.0c (on windows OS support of system proxy configuration)

See also: XMLHTTPRequest.canProxy

◆ XMLHTTPRequest() [2/2]

XMLHTTPRequest XMLHTTPRequest::XMLHTTPRequest ( bool useProxySetting = true )

Create a new XMLHTTPRequest object with option to switch off the query mechanism for proxy settings.

Parameters

useProxySetting Boolean value. Set to false to switch off the query for proxy settings.

Since: DOCUMENTS 5.0d HF2

Member Function Documentation

◆ abort()

boolean XMLHTTPRequest::abort ( )

Abort an asynchronous request if it already has been sent.

Returns: true if successful, false in case of any error.

Since: DOCUMENTS 4.0

Example:: var xmlHttp = new XMLHTTPRequest();
var async = true;
var url = "http://localhost:11001/";
xmlHttp.open("POST", url, async);
xmlHttp.send(content);
var timeout = 3000; // milliseconds
var idle = 200; // 200 ms
var timeoutTS = (new Date()).getTime() + timeout;
while (httpCon.readyState != httpCon.COMPLETED) {
if ((new Date()).getTime() > timeoutTS) {
xmlHttp.abort();
xmlHttp = null;
}
util.sleep(idle);
}
if (xmlHttp)
util.out(xmlHttp.status);

◆ addRequestHeader()

boolean XMLHTTPRequest::addRequestHeader	(	String	name,
		String	value
	)

Add a HTTP header to the request to be sent.

Parameters

name	String specifying the header name.
value	String specifying the header value.

Returns: true if the header was added successfully, false in case of any error.

Note: The request must be initialized via open() before.

Since: DOCUMENTS 4.0

Example:: var xmlHttp = new XMLHTTPRequest();
var async = true;
var url = "http://localhost:11001/";
xmlHttp.open("POST", url, async);
xmlHttp.addRequestHeader("Content-Type", "text/xml");
xmlHttp.send(c);

◆ getAllResponseHeaders()

String XMLHTTPRequest::getAllResponseHeaders ( )

Get all response headers as a string.

Each entry is in a separate line and has the form 'name:value'.

Returns: All response headers as a string.

Since: DOCUMENTS 4.0

Example:: var xmlHttp = new XMLHTTPRequest();
var async = false;
var url = "http://localhost:11001/";
xmlHttp.open("POST", url, async);
if (xmlHttp.send(content))
util.out(xmlHttp.getAllResponseHeaders());

◆ getResponseHeader()

String XMLHTTPRequest::getResponseHeader ( String name )

Get the value of the specified response header.

Parameters

name	String specifying the response header name.

Returns: String with the value of the response header, an empty string in case of any error.

Since: DOCUMENTS 4.0

Example:: var xmlHttp = new XMLHTTPRequest();
var async = false;
var url = "http://localhost:11001/";
xmlHttp.open("POST", url, async);
if (xmlHttp.send(content))
util.out(xmlHttp.getResponseHeader("Content-Type"));

◆ open()

boolean XMLHTTPRequest::open	(	String	method,
		String	url,
		boolean	async = `false`,
		String	user = `""`,
		String	passwd = `""`
	)

Initialize a HTTP request.

Parameters

method	String specifying the used HTTP method. The following methods are available: GET: Sending a GET request, for example, for querying a HTML file. PUT: Sending data to the HTTP server. The data must be passed in the send() call. The URI represents the name under which the data should be stored. Under this name, the data are then normally retrievable. POST: Sending data to the HTTP server. The data must be passed in the send() call. The URI represents the name of the consumer of the data. DELETE: Sending a DELETE request. PATCH: Sending a PATCH request, see RFC 5789 (https://tools.ietf.org/html/rfc5789).
url	String containing the URL for this request.
async	Optional flag indicating whether to handle the request asynchronously. In this case the operation send() returns immediately, in other word, it will not be waiting until a response is received. Asynchronous sending is only possible, when XMLHTTPRequest.canAsync returns `true`. If asynchronous sending is not possible, this flag will be ignored. For an asynchronous request you can use XMLHTTPRequest.readyState to get the current state of the request.
user	Optional user name must be specified only if the HTTP server requires authentication.
passwd	Optional password must also be specified only if the HTTP server requires authentication.

Returns: true if the request was successfully initialized, false in case of any error.

Since: DOCUMENTS 4.0; DOCUMENTS 5.0e (support PATCH request)

Example:: var xmlHttp = new XMLHTTPRequest();
var async = false;
var url = "http://localhost:11001/";
xmlHttp.open("GET", url + "?wsdl", async);
xmlHttp.send();

See also: XMLHTTPRequest.send(String content), XMLHTTPRequest.canAsync

◆ send()

boolean XMLHTTPRequest::send ( String content = "" )

Send the request to the HTTP server.

The request must be prepared via open() before.

Parameters

content Optional content to be sent; usually a String. See the remarks section about using other types.

Returns: true if the request was successfully performed or initiated (for asynchronous requests), false in case of any error.

Note: The request must be initialized via open() before. You can use XMLHTTPRequest.readyState to get the current state of an asynchronous request. The properties XMLHTTPRequest.status and XMLHTTPRequest.statusText return the status of the completed request while using getResponseHeader() and XMLHTTPRequest.response the actual result of the request can be retrieved. An asynchronous request can be canceled using abort().

Remarks: The type of the content parameter can be one of the following: String, ArrayBuffer, File. Caution: all other types will be converted to a string! Given a conventional array, the function will only send a string like "[object Array]".

About files
Passed files must be opened in binary read mode. If the file is not rewindable (a named pipe, for instance), the property FileSizeHint should be set before sending. The property is useful to supress an automatic length scan. The function implicitly closes the File object, though the file may remain open for asynchronous operation. When an asynchronous request is completed, its associated files become closed outside the JavaScript environment.

About Arraybuffers
Passing a TypedArray (UInt8Array, Int16Array etc.) instead of an ArrayBuffer is possible, but not recommended. The actual implementation always sends the complete associated buffer. The result can be unexpected, if the TypedArray covers only a section of a bigger buffer. This behaviour might change in future releases.

Since: DOCUMENTS 4.0; DOCUMENTS 5.0c (Support for sending File and ArrayBuffer)

Example:: var xmlHttp = new XMLHTTPRequest();
var async = false;
if (xmlHttp.canAsync)
async = true;
var url = "http://localhost:11001/";
xmlHttp.open("GET", url + "?wsdl", async);
xmlHttp.send(null);
if (async) {
while(xmlHttp.status != xmlHttp.COMPLETED) {
util.sleep(500); // sleep 500 ms
}
}
util.out(xmlHttp.status); // should be 200

Example:: var file = new File("E:\\test\\Lighthouse.jpg", "rb");
if(!file || !file.ok())
throw "File not found";
var req = new XMLHTTPRequest();
var url = "http://localhost:8080/myUploadServlet";
req.open("PUT", url, false);
// Uncomment the following instruction to suppress the
// "100-continue" communication cycle, if the target server
// does not support it. This might also speed up very little
// uploads. Otherwise better keep the default behaviour.
// req.addRequestHeader("Expect", " ");
req.addRequestHeader("Filename", "Lighthouse.jpg");
req.send(file);
util.out(req.status);
util.out(req.response);
// No need to close file here; send() already did.
util.out(req.status); // should be 200

See also: XMLHTTPRequest.open(String method, String url, boolean async, String user, String passwd), FileSizeHint

◆ setCAInfo()

void XMLHTTPRequest::setCAInfo	(	String	pemFile,
		int	options
	)

Set one or more certificates to verify the peer if using HTTPS.

Parameters

pemFile	String with the path to pem-file with the servers certificates (bundle of X.509 certificates in PEM format).
options	Integer with a bitmask of verification-options (XMLHTTPRequest.VERIFYPEER, XMLHTTPRequest.VERIFYHOST)

Since: DOCUMENTS 5.0c

Example:: var url = "https://someserver:443/";
var xmlHttp = new XMLHTTPRequest();
xmlHttp.setCAInfo("c:\\certs\\cabundle.pem", XMLHTTPRequest.VERIFYPEER + XMLHTTPRequest.VERIFYHOST);
var async = false;
xmlHttp.open("POST", url, async);
if (xmlHttp.send(content))
util.out(xmlHttp.getAllResponseHeaders());

Member Data Documentation

◆ canAsync

boolean XMLHTTPRequest::canAsync

Flag indicating whether asynchronous requests are possible on the used plattform.

Note: This property is readonly.

Since: DOCUMENTS 4.0

◆ canProxy

boolean XMLHTTPRequest::canProxy

Flag indicating whether the implementation on the used plattform allows the direct specifying of a proxy server.

Note: This property is readonly.

Since: DOCUMENTS 4.0

◆ COMPLETED

int XMLHTTPRequest::COMPLETED

The constant 4 for XMLHTTPRequest.readyState.

In this state the request is completed. All the data are available now.

Note: This property is readonly.

Since: DOCUMENTS 4.0

◆ FileSizeHint

int XMLHTTPRequest::FileSizeHint

Optional File size indicator for sending pure sequential files.

When uploading files, the send() function usually detects the file size and forwards it to lower APIs. This is helpful in most cases, because old simple HTTP servers do not support the transfer mode "chunked". Web services may reject uploads without an announced content-length, too.
However, the auto-detection will fail, if a given file is not rewindable (a named pipe, for instance). To avoid errors this property should be set before sending such a special file. After the transmission the property should be either set to "-1" or deleted.
The value is interpreted in the following way.

Values > 0 specify a precise file size in bytes.
The value -1 has the same effect as leaving the property undefined (enable auto-detection).
The value -2 disables file size detection and enforces a chunked transfer.

Note: This property serves as a hidden optional parameter to the send() function. On new objects it is undefined. Assigning an incorrect value >= 0 may trigger deadlocks or timeouts.

See also: send()

Since: DOCUMENTS 5.0c

◆ INTERACTIVE

int XMLHTTPRequest::INTERACTIVE

The constant 3 for XMLHTTPRequest.readyState.

In this state the request is partially completed. This means that some data has been received.

Note: This property is readonly.

Since: DOCUMENTS 4.0

◆ NOTSENT

int XMLHTTPRequest::NOTSENT

The constant 1 for XMLHTTPRequest.readyState.

In this state the object has been initialized, but not sent yet.

Note: This property is readonly.

Since: DOCUMENTS 4.0

◆ readyState

int XMLHTTPRequest::readyState

The current state of the asynchronous request.

The following states are available:

XMLHTTPRequest.UNINITIALIZED = 0 : the method open() has not been called.
XMLHTTPRequest.NOTSENT = 1: the object has been initialized, but not sent yet.
XMLHTTPRequest.SENT = 2 : the object has been sent. No data is available yet.
XMLHTTPRequest.INTERACTIVE = 3: the request is partially completed. This means that some data has been received.
XMLHTTPRequest.COMPLETED = 4: the request is completed. All the data are available now.

Note: This property is readonly.

Since: DOCUMENTS 4.0

◆ response

Var XMLHTTPRequest::response

The response received from the HTTP server or null if no response is received.

Note: This property is readonly. Starting with DOCUMENTS 5.0c its data type is influenced by the optional property responseType. The default type is String. For requests with an attached responseFile this value can be truncated after a few kBytes.

See also: responseType, responseFile

Since: DOCUMENTS 4.0

Example:: var xmlHttp = new XMLHTTPRequest();
var async = false;
var url = "http://localhost:11001/";
xmlHttp.open("POST", url, async);
if (xmlHttp.send(content))
util.out(xmlHttp.response);

◆ responseFile

File XMLHTTPRequest::responseFile

An optional writable file for streaming a large response.

To achieve an efficient download scripts can create a writable File an attach it to the request. The complete response will then be written into this file. The value of the response property, however, will be truncated after the first few kBytes.

Note: On new objects this property is undefined.
When send() is called, the request takes exclusive ownership of the attached file. The property will then be reset to null. Even in asynchronous mode send() seems to close the file immediately. In fact, send() detaches the native file handle from the JavaScript object to ensure exclusive access.
Received content will be written to the file, disregarding the HTTP status.

See also: response, responseType, File

Since: DOCUMENTS 5.0c

Example:: var url = "http://localhost:8080/documents/img/documents/skin/black/module/dashboard/48/view.png";
var req = new XMLHTTPRequest;
req.open("GET", url);
var file = new File("E:\\test\\downloaded.png", "wb");
if(!file.ok())
return "Cannot open response file for writing";
req.responseFile = file;
req.send();
return req.status;

◆ responseType

String XMLHTTPRequest::responseType

Preferred output format of the response property (optional).

By default, the object expects text responses and stores them in a String. If the application expects binary data, it may request an ArrayBuffer by setting this property to "arraybuffer".

Note: On new objects this property is undefined. ArrayBuffer responses are created only once after each request. If a script changes the received buffer, the response property will reflect these changes until a new request starts.

See also: response, responseFile

Since: DOCUMENTS 5.0c

◆ SENT

int XMLHTTPRequest::SENT

The constant 2 for XMLHTTPRequest.readyState.

In this state the object has been sent. No data is available yet.

Note: This property is readonly.

Since: DOCUMENTS 4.0

◆ status

int XMLHTTPRequest::status

The HTTP status code of the request.

Note: This property is readonly.

Since: DOCUMENTS 4.0

See also: XMLHTTPRequest.statusText

◆ statusText

String XMLHTTPRequest::statusText

The HTTP status text of the request.

Note: This property is readonly.

Since: DOCUMENTS 4.0

See also: XMLHTTPRequest.status

◆ UNINITIALIZED

int XMLHTTPRequest::UNINITIALIZED

The constant 0 for XMLHTTPRequest.readyState.

In this state the method open() has not been called.

Note: This property is readonly.

Since: DOCUMENTS 4.0

◆ VERIFYHOST

int XMLHTTPRequest::VERIFYHOST

Constant for CA Certificate verification if using HTTPS.

This option activate the verification of the host.

Note: This property is readonly.

Since: DOCUMENTS 5.0c

See also: XMLHTTPRequest.setCAInfo(String pemFile, int options)

◆ VERIFYPEER

int XMLHTTPRequest::VERIFYPEER

Constant for CA Certificate verification if using HTTPS.

This option activate the verification of the certificate chain.

Note: This property is readonly.

Since: DOCUMENTS 5.0c

See also: XMLHTTPRequest.setCAInfo(String pemFile, int options)

Public Member Functions

Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ XMLHTTPRequest() [1/2]

◆ XMLHTTPRequest() [2/2]

Member Function Documentation

◆ abort()

◆ addRequestHeader()

◆ getAllResponseHeaders()

◆ getResponseHeader()

◆ open()

◆ send()

◆ setCAInfo()

Member Data Documentation

◆ canAsync

◆ canProxy

◆ COMPLETED

◆ FileSizeHint

◆ INTERACTIVE

◆ NOTSENT

◆ readyState

◆ response

◆ responseFile

◆ responseType

◆ SENT

◆ status

◆ statusText

◆ UNINITIALIZED

◆ VERIFYHOST

◆ VERIFYPEER