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;
When sending a POST request with the HTTP client, the Content-Type header is set automatically depending on the platform and data type sent.
On the Android and iOS platforms:
multipart/form-data.application/x-www-form-urlencoded.Use the setRequestHeader method to override the default Content-Type header.
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 platform, 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.
Transport Layer Security (TLS) is a protocol that ensures privacy between communicating applications and their users on the Internet. When a server and client communicate, TLS ensures that no third party may eavesdrop or tamper with any message. TLS is the successor to the Secure Sockets Layer (SSL).
To communicate to servers with the TLS protocol, you need to use the same TLS version between the client and server.
| Protocol | Android | iOS |
|---|---|---|
| TLS 1.0 | 1.0+ | 1.0+ |
| TLS 1.1 | 4.1+ | 5.0+ |
| TLS 1.2 | 4.1+ | 5.0+ |
In Titanium, if a connection with TLS 1.2 fails, Titanium will re-attempt the connection with TLS 1.1 and TLS 1.0. By default, TLS 1.2 is only attempted first for devices running Android 4.1 and greater, or iOS 5.0 and greater. Prior to these versions, only TLS 1.0 is attempted since 1.0 is the only supported TLS version.
Use the tlsVersion property to set the version of the TLS protocol
if you know the version the server is running. If you do not know, do not set this property.
Titanium will not fallback with a lower TLS version if the tlsVersion property is set.
Setting the TLS version saves time from re-attempting connections with lower TLS versions and
provides added security by denying attempts to use lower TLS versions.
Starting with Release 3.6.0, you can set the TLS version for the Android and iOS platforms. Prior to Release 3.6.0, you can only set the TLS version for iOS.
On Android, the HTTPClient uses its own cookie store which does not share cookies with the
system cookie store used by Titanium.UI.WebView. Developers can manage their cookies for both
cookie stores using the methods Titanium.Network.addHTTPCookie, Titanium.Network.addSystemCookie,
Titanium.Network.getHTTPCookies, Titanium.Network.getHTTPCookiesForDomain, Titanium.Network.getSystemCookies,
Titanium.Network.removeHTTPCookie, Titanium.Network.removeHTTPCookiesForDomain, Titanium.Network.removeAllHTTPCookies,
Titanium.Network.removeSystemCookie, Titanium.Network.removeAllSystemCookies.
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.
The name of the API that this proxy corresponds to.
The name of the API that this proxy corresponds to.
The value of this property is the fully qualified name of the API. For example, Button
returns Ti.UI.Button.
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, POST or PATCH.
Connection type, normally either GET, POST or PATCH.
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
The Window or TabGroup whose Activity lifecycle should be triggered on the proxy.
The Window or TabGroup whose Activity lifecycle should be triggered on the proxy.
If this property is set to a Window or TabGroup, then the corresponding Activity lifecycle event callbacks will also be called on the proxy. Proxies that require the activity lifecycle will need this property set to the appropriate containing Window or TabGroup.
Absolute URL of the request.
Absolute URL of the request.
If the request redirects, this property returns the URL of the redirected request.
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. On iOS and Android as of 3.5.0, if the progress can not be calculated,
the value will be PROGRESS_UNKNOWN.
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.
Due to the asynchronous nature of the Titanium platform, the internal value of readyState might be different from the state change for which the event was fired. To address this discrepancy, the function is now invoked with a payload object of type ReadyStatePayload. This was introduced in version 3.4.2 of the SDK and is supported on the iOS and android platforms.
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.
This API can be assigned the following constants:
Returns all the response headers returned with the request.
Returns all the response headers returned with the request.
Contains a dictionary of response headers only after the http call has finished.
See also: getResponseHeader.
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.
The Security Manager for this client.
The Security Manager for this client.
This property must be specified during creation. Set this property on the HTTPClient to participate in the authentication and resource management of the connection. See SecurityManagerProtocol for further information.
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.
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 and Android versions.
Setting this property disables falling back to lower TLS versions.
This API can be assigned the following constants:
Default: undefined. Titanium.Network.TLS_VERSION_1_2 for Android 4.1 and later, or iOS 5 and later. Titanium.Network.TLS_VERSION_1_0 for Android 4.0 and earlier, or iOS 4 and earlier.
Sets the username parameter for authentication credentials.
Must be set before calling open.
Default: Undefined
Determines how SSL certification validation is performed on connection.
On Android, this property is ignored if the addKeyManager or addTrustManager methods
are used to create a custom SSL context.
Default: False when running in the simulator or on device in testing mode, and true if built for release in distribution mode.
Registers a new AuthSchemeFactory for a given scheme.
This method has been removed since 5.0.0
This has been deprecated. 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.
Adds a custom key manager.
This method has been removed since 3.4.0
Use this method to add support for X.509 certifcate-base keypairs.
If this method is used to create a custom SSLContext, the validatesSecureCertificate
property is ignored.
X.509 key manager. This key manager must implement the X509KeyManager inteface.
Adds a custom trust manager.
This method has been removed since 3.4.0
Use this method to add support for X.509 certifcates.
If this method is used to create a custom SSLContext, the validatesSecureCertificate
property is ignored.
X.509 trust manager. This trust manager must implement the X509TrustManager inteface.
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'. 'PATCH' is available on Android from SDK 4.1.0.
URL for the request.
Determines whether the request should be made asynchronously. Only used on iOS.
Removes 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).
To send array data, specify each array element individually as a property of the object. For example, normally, you specify an array in an object as:
var payload = { myArray: [1, 2, 3] };
Instead, for the HTTP client to encode the data correctly, you need to send the data as:
var payload = {
"myArray[0]" : 1,
"myArray[1]" : 2,
"myArray[2]" : 3
};
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.
Sets 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 lifecycleContainer 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 value of the securityManager property.
New value for the property.
Sets the value of the timeout property.
New value for the property.
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.