HTTP client object that (mostly) implements the XMLHttpRequest specification.
Use Titanium.Network.createHTTPClient to create a new HTTPClient object.
An HTTPClient object is intended to be used for a single request. It may be
possible to re-use an HTTPClient object, but this use case is not tested.
There are three steps in making a typical HTTP request:
HTTPClient object.HTTPClient object.Before opening the request, you must define one or more callbacks to handle the HTTP response, as well as errors, progress updates, and other conditions.
The HTTPClient callbacks operate somewhat differently from other
Titanium callbacks, in accordance with the XMLHttpRequest specification.
When the callbacks are invoked, the this value is set to either the
original HTTPClient object itself, or a response object that holds all
of the response-related properties defined for the HTTPClient object. So the
callbacks can use code like this to access the response values:
httpResponse = this.responseText;
status = this.status;
By default, the HTTPClient makes asynchronous requests. Asynchronous requests do not block
the application and use callbacks to process responses when they are received.
Synchronous requests block the execution of the application until it receives a response.
On the iOS and Mobile Web platforms, you can make synchronous requests by setting the optional
async parameter to false when calling the open method.
The Android platform does not support synchronous requests.
Mobile Web is limited by the same-origin policy. According to W3C: "User agents commonly apply same-origin restrictions to network requests. These restrictions prevent a client-side Web application running from one origin from obtaining data retrieved from another origin, and also limit unsafe HTTP requests that can be automatically launched toward destinations that differ from the running application's origin." This means that browsers cannot request information from a domain that the app itself does not reside on. If you are hosting the app at foo.example.com, then requests to any domain other than *.example.com will fail.
There are two solutions to get around this problem:
If you use a proxy, be sure to properly configure how cookies are passed through. You may not want cookies proxied to third parties that could identify a user.
More information about Cross-Origin Resource Sharing can be found on the W3C Cross-Origin Resource Sharing specification page.
The following code excerpt does a simple GET request and logs the response text.
var url = "http://www.appcelerator.com";
var client = Ti.Network.createHTTPClient({
// function called when the response data is available
onload : function(e) {
Ti.API.info("Received text: " + this.responseText);
alert('success');
},
// function called when an error occurs, including a timeout
onerror : function(e) {
Ti.API.debug(e.error);
alert('error');
},
timeout : 5000 // in milliseconds
});
// Prepare the connection.
client.open("GET", url);
// Send the request.
client.send();
Ready state constant indicating that the request is complete.
Ready state constant indicating that the request is complete.
In this ready state, either the data has been transferred, or an error has occured.
See also readyState.
Ready state constant indicating that response headers have been received.
Ready state constant indicating that response headers have been received.
See also readyState.
Ready state constant indicating that response data is being received from the remote server.
Ready state constant indicating that response data is being received from the remote server.
See also readyState.
Ready state constant indicating that the connection has been opened, but the request has not yet been sent.
Ready state constant indicating that the connection has been opened, but the request has not yet been sent.
See also readyState.
Ready state constant indicating that HTTPClient request has not been opened or sent.
Ready state constant indicating that HTTPClient request has not been opened or sent.
See also readyState.
All of the response headers.
All of the response headers.
Contains a single string, or an empty string if no headers are available.
See also: getResponseHeader.
Determines whether automatic encoding is enabled for the specified URL.
Set to false to disable automatic URL-encoding.
Default: true
Determines whether automatic automatic handling of HTTP redirects is enabled.
Set to false to disable automatic HTTP redirects handling.
Default: true
Indicates if the proxy will bubble an event to its parent.
Some proxies (most commonly views) have a relationship to other proxies, often established by the add() method. For example, for a button added to a window, a click event on the button would bubble up to the window. Other common parents are table sections to their rows, table views to their sections, and scrollable views to their views. Set this property to false to disable the bubbling to the proxy's parent.
Default: true
Determines whether HTTP responses are cached.
If cache is set to true, requests using this HTTP client will cache their responses
(respecting headers such as "no-cache", "no-store", and cache expiry). In this case, repeated
requests to the same URL may retrieve the initial response rather than triggering a new
request. The cache is shared between all instances of HTTPClient.
Caching should only be enabled for HTTP requests which you expect the result to remain consistent for.
If cache is false, any request on this HTTP client will result in a new HTTP request.
This propery must be set before open is called.
Default: false
Indicates whether the response was successful.
Indicates whether the response was successful.
Connection type, normally either GET or POST.
Connection type, normally either GET or POST.
Sets the domain parameter for authentication credentials.
Set this parameter when authentication against NTLM domains along with the username and password properties. iOS supports NTLM authentication natively. Android can be extended using the addAuthFactory method. Must be set before calling open.
Default: Undefined
Determines whether the client should attempt to keep a persistent connection.
Set to true to maintain a persistent connection.
Default: false
Function to be called at regular intervals as the request data is being received.
Function to be called at regular intervals as the request data is being received.
Must be set before calling open.
The progress property of the event will contain a value from 0.0-1.0 with the progress of
the request.
Function to be called upon a error response.
Function to be called upon a error response.
Must be set before calling open.
The callback's argument is an object with a single property, error, containing the error
string.
Function to be called upon a successful response.
Function to be called upon a successful response.
Must be set before calling open.
To access response data and headers, access the HTTPClient object itself (accessible as
this during the callback, or the source property of the callback event).
Function to be called for each readyState change.
Function to be called for each readyState change.
Must be set before calling open.
When the callback is invoked, this.readyState is set to one of the
Titanium.Network.HTTPClient ready-state constants,
OPENED,
HEADERS_RECEIVED,
LOADING,
or DONE.
Function to be called at regular intervals as the request data is being transmitted.
Function to be called at regular intervals as the request data is being transmitted.
Must be set before calling open.
The progress property of the event will contain a value from 0.0-1.0 with the progress of
the upload.
Sets the password parameter for authentication credentials.
Must be set before calling open.
Default: Undefined
The current ready state of this HTTP request.
The current ready state of this HTTP request.
The ready state describes the current state of the request. The ready state is set to one of
the five Titanium.Network.HTTPClient ready state constants. A typical HTTP request goes
through the states in this order:
The onreadystatechange callback is invoked each time the ready state changes.
Response as text.
Response as text.
Set to null if an error was received or no data was returned.
Response object as an XML DOM Document object.
Response object as an XML DOM Document object.
Set to null if the content type returned by the server was not XML or if the content could not be parsed.
Human-readable status message associated with the status code.
Human-readable status message associated with the status code.
Timeout in milliseconds when the connection should be aborted.
Timeout in milliseconds when the connection should be aborted.
On Mobile Web and Tizen, the timeout only works when making asynchronous requests.
Sets the TLS version to use for handshakes.
If you experience handshake failures, set this value to a lower version using the TLS constants in Titanium.Network. 'undefined', 'null', or unsupported values use the default behavior for that iOS version.
Default: undefined. For iOS 4, this is effectively TLS_VERSION_1_0. For iOS 5 and greater, this is TLS_VERSION_1_2.
Sets the username parameter for authentication credentials.
Must be set before calling open.
Default: Undefined
Determines how SSL certification validation is performed on connection.
Default: False when running in the simulator or on device in testing mode, and true if built for release in distribution mode.
Determines whether the request should include any cookies and HTTP authentication information.
Set to true to include cookies and HTTP authentication information with the request.
This property must be set before open() is called. Setting this to true will force the request to be asynchronous.
Default: false
Registers a new AuthSchemeFactory for a given scheme.
Use this method to add support for authorization schemes not natively supported by Android.
The authentication scheme.
The authentication factory. This factory must implement the AuthSchemeFactory interface.
Adds the specified callback as an event listener for the named event.
Name of the event.
Callback function to invoke when the event is fired.
Applies the properties to the proxy.
Properties are supplied as a dictionary. Each key-value pair in the object is applied to the proxy such that myproxy[key] = value.
A dictionary of properties to apply.
Clears any cookies stored for the host.
The URL of the host/domain to clear cookies for.
Fires a synthesized event to any registered listeners.
Name of the event.
A dictionary of keys and values to add to the Titanium.Event object sent to the listeners.
Returns the value of the specified response header.
Name of the header to retrieve.
Opens the request and prepares the connection.
HTTP method for this request, such as 'GET' or 'POST'.
URL for the request.
Determines whether the request should be made asynchronously. Only used on iOS, Mobile Web and Tizen.
Default: TrueRemoves the specified callback as an event listener for the named event.
Multiple listeners can be registered for the same event, so the
callback parameter is used to determine which listener to remove.
When adding a listener, you must save a reference to the callback function in order to remove the listener later:
var listener = function() { Ti.API.info("Event listener called."); }
window.addEventListener('click', listener);
To remove the listener, pass in a reference to the callback function:
window.removeEventListener('click', listener);
Name of the event.
Callback function to remove. Must be the same function passed to addEventListener.
Sends the request.
For POST requests, use the data parameter to send POST data.
If you pass a serializable JavaScript object, it is automatically turned into form-encoded POST data. You can also send an arbitrary string or binary data (in the form of a Titanium.Blob).
On iOS, you can specify a synchronous request when you call open by passing false for
the async parameter. In the case of a synchronous request, send blocks until the request
is complete.
Data to send with a POST request.
Default: no dataSets the value of the autoEncodeUrl property.
New value for the property.
Sets the value of the autoRedirect property.
New value for the property.
Sets the value of the bubbleParent property.
New value for the property.
Sets the value of the cache property.
New value for the property.
Sets the value of the domain property.
New value for the property.
Sets the value of the enableKeepAlive property.
New value for the property.
Sets the value of the file property.
New value for the property.
Sets the value of the ondatastream property.
New value for the property.
Sets the value of the onerror property.
New value for the property.
Sets the value of the onload property.
New value for the property.
Sets the value of the onreadystatechange property.
New value for the property.
Sets the value of the onsendstream property.
New value for the property.
Sets the value of the password property.
New value for the property.
Sets the value for the specified request header. Must be called after open but before send.
Name of the header to set.
Value to assign to the header. May be null to clear a default header value, such as
X-Requested-With.
Sets the request timeout.
On Mobile Web and Tizen, the timeout only works when making asynchronous requests.
Timeout in milliseconds.
Sets the value of the tlsVersion property.
New value for the property.
Sets the value of the username property.
New value for the property.
Sets the value of the validatesSecureCertificate property.
New value for the property.
Sets the value of the withCredentials property.
New value for the property.