Instance Method インスタンスメソッド

downloadTaskWithRequest:completionHandler:

Creates a download task that retrieves the contents of a URL based on the specified URL request object, saves the results to a file, and calls a handler upon completion. あるダウンロードタスクを作成します、それは指定されたURLリクエストオブジェクトに基づいてあるURLの内容を取ってきます、その結果をファイルに保存します、そしてあるハンドラを完了に関して呼び出します。

Declaration 宣言 

- (NSURLSessionDownloadTask *)downloadTaskWithRequest:(NSURLRequest *)request 
                                    completionHandler:(void (^)(NSURL *location, NSURLResponse *response, NSError *error))completionHandler;

Parameters パラメータ

request

A URL request object that provides the URL, cache policy, request type, body data or body stream, and so on. URL、キャッシュ方針、リクエスト型、ボディデータまたはボディストリーム、などを提供するURLリクエストオブジェクト。

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 downloadTaskWithRequest: method. あなたがnilを渡すならば、セッション委任先メソッドそれらだけがそのタスクが完了する時に呼び出され、このメソッドをdownloadTaskWithRequest:メソッドと等しいものにします。

location

The location of a temporary file where the server’s response is stored. You must move this file or open it for reading before your completion handler returns. Otherwise, the file is deleted, and the data is lost. サーバのもつ応答が格納されるところの一時ファイルの場所。あなたは、このファイルを移動する、またはそれを読み出すために開くことを、あなたの完了ハンドラが戻る前にしなければなりません。そうでなければ、このファイルは消去されます、そしてデータは失われます。

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 NSHTTPURLResponse object. あるオブジェクト、それは応答メタデータを提供します、たとえばHTTPヘッダおよび状態コード。あなたがHTTPまたはHTTPSリクエストをしているならば、返されるオブジェクトは事実上NSHTTPURLResponseオブジェクトです。

error

An error object that indicates why the request failed, or nil if the request was successful. あるエラーオブジェクト、それはなぜリクエストが失敗したかを指し示します、またはnil、もしリクエストがうまくいったならば。

Return Value 戻り値

The new session download task. 新しいセッションダウンロードタスク。

Discussion 議論

By creating a task based on a request object, you can tune various aspects of the task’s behavior, including the cache policy and timeout interval. リクエストオブジェクトに基づいてタスクを作成することによって、あなたはタスクのもつ挙動のさまざまな面を調整できます、キャッシュ方針とタイムアウト間隔を含めて。

By using a completion handler, the task bypasses calls to delegate methods for response and data delivery, and instead provides any resulting NSURL, NSURLResponse, and NSError objects inside the completion handler. Delegate methods for handling authentication challenges, however, are still called. 完了ハンドラを使うことによって、タスクは応答とデータを配達するための委任先メソッドへの呼び出しを迂回します、そして代わりに何らかの結果NSURL、NSURLResponse、そしてNSErrorオブジェクトを完了ハンドラ内部で提供します。認証チャレンジを取り扱う委任先メソッドは、しかしながら、依然として呼び出されます。

You should pass a nil completion handler only when creating tasks in sessions whose delegates include a URLSession:downloadTask:didFinishDownloadingToURL: method. あなたがnil完了ハンドラを渡すべきなのは唯一、委任先がURLSession:downloadTask:didFinishDownloadingToURL:メソッドを含むセッションにおいて、それらタスクを作成している時です。

After you create the task, you must start it by calling its resume method. あなたがタスクを作成する後、あなたはそれを、それのresumeメソッドを呼び出すことによって開始しなければなりません。

If the request completes successfully, the location parameter of the completion handler block contains the location of the temporary file, and the error parameter is nil. If the request fails, the location 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. リクエストが成功裏に完了するならば、完了ハンドラブロックのlocationパラメータは一時ファイルの場所を含みます、そしてerrorパラメータはnilです。リクエストが失敗するならば、locationパラメータはnilです、そしてerrorパラメータはその失敗についての情報を含みます。サーバからの応答が受け取られるならば、リクエストがうまく完了するか失敗するかどうかに関係なく、responseパラメータはその情報を含みます。

See Also 参照

Adding Download Tasks to a Session ダウンロードタスクをセッションに加える

- downloadTaskWithURL:
Creates a download task that retrieves the contents of the specified URL and saves the results to a file. あるダウンロードタスクを作成します、それは指定されたURLの内容を取ってきます、そして結果をファイルに保存します。
- downloadTaskWithURL:completionHandler:
Creates a download task that retrieves the contents of the specified URL, saves the results to a file, and calls a handler upon completion. あるダウンロードタスクを作成します、それは指定されたURLの内容を取ってきます、その結果をファイルに保存します、そしてあるハンドラを完了に関して呼び出します。
- downloadTaskWithRequest:
Creates a download task that retrieves the contents of a URL based on the specified URL request object and saves the results to a file. あるダウンロードタスクを作成します、それは指定されたURLリクエストオブジェクトに基づいてあるURLの内容を取ってきます、そして結果をファイルに保存します。
- downloadTaskWithResumeData:
Creates a download task to resume a previously canceled or failed download. あるダウンロードタスクを作成して、以前に取り消されたまたは失敗したダウンロードを再開します。
- downloadTaskWithResumeData:completionHandler:
Creates a download task to resume a previously canceled or failed download and calls a handler upon completion. あるダウンロードタスクを作成して、以前に取り消されたまたは失敗したダウンロードを再開します、そしてあるハンドラを完了に関して呼び出します。
NSURLSessionDownloadTask
A URL session task that stores downloaded data to a file. あるURLセッションタスク、それはダウンロードデータをあるファイルに格納します。
NSURLSessionDownloadDelegate
A protocol that defines methods that URL session instances call on their delegates to handle task-level events specific to download tasks. あるプロトコル、それはいくつかのメソッドを定義します、それらはURLセッションインスタンスがそれらの委任先上で呼び出して、ダウンロードタスクに特有なタスク水準イベントを取り扱うものです。