Add optional block to track download progress of image

2026-04-29 20:55:23 +08:00 · 2016-02-08 20:28:29 -08:00
parent 75b1e67226
commit da255a576c
5 changed files with 132 additions and 4 deletions
--- a/Pod/Classes/PINRemoteImageManager.h
+++ b/Pod/Classes/PINRemoteImageManager.h
@@ -114,6 +114,14 @@ typedef void(^PINRemoteImageManagerAuthenticationChallengeCompletionHandler)(NSU
 */
 typedef void(^PINRemoteImageManagerAuthenticationChallenge)(NSURLSessionTask * __nullable task, NSURLAuthenticationChallenge * __nonnull challenge, PINRemoteImageManagerAuthenticationChallengeCompletionHandler __nullable aHandler);

+/**
+ Handler called for many PINRemoteImage tasks providing the progress of the download.
+ 
+ @param completedBytes Amount of bytes that have been downloaded so far.
+ @param totalBytes Total amount of bytes in the image being downloaded.
+ */
+typedef void(^PINRemoteImageManagerDownloadProgress)(NSInteger completedBytes, NSInteger totalBytes);
+
@interface PINRemoteImageManager : NSObject

@property (nonatomic, readonly, nonnull) PINCache * cache;
@@ -302,6 +310,38 @@ typedef void(^PINRemoteImageManagerAuthenticationChallenge)(NSURLSessionTask * _
                                 progress:(nullable PINRemoteImageManagerImageCompletion)progress
                               completion:(nullable PINRemoteImageManagerImageCompletion)completion;

+/**
+ Download or retrieve from cache the image found at the url. All completions are called on an arbitrary callback queue unless called on the main thread and the result is in the memory cache (this is an optimization to allow synchronous results for the UI when an object is cached in memory).
+ 
+ @param url NSURL where the image to download resides.
+ @param options PINRemoteImageManagerDownloadOptions options with which to fetch the image.
+ @param downloadProgress PINRemoteImageManagerDownloadProgress block which will be called to update progress in bytes of the image download. NOTE: For performance reasons, this block is not called on the main thread every time, if you need to update your UI ensure that you dispatch to the main thread first.
+ @param completion PINRemoteImageManagerImageCompletion block to call when image has been fetched from the cache or downloaded.
+ 
+ @return An NSUUID which uniquely identifies this request. To be used for canceling requests and verifying that the callback is for the request you expect (see categories for example).
+ */
+- (nullable NSUUID *)downloadImageWithURL:(nonnull NSURL *)url
+                                  options:(PINRemoteImageManagerDownloadOptions)options
+                         downloadProgress:(nullable PINRemoteImageManagerDownloadProgress)downloadProgress
+                               completion:(nullable PINRemoteImageManagerImageCompletion)completion;
+
+/**
+ Download or retrieve from cache the image found at the url. All completions are called on an arbitrary callback queue unless called on the main thread and the result is in the memory cache (this is an optimization to allow synchronous results for the UI when an object is cached in memory).
+ 
+ @param url NSURL where the image to download resides.
+ @param options PINRemoteImageManagerDownloadOptions options with which to fetch the image.
+ @param progress PINRemoteImageManagerImageCompletion block which will be called to update progress of the image download.
+ @param downloadProgress PINRemoteImageManagerDownloadProgress block which will be called to update progress in bytes of the image download. NOTE: For performance reasons, this block is not called on the main thread every time, if you need to update your UI ensure that you dispatch to the main thread first.
+ @param completion PINRemoteImageManagerImageCompletion block to call when image has been fetched from the cache or downloaded.
+ 
+ @return An NSUUID which uniquely identifies this request. To be used for canceling requests and verifying that the callback is for the request you expect (see categories for example).
+ */
+- (nullable NSUUID *)downloadImageWithURL:(nonnull NSURL *)url
+                                  options:(PINRemoteImageManagerDownloadOptions)options
+                                 progress:(nullable PINRemoteImageManagerImageCompletion)progress
+                         downloadProgress:(nullable PINRemoteImageManagerDownloadProgress)downloadProgress
+                               completion:(nullable PINRemoteImageManagerImageCompletion)completion;
+
 /**
 Download or retrieve from cache the image found at the url and process it before calling completion. All completions are called on an arbitrary callback queue unless called on the main thread and the result is in the memory cache (this is an optimization to allow synchronous results for the UI when an object is cached in memory).
 
@@ -319,6 +359,25 @@ typedef void(^PINRemoteImageManagerAuthenticationChallenge)(NSURLSessionTask * _
                                processor:(nullable PINRemoteImageManagerImageProcessor)processor
                               completion:(nullable PINRemoteImageManagerImageCompletion)completion;

+/**
+ Download or retrieve from cache the image found at the url and process it before calling completion. All completions are called on an arbitrary callback queue unless called on the main thread and the result is in the memory cache (this is an optimization to allow synchronous results for the UI when an object is cached in memory).
+ 
+ @param url NSURL where the image to download resides.
+ @param options PINRemoteImageManagerDownloadOptions options with which to fetch the image.
+ @param processorKey NSString key to uniquely identify processor and process. Will be used for caching processed images.
+ @param downloadProgress PINRemoteImageManagerDownloadProgress block which will be called to update progress in bytes of the image download. NOTE: For performance reasons, this block is not called on the main thread every time, if you need to update your UI ensure that you dispatch to the main thread first.
+ @param processor PINRemoteImageManagerImageProcessor block which will be called to post-process downloaded image.
+ @param completion PINRemoteImageManagerImageCompletion block to call when image has been fetched from the cache or downloaded.
+ 
+ @return An NSUUID which uniquely identifies this request. To be used for canceling requests and verifying that the callback is for the request you expect (see categories for example).
+ */
+- (nullable NSUUID *)downloadImageWithURL:(nonnull NSURL *)url
+                                  options:(PINRemoteImageManagerDownloadOptions)options
+                             processorKey:(nullable NSString *)processorKey
+                                processor:(nullable PINRemoteImageManagerImageProcessor)processor
+                         downloadProgress:(nullable PINRemoteImageManagerDownloadProgress)downloadProgress
+                               completion:(nullable PINRemoteImageManagerImageCompletion)completion;
+
 /**
 Download or retrieve from cache one of the images found at the urls in the passed in array based on current network performance. URLs should be sorted from lowest quality image URL to highest. All completions are called on an arbitrary callback queue unless called on the main thread and the result is in the memory cache (this is an optimization to allow synchronous results for the UI when an object is cached in memory).