使用NSURLSession <- URL会话编程指南

NSURLSession及其相关的类提供了通过HTTP下载内容的API。这个类提供了丰富的委托方法来支持验证、以及在后台执行下载的能力(当app没有运行,或者iOS app被挂起的时候)。

使用NSURLSession API,app创建一些列的会话,它们每一个都协调一组关联的数据传输任务。例如,如果你正在编写web浏览器,app可以为每个标签或窗口创建一个会话。在每个会话中,app添加一系列的任务,每个任务负责一个指定URL请求(如果原始URL返回HTTP重定向,那就是任何后续的URL)。

和大多数网络API一样,NSURLSession API是高度依赖异步操作的。如果你使用默认配置,系统提供的委托,你必须提供完成处理器代码块,以便在传输完成的时候或出现错误的时候,将数据返回给app。或者,如果你提供自定义的委托对象,则任务对象调用这些委托方法时使用从服务器接收到的数据(或传输完成时,从文件下载)。

注意:完成回调主要用于使用自定义委托的替代方法。如果你使用完成回调的方法创建一个任务,那么用于响应和数据传递的委托方法将不会被调用。

NSURLSession API提供状态和进度属性,并传递这个信息给委托。它支持取消、重启(恢复)、一起挂起任务,并且它提供在挂起、取消、或者下载错误处重新恢复任务的功能。

理解URL会话概念

会话中任务的行为基于三个因素:会话(由创建它的配置对象的类型决定)的类型、任务的类型、以及当任务创建的时候app是否在前台。

会话类型

NSURLSession API支持三种会话类型,由用于创建会话的配置对象的类型决定:

  • 默认会话行为与其他下载URL的Foundation方法很类似。它们使用永久的基于磁盘的缓存,并在用户的钥匙串中存储证书。
  • 短暂会话不会存储任何数据到磁盘:所有缓存、证书存储等等都保存在RAM中,并与会话捆绑。因此,当app使会话无效时,它们将会被自动清除。
  • 除了要使用独立进程处理所有数据传输以外,后台会话和默认会话很类似。后台会话有一些额外的限制,详情见Background Transfer Considerations。
任务类型

在会话中,NSURLSession类支持三种任务类型:数据任务(data tasks)、下载任务(download tasks)、以及上传任务(upload tasks)。

  • 数据任务使用NSData对象来发送和接收数据。数据任务被用于从app到服务器的短的、需要经常交互的请求。数据任务可以在每接到一部分数据的时候就把它返回给app,也可以通过完成处理器一次性返回所有的数据。
  • 下载任务以文件的形式获取数据,并且在app没有运行的时候支持后台下载。
  • 上传任务以文件的形式发送数据,并且在app没有运行的时候支持后台上传。
后台传输注意事项

NSURLSession类支持在app被挂起的时候在后台传输。后台传输只有在会话任务是使用后台会话配置对象(通过调用backgroundSessionConfiguration:返回的对象)创建的时候才会被支持。

由于实际传输是通过独立的进程执行的,并且重器app的进程非常昂贵,所以使用后台会话,一些功能将不可用,这导致了以下限制:

  • 会话必须为事件传递提供委托。(对于上传和下载,委托行为和进程内传输是一样的。)
  • 只支持HTTP和HTTPS协议(没有自定义协议)。
  • 始终遵循重定向。
  • 只支持文件的上传任务(在程序退出之后,上传数据对象、或者数据流都将失败)。
  • 如果后台传输是在app在后台的时候被启动的,那么配置对象的discretionary属性将被是作为true。

注意: 在iOS 8和OS X10.10之前,不支持在后台执行数据任务。

当app重启时,它的行为的方式在iOS和OS X之间有略微的不同。

在iOS中,当后台传输完成或需要证书时,如果app没有在运行,iOS会自动在后台重启app,并调用app的UIApplicationDelegate对象中的application:handleEventsForBackgroundURLSession:completionHandler:方法。这个调用提供导致app重启的会话的识别码。App应该存储完成处理器,使用相同的标识符创建后台配置对象,并使用这个配置对象创建会话。这个新的会话会自动与正在运行的后台活动相关联。之后,当会话完成最后一个后台下载任务的时候,它会给会话委托发送一个URLSessionDidFinishEventsForBackgroundURLSession:消息。在委托方法中,调用之前在主线程中存储的完成处理器,以便让操作系统知道可以再次安全的挂起app。

无论在iOS还时OS X中,当应用重启app的时候,app应该立即使用相同的标识符(这个标识符是app上次运行时未完成任务的任何会话的)创建后台配置对象,然后为每个配置对象创建一个会话。这些新的会话也会自动与正在进行的后台活动重新关联。

注意:你必须为每个标识符(在创建配置对象的时候指定)创建会话。共享同一个标识符的多个会话的行为尚未被定义。

如果app在挂起期间完成任务,委托的URLSession:downloadTask:didFinishDownloadingToURL:方法将被调用,这个方法会使用与最新下载的文件相关联的任务(task)和URL。

类似的,如果任务请求验证,NSURLSession对象调用委托相应的URLSession:task:didReceiveChallenge:completionHandler: 或 URLSession:didReceiveChallenge:completionHandler:方法。

如果网络发生错误,在后台会话中的上传和下载任务会通过URL加载系统自动重试。没有必要使用可达性API来确定合适重试失败的任务。

对于如何使用NSURLSession在后台进行传输数据的例子,参见Simple Background Transfer。

生命周期和委托交互

根据你正在使用NSURLSession类所做的事,可能对你充分理解会话生命周期会有帮助,包括会话如何与它的委托交互、委托调用的顺序、当收到服务器返回重定向的时候发生了什么、当app恢复一个失败下载的时候发生了什么等等。

关于URL会话生命周期的完整描述,请阅读Life Cycle of a URL Session。

NSCopying行为

会话和任务对象遵守NSCoping协议,如下所述:

  • 当app拷贝会话或任务对象时,你会得到相同的对象。
  • 当app拷贝配置对象时,你会得到一个新的副本,你可以对它进行独立的修改。

委托类接口的示例

下面任务部分中的代码片段,都基于代码清单1-1中的类接口。

代码清单1-1 委托类接口的示例

@import Foundation;

 

NS_ASSUME_NONNULL_BEGIN

typedef void (^CompletionHandler)();

 

@interface MySessionDelegate : NSObject 

 

@property NSMutableDictionary *completionHandlers;

 

@end

NS_ASSUME_NONNULL_END
import Foundation

 

typealias CompletionHandler = () -> Void

 

class MySessionDelegate : NSObject, URLSessionDelegate, URLSessionTaskDelegate, URLSessionDataDelegate, URLSessionDownloadDelegate, URLSessionStreamDelegate {

    var completionHandlers: [String: CompletionHandler] = [:]

}

创建和配置会话

NSURLSession API提供了广泛的配置选项:

  • 以特定于单一会话的方式为缓存、cookie、证书、以及协议提供存储支持
  • 与特定请求(任务)或一组请求(会话)绑定的验证
  • 通过URL上传和下载文件,推荐将数据(文件的内容)从元数据(URL和设置)中分离出来
  • 配置每个主机的最大连接数
  • 如果整个资源在相当长的时间里没有被下载,则会触发该资源的超时
  • 支持TLS的最小和最大版本
  • 自定义代理字典
  • 控制cookie策略
  • 控制HTTP渠道(pipelining)行为

因为大多数设置被包含在独立的配置对象中,所以你通常可以重用这些设置。当你实例化一个会话对象的时候,请指定如下内容:

  • 一个用于管理会话行为及其任务的配置对象
  • 可选的,委托对象用来处理接收到的传入数据,并处理特定于会话及其任务的其他事件(例如服务器验证、确定是否将资源下载请求转换到下载)。如果你不能够提供委托,NSURLSession对象会使用系统提供的委托。这样,你可以轻松得使用NSURLSession替换使用NSURLSession上的sendAsynchronousRequest:queue:completionHandler:方便方法的现有代码。

注意:如果app需要执行后台传输,它必须提供自定义委托。

当你实例化会话对象之后,除非创建一个新的会话,否则你不能改变该配置或者委托。

代码清单1-2 显示了如何创建一般的、短暂的、和后台会话的例子。

代码清单1-2 创建和配置会话

// Creating session configurations

NSURLSessionConfiguration *defaultConfiguration = [NSURLSessionConfiguration defaultSessionConfiguration];

NSURLSessionConfiguration *ephemeralConfiguration = [NSURLSessionConfiguration ephemeralSessionConfiguration];

NSURLSessionConfiguration *backgroundConfiguration = [NSURLSessionConfiguration backgroundSessionConfigurationWithIdentifier: @"com.myapp.networking.background"];

 

// Configuring caching behavior for the default session

NSString *cachesDirectory = NSSearchPathForDirectoriesInDomains(NSCachesDirectory, NSUserDomainMask, YES).firstObject;

NSString *cachePath = [cachesDirectory stringByAppendingPathComponent:@"MyCache"];

 

/* Note:

 iOS requires the cache path to be

 a path relative to the ~/Library/Caches directory,

 but OS X expects an absolute path.

 */

#if TARGET_OS_OSX

cachePath = [cachePath stringByStandardizingPath];

#endif

 

NSURLCache *cache = [[NSURLCache alloc] initWithMemoryCapacity:16384 diskCapacity:268435456 diskPath:cachePath];

defaultConfiguration.URLCache = cache;

defaultConfiguration.requestCachePolicy = NSURLRequestUseProtocolCachePolicy;

 

// Creating sessions

id  delegate = [[MySessionDelegate alloc] init];

NSOperationQueue *operationQueue = [NSOperationQueue mainQueue];

 

NSURLSession *defaultSession = [NSURLSession sessionWithConfiguration:defaultConfiguration delegate:delegate operationQueue:operationQueue];

NSURLSession *ephemeralSession = [NSURLSession sessionWithConfiguration:ephemeralConfiguration delegate:delegate delegateQueue:operationQueue];

NSURLSession *backgroundSession = [NSURLSession sessionWithConfiguration:backgroundConfiguration delegate:delegate delegateQueue:operationQueue];
// Creating session configurations

let defaultConfiguration = URLSessionConfiguration.default()

let ephemeralConfiguration = URLSessionConfiguration.ephemeral()

let backgroundConfiguration = URLSessionConfiguration.backgroundSessionConfiguration(withIdentifier: "com.myapp.networking.background")

 

// Configuring caching behavior for the default session

let cachesDirectoryURL = FileManager.default().urlsForDirectory(.cachesDirectory, inDomains: .userDomainMask).first!

let cacheURL = try! cachesDirectoryURL.appendingPathComponent("MyCache")

var diskPath = cacheURL.path

 

/* Note:

 iOS requires the cache path to be

 a path relative to the ~/Library/Caches directory,

 but OS X expects an absolute path.

 */

#if os(OSX)

diskPath = cacheURL.absoluteString

#endif

 

let cache = URLCache(memoryCapacity:16384, diskCapacity: 268435456, diskPath: diskPath)

defaultConfiguration.urlCache = cache

defaultConfiguration.requestCachePolicy = .useProtocolCachePolicy

// Creating sessions

let delegate = MySessionDelegate()

let operationQueue = OperationQueue.main()

 

let defaultSession = URLSession(configuration: defaultConfiguration, delegate: delegate, delegateQueue: operationQueue)

let ephemeralSession = URLSession(configuration: ephemeralConfiguration, delegate: delegate, delegateQueue: operationQueue)

let backgroundSession = URLSession(configuration: backgroundConfiguration, delegate: delegate, delegateQueue: operationQueue)

除了后台配置外,你可以复用会话配置对象来创建其他会话。(你不能重用后台会话配置,因为标识符不同。)

你还可以在任何时候安全的修改配置对象。当你创建会话的时候,会话对配置对象执行了深拷贝,所以修改只影响新会话。例如,如果你希望只在Wi-Fi连接时检索某个内容,你就可以为该内容创建第二个会话。如代码清单1-3所示。

代码清单1-3 使用相同的配置对象创建第二个会话

ephemeralConfiguration.allowsCellularAccess = NO;

NSURLSession *ephemeralSessionWiFiOnly = [NSURLSession sessionWithConfiguration:ephemeralConfiguration delegate:delegate delegateQueue:operationQueue];
ephemeralConfiguration.allowsCellularAccess = false

let ephemeralSessionWiFiOnly = URLSession(configuration: ephemeralConfiguration, delegate: delegate, operationQueue: operationQueue)

使用系统提供的委托获取资源

使用NSURLSession最直接的方式就是实用系统提供的委托请求资源。实用这个方法,你只需要在app中提供两段代码:

  • 创建配置对象以及使用该对象创建会话的代码
  • 完成处理器,在数据接收完成后执行某些操作

实用系统提供的委托,每个请求只需要一行代码你就可以获取特定的URL。代码清单1-4显示了这种简化模式的示例。

注意:系统提供的委托仅提供有限的网络行为的定制。如果app有超过基本URL获取的需求,例如自定义验证、或后台下载,这个技术就不太适用。有关必须实现的各种委托情况的列表,参见Life Cycle of a URL Session。

清单 1-4 适用系统提供的委托请求资源

NSURLSession *sessionWithoutADelegate = [NSURLSession sessionWithConfiguration:defaultConfiguration];

NSURL *url = [NSURL URLWithString:@"https://www.example.com/"];

 

[[sessionWithoutADelegate dataTaskWithURL:url completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {

    NSLog(@"Got response %@ with error %@.\n", response, error);

    NSLog(@"DATA:\n%@\nEND DATA\n", [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding];

}] resume];
let sessionWithoutADelegate = URLSession(configuration: defaultConfiguration)

if let url = URL(string: "https://www.example.com/") {

    (sessionWithoutADelegate.dataTask(with: url) { (data, response, error) in

        if let error = error {

            print("Error: \(error)")

        } else if let response = response,

            let data = data,

            let string = String(data: data, encoding: .utf8) {

            print("Response: \(response)")

            print("DATA:\n\(string)\nEND DATA\n")

        }

    }).resume()

}

使用自定义委托获取数据

如果你使用自定义委托来检索数据,该委托必须实现下面方法中的至少一种:

  • URLSession:dataTask:didReceiveData:将请求中的数据提供给任务,一次一段。
  • URLSession:task:didCompleteWithError:向你的任务表明数据已经接收完成。

如果app需要使用URLSession:dataTask:didReceiveData:方法返回的数据,你的代码负责通过某种方式存储该数据。

例如,web浏览器或许需要显示到达的数据,以及之前接收到的数据。为此,它或许使用字典,把数据映射到NSMutableData对象来储存结果,然后使用这些对象的appendData:方法来添加新接收到的数据。

代码清单1-5 显示了你如何创建和开始一个数据任务。

代码清单1-5 数据任务示例

NSURL *url = [NSURL URLWithString: @"https://www.example.com/"];

NSURLSessionDataTask *dataTask = [defaultSession dataTaskWithURL:url];

[dataTask resume];
if let url = URL(string: "https://www.example.com/") {

    let dataTask = defaultSession.dataTask(with: url)

    dataTask.resume()

}

下载文件

在高级别中,下载文件和接收数据很类似。App应该实现下列委托方法:

  • URLSession:downloadTask:didFinishDownloadingToURL:给下载内容的临时文件提供用于存储的app的URL。

重要:在该方法返回之前,必须打开文件以进行读取,或把它移动到永久位置。当该方法返回时,删除临时文件。

  • URLSession:downloadTask:didWriteData:totalBytesWritten:totalBytesExpectedToWrite:提供给应用关于下载进程的状态信息。
  • URLSession:downloadTask:didResumeAtOffset:expectedTotalBytes:告诉app它试图恢复之前失败的下载已成功。
  • URLSession:task:didCompleteWithError:告诉app下载失败。

如果你在后台会话中安排下载,那么当app不运行时该下载仍会继续进行。如果你把下载安排在标准或短暂会话中,该下载必须是在app重启的时候才会重新开始。

在服务器传输期间,如果用户暂停了下载,app可以通过调用cancelByProducingResumeData:方法来取消任务。之后,app可以把返回的数据传递给downloadTaskWithResumeData:或者downloadTaskWithResumeData:completionHandler:方法,来创建新的下载任务来继续下载。

如果传输失败,你委托的URLSession:task:didCompleteWithError:方法被调用。如果任务是可恢复的,那么对象的userInfo字典包含一个NSURLSessionDownloadTaskResumeData键的值;应用可以把返回的数据传递给downloadTaskWithResumeData: 或 downloadTaskWithResumeData:completionHandler:方法来创建一个新的下载任务,来重试该下载。

代码清单1-6提供一个下载一般大文件的示例。代码清单1-7提供下载任务委托方法的示例。

代码清单1-6 下载任务示例

NSURL *url = [NSURL URLWithString:@"https://developer.apple.com/library/ios/documentation/Cocoa/Reference/Foundation/ObjC_classic/FoundationObjC.pdf"];

NSURLSessionDownloadTask *downloadTask = [backgroundSession downloadTaskWithURL:url];

[downloadTask resume];
if let url = URL(string: "https://www.example.com/") {

    let dataTask = defaultSession.dataTask(with: url)

    dataTask.resume()

}

代码清单 1-7 下载任务的委托方法

- (void)URLSession:(NSURLSession *)session

      downloadTask:(NSURLSessionDownloadTask *)downloadTask

      didWriteData:(int64_t)bytesWritten

 totalBytesWritten:(int64_t)totalBytesWritten

totalBytesExpectedToWrite:(int64_t)totalBytesExpectedToWrite

{

    NSLog(@"Session %@ download task %@ wrote an additional %lld bytes (total %lld bytes) out of an expected %lld bytes.\n", session, downloadTask, bytesWritten, totalBytesWritten, totalBytesExpectedToWrite);

}

 

- (void)URLSession:(NSURLSession *)session

      downloadTask:(NSURLSessionDownloadTask *)downloadTask

 didResumeAtOffset:(int64_t)fileOffset

expectedTotalBytes:(int64_t)expectedTotalBytes

{

    NSLog(@"Session %@ download task %@ resumed at offset %lld bytes out of an expected %lld bytes.\n", session, downloadTask, fileOffset, expectedTotalBytes);

}

 

- (void)URLSession:(NSURLSession *)session

      downloadTask:(NSURLSessionDownloadTask *)downloadTask

didFinishDownloadingToURL:(NSURL *)location

{

    NSLog(@"Session %@ download task %@ finished downloading to URL %@\n", session, downloadTask, location);

 

    // Perform the completion handler for the current session

    self.completionHandlers[session.configuration.identifier]();

 

   // Open the downloaded file for reading

    NSError *readError = nil;

    NSFileHandle *fileHandle = [NSFileHandle fileHandleForReadingFromURL:location error:readError];

    // ...

 

   // Move the file to a new URL

    NSFileManager *fileManager = [NSFileManager defaultManager];

    NSURL *cacheDirectory = [[fileManager URLsForDirectory:NSCachesDirectory inDomains:NSUserDomainMask] firstObject];

    NSError *moveError = nil;

    if ([fileManager moveItemAtURL:location toURL:cacheDirectory error:moveError]) {

        // ...

    }

}
func urlSession(_ session: URLSession, downloadTask: URLSessionDownloadTask, didWriteData bytesWritten: Int64, totalBytesWritten: Int64, totalBytesExpectedToWrite: Int64) {

    print("Session \(session) download task \(downloadTask) wrote an additional \(bytesWritten) bytes (total \(totalBytesWritten) bytes) out of an expected \(totalBytesExpectedToWrite) bytes.\n")

}

 

func urlSession(_ session: URLSession, downloadTask: URLSessionDownloadTask, didResumeAtOffset fileOffset: Int64, expectedTotalBytes: Int64) {

    print("Session \(session) download task \(downloadTask) resumed at offset \(fileOffset) bytes out of an expected \(expectedTotalBytes) bytes.\n")

}

 

func urlSession(_ session: URLSession, downloadTask: URLSessionDownloadTask, didFinishDownloadingTo location: URL) {

    print("Session \(session) download task \(downloadTask) finished downloading to URL \(location)\n")

    

    // Perform the completion handler for the current session

    self.completionHandlers[session.configuration.identifier]()

    

    // Open the downloaded file for reading

    if let fileHandle = try? FileHandle(forReadingFrom: location) {

        // ...

    }

    

    // Move the file to a new URL

    let fileManager = FileManager.default()

    if let cacheDirectory = fileManager.urlsForDirectory(.cachesDirectory, inDomains: .userDomainMask).first {

        do {

            try fileManager.moveItem(at: location, to: cacheDirectory)

        } catch {

            // ...

        }

    }

}

上传Body内容

App可以使用三种方式为HTTP POST请求提供请求体(body)内容:NSData对象、文件、或者流。通常,app应该:

  • 如果app在内存中已经有数据且没有理由清除它时,使用NSData对象。
  • 如果你要上传的内容是磁盘中的文件,如果你打算在后台进行传输,或者写入磁盘之后可以清楚内存中相关的数据,请使用文件。
  • 如果你正通过网络接收数据,请使用数据流。

无论你选择哪个类型,如果app提供了自定义会话委托,该委托应该实现URLSession:task:didSendBodyData:totalBytesSent:totalBytesExpectedToSend:委托方法类获取上传进度的信息。

另外,如果app使用数据流来提供请求体,它必须提供实现URLSession:task:needNewBodyStream:方法的自定义会话委托。更多详情在Uploading Body Content Using a Stream中描述。

使用NSData对象上传Body内容

想要使用NSData对象上传body内容,app需要调用uploadTaskWithRequest:fromData: 或 uploadTaskWithRequest:fromData:completionHandler:方法来创建上传任务,并通过fromData参数提供请求体数据。

会话对象会基于数据对象的尺寸来计算Content-Length(内容长度)头。

App必须提供给服务器要求的额外头部信息(例如,内容类型),作为URL请求对象的一部分。

代码清单 1-8 从数据示例上传任务

NSURL *textFileURL = [NSURL fileURLWithPath:@"/path/to/file.txt"];

NSData *data = [NSData dataWithContentsOfURL:textFileURL];

 

NSURL *url = [NSURL URLWithString:@"https://www.example.com/"];

NSMutableURLRequest *mutableRequest = [NSMutableURLRequest requestWithURL:url];

mutableRequest.HTTPMethod = @"POST";

[mutableRequest setValue:[NSString stringWithFormat:@"%lld", data.length] forHTTPHeaderField:@"Content-Length"];

[mutableRequest setValue:@"text/plain" forHTTPHeaderField:@"Content-Type"];

 

NSURLSessionUploadTask *uploadTask = [defaultSession uploadTaskWithRequest:mutableRequest fromData:data];

[uploadTask resume];
let textFileURL = URL(fileURLWithPath: "/path/to/file.txt")

if let data = try? Data(contentsOf: textFileURL) {

    if let url = URL(string: "https://www.example.com/") {

        var mutableRequest = MutableURLRequest(url: url)

        mutableRequest.httpMethod = "POST"

        mutableRequest.setValue("\(data.count)", forHTTPHeaderField: "Content-Length")

        mutableRequest.setValue("text/plain", forHTTPHeaderField: "Content-Type")

        

        let uploadTask = defaultSession.uploadTask(with: mutableRequest, from: data)

        uploadTask.resume()

    }

}
使用文件上传Body内容

想要从文件上传body你容,app应该调用uploadTaskWithRequest:fromFile: 或 uploadTaskWithRequest:fromFile:completionHandler:方法来创建上传任务,并文件的URL。

会话对象给予数据对象的尺寸计算Content-Length(内容长度)头。如果app没有提供Content-Length头,会话也会提供一个。

App可以提供服务器要求的任何额外头部信息,作为请求对象的URL。

清单1-9 从数据流请求上传任务的示例

NSURL *textFileURL = [NSURL fileURLWithPath:@"/path/to/file.txt"];

 

NSURL *url = [NSURL URLWithString:@"https://www.example.com/"];

NSMutableURLRequest *mutableRequest = [NSMutableURLRequest requestWithURL:url];

mutableRequest.HTTPMethod = @"POST";

 

NSURLSessionUploadTask *uploadTask = [defaultSession uploadTaskWithRequest:mutableRequest fromFile:textFileURL];

[uploadTask resume];
let textFileURL = URL(fileURLWithPath: "/path/to/file.txt")

if let url = URL(string: "https://www.example.com/") {

    var mutableRequest = MutableURLRequest(url: url)

    mutableRequest.httpMethod = "POST"

    mutableRequest.httpBodyStream = InputStream(fileAtPath: textFileURL.path!)

    mutableRequest.setValue("\(data.count)", forHTTPHeaderField: "Content-Length")

    mutableRequest.setValue("text/plain", forHTTPHeaderField: "Content-Type")

    

    let uploadTask = defaultSession.uploadTask(with: mutableRequest, from: textFileURL)

    uploadTask.resume()

}
使用数据流上传Body内容

想要使用数据流上传body内容,app应该调用uploadTaskWithStreamedRequest:方法类创建上传任务。App提供与body内容数据流相关的请求对象。

App必须提供任何服务器要求的额外信息(例如,内容类型及长度),作为URL请求对象的一部分。

另外,因为会话不一定能够将提供的数据流返回去重新读取数据,所以,当会话必须要重试请求的时候(例如,如果验证失败),app有责任为此提供一个新的数据流。为此,app提供URLSession:task:needNewBodyStream:方法。当该方法被调用的时候,app应该执行所需的任何操作来获取或创建新的body数据流,然后使用该新数据流调用提供的完成处理程序代码块。

注意:因为app必须提供URLSession:task:needNewBodyStream:委托方法,如果它通过数据流提供body,则该技术与系统提供的委托不兼容。

代码清单1-10 从数据流上传任务示例

NSURL *textFileURL = [NSURL fileURLWithPath:@"/path/to/file.txt"];

 

NSURL *url = [NSURL URLWithString:@"https://www.example.com/"];

NSMutableURLRequest *mutableRequest = [NSMutableURLRequest requestWithURL:url];

mutableRequest.HTTPMethod = @"POST";

mutableRequest.HTTPBodyStream = [NSInputStream inputStreamWithFileAtPath:textFileURL.path];

[mutableRequest setValue:@"text/plain" forHTTPHeaderField:@"Content-Type"];

[mutableRequest setValue:[NSString stringWithFormat:@"%lld", data.length] forHTTPHeaderField:@"Content-Length"];

 

NSURLSessionUploadTask *uploadTask = [defaultSession uploadTaskWithStreamedRequest:mutableRequest];

[uploadTask resume];
let textFileURL = URL(fileURLWithPath: "/path/to/file.txt")

if let url = URL(string: "https://www.example.com/") {

    var mutableRequest = MutableURLRequest(url: url)

    mutableRequest.httpMethod = "POST"

    

    let uploadTask = defaultSession.uploadTask(with: mutableRequest, from: textFileURL)

    uploadTask.resume()

}
使用下载任务上传文件

想要将下载内容作为上传的body内容,app必须提供NSData对象或body数据流,作为创建下载请求是提供的NSURLRequest对象的一部分。

如果你使用数据流提供数据,app必须提供URLSession:task:needNewBodyStream:委托方法来来在验证失败的情况下提供一个新body数据流。这个方法的功能描述在Uploading Body Content Using a Stream中。

下载任务行为和数据任务很相近,除了给app返回数据的方式之外。

处理身份验证和自定义TLS链验证

如果远程服务器返回一个状态码,表明需要进行身份验证,并且如果该身份验证要求连接级别的挑战(例如SSL客户端证书),那么NSURLSession会调用验证挑战委托方法。

  • 对于会话级别挑战——NSURLAuthenticationMethodNTLM, NSURLAuthenticationMethodNegotiate, NSURLAuthenticationMethodClientCertificate, 或 NSURLAuthenticationMethodServerTrust——NSURLSession对象调用会话委托的URLSession:didReceiveChallenge:completionHandler:方法。如果app没有提供会话委托方法,则NSURLSession对象调用任务委托的URLSession:task:didReceiveChallenge:completionHandler:方法来处理挑战。
  • 对于非会话级别的挑战(其他所有),NSURLSession对象调用任务委托的URLSession:task:didReceiveChallenge:completionHandler:方法来处理挑战。如果app提供会话委托,并且你需要处理身份验证,你必须处理在任务级别上的验证,或者提供一个明确调用每个会话任务级别的处理程序。该会话委托的URLSession:didReceiveChallenge:completionHandler:方法在非会话级别挑战中不会被调用。

注意:Kerberos验证是显式处理的。

当基于流的上传body任务验证失败的时候,该任务不必返回以及安全的重用数据流。相反,NSURLSession对象调用委托的URLSession:task:needNewBodyStream: 方法来获取新的NSInputStream对象,它为新请求提供body数据。(如果任务的上传body是由文件或NSData对象提供给的,则会话对象不用进行该回调。)

更多关于为NSURLSession编写身份验证委托方法的信息,请阅读Authentication Challenges and TLS Chain Validation。

处理iOS后台活动

如果你在iOS中使用NSURLSession,app会在下载完成的时候自动重启。App的application:handleEventsForBackgroundURLSession:completionHandler:应用程序委托方法负责重建适当的会话、存储一个完成处理程序、以及当该会话调用会话的委托的URLSessionDidFinishEventsForBackgroundURLSession:方法时调用该完成处理程序。

代码清单1-11 提供一个在后台创建并开始下载任务的示例。代码清单1-12和1-13分别显示了这些会话和app委托方法的示例。

代码清单1-11 后台下载任务会话的iOS例子

NSURL *url = [NSURL URLWithString:@"https://www.example.com/"];

 

NSURLSessionDownloadTask *backgroundDownloadTask = [backgroundSession downloadTaskWithURL:url];

[backgroundDownloadTask resume];
if let url = URL(string: "https://www.example.com/") {

    let backgroundDownloadTask = backgroundSession.downloadTask(with: url)

    backgroundDownloadTask.resume()

}

代码清单1-12 iOS后台下载的会话委托方法

- (void)URLSessionDidFinishEventsForBackgroundURLSession:(NSURLSession *)session {

    AppDelegate *appDelegate = (AppDelegate *)[[[UIApplication sharedApplication] delegate];

    if (appDelegate.backgroundSessionCompletionHandler) {

        CompletionHandler completionHandler = appDelegate.backgroundSessionCompletionHandler;

        appDelegate.backgroundSessionCompletionHandler = nil;

        completionHandler();

    }

 

    NSLog(@"All tasks are finished");

}
func urlSession(_ session: URLSession, downloadTask: URLSessionDownloadTask, didFinishDownloadingTo location: URL) {

    guard let appDelegate = UIApplication.sharedApplication.delegate as? AppDelegate else {

        return

    }

    

    if let completionHandler = appDelegate.backgroundSessionCompletionHandler {

        appDelegate.backgroundSessionCompletionHandler = nil

        completionHandler()

    }

}

代码清单1-13 iOS后台下载的app委托方法

@interface AppDelegate : UIResponder 

@property (strong, nonatomic) UIWindow *window;

@property (copy) CompletionHandler backgroundSessionCompletionHandler;

 

@end

 

@implementation AppDelegate

 

- (void)application:(UIApplication *)application

handleEventsForBackgroundURLSession:(NSString *)identifier

  completionHandler:(void (^)())completionHandler

{

    self.backgroundSessionCompletionHandler = completionHandler;

}

 

@end

class AppDelegate : UIResponder, UIApplicationDelegate {

    var window: UIWindow?

    var backgroundSessionCompletionHandler: CompletionHandler?

    

    func application(_ application: UIApplication, handleEventsForBackgroundURLSession identifier: String, completionHandler: () -> Void) {

你可能感兴趣的:(使用NSURLSession <- URL会话编程指南)