Object: XMLHttpRequest

Help Center

Search This Document

Download PDF

Availability

BlackBerry® Device Software version 4.6 or later

The XMLHttpRequest object enables you to transfer data to and from the server without reloading or replacing the current document.

To make an HTTP request, you create the instance of the object, open a URL, and send the request. The HTTP status code of the result, as well as the result document are available in the request object afterwards.

Because it allows you to communicate with a server in the background, the XMLHttpRequest object enables you to create extremely dynamic documents.

XMLHttpRequest properties

Property name	Type	Description	Status	Availability
`readyState`	unsigned short	Returns the status of the server's response. Each time the `readyState` property changes, the `onreadystatechange` function will be executed. This property may return the following values: `0` = `UNSENT`: Represents the initial state of the object. `1` = `OPENED`: Indicates that `XMLHttpRequest.open()` has been successfully invoked. `2` = `HEADERS_RECEIVED`: Indicates that all the response headers have been received. `3` = `LOADING`: Indicates that the response entity body is being received. `4` = `DONE`: Indicates that the data transfer is complete, or that the transfer was aborted due to an error. This state has an associated error flag which indicates whether the response was successfully received.	read only	4.6 or later
`responseText`	String	Returns the response text entity body. This might return only a fragment of the entity body, if the request response is still in the loading state.	read only	4.6 or later
`responseXML`	String	Returns the XML response entity body. This might return only a fragment of the entity body, if the request response is still in the loading state.	read only	4.6 or later
`status`	unsigned short	Returns the HTTP status code sent by the server, or, if no status code is available, throws an `INVALID_STATE_ERR` exception.	read only	4.6 or later
`statusText`	String	Returns the HTTP status text sent by the server, or, if no status text is available, throws an `INVALID_STATE_ERR` exception.	read only	4.6 or later

XMLHttpRequest event handlers

Property name	Type	Description	Status	Availability
`onreadystatechange`	`EventListener`	Specifies the function to perform when a form control loses focus after the user has modified the value.	writable	4.6 or later

XMLHttpRequest methods

Method name	Description	Availability
`abort()`	Adds an `EventListener` object to a set of event listeners for the window.	4.6 or later
`addEventListener()`	Adds an `EventListener` object to a set of event listeners for the given node.	4.6 or later
`dispatchEvent()`	Dispatches an Event object created by `Document.createEvent()`.	4.6 or later
`getAllResponseHeaders()`	Returns a complete set of headers and their values.	4.6 or later
`getResponseHeader()`	Returns the value of the given header.	4.6 or later
`open()`	Assigns the HTTP method and destination URL, as well as some additional optional parameters, for a pending request.	4.6 or later
`removeEventListener()`	Removes an event listener from an `EventTarget`.	4.6 or later
`send()`	Sends the request to the URL specified by `XMLHttpRequest.open()`.	4.6 or later
`setRequestHeader()`	Specifies the value of a header to be sent with the request.	4.6 or later

Method: XMLHttpRequest.abort()

Availability

BlackBerry® Device Software version 4.6 or later

The abort() method stops the current request in progress.

When a request is aborted, the value for XMLHttpRequest.readyState is automatically set to DONE.

Syntax

XMLHttpRequest.abort()

Parameters

None.

Return values

None.

Exceptions

None.

Method: XMLHttpRequest.addEventListener()

Availability

BlackBerry® Device Software version 4.6 or later

The addEventListener() method adds an EventListener object to the XMLHttpRequest object.

Syntax

XMLHttpRequest.addEventListener( type, listener, useCapture )

Parameters

Parameter	Type	Description
`type`	String	The type of event to add.
`listener`	`EventListener`	The `EventListener` function to be invoked.
`useCapture`	boolean	When `true`, indicates all events of the specified type to the registered `EventListener` before being dispatched to any `EventTarget` objects beneath the given node in the tree. Bubbling events will not trigger the `EventListener`. When `false`, this method dispatches events of the specified type to the registered `EventListener` before being dispatched to any `EventTarget` objects above the given node in the tree.

Parameter

Type

Description

type

String

The type of event to add.

listener

EventListener

The EventListener function to be invoked.

useCapture

boolean

When true, indicates all events of the specified type to the registered EventListener before being dispatched to any EventTarget objects beneath the given node in the tree. Bubbling events will not trigger the EventListener.

When false, this method dispatches events of the specified type to the registered EventListener before being dispatched to any EventTarget objects above the given node in the tree.

Return values

None.

Exceptions

None.

Method: XMLHttpRequest.dispatchEvent()

Availability

BlackBerry® Device Software version 4.6 or later

The dispatchEvent() method dispatches an Event object created by Document.createEvent().

Syntax

XMLHttpRequest.dispatchEvent( event )

Parameters

Parameter	Type	Description
`event`	`Event`	The `Event` object to be dispatched.

Return values

Returns true if the Event.preventDefault() was not called by any of the event listeners that handled the event. The Event.preventDefault() method prevents the default action for the event from occurring. Otherwise, returns false.

Exceptions

Exception	Description
`UNSPECIFIED_EVENT_TYPE_ERR`	This error is thrown if the event type was not specified by initializing the event before calling `dispatchEvent()`, or if the event type was null.

Method: XMLHttpRequest.getAllResponseHeaders()

Availability

BlackBerry® Device Software version 4.6 or later

The getAllResponseHeaders() method returns a complete set of headers and their values.

Syntax

XMLHttpRequest.getAllResponseHeaders()

Parameters

None.

Return values

Returns all the response headers as a single string, with each header separated by a carriage return and a line feed character.

Exceptions

Exception	Description
`INVALID_STATE_ERR`	This error is thrown if this method is called before any response headers have been received (that is, before the `XMLHttpRequest.readyState` property has a value of `2`, indicating `HEADERS_RECEIVED`).

Method: XMLHttpRequest.getResponseHeader()

Availability

BlackBerry® Device Software version 4.6 or later

The getResponseHeader() method returns the value of a given header.

Syntax

XMLHttpRequest.getResponseHeader( header )

Parameters

Parameter	Type	Description
`header`	String	The header to match on. This parameter is not case-sensitive.

Return values

Returns the value of the given header, or null if the header is not present in the header list. If header matches more than one header in the list of response headers, the values are concatenated into a single comma-separated list.

Exceptions

Exception	Description
`INVALID_STATE_ERR`	This error is thrown if this method is called before any response headers have been received (that is, before the `XMLHttpRequest.readyState` property has a value of `2`, indicating `HEADERS_RECEIVED`).

Method: XMLHttpResponse.open()

Availability

BlackBerry® Device Software version 4.6 or later

The open() method assigns the HTTP method and destination URL, as well as some additional optional parameters, for a pending request.

When this method is successfully invoked, the value for the XMLHttpRequest.readyState property is set to OPENED.

Syntax

XMLHttpRequest.open( method, url [, async] [, user] [, password] )

Parameters

Parameter	Type	Description
`method`	String	The HTTP method used to open the connection, This parameter may have one of the following values: `DELETE` `GET` `HEAD` `OPTIONS` `POST` `PUT`
`url`	String	The destination URL of the request. The URL may be an absolute or a relative URL. If you specify a relative URL, this method resolves the address by accessing the `baseURI` property of the `Document` object reference that is created when the `XMLHttpRequest` object is constructed.
`async`	boolean	Optional. When set to `true`, this parameter indicates that the request is asynchronous. If no value is specified, a value of `true` is specified by default. When set to a value of `false`, the request is synchronous. if a request is synchronous, no other operations can be performed by the browser until the data has been received, or the request is aborted. Because of the variability of network speed and connection availability in a wireless browsing environment, when the `XMLHttpRequest` object is used in conjunction with the BlackBerry® Browser, requests should in almost all cases be made asynchronous.
`user`	String	Optional. Specifies a username, if the server requires user authentication. If this value is not specified and the destination URL requires the user to be authenticated, the user will be prompted for their user credentials.
`password`	String	Optional. Specifies a password, if the server requires user authentication.

Return values

None.

Method: XMLHttpRequest.removeEventListener()

Availability

BlackBerry® Device Software version 4.6 or later

The removeEventListener() method removes an event listener from an EventTarget.

Syntax

XMLHttpRequest.removeEventListener( type, listener, useCapture )

Parameters

Parameter	Type	Description
`type`	String	The type of event.
`listener`	`EventListener`	The event listener function to be removed.
`useCapture`	boolean	When `true`, indicates that the `EventListener` being removed was registered as a capturing listener. A listener may be registered twice, once as a capturing listener, and once as a non-capturing listener. Each must be removed separately.

Parameter

Type

Description

type

String

The type of event.

listener

EventListener

The event listener function to be removed.

useCapture

boolean

When true, indicates that the EventListener being removed was registered as a capturing listener.

A listener may be registered twice, once as a capturing listener, and once as a non-capturing listener. Each must be removed separately.

Return values

None.

Exceptions

None.

Method: XMLHttpRequest.send()

Availability

BlackBerry® Device Software version 4.6 or later

The send() method sends the request to the URL specified by XMLHttpRequest.open(). If the request is asynchronous, this method is returned as a callback when the response has been successfully received. The send() method must be called only after the request has been opened using XMLHttpRequest.open().

This method can pass data to the server either as a string of text or as a Document object.

If a value for the data parameter is specified, it becomes the entity body for the request. In order for the server to properly handle the data, you should specify the content type using XMLHttpRequest.setRequestHeader() before invoking this method.

If data is not specified, no entity body is sent with the request.

Syntax

XMLHttpRequest.send( [data] )

Parameters

Parameter	Type	Description
`data`	String \|`Document`	Optional. The data to send to the server. If `data` is not a string or a `Document` object, the BlackBerry® Browser attempts to convert it into a string before passing it on to the server. If it is unable to do so, the request is sent as if `data` had a null value.

Parameter

Type

Description

data

String |Document

Optional. The data to send to the server.

If data is not a string or a Document object, the BlackBerry® Browser attempts to convert it into a string before passing it on to the server. If it is unable to do so, the request is sent as if data had a null value.

Return values

If the request was asynchronous, this method returns the callback when the response has been successfully received.

Exceptions

Exception	Description
`ABORT_ERR`	This error is thrown if the request was cancelled by the user.
`INVALID_STATE_ERR`	This error is thrown if this method is called before the request has been opened using `XMLHttpRequest.open()`.
`NETWORK_ERR`	This error is thrown if there was a network error preventing the request from being delivered to the destination URL, or if the destination URL is a redirection that violates security or would result in an infinite loop.

Method: XMLHttpRequest.setRequestHeader()

Availability

BlackBerry® Device Software version 4.6 or later

The setRequestHeader() method specifies the value of a header to be sent with the request.

This method must be called only after the request has been opened using XMLHttpRequest.open().

Syntax

XMLHttpRequest.setRequestHeader( header, value )

Parameters

Parameter	Type	Description
`header`	String	The header to set. This parameter may not have as its value any of the following: `Accept-Charset`, `Accept-Encoding`, `Connection`, `Content-Length`, `Content-Transfer-Encoding`, `Date`, `Expect`, `Host`, `Keep-Alive`, `Referer`, `TE`, `Trailer`, `Transfer-Encoding`, `Upgrade`, `Via`, or any value starting with `Proxy-` or `Sec-`.
`value`	String	The value of the header.

Parameter

Type

Description

header

String

The header to set.

This parameter may not have as its value any of the following: Accept-Charset, Accept-Encoding, Connection, Content-Length, Content-Transfer-Encoding, Date, Expect, Host, Keep-Alive, Referer, TE, Trailer, Transfer-Encoding, Upgrade, Via, or any value starting with Proxy- or Sec-.

value

String

The value of the header.

Return values

None.

Exceptions

Exception

Description

ABORT_ERR

This error is thrown if the request was cancelled by the user.

INVALID_STATE_ERR

This error is thrown if this method is called before the request has been opened using XMLHttpRequest.open().

NETWORK_ERR

This error is thrown if

header is not recognized as a valid header name.
value is not recognized as a valid header value.

Global Navigation

Help Center

Local Navigation