SDImageCache.h 7.6 KB

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