SDWebImageManager.h 10 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275
  1. /*
  2. * This file is part of the SDWebImage package.
  3. * (c) Olivier Poitrey <rs@dailymotion.com>
  4. *
  5. * For the full copyright and license information, please view the LICENSE
  6. * file that was distributed with this source code.
  7. */
  8. #import "SDWebImageCompat.h"
  9. #import "SDWebImageOperation.h"
  10. #import "SDWebImageDownloader.h"
  11. #import "SDImageCache.h"
  12. typedef NS_OPTIONS(NSUInteger, SDWebImageOptions) {
  13. /**
  14. * By default, when a URL fail to be downloaded, the URL is blacklisted so the library won't keep trying.
  15. * This flag disable this blacklisting.
  16. */
  17. SDWebImageRetryFailed = 1 << 0,
  18. /**
  19. * By default, image downloads are started during UI interactions, this flags disable this feature,
  20. * leading to delayed download on UIScrollView deceleration for instance.
  21. */
  22. SDWebImageLowPriority = 1 << 1,
  23. /**
  24. * This flag disables on-disk caching
  25. */
  26. SDWebImageCacheMemoryOnly = 1 << 2,
  27. /**
  28. * This flag enables progressive download, the image is displayed progressively during download as a browser would do.
  29. * By default, the image is only displayed once completely downloaded.
  30. */
  31. SDWebImageProgressiveDownload = 1 << 3,
  32. /**
  33. * Even if the image is cached, respect the HTTP response cache control, and refresh the image from remote location if needed.
  34. * The disk caching will be handled by NSURLCache instead of SDWebImage leading to slight performance degradation.
  35. * This option helps deal with images changing behind the same request URL, e.g. Facebook graph api profile pics.
  36. * If a cached image is refreshed, the completion block is called once with the cached image and again with the final image.
  37. *
  38. * Use this flag only if you can't make your URLs static with embedded cache busting parameter.
  39. */
  40. SDWebImageRefreshCached = 1 << 4,
  41. /**
  42. * In iOS 4+, continue the download of the image if the app goes to background. This is achieved by asking the system for
  43. * extra time in background to let the request finish. If the background task expires the operation will be cancelled.
  44. */
  45. SDWebImageContinueInBackground = 1 << 5,
  46. /**
  47. * Handles cookies stored in NSHTTPCookieStore by setting
  48. * NSMutableURLRequest.HTTPShouldHandleCookies = YES;
  49. */
  50. SDWebImageHandleCookies = 1 << 6,
  51. /**
  52. * Enable to allow untrusted SSL certificates.
  53. * Useful for testing purposes. Use with caution in production.
  54. */
  55. SDWebImageAllowInvalidSSLCertificates = 1 << 7,
  56. /**
  57. * By default, images are loaded in the order in which they were queued. This flag moves them to
  58. * the front of the queue.
  59. */
  60. SDWebImageHighPriority = 1 << 8,
  61. /**
  62. * By default, placeholder images are loaded while the image is loading. This flag will delay the loading
  63. * of the placeholder image until after the image has finished loading.
  64. */
  65. SDWebImageDelayPlaceholder = 1 << 9,
  66. /**
  67. * We usually don't call transformDownloadedImage delegate method on animated images,
  68. * as most transformation code would mangle it.
  69. * Use this flag to transform them anyway.
  70. */
  71. SDWebImageTransformAnimatedImage = 1 << 10,
  72. /**
  73. * By default, image is added to the imageView after download. But in some cases, we want to
  74. * have the hand before setting the image (apply a filter or add it with cross-fade animation for instance)
  75. * Use this flag if you want to manually set the image in the completion when success
  76. */
  77. SDWebImageAvoidAutoSetImage = 1 << 11,
  78. /**
  79. * By default, images are decoded respecting their original size. On iOS, this flag will scale down the
  80. * images to a size compatible with the constrained memory of devices.
  81. * If `SDWebImageProgressiveDownload` flag is set the scale down is deactivated.
  82. */
  83. SDWebImageScaleDownLargeImages = 1 << 12
  84. };
  85. typedef void(^SDExternalCompletionBlock)(UIImage * _Nullable image, NSError * _Nullable error, SDImageCacheType cacheType, NSURL * _Nullable imageURL);
  86. typedef void(^SDInternalCompletionBlock)(UIImage * _Nullable image, NSData * _Nullable data, NSError * _Nullable error, SDImageCacheType cacheType, BOOL finished, NSURL * _Nullable imageURL);
  87. typedef NSString * _Nullable (^SDWebImageCacheKeyFilterBlock)(NSURL * _Nullable url);
  88. @class SDWebImageManager;
  89. @protocol SDWebImageManagerDelegate <NSObject>
  90. @optional
  91. /**
  92. * Controls which image should be downloaded when the image is not found in the cache.
  93. *
  94. * @param imageManager The current `SDWebImageManager`
  95. * @param imageURL The url of the image to be downloaded
  96. *
  97. * @return Return NO to prevent the downloading of the image on cache misses. If not implemented, YES is implied.
  98. */
  99. - (BOOL)imageManager:(nonnull SDWebImageManager *)imageManager shouldDownloadImageForURL:(nullable NSURL *)imageURL;
  100. /**
  101. * Allows to transform the image immediately after it has been downloaded and just before to cache it on disk and memory.
  102. * NOTE: This method is called from a global queue in order to not to block the main thread.
  103. *
  104. * @param imageManager The current `SDWebImageManager`
  105. * @param image The image to transform
  106. * @param imageURL The url of the image to transform
  107. *
  108. * @return The transformed image object.
  109. */
  110. - (nullable UIImage *)imageManager:(nonnull SDWebImageManager *)imageManager transformDownloadedImage:(nullable UIImage *)image withURL:(nullable NSURL *)imageURL;
  111. @end
  112. /**
  113. * The SDWebImageManager is the class behind the UIImageView+WebCache category and likes.
  114. * It ties the asynchronous downloader (SDWebImageDownloader) with the image cache store (SDImageCache).
  115. * You can use this class directly to benefit from web image downloading with caching in another context than
  116. * a UIView.
  117. *
  118. * Here is a simple example of how to use SDWebImageManager:
  119. *
  120. * @code
  121. SDWebImageManager *manager = [SDWebImageManager sharedManager];
  122. [manager loadImageWithURL:imageURL
  123. options:0
  124. progress:nil
  125. completed:^(UIImage *image, NSError *error, SDImageCacheType cacheType, BOOL finished, NSURL *imageURL) {
  126. if (image) {
  127. // do something with image
  128. }
  129. }];
  130. * @endcode
  131. */
  132. @interface SDWebImageManager : NSObject
  133. @property (weak, nonatomic, nullable) id <SDWebImageManagerDelegate> delegate;
  134. @property (strong, nonatomic, readonly, nullable) SDImageCache *imageCache;
  135. @property (strong, nonatomic, readonly, nullable) SDWebImageDownloader *imageDownloader;
  136. /**
  137. * The cache filter is a block used each time SDWebImageManager need to convert an URL into a cache key. This can
  138. * be used to remove dynamic part of an image URL.
  139. *
  140. * The following example sets a filter in the application delegate that will remove any query-string from the
  141. * URL before to use it as a cache key:
  142. *
  143. * @code
  144. [[SDWebImageManager sharedManager] setCacheKeyFilter:^(NSURL *url) {
  145. url = [[NSURL alloc] initWithScheme:url.scheme host:url.host path:url.path];
  146. return [url absoluteString];
  147. }];
  148. * @endcode
  149. */
  150. @property (nonatomic, copy, nullable) SDWebImageCacheKeyFilterBlock cacheKeyFilter;
  151. /**
  152. * Returns global SDWebImageManager instance.
  153. *
  154. * @return SDWebImageManager shared instance
  155. */
  156. + (nonnull instancetype)sharedManager;
  157. /**
  158. * Allows to specify instance of cache and image downloader used with image manager.
  159. * @return new instance of `SDWebImageManager` with specified cache and downloader.
  160. */
  161. - (nonnull instancetype)initWithCache:(nonnull SDImageCache *)cache downloader:(nonnull SDWebImageDownloader *)downloader NS_DESIGNATED_INITIALIZER;
  162. /**
  163. * Downloads the image at the given URL if not present in cache or return the cached version otherwise.
  164. *
  165. * @param url The URL to the image
  166. * @param options A mask to specify options to use for this request
  167. * @param progressBlock A block called while image is downloading
  168. * @note the progress block is executed on a background queue
  169. * @param completedBlock A block called when operation has been completed.
  170. *
  171. * This parameter is required.
  172. *
  173. * This block has no return value and takes the requested UIImage as first parameter and the NSData representation as second parameter.
  174. * In case of error the image parameter is nil and the third parameter may contain an NSError.
  175. *
  176. * The forth parameter is an `SDImageCacheType` enum indicating if the image was retrieved from the local cache
  177. * or from the memory cache or from the network.
  178. *
  179. * The fith parameter is set to NO when the SDWebImageProgressiveDownload option is used and the image is
  180. * downloading. This block is thus called repeatedly with a partial image. When image is fully downloaded, the
  181. * block is called a last time with the full image and the last parameter set to YES.
  182. *
  183. * The last parameter is the original image URL
  184. *
  185. * @return Returns an NSObject conforming to SDWebImageOperation. Should be an instance of SDWebImageDownloaderOperation
  186. */
  187. - (nullable id <SDWebImageOperation>)loadImageWithURL:(nullable NSURL *)url
  188. options:(SDWebImageOptions)options
  189. progress:(nullable SDWebImageDownloaderProgressBlock)progressBlock
  190. completed:(nullable SDInternalCompletionBlock)completedBlock;
  191. /**
  192. * Saves image to cache for given URL
  193. *
  194. * @param image The image to cache
  195. * @param url The URL to the image
  196. *
  197. */
  198. - (void)saveImageToCache:(nullable UIImage *)image forURL:(nullable NSURL *)url;
  199. /**
  200. * Cancel all current operations
  201. */
  202. - (void)cancelAll;
  203. /**
  204. * Check one or more operations running
  205. */
  206. - (BOOL)isRunning;
  207. /**
  208. * Async check if image has already been cached
  209. *
  210. * @param url image url
  211. * @param completionBlock the block to be executed when the check is finished
  212. *
  213. * @note the completion block is always executed on the main queue
  214. */
  215. - (void)cachedImageExistsForURL:(nullable NSURL *)url
  216. completion:(nullable SDWebImageCheckCacheCompletionBlock)completionBlock;
  217. /**
  218. * Async check if image has already been cached on disk only
  219. *
  220. * @param url image url
  221. * @param completionBlock the block to be executed when the check is finished
  222. *
  223. * @note the completion block is always executed on the main queue
  224. */
  225. - (void)diskImageExistsForURL:(nullable NSURL *)url
  226. completion:(nullable SDWebImageCheckCacheCompletionBlock)completionBlock;
  227. /**
  228. *Return the cache key for a given URL
  229. */
  230. - (nullable NSString *)cacheKeyForURL:(nullable NSURL *)url;
  231. @end