NSURLSessionTask Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in iOS 7.0 and later.
Declared in
NSURLSession.h

Overview

The NSURLSessionTask 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 NSURLSession object. The method you call determines the type of task.

URL sessions provide three types of tasks: data tasks, upload tasks, and download tasks. These tasks are instances of the NSURLSessionDataTask, NSURLSessionUploadTask, and NSURLSessionDownloadTask subclasses of NSURLSessionTask, respectively.

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.

Tasks

Controlling the Task State

Obtaining Task Progress

Obtaining General Task Information

Properties

countOfBytesExpectedToReceive

The number of bytes that the task expects to receive in the response body. (read-only)

@property(readonly) int64_t countOfBytesExpectedToReceive
Discussion

This value is determined based on the Content-Length header received from the server. If that header is absent, the value is NSURLSessionTransferSizeUnknown.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSURLSession.h

countOfBytesExpectedToSend

The number of bytes that the task expects to send in the request body. (read-only)

@property(readonly) int64_t countOfBytesExpectedToSend
Discussion

The URL loading system can determine the length of the upload data in three ways:

  • From the length of the NSData object provided as the upload body.

  • From the length of the file on disk provided as the upload body of an upload task (not a download task).

  • From the Content-Length in the request object, if you explicitly set it.

Otherwise, the value is NSURLSessionTransferSizeUnknown (-1) if you provided a stream or body data object, or zero (0) if you did not.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSURLSession.h

countOfBytesReceived

The number of bytes that the task has received from the server in the response body. (read-only)

@property(readonly) int64_t countOfBytesReceived
Discussion

To be notified when this value changes, implement the URLSession:dataTask:didReceiveData: delegate method (for data and upload tasks) or the URLSession:downloadTask:didWriteData:totalBytesWritten:totalBytesExpectedToWrite: method (for download tasks).

Availability
  • Available in iOS 7.0 and later.
Declared In
NSURLSession.h

countOfBytesSent

The number of bytes that the task has sent to the server in the request body. (read-only)

@property(readonly) int64_t countOfBytesSent
Discussion

This byte count includes only the length of the request body itself, not the request headers.

To be notified when this value changes, implement the URLSession:task:didSendBodyData:totalBytesSent:totalBytesExpectedToSend: delegate method.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSURLSession.h

currentRequest

The URL request object currently being handled by the task. (read-only)

@property(readonly, copy) NSURLRequest *currentRequest
Discussion

This value is typically the same as the initial request (originalRequest) except when the server has responded to the initial request with a redirect to a different URL.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSURLSession.h

error

An error object that indicates why the task failed. (read-only)

@property(readonly, copy) NSError *error
Discussion

This value is NULL if the task is still active or if the transfer completed successfully.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSURLSession.h

originalRequest

The original request object passed when the task was created. (read-only)

@property(readonly, copy) NSURLRequest *originalRequest
Discussion

This value is typically the same as the currently active request (currentRequest) except when the server has responded to the initial request with a redirect to a different URL.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSURLSession.h

response

The server’s response to the currently active request. (read-only)

@property(readonly, copy) NSURLResponse *response
Discussion

This object provides information about the request as provided by the server. This information always includes the original URL. It may also include an expected length, MIME type information, encoding information, a suggested filename, or a combination of these.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSURLSession.h

state

The current state of the task—active, suspended, in the process of being canceled, or completed. (read-only)

@property(readonly) NSURLSessionTaskState state
Availability
  • Available in iOS 7.0 and later.
Declared In
NSURLSession.h

taskDescription

An app-provided description of the current task.

@property(copy) NSString *taskDescription
Discussion

This value may be nil. It is intended to contain human-readable strings that you can then display to the user as part of your app’s user interface.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSURLSession.h

taskIdentifier

An identifier uniquely identifies the task within a given session. (read-only)

@property(readonly) NSUInteger taskIdentifier
Discussion

This value is unique only within the context of a single session; tasks in other sessions may have the same taskIdentifier value.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSURLSession.h

Instance Methods

cancel

Cancels the task.

- (void)cancel
Availability
  • Available in iOS 7.0 and later.
Declared In
NSURLSession.h

resume

Resumes the task, if it is suspended.

- (void)resume
Availability
  • Available in iOS 7.0 and later.
Declared In
NSURLSession.h

suspend

Temporarily suspends a task.

- (void)suspend
Discussion

A task, while suspended, produces no network traffic and is not subject to timeouts. A download task can continue transferring data at a later time. All other tasks must start over when resumed.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSURLSession.h

Constants

NSURLSessionTaskState

Constants for determining the current state of a task.

typedef NS_ENUM(NSInteger,
   NSURLSessionTaskState) {
   NSURLSessionTaskStateRunning = 0,
   NSURLSessionTaskStateSuspended = 1,
   NSURLSessionTaskStateCanceling = 2,
   NSURLSessionTaskStateCompleted = 3,
};
Constants
NSURLSessionTaskStateRunning

The task is currently being serviced by the session. A task in this state is subject to the request and resource timeouts specified in the session configuration object.

Available in iOS 7.0 and later.

Declared in NSURLSession.h.

NSURLSessionTaskStateSuspended

The task was suspended by the app. No further processing takes place until it is resumed. A task in this state is not subject to timeouts.

Available in iOS 7.0 and later.

Declared in NSURLSession.h.

NSURLSessionTaskStateCanceling

The task has received a cancel message. The delegate may or may not have received a URLSession:task:didCompleteWithError: message yet. A task in this state is not subject to timeouts.

Available in iOS 7.0 and later.

Declared in NSURLSession.h.

NSURLSessionTaskStateCompleted

The task has completed (without being canceled), and the task's delegate receives no further callbacks. If the task completed successfully, the task’s error property is nil. Otherwise, it provides an error object that tells what went wrong. A task in this state is not subject to timeouts.

Available in iOS 7.0 and later.

Declared in NSURLSession.h.