iOS/Pods/Alamofire/Source/Alamofire.swift

   1 //
   2 //  Alamofire.swift
   3 //
   4 //  Copyright (c) 2014-2017 Alamofire Software Foundation (http://alamofire.org/)
   5 //
   6 //  Permission is hereby granted, free of charge, to any person obtaining a copy
   7 //  of this software and associated documentation files (the "Software"), to deal
   8 //  in the Software without restriction, including without limitation the rights
   9 //  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  10 //  copies of the Software, and to permit persons to whom the Software is
  11 //  furnished to do so, subject to the following conditions:
  12 //
  13 //  The above copyright notice and this permission notice shall be included in
  14 //  all copies or substantial portions of the Software.
  15 //
  16 //  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  17 //  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  18 //  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  19 //  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  20 //  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  21 //  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  22 //  THE SOFTWARE.
  23 //
  24
  25 import Foundation
  26
  27 /// Types adopting the `URLConvertible` protocol can be used to construct URLs, which are then used to construct
  28 /// URL requests.
  29 public protocol URLConvertible {
  30     /// Returns a URL that conforms to RFC 2396 or throws an `Error`.
  31     ///
  32     /// - throws: An `Error` if the type cannot be converted to a `URL`.
  33     ///
  34     /// - returns: A URL or throws an `Error`.
  35     func asURL() throws -> URL
  36 }
  37
  38 extension String: URLConvertible {
  39     /// Returns a URL if `self` represents a valid URL string that conforms to RFC 2396 or throws an `AFError`.
  40     ///
  41     /// - throws: An `AFError.invalidURL` if `self` is not a valid URL string.
  42     ///
  43     /// - returns: A URL or throws an `AFError`.
  44     public func asURL() throws -> URL {
  45         guard let url = URL(string: self) else { throw AFError.invalidURL(url: self) }
  46         return url
  47     }
  48 }
  49
  50 extension URL: URLConvertible {
  51     /// Returns self.
  52     public func asURL() throws -> URL { return self }
  53 }
  54
  55 extension URLComponents: URLConvertible {
  56     /// Returns a URL if `url` is not nil, otherwise throws an `Error`.
  57     ///
  58     /// - throws: An `AFError.invalidURL` if `url` is `nil`.
  59     ///
  60     /// - returns: A URL or throws an `AFError`.
  61     public func asURL() throws -> URL {
  62         guard let url = url else { throw AFError.invalidURL(url: self) }
  63         return url
  64     }
  65 }
  66
  67 // MARK: -
  68
  69 /// Types adopting the `URLRequestConvertible` protocol can be used to construct URL requests.
  70 public protocol URLRequestConvertible {
  71     /// Returns a URL request or throws if an `Error` was encountered.
  72     ///
  73     /// - throws: An `Error` if the underlying `URLRequest` is `nil`.
  74     ///
  75     /// - returns: A URL request.
  76     func asURLRequest() throws -> URLRequest
  77 }
  78
  79 extension URLRequestConvertible {
  80     /// The URL request.
  81     public var urlRequest: URLRequest? { return try? asURLRequest() }
  82 }
  83
  84 extension URLRequest: URLRequestConvertible {
  85     /// Returns a URL request or throws if an `Error` was encountered.
  86     public func asURLRequest() throws -> URLRequest { return self }
  87 }
  88
  89 // MARK: -
  90
  91 extension URLRequest {
  92     /// Creates an instance with the specified `method`, `urlString` and `headers`.
  93     ///
  94     /// - parameter url:     The URL.
  95     /// - parameter method:  The HTTP method.
  96     /// - parameter headers: The HTTP headers. `nil` by default.
  97     ///
  98     /// - returns: The new `URLRequest` instance.
  99     public init(url: URLConvertible, method: HTTPMethod, headers: HTTPHeaders? = nil) throws {
 100         let url = try url.asURL()
 101
 102         self.init(url: url)
 103
 104         httpMethod = method.rawValue
 105
 106         if let headers = headers {
 107             for (headerField, headerValue) in headers {
 108                 setValue(headerValue, forHTTPHeaderField: headerField)
 109             }
 110         }
 111     }
 112
 113     func adapt(using adapter: RequestAdapter?) throws -> URLRequest {
 114         guard let adapter = adapter else { return self }
 115         return try adapter.adapt(self)
 116     }
 117 }
 118
 119 // MARK: - Data Request
 120
 121 /// Creates a `DataRequest` using the default `SessionManager` to retrieve the contents of the specified `url`,
 122 /// `method`, `parameters`, `encoding` and `headers`.
 123 ///
 124 /// - parameter url:        The URL.
 125 /// - parameter method:     The HTTP method. `.get` by default.
 126 /// - parameter parameters: The parameters. `nil` by default.
 127 /// - parameter encoding:   The parameter encoding. `URLEncoding.default` by default.
 128 /// - parameter headers:    The HTTP headers. `nil` by default.
 129 ///
 130 /// - returns: The created `DataRequest`.
 131 @discardableResult
 132 public func request(
 133     _ url: URLConvertible,
 134     method: HTTPMethod = .get,
 135     parameters: Parameters? = nil,
 136     encoding: ParameterEncoding = URLEncoding.default,
 137     headers: HTTPHeaders? = nil)
 138     -> DataRequest
 139 {
 140     return SessionManager.default.request(
 141         url,
 142         method: method,
 143         parameters: parameters,
 144         encoding: encoding,
 145         headers: headers
 146     )
 147 }
 148
 149 /// Creates a `DataRequest` using the default `SessionManager` to retrieve the contents of a URL based on the
 150 /// specified `urlRequest`.
 151 ///
 152 /// - parameter urlRequest: The URL request
 153 ///
 154 /// - returns: The created `DataRequest`.
 155 @discardableResult
 156 public func request(_ urlRequest: URLRequestConvertible) -> DataRequest {
 157     return SessionManager.default.request(urlRequest)
 158 }
 159
 160 // MARK: - Download Request
 161
 162 // MARK: URL Request
 163
 164 /// Creates a `DownloadRequest` using the default `SessionManager` to retrieve the contents of the specified `url`,
 165 /// `method`, `parameters`, `encoding`, `headers` and save them to the `destination`.
 166 ///
 167 /// If `destination` is not specified, the contents will remain in the temporary location determined by the
 168 /// underlying URL session.
 169 ///
 170 /// - parameter url:         The URL.
 171 /// - parameter method:      The HTTP method. `.get` by default.
 172 /// - parameter parameters:  The parameters. `nil` by default.
 173 /// - parameter encoding:    The parameter encoding. `URLEncoding.default` by default.
 174 /// - parameter headers:     The HTTP headers. `nil` by default.
 175 /// - parameter destination: The closure used to determine the destination of the downloaded file. `nil` by default.
 176 ///
 177 /// - returns: The created `DownloadRequest`.
 178 @discardableResult
 179 public func download(
 180     _ url: URLConvertible,
 181     method: HTTPMethod = .get,
 182     parameters: Parameters? = nil,
 183     encoding: ParameterEncoding = URLEncoding.default,
 184     headers: HTTPHeaders? = nil,
 185     to destination: DownloadRequest.DownloadFileDestination? = nil)
 186     -> DownloadRequest
 187 {
 188     return SessionManager.default.download(
 189         url,
 190         method: method,
 191         parameters: parameters,
 192         encoding: encoding,
 193         headers: headers,
 194         to: destination
 195     )
 196 }
 197
 198 /// Creates a `DownloadRequest` using the default `SessionManager` to retrieve the contents of a URL based on the
 199 /// specified `urlRequest` and save them to the `destination`.
 200 ///
 201 /// If `destination` is not specified, the contents will remain in the temporary location determined by the
 202 /// underlying URL session.
 203 ///
 204 /// - parameter urlRequest:  The URL request.
 205 /// - parameter destination: The closure used to determine the destination of the downloaded file. `nil` by default.
 206 ///
 207 /// - returns: The created `DownloadRequest`.
 208 @discardableResult
 209 public func download(
 210     _ urlRequest: URLRequestConvertible,
 211     to destination: DownloadRequest.DownloadFileDestination? = nil)
 212     -> DownloadRequest
 213 {
 214     return SessionManager.default.download(urlRequest, to: destination)
 215 }
 216
 217 // MARK: Resume Data
 218
 219 /// Creates a `DownloadRequest` using the default `SessionManager` from the `resumeData` produced from a
 220 /// previous request cancellation to retrieve the contents of the original request and save them to the `destination`.
 221 ///
 222 /// If `destination` is not specified, the contents will remain in the temporary location determined by the
 223 /// underlying URL session.
 224 ///
 225 /// On the latest release of all the Apple platforms (iOS 10, macOS 10.12, tvOS 10, watchOS 3), `resumeData` is broken
 226 /// on background URL session configurations. There's an underlying bug in the `resumeData` generation logic where the
 227 /// data is written incorrectly and will always fail to resume the download. For more information about the bug and
 228 /// possible workarounds, please refer to the following Stack Overflow post:
 229 ///
 230 ///    - http://stackoverflow.com/a/39347461/1342462
 231 ///
 232 /// - parameter resumeData:  The resume data. This is an opaque data blob produced by `URLSessionDownloadTask`
 233 ///                          when a task is cancelled. See `URLSession -downloadTask(withResumeData:)` for additional
 234 ///                          information.
 235 /// - parameter destination: The closure used to determine the destination of the downloaded file. `nil` by default.
 236 ///
 237 /// - returns: The created `DownloadRequest`.
 238 @discardableResult
 239 public func download(
 240     resumingWith resumeData: Data,
 241     to destination: DownloadRequest.DownloadFileDestination? = nil)
 242     -> DownloadRequest
 243 {
 244     return SessionManager.default.download(resumingWith: resumeData, to: destination)
 245 }
 246
 247 // MARK: - Upload Request
 248
 249 // MARK: File
 250
 251 /// Creates an `UploadRequest` using the default `SessionManager` from the specified `url`, `method` and `headers`
 252 /// for uploading the `file`.
 253 ///
 254 /// - parameter file:    The file to upload.
 255 /// - parameter url:     The URL.
 256 /// - parameter method:  The HTTP method. `.post` by default.
 257 /// - parameter headers: The HTTP headers. `nil` by default.
 258 ///
 259 /// - returns: The created `UploadRequest`.
 260 @discardableResult
 261 public func upload(
 262     _ fileURL: URL,
 263     to url: URLConvertible,
 264     method: HTTPMethod = .post,
 265     headers: HTTPHeaders? = nil)
 266     -> UploadRequest
 267 {
 268     return SessionManager.default.upload(fileURL, to: url, method: method, headers: headers)
 269 }
 270
 271 /// Creates a `UploadRequest` using the default `SessionManager` from the specified `urlRequest` for
 272 /// uploading the `file`.
 273 ///
 274 /// - parameter file:       The file to upload.
 275 /// - parameter urlRequest: The URL request.
 276 ///
 277 /// - returns: The created `UploadRequest`.
 278 @discardableResult
 279 public func upload(_ fileURL: URL, with urlRequest: URLRequestConvertible) -> UploadRequest {
 280     return SessionManager.default.upload(fileURL, with: urlRequest)
 281 }
 282
 283 // MARK: Data
 284
 285 /// Creates an `UploadRequest` using the default `SessionManager` from the specified `url`, `method` and `headers`
 286 /// for uploading the `data`.
 287 ///
 288 /// - parameter data:    The data to upload.
 289 /// - parameter url:     The URL.
 290 /// - parameter method:  The HTTP method. `.post` by default.
 291 /// - parameter headers: The HTTP headers. `nil` by default.
 292 ///
 293 /// - returns: The created `UploadRequest`.
 294 @discardableResult
 295 public func upload(
 296     _ data: Data,
 297     to url: URLConvertible,
 298     method: HTTPMethod = .post,
 299     headers: HTTPHeaders? = nil)
 300     -> UploadRequest
 301 {
 302     return SessionManager.default.upload(data, to: url, method: method, headers: headers)
 303 }
 304
 305 /// Creates an `UploadRequest` using the default `SessionManager` from the specified `urlRequest` for
 306 /// uploading the `data`.
 307 ///
 308 /// - parameter data:       The data to upload.
 309 /// - parameter urlRequest: The URL request.
 310 ///
 311 /// - returns: The created `UploadRequest`.
 312 @discardableResult
 313 public func upload(_ data: Data, with urlRequest: URLRequestConvertible) -> UploadRequest {
 314     return SessionManager.default.upload(data, with: urlRequest)
 315 }
 316
 317 // MARK: InputStream
 318
 319 /// Creates an `UploadRequest` using the default `SessionManager` from the specified `url`, `method` and `headers`
 320 /// for uploading the `stream`.
 321 ///
 322 /// - parameter stream:  The stream to upload.
 323 /// - parameter url:     The URL.
 324 /// - parameter method:  The HTTP method. `.post` by default.
 325 /// - parameter headers: The HTTP headers. `nil` by default.
 326 ///
 327 /// - returns: The created `UploadRequest`.
 328 @discardableResult
 329 public func upload(
 330     _ stream: InputStream,
 331     to url: URLConvertible,
 332     method: HTTPMethod = .post,
 333     headers: HTTPHeaders? = nil)
 334     -> UploadRequest
 335 {
 336     return SessionManager.default.upload(stream, to: url, method: method, headers: headers)
 337 }
 338
 339 /// Creates an `UploadRequest` using the default `SessionManager` from the specified `urlRequest` for
 340 /// uploading the `stream`.
 341 ///
 342 /// - parameter urlRequest: The URL request.
 343 /// - parameter stream:     The stream to upload.
 344 ///
 345 /// - returns: The created `UploadRequest`.
 346 @discardableResult
 347 public func upload(_ stream: InputStream, with urlRequest: URLRequestConvertible) -> UploadRequest {
 348     return SessionManager.default.upload(stream, with: urlRequest)
 349 }
 350
 351 // MARK: MultipartFormData
 352
 353 /// Encodes `multipartFormData` using `encodingMemoryThreshold` with the default `SessionManager` and calls
 354 /// `encodingCompletion` with new `UploadRequest` using the `url`, `method` and `headers`.
 355 ///
 356 /// It is important to understand the memory implications of uploading `MultipartFormData`. If the cummulative
 357 /// payload is small, encoding the data in-memory and directly uploading to a server is the by far the most
 358 /// efficient approach. However, if the payload is too large, encoding the data in-memory could cause your app to
 359 /// be terminated. Larger payloads must first be written to disk using input and output streams to keep the memory
 360 /// footprint low, then the data can be uploaded as a stream from the resulting file. Streaming from disk MUST be
 361 /// used for larger payloads such as video content.
 362 ///
 363 /// The `encodingMemoryThreshold` parameter allows Alamofire to automatically determine whether to encode in-memory
 364 /// or stream from disk. If the content length of the `MultipartFormData` is below the `encodingMemoryThreshold`,
 365 /// encoding takes place in-memory. If the content length exceeds the threshold, the data is streamed to disk
 366 /// during the encoding process. Then the result is uploaded as data or as a stream depending on which encoding
 367 /// technique was used.
 368 ///
 369 /// - parameter multipartFormData:       The closure used to append body parts to the `MultipartFormData`.
 370 /// - parameter encodingMemoryThreshold: The encoding memory threshold in bytes.
 371 ///                                      `multipartFormDataEncodingMemoryThreshold` by default.
 372 /// - parameter url:                     The URL.
 373 /// - parameter method:                  The HTTP method. `.post` by default.
 374 /// - parameter headers:                 The HTTP headers. `nil` by default.
 375 /// - parameter encodingCompletion:      The closure called when the `MultipartFormData` encoding is complete.
 376 public func upload(
 377     multipartFormData: @escaping (MultipartFormData) -> Void,
 378     usingThreshold encodingMemoryThreshold: UInt64 = SessionManager.multipartFormDataEncodingMemoryThreshold,
 379     to url: URLConvertible,
 380     method: HTTPMethod = .post,
 381     headers: HTTPHeaders? = nil,
 382     encodingCompletion: ((SessionManager.MultipartFormDataEncodingResult) -> Void)?)
 383 {
 384     return SessionManager.default.upload(
 385         multipartFormData: multipartFormData,
 386         usingThreshold: encodingMemoryThreshold,
 387         to: url,
 388         method: method,
 389         headers: headers,
 390         encodingCompletion: encodingCompletion
 391     )
 392 }
 393
 394 /// Encodes `multipartFormData` using `encodingMemoryThreshold` and the default `SessionManager` and
 395 /// calls `encodingCompletion` with new `UploadRequest` using the `urlRequest`.
 396 ///
 397 /// It is important to understand the memory implications of uploading `MultipartFormData`. If the cummulative
 398 /// payload is small, encoding the data in-memory and directly uploading to a server is the by far the most
 399 /// efficient approach. However, if the payload is too large, encoding the data in-memory could cause your app to
 400 /// be terminated. Larger payloads must first be written to disk using input and output streams to keep the memory
 401 /// footprint low, then the data can be uploaded as a stream from the resulting file. Streaming from disk MUST be
 402 /// used for larger payloads such as video content.
 403 ///
 404 /// The `encodingMemoryThreshold` parameter allows Alamofire to automatically determine whether to encode in-memory
 405 /// or stream from disk. If the content length of the `MultipartFormData` is below the `encodingMemoryThreshold`,
 406 /// encoding takes place in-memory. If the content length exceeds the threshold, the data is streamed to disk
 407 /// during the encoding process. Then the result is uploaded as data or as a stream depending on which encoding
 408 /// technique was used.
 409 ///
 410 /// - parameter multipartFormData:       The closure used to append body parts to the `MultipartFormData`.
 411 /// - parameter encodingMemoryThreshold: The encoding memory threshold in bytes.
 412 ///                                      `multipartFormDataEncodingMemoryThreshold` by default.
 413 /// - parameter urlRequest:              The URL request.
 414 /// - parameter encodingCompletion:      The closure called when the `MultipartFormData` encoding is complete.
 415 public func upload(
 416     multipartFormData: @escaping (MultipartFormData) -> Void,
 417     usingThreshold encodingMemoryThreshold: UInt64 = SessionManager.multipartFormDataEncodingMemoryThreshold,
 418     with urlRequest: URLRequestConvertible,
 419     encodingCompletion: ((SessionManager.MultipartFormDataEncodingResult) -> Void)?)
 420 {
 421     return SessionManager.default.upload(
 422         multipartFormData: multipartFormData,
 423         usingThreshold: encodingMemoryThreshold,
 424         with: urlRequest,
 425         encodingCompletion: encodingCompletion
 426     )
 427 }
 428
 429 #if !os(watchOS)
 430
 431 // MARK: - Stream Request
 432
 433 // MARK: Hostname and Port
 434
 435 /// Creates a `StreamRequest` using the default `SessionManager` for bidirectional streaming with the `hostname`
 436 /// and `port`.
 437 ///
 438 /// If `startRequestsImmediately` is `true`, the request will have `resume()` called before being returned.
 439 ///
 440 /// - parameter hostName: The hostname of the server to connect to.
 441 /// - parameter port:     The port of the server to connect to.
 442 ///
 443 /// - returns: The created `StreamRequest`.
 444 @discardableResult
 445 @available(iOS 9.0, macOS 10.11, tvOS 9.0, *)
 446 public func stream(withHostName hostName: String, port: Int) -> StreamRequest {
 447     return SessionManager.default.stream(withHostName: hostName, port: port)
 448 }
 449
 450 // MARK: NetService
 451
 452 /// Creates a `StreamRequest` using the default `SessionManager` for bidirectional streaming with the `netService`.
 453 ///
 454 /// If `startRequestsImmediately` is `true`, the request will have `resume()` called before being returned.
 455 ///
 456 /// - parameter netService: The net service used to identify the endpoint.
 457 ///
 458 /// - returns: The created `StreamRequest`.
 459 @discardableResult
 460 @available(iOS 9.0, macOS 10.11, tvOS 9.0, *)
 461 public func stream(with netService: NetService) -> StreamRequest {
 462     return SessionManager.default.stream(with: netService)
 463 }
 464
 465 #endif