Titanium Mobile

# Titanium.Network.HTTPClient

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

Availability
0.8
0.8
9.2.0
Extends
Titanium.Proxy

# Overview

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;

# Content-Type Header

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:

  • If you are sending a JavaScript object, the content type is set to multipart/form-data.
  • For all other data types on Android, the content type is set to application/x-www-form-urlencoded.
  • For all other data types on iOS, the content type is NOT set.

Use the Titanium.Network.HTTPClient.setRequestHeader method to override the default Content-Type header.

# Asynchronous vs. Synchronous HTTP Requests

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 Titanium.Network.HTTPClient.open method.

The Android platform does not support synchronous requests.

# TLS Support

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.

TLS versions by platform
Protocol Android iOS
TLS 1.0 1.0+ 1.0+
TLS 1.1 4.1+ 5.0+
TLS 1.2 4.1+ 5.0+
TLS 1.3 10.0+ 12.2+

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 attempted first.

On Android, use the Titanium.Network.HTTPClient.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.

On iOS, add the NSExceptionMinimumTLSVersion key in the <plist> section of tiapp.xml to set a minimum TLS version. See following example:

<key>NSAppTransportSecurity</key>
<dict>
  <key>NSExceptionDomains</key>
  <dict>
    <key>www.appcelerator.com</key>
    <dict>
      <key>NSExceptionMinimumTLSVersion</key>
      <string>TLSv1.3</string>
    </dict>
  </dict>
</dict>

Titanium will not fallback with a lower TLS version if the tlsVersion property in android or NSExceptionMinimumTLSVersion in iOS, 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.

# Caching Data

You can also use the HTTP client API to cache image, response data or related. A convenient way to do so is by setting the Titanium.Network.HTTPClient.file property to a path or target file, which will be populated with the response data in a successful case (e.g. in the onload callback). For more complex use cases, make sure to check To.ImageCache (opens new window) which also supports expire-handling and extended cache control.

# Android Platform Implementation Notes

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.

# Connect to local network in iOS

On iOS 14 and later, while connecting to local network a prompt will be shown to request user's permission. Add key NSLocalNetworkUsageDescription to the ios plist section of the tiapp.xml file to show the message on prompt. If this key is not added default message will be shown in prompt.

Example:

<ti:app>
  <!-- ... -->
  <ios>
    <plist>
      <dict>
        <!-- Reason to access local network-->
        <key>NSLocalNetworkUsageDescription</key>
        <string>
            Specify the reason for accessing the local network.
            This appears in the alert dialog when asking the user 
            for permission to access local network.
        </string>
      </dict>
    </plist>
  </ios>
  <!-- ... -->
</ti:app>

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

# Properties

# allResponseHeaders READONLY

Availability
0.8
allResponseHeaders :String

All of the response headers.

Contains a single string, or an empty string if no headers are available.

See also: getResponseHeader.

# autoEncodeUrl

Availability
0.8
autoEncodeUrl :Boolean

Determines whether automatic encoding is enabled for the specified URL.

Set to false to disable automatic URL-encoding.

Default: true

# autoRedirect

Availability
0.8
0.8
9.2.0
autoRedirect :Boolean

Determines whether automatic automatic handling of HTTP redirects is enabled.

Set to false to disable automatic HTTP redirects handling.

Default: true

# cache

Availability
2.0.0
9.2.0
cache :Boolean

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

# connected READONLY

Availability
0.8
0.8
9.2.0
connected :Boolean

Indicates whether the response was successful.

# connectionType READONLY

Availability
0.8
0.8
9.2.0
connectionType :String

Connection type, normally either GET, POST or PATCH.

# domain

Availability
3.0.0
3.0.0
9.2.0
domain :String

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

# enableKeepAlive

Availability
0.8
9.2.0
enableKeepAlive :Boolean

Determines whether the client should attempt to keep a persistent connection.

Set to true to maintain a persistent connection.

Default: false

# file

Availability
3.4.0
0.8
9.2.0
file :String | Titanium.Filesystem.File

Target local file or file path to receive data.

This property can be set anytime prior to calling send. The file must be writable such as the application data directory or temp directory.

# location READONLY

Availability
0.8
0.8
9.2.0
location :String

Absolute URL of the request.

If the request redirects, this property returns the URL of the redirected request.

# ondatastream

Availability
0.8
0.8
9.2.0
ondatastream :Callback<Object>

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. If the progress can not be calculated, the value will be PROGRESS_UNKNOWN.

# onerror

Availability
0.8
0.8
9.2.0
onerror :Callback<FailureResponse>

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.

# onload

Availability
0.8
0.8
9.2.0
onload :Callback<SuccessResponse>

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).

# onreadystatechange

Availability
0.8
0.8
9.2.0
onreadystatechange :Callback<Object>

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 is supported on the iOS and Android platforms.

# onsendstream

Availability
0.8
0.8
9.2.0
onsendstream :Callback<Object>

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.

# password

Availability
3.0.0
3.0.0
9.2.0
password :String

Sets the password parameter for authentication credentials.

Must be set before calling open.

Default: undefined

# readyState READONLY

Availability
0.8
0.8
9.2.0
readyState :Number

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:

# responseData READONLY

Availability
0.8
0.8
9.2.0
responseData :Titanium.Blob

Response data as a Blob object.

# responseHeaders READONLY

Availability
0.8
9.2.0
responseHeaders :Dictionary

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.

# responseText READONLY

Availability
0.8
0.8
9.2.0
responseText :String

Response as text.

Set to null if an error was received or no data was returned.

# responseXML READONLY

Availability
0.8
0.8
9.2.0
responseXML :Titanium.XML.Document

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.

# securityManager CREATION ONLY

Availability
3.3.0
3.3.0
9.2.0
securityManager :SecurityManagerProtocol

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.

# status READONLY

Availability
0.8
0.8
9.2.0
status :Number

Response HTTP status code.

# statusText READONLY

Availability
0.8
0.8
9.2.0
statusText :String

Human-readable status message associated with the status code.

# timeout

Availability
0.8
0.8
9.2.0
timeout :Number

Timeout in milliseconds when the connection should be aborted.

Default: On iOS, the default is 15000 (15 seconds).

# timeoutForResource

Availability
9.2.0
timeoutForResource :Number

The maximum amount of time (in milliseconds) that a resource request should be allowed to take.

The resource timeout controls how long (in milliseconds) to wait for an entire resource to transfer before giving up. The resource timer starts when the request is initiated and counts until either the request completes or this timeout is reached, whichever comes first. For more detail see timeoutintervalforresource from Apple documentation. This property also applies if <Ti.Network.HttpClient.waitsForConnectivity> is set to true.

Default: The default is `7*24*60*60*1000` milliseconds (7 days).

# tlsVersion

Availability
3.6.0
tlsVersion :Number

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 Android versions.

Setting this property disables falling back to lower TLS versions.

This API can be assigned the following constants:

Default: undefined, behaves as `Ti.Network.TLS_VERSION_1_2`.

# username

Availability
3.0.0
3.0.0
9.2.0
username :String

Sets the username parameter for authentication credentials.

Must be set before calling open.

Default: undefined

# validatesSecureCertificate

Availability
0.8
0.8
9.2.0
validatesSecureCertificate :Boolean

Determines how SSL certification validation is performed on connection.

On Android, this property is ignored if the securityManager property is used to create a custom SSL context and will handle the given URI.

Default: False when running in the simulator or on device in testing mode, and true if built for release in distribution mode.

# waitsForConnectivity

Availability
9.2.0
waitsForConnectivity :Boolean

A Boolean value that indicates whether the session should wait for connectivity to become available, or fail immediately.

Causes tasks to wait for network connectivity to become available, rather than immediately failing with an error when it is not. When waiting for connectivity, the <Ti.Network.HttpClient.timeout> property does not apply, but the <Ti.Network.HttpClient.timeoutForResource> property does.

Default: false

# Methods

# abort

Availability
0.8
0.8
9.2.0
abort() → void

Cancels a pending request.

Returns

Type
void

# clearCookies

Availability
0.8
0.8
9.2.0
clearCookies(host) → void

Clears any cookies stored for the host.

Parameters

Name Type Description
host String

The URL of the host/domain to clear cookies for.

Returns

Type
void

# getAllResponseHeaders

Availability
0.8
10.0.0
10.0.0
getAllResponseHeaders() → String

All of the response headers.

Contains a single string, or an empty string if no headers are available.

See also: getResponseHeader.

Intended to match the XMLHTTPRequest getAllResponseHeaders API.

Returns

Type
String

# getResponseHeader

Availability
0.8
0.8
9.2.0
getResponseHeader(name) → String

Returns the value of the specified response header.

Parameters

Name Type Description
name String

Name of the header to retrieve.

Returns

Type
String

# open

Availability
0.8
0.8
9.2.0
open(method, url[, async]) → void

Opens the request and prepares the connection.

Parameters

Name Type Description
method String

HTTP method for this request, such as 'GET' or 'POST'. 'PATCH' is available on Android from SDK 4.1.0.

url String

URL for the request.

async Boolean

Determines whether the request should be made asynchronously. Only used on iOS.

Returns

Type
void

# send

Availability
0.8
0.8
9.2.0
send([data]) → void

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.

Parameters

Name Type Description
data Object | String | Titanium.Filesystem.File | Titanium.Blob

Data to send with a POST request.

Returns

Type
void

# setRequestHeader

Availability
0.8
0.8
9.2.0
setRequestHeader(name, value) → void

Sets the value for the specified request header. Must be called after open but before send.

Parameters

Name Type Description
name String

Name of the header to set.

value String

Value to assign to the header. May be null to clear a default header value, such as X-Requested-With.

Returns

Type
void

# setTimeout DEPRECATED

Availability
0.8
0.8
9.2.0
setTimeout(timeout) → void

DEPRECATED SINCE 10.0.0

Use the timeout property instead.

Sets the request timeout.

Parameters

Name Type Description
timeout Number

Timeout in milliseconds.

Returns

Type
void

# Constants

# DONE

Availability
0.8
0.8
9.2.0
DONE :Number

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.

# HEADERS_RECEIVED

Availability
0.8
0.8
9.2.0
HEADERS_RECEIVED :Number

Ready state constant indicating that response headers have been received.

See also readyState.

# LOADING

Availability
0.8
0.8
9.2.0
LOADING :Number

Ready state constant indicating that response data is being received from the remote server.

See also readyState.

# OPENED

Availability
0.8
0.8
9.2.0
OPENED :Number

Ready state constant indicating that the connection has been opened, but the request has not yet been sent.

See also readyState.

# UNSENT

Availability
0.8
0.8
9.2.0
UNSENT :Number

Ready state constant indicating that HTTPClient request has not been opened or sent.

See also readyState.

Contents