EMSDWebImageManager.h 10 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286
  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 "EMSDWebImageCompat.h"
  9. #import "EMSDWebImageOperation.h"
  10. #import "EMSDWebImageDownloader.h"
  11. #import "EMSDImageCache.h"
  12. typedef NS_OPTIONS(NSUInteger, EMSDWebImageOptions) {
  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. EMSDWebImageRetryFailed = 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. EMSDWebImageLowPriority = 1 << 1,
  23. /**
  24. * This flag disables on-disk caching
  25. */
  26. EMSDWebImageCacheMemoryOnly = 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. EMSDWebImageProgressiveDownload = 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 embeded cache busting parameter.
  39. */
  40. EMSDWebImageRefreshCached = 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. EMSDWebImageContinueInBackground = 1 << 5,
  46. /**
  47. * Handles cookies stored in NSHTTPCookieStore by setting
  48. * NSMutableURLRequest.HTTPShouldHandleCookies = YES;
  49. */
  50. EMSDWebImageHandleCookies = 1 << 6,
  51. /**
  52. * Enable to allow untrusted SSL ceriticates.
  53. * Useful for testing purposes. Use with caution in production.
  54. */
  55. EMSDWebImageAllowInvalidSSLCertificates = 1 << 7,
  56. /**
  57. * By default, image are loaded in the order they were queued. This flag move them to
  58. * the front of the queue and is loaded immediately instead of waiting for the current queue to be loaded (which
  59. * could take a while).
  60. */
  61. EMSDWebImageHighPriority = 1 << 8,
  62. /**
  63. * By default, placeholder images are loaded while the image is loading. This flag will delay the loading
  64. * of the placeholder image until after the image has finished loading.
  65. */
  66. EMSDWebImageDelayPlaceholder = 1 << 9
  67. };
  68. typedef void(^EMSDWebImageCompletionBlock)(UIImage *image, NSError *error, EMSDImageCacheType cacheType, NSURL *imageURL);
  69. typedef void(^EMSDWebImageCompletionWithFinishedBlock)(UIImage *image, NSError *error, EMSDImageCacheType cacheType, BOOL finished, NSURL *imageURL);
  70. typedef NSString *(^EMSDWebImageCacheKeyFilterBlock)(NSURL *url);
  71. @class EMSDWebImageManager;
  72. @protocol EMSDWebImageManagerDelegate <NSObject>
  73. @optional
  74. /**
  75. * Controls which image should be downloaded when the image is not found in the cache.
  76. *
  77. * @param imageManager The current `EMSDWebImageManager`
  78. * @param imageURL The url of the image to be downloaded
  79. *
  80. * @return Return NO to prevent the downloading of the image on cache misses. If not implemented, YES is implied.
  81. */
  82. - (BOOL)imageManager:(EMSDWebImageManager *)imageManager shouldDownloadImageForURL:(NSURL *)imageURL;
  83. /**
  84. * Allows to transform the image immediately after it has been downloaded and just before to cache it on disk and memory.
  85. * NOTE: This method is called from a global queue in order to not to block the main thread.
  86. *
  87. * @param imageManager The current `EMSDWebImageManager`
  88. * @param image The image to transform
  89. * @param imageURL The url of the image to transform
  90. *
  91. * @return The transformed image object.
  92. */
  93. - (UIImage *)imageManager:(EMSDWebImageManager *)imageManager transformDownloadedImage:(UIImage *)image withURL:(NSURL *)imageURL;
  94. @end
  95. /**
  96. * The EMSDWebImageManager is the class behind the UIImageView+EMWebCache category and likes.
  97. * It ties the asynchronous downloader (EMSDWebImageDownloader) with the image cache store (EMSDImageCache).
  98. * You can use this class directly to benefit from web image downloading with caching in another context than
  99. * a UIView.
  100. *
  101. * Here is a simple example of how to use EMSDWebImageManager:
  102. *
  103. * @code
  104. EMSDWebImageManager *manager = [EMSDWebImageManager sharedManager];
  105. [manager downloadWithURL:imageURL
  106. options:0
  107. progress:nil
  108. completed:^(UIImage *image, NSError *error, EMSDImageCacheType cacheType, BOOL finished, NSURL *imageURL) {
  109. if (image) {
  110. // do something with image
  111. }
  112. }];
  113. * @endcode
  114. */
  115. @interface EMSDWebImageManager : NSObject
  116. @property (weak, nonatomic) id <EMSDWebImageManagerDelegate> delegate;
  117. @property (strong, nonatomic, readonly) EMSDImageCache *imageCache;
  118. @property (strong, nonatomic, readonly) EMSDWebImageDownloader *imageDownloader;
  119. /**
  120. * The cache filter is a block used each time EMSDWebImageManager need to convert an URL into a cache key. This can
  121. * be used to remove dynamic part of an image URL.
  122. *
  123. * The following example sets a filter in the application delegate that will remove any query-string from the
  124. * URL before to use it as a cache key:
  125. *
  126. * @code
  127. [[EMSDWebImageManager sharedManager] setCacheKeyFilter:^(NSURL *url) {
  128. url = [[NSURL alloc] initWithScheme:url.scheme host:url.host path:url.path];
  129. return [url absoluteString];
  130. }];
  131. * @endcode
  132. */
  133. @property (copy) EMSDWebImageCacheKeyFilterBlock cacheKeyFilter;
  134. /**
  135. * Returns global EMSDWebImageManager instance.
  136. *
  137. * @return EMSDWebImageManager shared instance
  138. */
  139. + (EMSDWebImageManager *)sharedManager;
  140. /**
  141. * Downloads the image at the given URL if not present in cache or return the cached version otherwise.
  142. *
  143. * @param url The URL to the image
  144. * @param options A mask to specify options to use for this request
  145. * @param progressBlock A block called while image is downloading
  146. * @param completedBlock A block called when operation has been completed.
  147. *
  148. * This parameter is required.
  149. *
  150. * This block has no return value and takes the requested UIImage as first parameter.
  151. * In case of error the image parameter is nil and the second parameter may contain an NSError.
  152. *
  153. * The third parameter is an `EMSDImageCacheType` enum indicating if the image was retrived from the local cache
  154. * or from the memory cache or from the network.
  155. *
  156. * The last parameter is set to NO when the EMSDWebImageProgressiveDownload option is used and the image is
  157. * downloading. This block is thus called repetidly with a partial image. When image is fully downloaded, the
  158. * block is called a last time with the full image and the last parameter set to YES.
  159. *
  160. * @return Returns an NSObject conforming to EMSDWebImageOperation. Should be an instance of EMSDWebImageDownloaderOperation
  161. */
  162. - (id <EMSDWebImageOperation>)downloadImageWithURL:(NSURL *)url
  163. options:(EMSDWebImageOptions)options
  164. progress:(EMSDWebImageDownloaderProgressBlock)progressBlock
  165. completed:(EMSDWebImageCompletionWithFinishedBlock)completedBlock;
  166. /**
  167. * Saves image to cache for given URL
  168. *
  169. * @param image The image to cache
  170. * @param url The URL to the image
  171. *
  172. */
  173. - (void)saveImageToCache:(UIImage *)image forURL:(NSURL *)url;
  174. /**
  175. * Cancel all current opreations
  176. */
  177. - (void)cancelAll;
  178. /**
  179. * Check one or more operations running
  180. */
  181. - (BOOL)isRunning;
  182. /**
  183. * Check if image has already been cached
  184. *
  185. * @param url image url
  186. *
  187. * @return if the image was already cached
  188. */
  189. - (BOOL)cachedImageExistsForURL:(NSURL *)url;
  190. /**
  191. * Check if image has already been cached on disk only
  192. *
  193. * @param url image url
  194. *
  195. * @return if the image was already cached (disk only)
  196. */
  197. - (BOOL)diskImageExistsForURL:(NSURL *)url;
  198. /**
  199. * Async check if image has already been cached
  200. *
  201. * @param url image url
  202. * @param completionBlock the block to be executed when the check is finished
  203. *
  204. * @note the completion block is always executed on the main queue
  205. */
  206. - (void)cachedImageExistsForURL:(NSURL *)url
  207. completion:(EMSDWebImageCheckCacheCompletionBlock)completionBlock;
  208. /**
  209. * Async check if image has already been cached on disk only
  210. *
  211. * @param url image url
  212. * @param completionBlock the block to be executed when the check is finished
  213. *
  214. * @note the completion block is always executed on the main queue
  215. */
  216. - (void)diskImageExistsForURL:(NSURL *)url
  217. completion:(EMSDWebImageCheckCacheCompletionBlock)completionBlock;
  218. /**
  219. *Return the cache key for a given URL
  220. */
  221. - (NSString *)cacheKeyForURL:(NSURL *)url;
  222. @end
  223. #pragma mark - Deprecated
  224. typedef void(^EMSDWebImageCompletedBlock)(UIImage *image, NSError *error, EMSDImageCacheType cacheType) __deprecated_msg("Block type deprecated. Use `EMSDWebImageCompletionBlock`");
  225. typedef void(^EMSDWebImageCompletedWithFinishedBlock)(UIImage *image, NSError *error, EMSDImageCacheType cacheType, BOOL finished) __deprecated_msg("Block type deprecated. Use `EMSDWebImageCompletionWithFinishedBlock`");
  226. @interface EMSDWebImageManager (Deprecated)
  227. /**
  228. * Downloads the image at the given URL if not present in cache or return the cached version otherwise.
  229. *
  230. * @deprecated This method has been deprecated. Use `downloadImageWithURL:options:progress:completed:`
  231. */
  232. - (id <EMSDWebImageOperation>)downloadWithURL:(NSURL *)url
  233. options:(EMSDWebImageOptions)options
  234. progress:(EMSDWebImageDownloaderProgressBlock)progressBlock
  235. completed:(EMSDWebImageCompletedWithFinishedBlock)completedBlock __deprecated_msg("Method deprecated. Use `downloadImageWithURL:options:progress:completed:`");
  236. @end