iOS Developer Library

Developer

Foundation Framework Reference NSURLSessionTask Class Reference

Options
Deployment Target:

On This Page
Language:

NSURLSessionTask

Inherits From


Conforms To


Import Statement


Swift

import Foundation

Objective-C

@import Foundation;

Availability


Available in iOS 7.0 and later

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.

  • 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.

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.

  • Cancels the task.

    Declaration

    Swift

    func cancel()

    Objective-C

    - (void)cancel

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 7.0 and later

  • Resumes the task, if it is suspended.

    Declaration

    Swift

    func resume()

    Objective-C

    - (void)resume

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 7.0 and later

  • Temporarily suspends a task.

    Declaration

    Swift

    func suspend()

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 7.0 and later

  • state state Property

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

    Declaration

    Swift

    var state: NSURLSessionTaskState { get }

    Objective-C

    @property(readonly) NSURLSessionTaskState state

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 7.0 and later

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

    Declaration

    Swift

    var countOfBytesExpectedToReceive: Int64 { get }

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 7.0 and later

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

    Declaration

    Swift

    var countOfBytesReceived: Int64 { get }

    Objective-C

    @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).

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 7.0 and later

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

    Declaration

    Swift

    var countOfBytesExpectedToSend: Int64 { get }

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 7.0 and later

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

    Declaration

    Swift

    var countOfBytesSent: Int64 { get }

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 7.0 and later

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

    Declaration

    Swift

    @NSCopying var currentRequest: NSURLRequest { get }

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 7.0 and later

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

    Declaration

    Swift

    @NSCopying var originalRequest: NSURLRequest { get }

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 7.0 and later

  • response response Property

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

    Declaration

    Swift

    @NSCopying var response: NSURLResponse? { get }

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 7.0 and later

  • An app-provided description of the current task.

    Declaration

    Swift

    var taskDescription: String

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 7.0 and later

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

    Declaration

    Swift

    var taskIdentifier: Int { get }

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 7.0 and later

  • error error Property

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

    Declaration

    Swift

    @NSCopying var error: NSError? { get }

    Objective-C

    @property(readonly, copy) NSError *error

    Discussion

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 7.0 and later

  • Constants for determining the current state of a task.

    Declaration

    Swift

    enum NSURLSessionTaskState : Int { case Running case Suspended case Canceling case Completed }

    Objective-C

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

    Constants

    • Running

      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

    • Suspended

      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

    • Canceling

      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

    • Completed

      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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 7.0 and later