|
|
@@ -7,9 +7,11 @@ Common tasks related to the ``ImageDownloader`` in Kingfisher.
|
|
|
``ImageDownloader`` wraps a `URLSession` for downloading an image from the Internet. Similar to ``ImageCache``, there
|
|
|
is a ``ImageDownloader/default`` downloader for downloading tasks.
|
|
|
|
|
|
-### Downloading an image manually
|
|
|
+### Download an image manually
|
|
|
|
|
|
-Usually, you may use Kingfisher's view extension methods or `KingfisherManager` to retrieve an image. They will try to search in the cache first to prevent unnecessary download task. In some cases, if you only want to download a target image without caching it:
|
|
|
+Typically, you might use Kingfisher's view extension methods or ``KingfisherManager`` for image retrieval. These methods
|
|
|
+prioritize searching the cache to avoid unnecessary downloads. If you need to download an image without caching it,
|
|
|
+consider the following approach:
|
|
|
|
|
|
```swift
|
|
|
let downloader = ImageDownloader.default
|
|
|
@@ -23,9 +25,10 @@ downloader.downloadImage(with: url) { result in
|
|
|
}
|
|
|
```
|
|
|
|
|
|
-### Modify a Request Before Sending
|
|
|
+### Modify a request before sending
|
|
|
|
|
|
-When you have permission control for your image resource, you can modify the request by using a `.requestModifier`:
|
|
|
+When managing access to your image resources with permission controls, you can customize the request using a
|
|
|
+``KingfisherOptionsInfoItem/requestModifier(_:)``:
|
|
|
|
|
|
```swift
|
|
|
let modifier = AnyModifier { request in
|
|
|
@@ -42,9 +45,10 @@ downloader.downloadImage(with: url, options: [.requestModifier(modifier)]) {
|
|
|
imageView.kf.setImage(with: url, options: [.requestModifier(modifier)])
|
|
|
```
|
|
|
|
|
|
-### Async Request Modifier
|
|
|
+### Use async request modifier
|
|
|
|
|
|
-If you need to perform some asynchronous operation before modifying the request, create a type and conform to `AsyncImageDownloadRequestModifier`:
|
|
|
+If an asynchronous operation is required before modifying the request, create a type that conforms to
|
|
|
+``AsyncImageDownloadRequestModifier``:
|
|
|
|
|
|
```swift
|
|
|
class AsyncModifier: AsyncImageDownloadRequestModifier {
|
|
|
@@ -60,7 +64,11 @@ class AsyncModifier: AsyncImageDownloadRequestModifier {
|
|
|
}
|
|
|
```
|
|
|
|
|
|
-Similar as above, you can use the `.requestModifier` to use this modifier. In this case, the `setImage(with:options:)` or `ImageDownloader.downloadImage(with:options:)` method will not return a `DownloadTask` anymore (since it does not start the download task immediately). Instead, you observe one from the `onDownloadTaskStarted` callback if you need a reference to the task:
|
|
|
+Similarly, use the ``KingfisherOptionsInfoItem/requestModifier(_:)`` to apply this modifier. In such scenarios, the
|
|
|
+``KingfisherWrapper/setImage(with:placeholder:options:progressBlock:completionHandler:)-2uid3`` or
|
|
|
+``ImageDownloader/downloadImage(with:options:completionHandler:)-5x6sa`` method will no longer return a ``DownloadTask``
|
|
|
+directly, as the download task isn't initiated instantly. To reference the task, monitor the
|
|
|
+``AsyncImageDownloadRequestModifier/onDownloadTaskStarted`` callback.
|
|
|
|
|
|
```swift
|
|
|
let modifier = AsyncModifier()
|
|
|
@@ -72,9 +80,10 @@ modifier.onDownloadTaskStarted = { task in
|
|
|
let nilTask = imageView.kf.setImage(with: url, options: [.requestModifier(modifier)])
|
|
|
```
|
|
|
|
|
|
-### Cancelling a Download Task
|
|
|
+### Cancel a download task
|
|
|
|
|
|
-If the downloading started, a `DownloadTask` will be returned. You can use it to cancel an on-going download task:
|
|
|
+Once the download has started, a ``DownloadTask`` will be created and returned. This can be used to cancel an ongoing
|
|
|
+download task.
|
|
|
|
|
|
```swift
|
|
|
let task = downloader.downloadImage(with: url) { result in
|
|
|
@@ -85,20 +94,22 @@ let task = downloader.downloadImage(with: url) { result in
|
|
|
|
|
|
}
|
|
|
|
|
|
-// After for a while, before download task finishes.
|
|
|
+// After some time, but before the download task completes.
|
|
|
task?.cancel()
|
|
|
```
|
|
|
|
|
|
-If the task already finished when you call `task?.cancel()`, nothing will happen.
|
|
|
+If you call ``DownloadTask/cancel()`` after the task has already finished, no action will be taken.
|
|
|
|
|
|
-Similar, the view extension methods also return `DownloadTask`. You can store and cancel it:
|
|
|
+Likewise, the view extension methods return a ``DownloadTask`` as well. This allows you to store the task and cancel it
|
|
|
+if needed:
|
|
|
|
|
|
```swift
|
|
|
let task = imageView.kf.set(with: url)
|
|
|
task?.cancel()
|
|
|
```
|
|
|
|
|
|
-Or, you can call `cancelDownloadTask` on the image view to cancel the **current downloading task**:
|
|
|
+Alternatively, you can invoke ``KingfisherWrapper/cancelDownloadTask()`` on the image view to cancel the
|
|
|
+**current downloading task**.
|
|
|
|
|
|
```swift
|
|
|
let task1 = imageView.kf.set(with: url1)
|
|
|
@@ -111,7 +122,8 @@ imageView.kf.cancelDownloadTask()
|
|
|
|
|
|
### Authentication with `NSURLCredential`
|
|
|
|
|
|
-The `ImageDownloader` uses a default behavior (`.performDefaultHandling`) when receives a challenge from server. If you need to provide your own credentials, setup an `authenticationChallengeResponder`:
|
|
|
+The ``ImageDownloader`` defaults to `.performDefaultHandling` upon receiving a server challenge. To supply custom
|
|
|
+credentials, configure an ``ImageDownloader/authenticationChallengeResponder``:
|
|
|
|
|
|
```swift
|
|
|
// In ViewController
|
|
|
@@ -143,16 +155,16 @@ extension ViewController: AuthenticationChallengeResponsable {
|
|
|
}
|
|
|
```
|
|
|
|
|
|
-### Download Timeout
|
|
|
+### Set customize timeout
|
|
|
|
|
|
-By default, the download timeout for a request is 15 seconds. To set it for the downloader:
|
|
|
+The default download timeout for a request is 15 seconds. To customize this for the downloader:
|
|
|
|
|
|
```swift
|
|
|
-// Set timeout to 1 minute.
|
|
|
+// Set the timeout to 1 minute.
|
|
|
downloader.downloadTimeout = 60
|
|
|
```
|
|
|
|
|
|
-To define a timeout for a certain request, use a `.requestModifier`:
|
|
|
+For setting a timeout specific to a request, utilize a ``KingfisherOptionsInfoItem/requestModifier(_:):``:
|
|
|
|
|
|
```swift
|
|
|
let modifier = AnyModifier { request in
|