Merge pull request #2189 from dreampiggy/refactor_context_option

Pass the context arg from the top level to the bottom level to allow specify logic in the future

SDWebImage/SDImageCache.h

@@ -204,6 +204,18 @@ typedef void(^SDWebImageCompletionWithPossibleErrorBlock)(NSError * _Nullable er
  */
 - (nullable NSOperation *)queryCacheOperationForKey:(nullable NSString *)key options:(SDImageCacheOptions)options done:(nullable SDCacheQueryCompletedBlock)doneBlock;
 
+/**
+ * Asynchronously queries the cache with operation and call the completion when done.
+ *
+ * @param key       The unique key used to store the wanted image
+ * @param options   A mask to specify options to use for this cache query
+ * @param doneBlock The completion block. Will not get called if the operation is cancelled
+ * @param context   A context contains different options to perform specify changes or processes, see `SDWebImageContextOption`. This hold the extra objects which `options` enum can not hold.
+ *
+ * @return a NSOperation instance containing the cache op
+ */
+- (nullable NSOperation *)queryCacheOperationForKey:(nullable NSString *)key options:(SDImageCacheOptions)options done:(nullable SDCacheQueryCompletedBlock)doneBlock context:(nullable SDWebImageContext *)context;
+
 /**
  * Synchronously query the memory cache.
  *

SDWebImage/SDImageCache.m

@@ -385,11 +385,15 @@ FOUNDATION_STATIC_INLINE NSUInteger SDCacheCostForImage(UIImage *image) {
     return SDScaledImageForKey(key, image);
 }
 
-- (NSOperation *)queryCacheOperationForKey:(NSString *)key done:(SDCacheQueryCompletedBlock)doneBlock {
+- (nullable NSOperation *)queryCacheOperationForKey:(NSString *)key done:(SDCacheQueryCompletedBlock)doneBlock {
     return [self queryCacheOperationForKey:key options:0 done:doneBlock];
 }
 
-- (nullable NSOperation *)queryCacheOperationForKey:(nullable NSString *)key options:(SDImageCacheOptions)options done:(nullable SDCacheQueryCompletedBlock)doneBlock {
+- (nullable NSOperation *)queryCacheOperationForKey:(NSString *)key options:(SDImageCacheOptions)options done:(SDCacheQueryCompletedBlock)doneBlock {
+    return [self queryCacheOperationForKey:key options:options done:doneBlock context:nil];
+}
+
+- (nullable NSOperation *)queryCacheOperationForKey:(nullable NSString *)key options:(SDImageCacheOptions)options done:(nullable SDCacheQueryCompletedBlock)doneBlock context:(nullable SDWebImageContext *)context {
     if (!key) {
         if (doneBlock) {
             doneBlock(nil, nil, SDImageCacheTypeNone);

SDWebImage/SDWebImageDownloader.h

@@ -227,6 +227,28 @@ typedef SDHTTPHeadersDictionary * _Nullable (^SDWebImageDownloaderHeadersFilterB
                                                   progress:(nullable SDWebImageDownloaderProgressBlock)progressBlock
                                                  completed:(nullable SDWebImageDownloaderCompletedBlock)completedBlock;
 
+/**
+ * Creates a SDWebImageDownloader async downloader instance with a given URL
+ *
+ * The delegate will be informed when the image is finish downloaded or an error has happen.
+ *
+ * @see SDWebImageDownloaderDelegate
+ *
+ * @param url            The URL to the image to download
+ * @param options        The options to be used for this download
+ * @param progressBlock  A block called repeatedly while the image is downloading
+ *                       @note the progress block is executed on a background queue
+ * @param completedBlock A block called once the download is completed.
+ * @param context        A context contains different options to perform specify changes or processes, see `SDWebImageContextOption`. This hold the extra objects which `options` enum can not hold.
+ *
+ * @return A token (SDWebImageDownloadToken) that can be passed to -cancel: to cancel this operation
+ */
+- (nullable SDWebImageDownloadToken *)downloadImageWithURL:(nullable NSURL *)url
+                                                   options:(SDWebImageDownloaderOptions)options
+                                                  progress:(nullable SDWebImageDownloaderProgressBlock)progressBlock
+                                                 completed:(nullable SDWebImageDownloaderCompletedBlock)completedBlock
+                                                   context:(nullable SDWebImageContext *)context;
+
 /**
  * Cancels a download that was previously queued using -downloadImageWithURL:options:progress:completed:
  *

SDWebImage/SDWebImageDownloader.m

@@ -174,10 +174,14 @@
     }
 }
 
+- (nullable SDWebImageDownloadToken *)downloadImageWithURL:(NSURL *)url options:(SDWebImageDownloaderOptions)options progress:(SDWebImageDownloaderProgressBlock)progressBlock completed:(SDWebImageDownloaderCompletedBlock)completedBlock {
+    return [self downloadImageWithURL:url options:options progress:progressBlock completed:completedBlock context:nil];
+}
+
 - (nullable SDWebImageDownloadToken *)downloadImageWithURL:(nullable NSURL *)url
                                                    options:(SDWebImageDownloaderOptions)options
                                                   progress:(nullable SDWebImageDownloaderProgressBlock)progressBlock
-                                                 completed:(nullable SDWebImageDownloaderCompletedBlock)completedBlock {
+                                                 completed:(nullable SDWebImageDownloaderCompletedBlock)completedBlock context:(nullable SDWebImageContext *)context {
     __weak SDWebImageDownloader *wself = self;
 
     return [self addProgressCallback:progressBlock completedBlock:completedBlock forURL:url createCallback:^SDWebImageDownloaderOperation *{
@@ -203,6 +207,7 @@
         }
         SDWebImageDownloaderOperation *operation = [[sself.operationClass alloc] initWithRequest:request inSession:sself.session options:options];
         operation.shouldDecompressImages = sself.shouldDecompressImages;
+        operation.context = context;
         
         if (sself.urlCredential) {
             operation.credential = sself.urlCredential;

SDWebImage/SDWebImageDownloaderOperation.h

@@ -36,6 +36,9 @@ FOUNDATION_EXPORT NSString * _Nonnull const SDWebImageDownloadFinishNotification
 - (nullable NSURLCredential *)credential;
 - (void)setCredential:(nullable NSURLCredential *)value;
 
+- (nullable SDWebImageContext *)context;
+- (void)setContext:(nullable SDWebImageContext *)context;
+
 - (BOOL)cancel:(nullable id)token;
 
 @end
@@ -67,19 +70,24 @@ FOUNDATION_EXPORT NSString * _Nonnull const SDWebImageDownloadFinishNotification
 @property (nonatomic, strong, nullable) NSURLCredential *credential;
 
 /**
- * The SDWebImageDownloaderOptions for the receiver.
+ * The options for the receiver.
  */
 @property (assign, nonatomic, readonly) SDWebImageDownloaderOptions options;
 
+/**
+ * The context for the receiver.
+ */
+@property (copy, nonatomic, nullable) SDWebImageContext *context;
+
 /**
  * The expected size of data.
  */
-@property (assign, nonatomic) NSInteger expectedSize;
+@property (assign, nonatomic, readonly) NSInteger expectedSize;
 
 /**
  * The response returned by the operation's connection.
  */
-@property (strong, nonatomic, nullable) NSURLResponse *response;
+@property (strong, nonatomic, nullable, readonly) NSURLResponse *response;
 
 /**
  *  Initializes a `SDWebImageDownloaderOperation` object

SDWebImage/SDWebImageDownloaderOperation.m

@@ -29,6 +29,8 @@ typedef NSMutableDictionary<NSString *, id> SDCallbacksDictionary;
 @property (assign, nonatomic, getter = isFinished) BOOL finished;
 @property (strong, nonatomic, nullable) NSMutableData *imageData;
 @property (copy, nonatomic, nullable) NSData *cachedData;
+@property (assign, nonatomic, readwrite) NSInteger expectedSize;
+@property (strong, nonatomic, nullable, readwrite) NSURLResponse *response;
 
 // This is weak because it is injected by whoever manages this session. If this gets nil-ed out, we won't be able to run
 // the task associated with this operation

SDWebImage/SDWebImageManager.h

@@ -241,6 +241,24 @@ SDWebImageManager *manager = [SDWebImageManager sharedManager];
                                              progress:(nullable SDWebImageDownloaderProgressBlock)progressBlock
                                             completed:(nonnull SDInternalCompletionBlock)completedBlock;
 
+/**
+ * Downloads the image at the given URL if not present in cache or return the cached version otherwise.
+ *
+ * @param url            The URL to the image
+ * @param options        A mask to specify options to use for this request
+ * @param progressBlock  A block called while image is downloading
+ *                       @note the progress block is executed on a background queue
+ * @param completedBlock A block called when operation has been completed.
+ * @param context        A context contains different options to perform specify changes or processes, see `SDWebImageContextOption`. This hold the extra objects which `options` enum can not hold.
+ *
+ * @return Returns an NSObject conforming to SDWebImageOperation. Should be an instance of SDWebImageDownloaderOperation
+ */
+- (nullable id <SDWebImageOperation>)loadImageWithURL:(nullable NSURL *)url
+                                              options:(SDWebImageOptions)options
+                                             progress:(nullable SDWebImageDownloaderProgressBlock)progressBlock
+                                            completed:(nonnull SDInternalCompletionBlock)completedBlock
+                                              context:(nullable SDWebImageContext *)context;
+
 /**
  * Saves image to cache for given URL
  *

SDWebImage/SDWebImageManager.m

@@ -107,10 +107,15 @@
     }];
 }
 
-- (id <SDWebImageOperation>)loadImageWithURL:(nullable NSURL *)url
+- (id<SDWebImageOperation>)loadImageWithURL:(NSURL *)url options:(SDWebImageOptions)options progress:(SDWebImageDownloaderProgressBlock)progressBlock completed:(SDInternalCompletionBlock)completedBlock {
-                                     options:(SDWebImageOptions)options
+    return [self loadImageWithURL:url options:options progress:progressBlock completed:completedBlock context:nil];
-                                    progress:(nullable SDWebImageDownloaderProgressBlock)progressBlock
+}
-                                   completed:(nonnull SDInternalCompletionBlock)completedBlock {
+
+- (id<SDWebImageOperation>)loadImageWithURL:(nullable NSURL *)url
+                                    options:(SDWebImageOptions)options
+                                   progress:(nullable SDWebImageDownloaderProgressBlock)progressBlock
+                                  completed:(nonnull SDInternalCompletionBlock)completedBlock
+                                    context:(nullable SDWebImageContext *)context {
     // Invoking this method without a completedBlock is pointless
     NSAssert(completedBlock != nil, @"If you mean to prefetch the image, use -[SDWebImagePrefetcher prefetchURLs] instead");
 
@@ -250,7 +255,7 @@
                 if (finished) {
                     [self safelyRemoveOperationFromRunning:strongSubOperation];
                 }
-            }];
+            } context:context];
         } else if (cachedImage) {
             [self callCompletionBlockForOperation:strongOperation completion:completedBlock image:cachedImage data:cachedData error:nil cacheType:cacheType finished:YES url:url];
             [self safelyRemoveOperationFromRunning:strongOperation];
@@ -259,7 +264,7 @@
             [self callCompletionBlockForOperation:strongOperation completion:completedBlock image:nil data:nil error:nil cacheType:SDImageCacheTypeNone finished:YES url:url];
             [self safelyRemoveOperationFromRunning:strongOperation];
         }
-    }];
+    } context:context];
 
     return operation;
 }

SDWebImage/UIView+WebCache.m

@@ -161,7 +161,7 @@ static char TAG_ACTIVITY_SHOW;
                     callCompletedBlockClojure();
                 });
             }
-        }];
+        } context:context];
         [self sd_setImageLoadOperation:operation forKey:validOperationKey];
     } else {
         dispatch_main_async_safe(^{