Titanium.Network.HTTPClient

Object of Titanium.Network.

Platform	Since
Android	0.1
iPhone	0.1
iPad	0.1
Mobile Web	1.8

Summary

HTTP client object that (mostly) implements the XMLHttpRequest specification.

Description

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:

Creating an HTTPClient object.
Opening the HTTPClient object.
Sending the request.

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;

Mobile web requires cross-domain origin policies to be configured on the web servers in order for cross-domain connections to work.

Code Examples

Simple GET Request

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();

Methods

Name	Summary
abort	Cancels a pending request.
addEventListener	Adds the specified callback as an event listener for the named event.
clearCookies	Clears any cookies stored for this host. (Android, iPhone, iPad only.)
fireEvent	Fires a synthesized event to any registered listeners.
getAllResponseHeaders	Gets the value of the allResponseHeaders property. (Android only.)
getAutoEncodeUrl	Gets the value of the autoEncodeUrl property. (Android only.)
getAutoRedirect	Gets the value of the autoRedirect property. (Android, iPhone, iPad only.)
getCache	Gets the value of the cache property. (iPhone, iPad only.)
getConnected	Gets the value of the connected property.
getConnectionType	Gets the value of the connectionType property.
getEnableKeepAlive	Gets the value of the enableKeepAlive property. (iPhone, iPad only.)
getFile	Gets the value of the file property. (iPhone, iPad only.)
getLocation	Gets the value of the location property.
getOndatastream	Gets the value of the ondatastream property.
getOnerror	Gets the value of the onerror property.
getOnload	Gets the value of the onload property.
getOnreadystatechange	Gets the value of the onreadystatechange property.
getOnsendstream	Gets the value of the onsendstream property.
getReadyState	Gets the value of the readyState property.
getResponseData	Gets the value of the responseData property.
getResponseHeader	Returns the value of the specified response header.
getResponseText	Gets the value of the responseText property.
getResponseXML	Gets the value of the responseXML property.
getStatus	Gets the value of the status property.
getStatusText	Gets the value of the statusText property.
getTimeout	Gets the value of the timeout property.
getTlsVersion	Gets the value of the tlsVersion property. (iPhone, iPad only.)
getValidatesSecureCertificate	Gets the value of the validatesSecureCertificate property. (Android, iPhone, iPad only.)
open	Opens the request and readies the connection.
removeEventListener	Removes the specified callback as an event listener for the named event.
send	Sends the request.
setAutoEncodeUrl	Sets the value of the autoEncodeUrl property. (Android only.)
setAutoRedirect	Sets the value of the autoRedirect property. (Android, iPhone, iPad only.)
setCache	Sets the value of the cache property. (iPhone, iPad only.)
setEnableKeepAlive	Sets the value of the enableKeepAlive property. (iPhone, iPad only.)
setFile	Sets the value of the file property. (iPhone, iPad only.)
setOndatastream	Sets the value of the ondatastream property.
setOnerror	Sets the value of the onerror property.
setOnload	Sets the value of the onload property.
setOnreadystatechange	Sets the value of the onreadystatechange property.
setOnsendstream	Sets the value of the onsendstream property.
setRequestHeader	Sets the value for the specified request header. Must be called after `open` but before `send`.
setTimeout	Sets the request timeout.
setTlsVersion	Sets the value of the tlsVersion property. (iPhone, iPad only.)
setValidatesSecureCertificate	Sets the value of the validatesSecureCertificate property. (Android, iPhone, iPad only.)

Properties

Name	Type	Summary
DONE	Number	Ready state constant indicating that the request is complete. read-only
HEADERS_RECEIVED	Number	Ready state constant indicating that response headers have been received. read-only
LOADING	Number	Ready state constant indicating that response data is being received from the remote server. read-only
OPENED	Number	Ready state constant indicating that the connection has been opened, but the request has not yet been sent. read-only
UNSENT	Number	Ready state constant indicating that HTTPClient request has not been opened or sent. read-only
allResponseHeaders	String	All of the response headers as a single string, or an empty string if no headers are available. (Android only.) read-only
autoEncodeUrl	Boolean	Set to `false` to suppress URL-encoding of the specified URL. (Android only.)
autoRedirect	Boolean	Set to `false` to disable automatic handling of HTTP redirects. (Android, iPhone, iPad only.)
cache	Boolean	Controls whether or not HTTP responses are cached. (iPhone, iPad only.)
connected	Boolean	boolean to indicate that the response was successful read-only
connectionType	String	Connection type, normally either `GET` or `POST`. read-only
enableKeepAlive	Boolean	Determines whether the client should attempt to keep a persistent connection. (iPhone, iPad only.)
file	String	File to download contents to. Can only be set after calling open. (iPhone, iPad only.)
location	String	Absolute URL of the request. read-only
ondatastream	Callback<`Object`>	Function to be called at regular intervals as the request data is being received.
onerror	Callback<`Object`>	Function to be called upon a error response.
onload	Callback<`Object`>	Function to be called upon a successful response.
onreadystatechange	Callback<`Object`>	Function to be called for each readyState change.
onsendstream	Callback<`Object`>	Function to be called at regular intervals as the request data is being transmitted.
readyState	Number	The current ready state of this HTTP request. read-only
responseData	`Titanium.Blob`	Response data as a `Blob` object. read-only
responseText	String	Response as text or `null` if an error was received or no data was returned. read-only
responseXML	`Titanium.XML.Document`	Response object as an XML DOM Document object. read-only
status	Number	Response HTTP status code. read-only
statusText	String	Human-readable status message associated with the status code. read-only
timeout	Number	Timeout in milliseconds when the connection should be aborted
tlsVersion	Number	Sets the TLS version to use for handshakes. (iPhone, iPad only.)
validatesSecureCertificate	Boolean	Controls how SSL certification validation is performed on connection. (Android, iPhone, iPad only.)

Events

This type has no events.