# Titanium.Network

The top level network module.

Availability

0.8

9.2.0

Extends

Titanium.Module

# Overview

The Network module is used to access networking related functionality.

For TCP sockets, see Titanium.Network.Socket.TCP.

The legacy Titanium.Network.TCPSocket object is still required by the Titanium.Network.BonjourBrowser and Titanium.Network.BonjourService objects.

For all other socket needs, use Titanium.Network.Socket.TCP.

# App Transport Security

Starting with iOS 9, Apple introduced new security and compatibility guidelines for networking and connectivity, which include:

All connections must support TLS 1.2 or greater, and use forward secrecy ciphers supported by iOS
Certificates must use at least a SHA-256 fingerprint with either a 2048-bit or greater RSA key, or a 256-bit or greater ECC key
Application must be compatible with IPv6 DNS64/NAT64 networks as part of App Store submissions

Because of the new requirements, Titanium disables the App Transport Security (ATS) requirements, which only includes the TLS and certificate cipher requirements, to allow all connections by default.

If you wish to re-enable ATS, add the NSAppTransportSecurity dict to the ios plist section of the tiapp.xml file, then add the NSAllowArbitraryLoads key and set it to false, indicating that you want to manage your whitelisted URL's yourself.

<ti:app>
  <!-- ... -->
  <ios>
    <plist>
      <dict>
        <key>NSAppTransportSecurity</key>
        <dict>
          <key>NSAllowsArbitraryLoads</key>
          <false/>
        </dict>
      </dict>
    </plist>
  </ios>
  <!-- ... -->
</ti:app>

Note that Titanium will inject code into the plist file to whitelist appcelerator.com subdomains, which is needed to communicate with the Appcelerator Anayltics server. To disable the whitelist, set the ios.whitelist.appcelerator.com tiapp application property to false.

<ti:app>
    <property name="ios.whitelist.appcelerator.com" type="bool">false</property>
</ti:app>

Listed below are other guidelines from Apple.

Avoid hard-coded IPv4 address literals

Try not to include hard-coded IPv4 address literals in your application, for example, 127.0.0.1.

Whitelist URLs

If ATS is enabled and the web service you are trying to contact does not support the new security guidelines, iOS will not allow you to connect to the service. An error will be returned in the network response stating the connection failed because it did not meet the ATS policy standards.

To allow the connection, you will need to add a NSAppTransportSecurity dict to the ios plist section of the tiapp.xml file. In the NSAppTransportSecurity dict, you add the NSExceptionDomains dict to whitelist specific domains.

For more information, see iOS Developer Library: App Transport Security (opens new window).

Example:

<ti:app>
  <!-- ... -->
  <ios>
    <plist>
      <dict>
        <key>NSAppTransportSecurity</key>
        <dict>
          <!-- 1) Default: Disable ATS completely -->
          <key>NSAllowsArbitraryLoads</key>
          <true/>

          <-- 2) Alternative: Define whitelisted domains -->
          <key>NSExceptionDomains</key>
          <dict>
            <!-- Loosen security measure for www.foo.com domain -->
            <key>www.foo.com</key>
            <dict>
              <!-- Set TLS v1.0 as the minimum TLS version -->
              <key>NSExceptionMinimumTLSVersion</key>
              <string>TLSv1.0</string>
              <!-- Can use other ciphers besides forward secrecy ciphers -->
              <key>NSExceptionRequiresForwardSecrecy</key>
              <false/>
              <!-- Allow HTTP connections -->
              <key>NSExceptionAllowsInsecureHTTPLoads</key>
              <true/>
            </dict>
          </dict>
        </dict>
      </dict>
    </plist>
  </ios>
  <!-- ... -->
</ti:app>

Test IPV6 DNS64/NAT64

If you submit your application to the iTunes Store, you should setup an IPv6 DNS64/NAT64 network to test your application to verify it is compatible with IPv6.

If you are running macOS 10.11 or greater, you can use your computer to setup a local IPv6 Wi-Fi network, which requires an Internet connection not through Wi-Fi.

To create the network, from System Preferences, enable Internet sharing with NAT64 network enabled to share your Wi-Fi connection.

For detailed instructions, see Mac Developer Library: Test for IPv6 DNS64/NAT64 Compatibility (opens new window).

# Properties

# allHTTPCookies READONLY

Availability

3.3.0

9.2.0

allHTTPCookies :Array<Titanium.Network.Cookie>

A list of all cookies in the cookie storage.

# networkType READONLY

Availability

0.8

9.2.0

networkType :Number

Network type value as a constant.

One of the NETWORK constants defined in Titanium.Network.

This API can be assigned the following constants:

# networkTypeName READONLY

Availability

0.8

9.2.0

networkTypeName :String

Network type as a String. Returns one of NONE, WIFI, LAN, MOBILE, or UNKNOWN.

# online READONLY

Availability

0.8

9.2.0

online :Boolean

Boolean value indicating if the device is connected to the network.

The online property is true if the device has network access via WiFi, LAN, or mobile/cellular network.

Note that if the device is connected to a private network without Internet access, then this property will be true as well. This means you cannot assume the device has Internet access if it's connected to the network.

# remoteDeviceUUID READONLY

Availability

0.8

9.2.0

remoteDeviceUUID :String

Remote device UUID if the device is registered with the Apple Push Notification Service, or null if it is not registered.

# remoteNotificationsEnabled READONLY

Availability

0.8

9.2.0

remoteNotificationsEnabled :Boolean

Indicates whether push notifications have been enabled using registerForPushNotifications.

# remoteNotificationTypes READONLY

Availability

0.8

9.2.0

remoteNotificationTypes :Array<Number>

Array of push notification type constants enabled for the application.

# Methods

# addHTTPCookie

Availability

3.2.0

3.3.0

9.2.0

addHTTPCookie(cookie) → void

Adds a cookie to the HTTP client cookie store.

On iOS, the cookie will override an existing cookie with the same name, domain and path, if any. The cookie's expiryDate property must be a date later than the creating date, otherwise the cookie will not persist in the cookie storage. On Android, any existing cookie with the same domain and name will be replaced with the new cookie. This is a bug in BasicCookieStore because based on RFC6265, an existing cookie can be evicted and replaced only when it has the same cookie-name, domain-value and path-value with the new cookie.

Parameters

Name	Type	Description
`cookie`	Titanium.Network.Cookie	The cookie to add

Returns

Type: void

# addSystemCookie

Availability

3.2.0

addSystemCookie(cookie) → void

Adds a cookie to the system cookie store.

On Android, Titanium.UI.WebView uses the system cookie store. Any existing cookie with the same domain, path and name will be replaced with the new cookie.

Parameters

Name	Type	Description
`cookie`	Titanium.Network.Cookie	The cookie to add

Returns

Type: void

# createBonjourBrowser

Availability

0.8

9.2.0

createBonjourBrowser(serviceType, domain[, parameters]) → Titanium.Network.BonjourBrowser

Creates and returns a BonjourBrowser object.

Parameters

Name	Type	Description
`serviceType`	String	Service to search for, must include the protocol type suffix (._tcp).
`domain`	String	Bonjour service domain to conduct the search in.
`parameters`	Dictionary<Titanium.Network.BonjourBrowser>	A dictionary object of properties defined in Titanium.Network.BonjourBrowser.

Returns

Type: Titanium.Network.BonjourBrowser

# createBonjourService

Availability

0.8

9.2.0

createBonjourService(name, type, domain[, parameters]) → Titanium.Network.BonjourService

Creates and returns a BonjourService object.

Parameters

Name	Type	Description
`name`	String	Name of the service. Must be a unique identifier for this service type and domain.
`type`	String	Type of service. Must include the protocol identifier (._tcp).
`domain`	String	Domain to publish the service in.
`parameters`	Dictionary<Titanium.Network.BonjourService>	Dictionary object of properties defined in Titanium.Network.BonjourService.

Returns

Type: Titanium.Network.BonjourService

# createCookie

Availability

3.2.0

3.3.0

9.2.0

createCookie([parameters]) → Titanium.Network.Cookie

Creates and returns an instance of Titanium.Network.Cookie.

Parameters

Name	Type	Description
`parameters`	Dictionary<Titanium.Network.Cookie>	Properties to set on a new object, including any defined by Titanium.Network.Cookie except those marked not-creation or read-only.

Returns

Type: Titanium.Network.Cookie

# createHTTPClient

Availability

0.8

9.2.0

createHTTPClient([parameters]) → Titanium.Network.HTTPClient

Creates and returns an instance of Titanium.Network.HTTPClient.

Parameters

Name	Type	Description
`parameters`	Dictionary<Titanium.Network.HTTPClient>	Properties to set on a new object, including any defined by Titanium.Network.HTTPClient except those marked not-creation or read-only.

Returns

Type: Titanium.Network.HTTPClient

# createTCPSocket DEPRECATED

Availability

0.8

createTCPSocket(hostName, port, mode, parameters) → Titanium.Network.TCPSocket

DEPRECATED SINCE 1.7.0

Use createTCP instead.

Legacy method to create and return an instance of Titanium.Network.TCPSocket.

Note that TCPSocket is still used with the Bonjour services. For other uses, see Titanium.Network.Socket.TCP.

Parameters

Name	Type	Description
`hostName`	String	Host name to connect to/listen on.
`port`	Number	Port for the socket.
`mode`	Number	Socket's mode; one of READ_MODE, WRITE_MODE, READ_WRITE_MODE.
`parameters`	Dictionary<Titanium.Network.TCPSocket>	Dictionary object with properties defined in Titanium.Network.TCPSocket.

Returns

Type: Titanium.Network.TCPSocket

# decodeURIComponent

Availability

0.8

9.2.0

decodeURIComponent(value) → String

Returns a decoded version of a URI encoded value.

Parameters

Name	Type	Description
`value`	String	URI encoded input value to be decoded.

Returns

Type: String

# encodeURIComponent

Availability

0.8

9.2.0

encodeURIComponent(value) → String

Returns a URI encoded version of the specified URI component.

On iOS, this also escapes the following characters, which are allowed in a URL but may not be allowed or desirable inside a path component:

!*'();:@+$,/?%#[]=&

Parameters

Name	Type	Description
`value`	String	Input value to be encoded.

Returns

Type: String

# getHTTPCookies

Availability

3.2.0

3.3.0

9.2.0

getHTTPCookies(domain, path, name) → Array<Titanium.Network.Cookie>

Gets all the cookies with the domain, path and name matched with the given values from the HTTP client cookie store.

The domain matching and path matching follow RFC6265. If name is null, return all the cookies with the domain and path matched.

Parameters

Name	Type	Description
`domain`	String	The domain of the cookie to get. It is case-insensitive.
`path`	String	The path of the cookie to get. It is case-sensitive.
`name`	String	The name of the cookie to get. It is case-sensitive.

Returns

Type: Array<Titanium.Network.Cookie>

# getHTTPCookiesForDomain

Availability

3.2.0

3.3.0

9.2.0

getHTTPCookiesForDomain(domain) → Array<Titanium.Network.Cookie>

Gets all the cookies with the domain matched with the given values from the HTTP client cookie store.

The domain matching follows RFC6265.

Parameters

Name	Type	Description
`domain`	String	The domain of the cookie to get. It is case-insensitive.

Returns

Type: Array<Titanium.Network.Cookie>

# getSystemCookies

Availability

3.2.0

getSystemCookies(domain, path, name) → Array<Titanium.Network.Cookie>

Gets all the cookies with the domain, path and name matched with the given values from the system cookie store.

On Android, Titanium.UI.WebView uses the system cookie store. The domain matching and path matching follow RFC6265. If name is null, return all the cookies with the domain and path matched. The returned cookies only have their name and value properties returned.

Parameters

Name	Type	Description
`domain`	String	The domain of the cookie to get. It is case-insensitive.
`path`	String	The path of the cookie to get. It is case-sensitive.
`name`	String	The name of the cookie to get. It is case-sensitive.

Returns

Type: Array<Titanium.Network.Cookie>

# registerForPushNotifications

Availability

0.8

9.2.0

registerForPushNotifications(config) → void

Registers for push notifications with the Apple Push Notification Service.

Call this method at application startup.

Before calling this method, the application needs to call the registerUserNotificationSettings method and pass it the notification types to use. Setting the notification types with this method will have no effect and throws a warning.

Parameters

Name	Type	Description
`config`	PushNotificationConfig	Dictionary specifying push-notification related options.

Returns

Type: void

# removeAllHTTPCookies

Availability

3.2.0

3.3.0

9.2.0

removeAllHTTPCookies() → void

Removes all the cookies from the HTTP client cookie store.

Returns

Type: void

# removeAllSystemCookies

Availability

3.2.0

removeAllSystemCookies() → void

Removes all the cookie from the system client cookie store.

On Android, Titanium.UI.WebView uses the system cookie store.

Returns

Type: void

# removeHTTPCookie

Availability

3.2.0

3.3.0

9.2.0

removeHTTPCookie(domain, path, name) → void

Removes the cookie with the domain, path and name exactly the same as the given values from the HTTP client cookie store.

Parameters

Name	Type	Description
`domain`	String	The domain of the cookie to remove. It is case-insensitive.
`path`	String	The path of the cookie to remove. It is case-sensitive.
`name`	String	The name of the cookie to remove. It is case-sensitive.

Returns

Type: void

# removeHTTPCookiesForDomain

Availability

3.2.0

3.3.0

9.2.0

removeHTTPCookiesForDomain(domain) → void

Removes the cookies with the domain matched with the given values from the HTTP client cookie store.

The domain matching follows RFC6265.

Parameters

Name	Type	Description
`domain`	String	The domain of the cookie to remove. It is case-insensitive.

Returns

Type: void

# removeSystemCookie

Availability

3.2.0

removeSystemCookie(domain, path, name) → void

Removes the cookie with the domain, path and name exactly the same as the given values from the system cookie store.

On Android, Titanium.UI.WebView uses the system cookie store.

Parameters

Name	Type	Description
`domain`	String	The domain of the cookie to remove. It is case-insensitive.
`path`	String	The path of the cookie to remove. It is case-sensitive.
`name`	String	The name of the cookie to remove. It is case-sensitive.

Returns

Type: void

# unregisterForPushNotifications

Availability

0.8

9.2.0

unregisterForPushNotifications() → void

Unregisters the application for push notifications.

Per Apple's documentation, it is rarely necessary to call this method. See: unregisterForRemoteNotifications in the UIApplication Class Reference

For example, calling this method would be required if a new version of your application no longer supports push notifications.

Returns

Type: void

# Events

# change

Availability

0.8

9.2.0

Fired when network connectivity changes.

Properties

Name	Type	Description
networkTypeName	String	New network type as a string.
online	Boolean	Boolean indicating if the device is connected to the network.
networkType	Number	New network type
reason	String	Human-readable text describing the reason for the change.
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# Constants

# INADDR_ANY DEPRECATED

Availability

0.8

INADDR_ANY :String

DEPRECATED SINCE 1.7.0

Special hostname value for listening sockets, representing all locally available network interfaces.

# NETWORK_LAN

Availability

0.8

9.2.0

NETWORK_LAN :Number

A networkType value indicating that the device is communicating over a local-area network.

This constant is also a possible value for the networkType property of the change event.

# NETWORK_MOBILE

Availability

0.8

9.2.0

NETWORK_MOBILE :Number

A networkType value indicating that the device is communicating over a mobile network.

This constant is also a possible value for the networkType property of the change event.

# NETWORK_NONE

Availability

0.8

9.2.0

NETWORK_NONE :Number

A networkType value indicating that no network is available.

This constant is also a possible value for the networkType property of the change event.

# NETWORK_UNKNOWN

Availability

0.8

9.2.0

NETWORK_UNKNOWN :Number

A networkType value indicating that the current network type is unknown.

This constant is also a possible value for the networkType property of the change event.

# NETWORK_WIFI

Availability

0.8

9.2.0

NETWORK_WIFI :Number

A networkType value indicating that the device is communicating over a WiFi network.

This constant is also a possible value for the networkType property of the change event.

# NOTIFICATION_TYPE_ALERT

Availability

0.8

9.2.0

NOTIFICATION_TYPE_ALERT :Number

Constant value for an Alert style push notification.

# NOTIFICATION_TYPE_BADGE

Availability

0.8

9.2.0

NOTIFICATION_TYPE_BADGE :Number

Constant value for a Badge style push notification.

# NOTIFICATION_TYPE_NEWSSTAND

Availability

0.8

9.2.0

NOTIFICATION_TYPE_NEWSSTAND :Number

Constant value for a Newsstand style push notification. Only available on iOS5 and later

# NOTIFICATION_TYPE_SOUND

Availability

0.8

9.2.0

NOTIFICATION_TYPE_SOUND :Number

Constant value for a Sound style push notification.

# PROGRESS_UNKNOWN

Availability

3.5.0

9.2.0

PROGRESS_UNKNOWN :Number

Constant value specifying that the progress of a download can not be calculated.

# READ_MODE DEPRECATED

Availability

0.8

READ_MODE :Number

DEPRECATED SINCE 1.7.0

Used with the deprecated Titanium.Network.TCPSocket only.

See Titanium.Network.Socket for constants used with Titanium.Network.Socket.TCP sockets.

Constant value specifying read-only mode for sockets.

# READ_WRITE_MODE DEPRECATED

Availability

0.8

READ_WRITE_MODE :Number

DEPRECATED SINCE 1.7.0

Used with the deprecated Titanium.Network.TCPSocket only.

See Titanium.Network.Socket for constants used with Titanium.Network.Socket.TCP sockets.

Constant value specifying read-write mode for sockets.

# SOCKET_LISTENING DEPRECATED

Availability

0.8

SOCKET_LISTENING :Number

DEPRECATED SINCE 1.7.0

Used with the deprecated Titanium.Network.TCPSocket only.

See Titanium.Network.Socket for constants used with Titanium.Network.Socket.TCP sockets.

Constant value representing a socket in the LISTENING state.

# TLS_VERSION_1_0

Availability

3.6.0

1.8.0.1

9.2.0

TLS_VERSION_1_0 :Number

Constant value specifying TLS version 1.0 for SSL.

# TLS_VERSION_1_1

Availability

3.6.0

1.8.0.1

9.2.0

TLS_VERSION_1_1 :Number

Constant value specifying TLS version 1.1 for SSL.

# TLS_VERSION_1_2

Availability

3.6.0

1.8.0.1

9.2.0

TLS_VERSION_1_2 :Number

Constant value specifying TLS version 1.2 for SSL.

# TLS_VERSION_1_3

Availability

8.3.0

9.2.0

TLS_VERSION_1_3 :Number

Constant value specifying TLS version 1.3 for SSL.

# WRITE_MODE DEPRECATED

Availability

0.8

WRITE_MODE :Number

DEPRECATED SINCE 1.7.0

Used with the deprecated Titanium.Network.TCPSocket only.

See Titanium.Network.Socket for constants used with Titanium.Network.Socket.TCP sockets.

Constant value specifying write-only mode for sockets.