Creates a task that performs an HTTP request for the specified URL request object, uploads the provided data, and calls a handler upon completion.
SDKs
- iOS 7.0+
- macOS 10.9+
- tvOS 9.0+
- watchOS 2.0+
Framework
- Foundation
Declaration
func uploadTask(with request: URLRequest, from bodyData: Data?, completionHandler: @escaping (Data?, URLResponse?, Error?) -> Void) -> URLSession Upload Task
Parameters
request
A URL request 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 theupload
method.Task(with: from:) 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 create a request object so that you can provide metadata for the upload, like HTTP request headers.
Unlike upload
, 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.
By using a completion handler, the task bypasses calls to delegate methods for response and data delivery, and instead provides any resulting data, response, or error inside the completion handler. Delegate methods for handling authentication challenges, however, are still called.
Typically you pass a nil
completion handler only when creating tasks in sessions whose delegates include a url
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.
After you create the task, you must start it by calling its resume()
method.
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 contains 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.