EMSDImageCache.h 7.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242
  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 <Foundation/Foundation.h>
  9. #import "EMSDWebImageCompat.h"
  10. typedef NS_ENUM(NSInteger, EMSDImageCacheType) {
  11. /**
  12. * The image wasn't available the SDWebImage caches, but was downloaded from the web.
  13. */
  14. EMSDImageCacheTypeNone,
  15. /**
  16. * The image was obtained from the disk cache.
  17. */
  18. EMSDImageCacheTypeDisk,
  19. /**
  20. * The image was obtained from the memory cache.
  21. */
  22. EMSDImageCacheTypeMemory
  23. };
  24. typedef void(^EMSDWebImageQueryCompletedBlock)(UIImage *image, EMSDImageCacheType cacheType);
  25. typedef void(^EMSDWebImageCheckCacheCompletionBlock)(BOOL isInCache);
  26. typedef void(^EMSDWebImageCalculateSizeBlock)(NSUInteger fileCount, NSUInteger totalSize);
  27. /**
  28. * EMSDImageCache maintains a memory cache and an optional disk cache. Disk cache write operations are performed
  29. * asynchronous so it doesn’t add unnecessary latency to the UI.
  30. */
  31. @interface EMSDImageCache : NSObject
  32. /**
  33. * The maximum "total cost" of the in-memory image cache. The cost function is the number of pixels held in memory.
  34. */
  35. @property (assign, nonatomic) NSUInteger maxMemoryCost;
  36. /**
  37. * The maximum length of time to keep an image in the cache, in seconds
  38. */
  39. @property (assign, nonatomic) NSInteger maxCacheAge;
  40. /**
  41. * The maximum size of the cache, in bytes.
  42. */
  43. @property (assign, nonatomic) NSUInteger maxCacheSize;
  44. /**
  45. * Returns global shared cache instance
  46. *
  47. * @return EMSDImageCache global instance
  48. */
  49. + (EMSDImageCache *)sharedImageCache;
  50. /**
  51. * Init a new cache store with a specific namespace
  52. *
  53. * @param ns The namespace to use for this cache store
  54. */
  55. - (id)initWithNamespace:(NSString *)ns;
  56. /**
  57. * Add a read-only cache path to search for images pre-cached by EMSDImageCache
  58. * Useful if you want to bundle pre-loaded images with your app
  59. *
  60. * @param path The path to use for this read-only cache path
  61. */
  62. - (void)addReadOnlyCachePath:(NSString *)path;
  63. /**
  64. * Store an image into memory and disk cache at the given key.
  65. *
  66. * @param image The image to store
  67. * @param key The unique image cache key, usually it's image absolute URL
  68. */
  69. - (void)storeImage:(UIImage *)image forKey:(NSString *)key;
  70. /**
  71. * Store an image into memory and optionally disk cache at the given key.
  72. *
  73. * @param image The image to store
  74. * @param key The unique image cache key, usually it's image absolute URL
  75. * @param toDisk Store the image to disk cache if YES
  76. */
  77. - (void)storeImage:(UIImage *)image forKey:(NSString *)key toDisk:(BOOL)toDisk;
  78. /**
  79. * Store an image into memory and optionally disk cache at the given key.
  80. *
  81. * @param image The image to store
  82. * @param recalculate BOOL indicates if imageData can be used or a new data should be constructed from the UIImage
  83. * @param imageData The image data as returned by the server, this representation will be used for disk storage
  84. * instead of converting the given image object into a storable/compressed image format in order
  85. * to save quality and CPU
  86. * @param key The unique image cache key, usually it's image absolute URL
  87. * @param toDisk Store the image to disk cache if YES
  88. */
  89. - (void)storeImage:(UIImage *)image recalculateFromImage:(BOOL)recalculate imageData:(NSData *)imageData forKey:(NSString *)key toDisk:(BOOL)toDisk;
  90. /**
  91. * Query the disk cache asynchronously.
  92. *
  93. * @param key The unique key used to store the wanted image
  94. */
  95. - (NSOperation *)queryDiskCacheForKey:(NSString *)key done:(EMSDWebImageQueryCompletedBlock)doneBlock;
  96. /**
  97. * Query the memory cache synchronously.
  98. *
  99. * @param key The unique key used to store the wanted image
  100. */
  101. - (UIImage *)imageFromMemoryCacheForKey:(NSString *)key;
  102. /**
  103. * Query the disk cache synchronously after checking the memory cache.
  104. *
  105. * @param key The unique key used to store the wanted image
  106. */
  107. - (UIImage *)imageFromDiskCacheForKey:(NSString *)key;
  108. /**
  109. * Remove the image from memory and disk cache synchronously
  110. *
  111. * @param key The unique image cache key
  112. */
  113. - (void)removeImageForKey:(NSString *)key;
  114. /**
  115. * Remove the image from memory and disk cache synchronously
  116. *
  117. * @param key The unique image cache key
  118. * @param completionBlock An block that should be executed after the image has been removed (optional)
  119. */
  120. - (void)removeImageForKey:(NSString *)key withCompletion:(EMSDWebImageNoParamsBlock)completion;
  121. /**
  122. * Remove the image from memory and optionally disk cache synchronously
  123. *
  124. * @param key The unique image cache key
  125. * @param fromDisk Also remove cache entry from disk if YES
  126. */
  127. - (void)removeImageForKey:(NSString *)key fromDisk:(BOOL)fromDisk;
  128. /**
  129. * Remove the image from memory and optionally disk cache synchronously
  130. *
  131. * @param key The unique image cache key
  132. * @param fromDisk Also remove cache entry from disk if YES
  133. * @param completionBlock An block that should be executed after the image has been removed (optional)
  134. */
  135. - (void)removeImageForKey:(NSString *)key fromDisk:(BOOL)fromDisk withCompletion:(EMSDWebImageNoParamsBlock)completion;
  136. /**
  137. * Clear all memory cached images
  138. */
  139. - (void)clearMemory;
  140. /**
  141. * Clear all disk cached images. Non-blocking method - returns immediately.
  142. * @param completionBlock An block that should be executed after cache expiration completes (optional)
  143. */
  144. - (void)clearDiskOnCompletion:(EMSDWebImageNoParamsBlock)completion;
  145. /**
  146. * Clear all disk cached images
  147. * @see clearDiskOnCompletion:
  148. */
  149. - (void)clearDisk;
  150. /**
  151. * Remove all expired cached image from disk. Non-blocking method - returns immediately.
  152. * @param completionBlock An block that should be executed after cache expiration completes (optional)
  153. */
  154. - (void)cleanDiskWithCompletionBlock:(EMSDWebImageNoParamsBlock)completionBlock;
  155. /**
  156. * Remove all expired cached image from disk
  157. * @see cleanDiskWithCompletionBlock:
  158. */
  159. - (void)cleanDisk;
  160. /**
  161. * Get the size used by the disk cache
  162. */
  163. - (NSUInteger)getSize;
  164. /**
  165. * Get the number of images in the disk cache
  166. */
  167. - (NSUInteger)getDiskCount;
  168. /**
  169. * Asynchronously calculate the disk cache's size.
  170. */
  171. - (void)calculateSizeWithCompletionBlock:(EMSDWebImageCalculateSizeBlock)completionBlock;
  172. /**
  173. * Async check if image exists in disk cache already (does not load the image)
  174. *
  175. * @param key the key describing the url
  176. * @param completionBlock the block to be executed when the check is done.
  177. * @note the completion block will be always executed on the main queue
  178. */
  179. - (void)diskImageExistsWithKey:(NSString *)key completion:(EMSDWebImageCheckCacheCompletionBlock)completionBlock;
  180. /**
  181. * Check if image exists in disk cache already (does not load the image)
  182. *
  183. * @param key the key describing the url
  184. *
  185. * @return YES if an image exists for the given key
  186. */
  187. - (BOOL)diskImageExistsWithKey:(NSString *)key;
  188. /**
  189. * Get the cache path for a certain key (needs the cache path root folder)
  190. *
  191. * @param key the key (can be obtained from url using cacheKeyForURL)
  192. * @param path the cach path root folder
  193. *
  194. * @return the cache path
  195. */
  196. - (NSString *)cachePathForKey:(NSString *)key inPath:(NSString *)path;
  197. /**
  198. * Get the default cache path for a certain key
  199. *
  200. * @param key the key (can be obtained from url using cacheKeyForURL)
  201. *
  202. * @return the default cache path
  203. */
  204. - (NSString *)defaultCachePathForKey:(NSString *)key;
  205. @end