SDImageCache.h 8.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266
  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. #import "SDImageCacheConfig.h"
  11. typedef NS_ENUM(NSInteger, SDImageCacheType) {
  12. /**
  13. * The image wasn't available the SDWebImage caches, but was downloaded from the web.
  14. */
  15. SDImageCacheTypeNone,
  16. /**
  17. * The image was obtained from the disk cache.
  18. */
  19. SDImageCacheTypeDisk,
  20. /**
  21. * The image was obtained from the memory cache.
  22. */
  23. SDImageCacheTypeMemory
  24. };
  25. typedef void(^SDCacheQueryCompletedBlock)(UIImage * _Nullable image, NSData * _Nullable data, SDImageCacheType cacheType);
  26. typedef void(^SDWebImageCheckCacheCompletionBlock)(BOOL isInCache);
  27. typedef void(^SDWebImageCalculateSizeBlock)(NSUInteger fileCount, NSUInteger totalSize);
  28. /**
  29. * SDImageCache maintains a memory cache and an optional disk cache. Disk cache write operations are performed
  30. * asynchronous so it doesn’t add unnecessary latency to the UI.
  31. */
  32. @interface SDImageCache : NSObject
  33. #pragma mark - Properties
  34. /**
  35. * Cache Config object - storing all kind of settings
  36. */
  37. @property (nonatomic, nonnull, readonly) SDImageCacheConfig *config;
  38. /**
  39. * The maximum "total cost" of the in-memory image cache. The cost function is the number of pixels held in memory.
  40. */
  41. @property (assign, nonatomic) NSUInteger maxMemoryCost;
  42. /**
  43. * The maximum number of objects the cache should hold.
  44. */
  45. @property (assign, nonatomic) NSUInteger maxMemoryCountLimit;
  46. #pragma mark - Singleton and initialization
  47. /**
  48. * Returns global shared cache instance
  49. *
  50. * @return SDImageCache global instance
  51. */
  52. + (nonnull instancetype)sharedImageCache;
  53. /**
  54. * Init a new cache store with a specific namespace
  55. *
  56. * @param ns The namespace to use for this cache store
  57. */
  58. - (nonnull instancetype)initWithNamespace:(nonnull NSString *)ns;
  59. /**
  60. * Init a new cache store with a specific namespace and directory
  61. *
  62. * @param ns The namespace to use for this cache store
  63. * @param directory Directory to cache disk images in
  64. */
  65. - (nonnull instancetype)initWithNamespace:(nonnull NSString *)ns
  66. diskCacheDirectory:(nonnull NSString *)directory NS_DESIGNATED_INITIALIZER;
  67. #pragma mark - Cache paths
  68. - (nullable NSString *)makeDiskCachePath:(nonnull NSString*)fullNamespace;
  69. /**
  70. * Add a read-only cache path to search for images pre-cached by SDImageCache
  71. * Useful if you want to bundle pre-loaded images with your app
  72. *
  73. * @param path The path to use for this read-only cache path
  74. */
  75. - (void)addReadOnlyCachePath:(nonnull NSString *)path;
  76. #pragma mark - Store Ops
  77. /**
  78. * Asynchronously store an image into memory and disk cache at the given key.
  79. *
  80. * @param image The image to store
  81. * @param key The unique image cache key, usually it's image absolute URL
  82. * @param completionBlock A block executed after the operation is finished
  83. */
  84. - (void)storeImage:(nullable UIImage *)image
  85. forKey:(nullable NSString *)key
  86. completion:(nullable SDWebImageNoParamsBlock)completionBlock;
  87. /**
  88. * Asynchronously store an image into memory and disk cache at the given key.
  89. *
  90. * @param image The image to store
  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. * @param completionBlock A block executed after the operation is finished
  94. */
  95. - (void)storeImage:(nullable UIImage *)image
  96. forKey:(nullable NSString *)key
  97. toDisk:(BOOL)toDisk
  98. completion:(nullable SDWebImageNoParamsBlock)completionBlock;
  99. /**
  100. * Asynchronously store an image into memory and disk cache at the given key.
  101. *
  102. * @param image The image to store
  103. * @param imageData The image data as returned by the server, this representation will be used for disk storage
  104. * instead of converting the given image object into a storable/compressed image format in order
  105. * to save quality and CPU
  106. * @param key The unique image cache key, usually it's image absolute URL
  107. * @param toDisk Store the image to disk cache if YES
  108. * @param completionBlock A block executed after the operation is finished
  109. */
  110. - (void)storeImage:(nullable UIImage *)image
  111. imageData:(nullable NSData *)imageData
  112. forKey:(nullable NSString *)key
  113. toDisk:(BOOL)toDisk
  114. completion:(nullable SDWebImageNoParamsBlock)completionBlock;
  115. /**
  116. * Synchronously store image NSData into disk cache at the given key.
  117. *
  118. * @warning This method is synchronous, make sure to call it from the ioQueue
  119. *
  120. * @param imageData The image data to store
  121. * @param key The unique image cache key, usually it's image absolute URL
  122. */
  123. - (void)storeImageDataToDisk:(nullable NSData *)imageData forKey:(nullable NSString *)key;
  124. #pragma mark - Query and Retrieve Ops
  125. /**
  126. * Async check if image exists in disk cache already (does not load the image)
  127. *
  128. * @param key the key describing the url
  129. * @param completionBlock the block to be executed when the check is done.
  130. * @note the completion block will be always executed on the main queue
  131. */
  132. - (void)diskImageExistsWithKey:(nullable NSString *)key completion:(nullable SDWebImageCheckCacheCompletionBlock)completionBlock;
  133. /**
  134. * Operation that queries the cache asynchronously and call the completion when done.
  135. *
  136. * @param key The unique key used to store the wanted image
  137. * @param doneBlock The completion block. Will not get called if the operation is cancelled
  138. *
  139. * @return a NSOperation instance containing the cache op
  140. */
  141. - (nullable NSOperation *)queryCacheOperationForKey:(nullable NSString *)key done:(nullable SDCacheQueryCompletedBlock)doneBlock;
  142. /**
  143. * Query the memory cache synchronously.
  144. *
  145. * @param key The unique key used to store the image
  146. */
  147. - (nullable UIImage *)imageFromMemoryCacheForKey:(nullable NSString *)key;
  148. /**
  149. * Query the disk cache synchronously.
  150. *
  151. * @param key The unique key used to store the image
  152. */
  153. - (nullable UIImage *)imageFromDiskCacheForKey:(nullable NSString *)key;
  154. /**
  155. * Query the cache (memory and or disk) synchronously after checking the memory cache.
  156. *
  157. * @param key The unique key used to store the image
  158. */
  159. - (nullable UIImage *)imageFromCacheForKey:(nullable NSString *)key;
  160. #pragma mark - Remove Ops
  161. /**
  162. * Remove the image from memory and disk cache asynchronously
  163. *
  164. * @param key The unique image cache key
  165. * @param completion A block that should be executed after the image has been removed (optional)
  166. */
  167. - (void)removeImageForKey:(nullable NSString *)key withCompletion:(nullable SDWebImageNoParamsBlock)completion;
  168. /**
  169. * Remove the image from memory and optionally disk cache asynchronously
  170. *
  171. * @param key The unique image cache key
  172. * @param fromDisk Also remove cache entry from disk if YES
  173. * @param completion A block that should be executed after the image has been removed (optional)
  174. */
  175. - (void)removeImageForKey:(nullable NSString *)key fromDisk:(BOOL)fromDisk withCompletion:(nullable SDWebImageNoParamsBlock)completion;
  176. #pragma mark - Cache clean Ops
  177. /**
  178. * Clear all memory cached images
  179. */
  180. - (void)clearMemory;
  181. /**
  182. * Async clear all disk cached images. Non-blocking method - returns immediately.
  183. * @param completion A block that should be executed after cache expiration completes (optional)
  184. */
  185. - (void)clearDiskOnCompletion:(nullable SDWebImageNoParamsBlock)completion;
  186. /**
  187. * Async remove all expired cached image from disk. Non-blocking method - returns immediately.
  188. * @param completionBlock A block that should be executed after cache expiration completes (optional)
  189. */
  190. - (void)deleteOldFilesWithCompletionBlock:(nullable SDWebImageNoParamsBlock)completionBlock;
  191. #pragma mark - Cache Info
  192. /**
  193. * Get the size used by the disk cache
  194. */
  195. - (NSUInteger)getSize;
  196. /**
  197. * Get the number of images in the disk cache
  198. */
  199. - (NSUInteger)getDiskCount;
  200. /**
  201. * Asynchronously calculate the disk cache's size.
  202. */
  203. - (void)calculateSizeWithCompletionBlock:(nullable SDWebImageCalculateSizeBlock)completionBlock;
  204. #pragma mark - Cache Paths
  205. /**
  206. * Get the cache path for a certain key (needs the cache path root folder)
  207. *
  208. * @param key the key (can be obtained from url using cacheKeyForURL)
  209. * @param path the cache path root folder
  210. *
  211. * @return the cache path
  212. */
  213. - (nullable NSString *)cachePathForKey:(nullable NSString *)key inPath:(nonnull NSString *)path;
  214. /**
  215. * Get the default cache path for a certain key
  216. *
  217. * @param key the key (can be obtained from url using cacheKeyForURL)
  218. *
  219. * @return the default cache path
  220. */
  221. - (nullable NSString *)defaultCachePathForKey:(nullable NSString *)key;
  222. @end