Titanium SDK # Modules.URLSession
Wrapper to support iOS's NSURLSession class for background downloads.
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
- Create a URL session and a background download task.
- Monitor events to check the progress of the download and session.
- Cancel downloads and invalidate sessions.
URL session events are monitored through the following iOS application-level events:
- Titanium.App.iOS.backgroundtransfer
- Titanium.App.iOS.downloadprogress
- Titanium.App.iOS.downloadcompleted
- Titanium.App.iOS.sessioncompleted
- Titanium.App.iOS.sessioneventscompleted
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
3.2.0The 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
3.2.0The 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
3.2.0Applies 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
3.2.0DEPRECATED 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
3.2.0DEPRECATED 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
3.2.0DEPRECATED 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