Instance Method

uploadTask(with:from:completionHandler:)

Creates a task that performs an HTTP request for the specified URL request object, uploads the provided data, and calls a handler upon completion. The task bypasses calls to delegate methods for response and data delivery, and instead provides any resulting NSData, URLResponse, and NSError objects inside the completion handler. Delegate methods for handling authentication challenges, however, are still called.

Declaration

func uploadTask(with request: URLRequest, from bodyData: Data?, completionHandler: @escaping (Data?, URLResponse?, Error?) -> Void) -> URLSessionUploadTask

Parameters

request

An NSURLRequest object that provides the URL, cache policy, request type, and so on. The body stream and body data in this request object are ignored.

bodyData

The body data for the request.

completionHandler

The completion handler to call when the load request is complete. This handler is executed on the delegate queue.

If you pass nil, only the session delegate methods are called when the task completes, making this method equivalent to the uploadTask(with:from:) method.

This completion handler takes the following parameters:

data

The data returned by the server.

response

An object that provides response metadata, such as HTTP headers and status code. If you are making an HTTP or HTTPS request, the returned object is actually an HTTPURLResponse object.

error

An error object that indicates why the request failed, or nil if the request was successful.

Return Value

The new session upload task.

Discussion

An HTTP upload request is any request that contains a request body, such as a POST or PUT request. Upload tasks require you to provide a request object so that you can provide metadata for the upload, such as HTTP request headers.

Unlike uploadTask(with:from:), this method returns the response body after it has been received in full, and does not require you to write a custom delegate to obtain the response body.

After you create the task, you must start it by calling its resume() method.

You should usually pass a nil completion handler only when creating tasks in sessions whose delegates include a urlSession(_:dataTask:didReceive:) method. However, if you do not need the response data, use key-value observing to watch for changes to the task’s status to determine when it completes.

If the request completes successfully, the data parameter of the completion handler block contains the resource data, and the error parameter is nil. If the request fails, the data parameter is nil and the error parameter contain information about the failure. If a response from the server is received, regardless of whether the request completes successfully or fails, the response parameter contains that information.

See Also

Adding Upload Tasks to a Session

func uploadTask(with: URLRequest, from: Data)

Creates a task that performs an HTTP request for the specified URL request object and uploads the provided data.

func uploadTask(with: URLRequest, fromFile: URL)

Creates a task that performs an HTTP request for uploading the specified file.

func uploadTask(with: URLRequest, fromFile: URL, completionHandler: (Data?, URLResponse?, Error?) -> Void)

Creates a task that performs an HTTP request for uploading the specified file, then calls a handler upon completion. The task bypasses calls to delegate methods for response and data delivery, and instead provides any resulting NSData, URLResponse, and NSError objects inside the completion handler. Delegate methods for handling authentication challenges, however, are still called.

func uploadTask(withStreamedRequest: URLRequest)

Creates a task that performs an HTTP request for uploading data based on the specified URL request.

class URLSessionUploadTask

A URL session task that uploads data to the network in a request body.

protocol URLSessionDataDelegate

The NSURLSessionDataDelegate protocol defines the methods that a delegate of an URLSession object can implement to handle task-level events specific to data tasks and upload tasks. Your session delegate should also implement the methods in the URLSessionTaskDelegate protocol to handle task-level events that are common to all task types, and methods in the URLSessionDelegate protocol to handle session-level events.