# Modules.URLSession

Wrapper to support iOS's NSURLSession class for background downloads.

Availability
3.2.0

# Overview

These APIs are supported on iOS 7 and later.

The URL session module (com.appcelerator.urlSession) provides the application the ability to download large content via HTTP while the application is in the background. With this module, you can

  1. Create a URL session and a background download task.
  2. Monitor events to check the progress of the download and session.
  3. Cancel downloads and invalidate sessions.

URL session events are monitored through the following iOS application-level events:

These events are monitored as application-level events by using the addEventListener method with the Titanium.App.iOS namespace.

For more information on getting started, refer to the iOS Background Services guide (opens new window).

# Properties

# apiName READONLY

Availability
3.2.0
apiName :String

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, Titanium.UI.Button returns Ti.UI.Button.


# configuration CREATION ONLY

Availability
3.2.0

The configuration used for this url session.

Configuration options for an Modules.URLSession.Session object.
When a session is created, a copy of the configuration object is made. you cannot modify the configuration of a session after it has been created.

The shared session uses the global singleton credential, cache and cookie storage objects.

An ephemeral session has no persistent disk storage for cookies, cache or credentials.

A background session can be used to perform networking operations on behalf of a suspended application, within certain constraints.

# Methods

# applyProperties

Availability
3.2.0
applyProperties(props) void

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.

Parameters

Name Type Description
props Dictionary

A dictionary of properties to apply.

Returns

Type
void

# backgroundDownloadTaskWithURL DEPRECATED

Availability
3.2.0
backgroundDownloadTaskWithURL(session, url) String

DEPRECATED SINCE 6.1.0

Use downloadTask on the session directly.

Creates a download task for the specified URL, within the provided session object and saves the results to a file.

Once this function is called, the download starts automatically. The progress of the download can be monitored by listening to the downloadprogress, downloadcompleted, sessioneventscompleted and sessioncompleted events.

Parameters

Name Type Description
session Object

URL session object.

url String

URL to download content from.

Returns

Task's identifier number.

Type
String

# finishTasksAndInvalidate DEPRECATED

Availability
3.2.0
finishTasksAndInvalidate(session) void

DEPRECATED SINCE 6.1.0

Use finishTasksAndInvalidate (on the session object) instead.

Invalidates the given session object, allowing any outstanding tasks to finish.

This method returns immediately without waiting for tasks to finish. Once a session is invalidated, new tasks cannot be created in the session, but existing tasks continue until completion. Once invalidated, references to the events and callback objects are broken. Session objects cannot be reused. To cancel all outstanding tasks, call invalidateAndCancel instead.

Parameters

Name Type Description
session Object

URL session object.

Returns

Type
void

# invalidateAndCancel DEPRECATED

Availability
3.2.0
invalidateAndCancel(session) void

DEPRECATED SINCE 6.1.0

Use invalidateAndCancel (on the session object) instead.

Cancels all outstanding tasks and then invalidates the session object.

Once invalidated, references to the events and callback objects are broken. Session objects cannot be reused. To allow outstanding tasks to run until completion, call finishTasksAndInvalidate instead.

Parameters

Name Type Description
session Object

URL session object.

Returns

Type
void