Class

URLSessionTask

The URLSessionTask class is the base class for tasks in a URL session. Tasks are always part of a session; you create a task by calling one of the task creation methods on an URLSession object. The method you call determines the type of task.

Overview

URL sessions provide three types of tasks: data tasks, upload tasks, and download tasks. These tasks are instances of the URLSessionDataTask, URLSessionUploadTask, URLSessionDownloadTask, URLSessionStreamTask subclasses of NSURLSessionTask, respectively.

  • Data tasks request a resource, returning the server’s response as one or more NSData objects in memory. They are supported in default, ephemeral, and shared sessions, but are not supported in background sessions.

  • Upload tasks are like data tasks, except that they make it easier to provide a request body so you can upload data before retrieving the server’s response. Additionally, upload tasks are supported in background sessions.

  • Download tasks download a resource directly to a file on disk. Download tasks are supported in any type of session.

  • Stream tasks establish a TCP/IP connection from a host name and port or a net service object.

After you create a task, you start it by calling its resume() method. The session then maintains a strong reference to the task until the request finishes or fails; you do not need to maintain a reference to the task unless it is useful to do so for your app’s internal bookkeeping purposes.

Nested Types

URLSessionTask.State

Constants for determining the current state of a task.

Symbols

Controlling the Task State

func cancel()

Cancels the task.

func resume()

Resumes the task, if it is suspended.

func suspend()

Temporarily suspends a task.

var state: URLSessionTask.State

The current state of the task—active, suspended, in the process of being canceled, or completed.

var priority: Float

The relative priority at which you’d like a host to handle the task, specified as a floating point value between 0.0 (lowest priority) and 1.0 (highest priority).

Obtaining Task Progress

var countOfBytesExpectedToReceive: Int64

The number of bytes that the task expects to receive in the response body.

var countOfBytesReceived: Int64

The number of bytes that the task has received from the server in the response body.

var countOfBytesExpectedToSend: Int64

The number of bytes that the task expects to send in the request body.

var countOfBytesSent: Int64

The number of bytes that the task has sent to the server in the request body.

Obtaining General Task Information

var currentRequest: URLRequest?

The URL request object currently being handled by the task.

var originalRequest: URLRequest?

The original request object passed when the task was created.

var response: URLResponse?

The server’s response to the currently active request.

var taskDescription: String?

An app-provided description of the current task.

var taskIdentifier: Int

An identifier uniquely identifies the task within a given session.

var error: Error?

An error object that indicates why the task failed.

Constants

URLSessionTask.State

Constants for determining the current state of a task.

URL Session Task Priority

Constants for providing task priority hints to a host, used with the priority property.

Relationships

Inherits From