/*
|
* This file is part of the SDWebImage package.
|
* (c) Olivier Poitrey <rs@dailymotion.com>
|
*
|
* For the full copyright and license information, please view the LICENSE
|
* file that was distributed with this source code.
|
*/
|
|
#import <Foundation/Foundation.h>
|
#import "SDWebImageCompat.h"
|
#import "SDImageCacheConfig.h"
|
|
typedef NS_ENUM(NSInteger, SDImageCacheType) {
|
/**
|
* The image wasn't available the SDWebImage caches, but was downloaded from the web.
|
*/
|
SDImageCacheTypeNone,
|
/**
|
* The image was obtained from the disk cache.
|
*/
|
SDImageCacheTypeDisk,
|
/**
|
* The image was obtained from the memory cache.
|
*/
|
SDImageCacheTypeMemory
|
};
|
|
typedef NS_OPTIONS(NSUInteger, SDImageCacheOptions) {
|
/**
|
* By default, we do not query disk data when the image is cached in memory. This mask can force to query disk data at the same time.
|
*/
|
SDImageCacheQueryDataWhenInMemory = 1 << 0,
|
/**
|
* By default, we query the memory cache synchronously, disk cache asynchronously. This mask can force to query disk cache synchronously.
|
*/
|
SDImageCacheQueryDiskSync = 1 << 1,
|
/**
|
* By default, images are decoded respecting their original size. On iOS, this flag will scale down the
|
* images to a size compatible with the constrained memory of devices.
|
*/
|
SDImageCacheScaleDownLargeImages = 1 << 2
|
};
|
|
typedef void(^SDCacheQueryCompletedBlock)(UIImage * _Nullable image, NSData * _Nullable data, SDImageCacheType cacheType);
|
|
typedef void(^SDWebImageCheckCacheCompletionBlock)(BOOL isInCache);
|
|
typedef void(^SDWebImageCalculateSizeBlock)(NSUInteger fileCount, NSUInteger totalSize);
|
|
|
/**
|
* SDImageCache maintains a memory cache and an optional disk cache. Disk cache write operations are performed
|
* asynchronous so it doesn’t add unnecessary latency to the UI.
|
*/
|
@interface SDImageCache : NSObject
|
|
#pragma mark - Properties
|
|
/**
|
* Cache Config object - storing all kind of settings
|
*/
|
@property (nonatomic, nonnull, readonly) SDImageCacheConfig *config;
|
|
/**
|
* The maximum "total cost" of the in-memory image cache. The cost function is the number of pixels held in memory.
|
*/
|
@property (assign, nonatomic) NSUInteger maxMemoryCost;
|
|
/**
|
* The maximum number of objects the cache should hold.
|
*/
|
@property (assign, nonatomic) NSUInteger maxMemoryCountLimit;
|
|
#pragma mark - Singleton and initialization
|
|
/**
|
* Returns global shared cache instance
|
*
|
* @return SDImageCache global instance
|
*/
|
+ (nonnull instancetype)sharedImageCache;
|
|
/**
|
* Init a new cache store with a specific namespace
|
*
|
* @param ns The namespace to use for this cache store
|
*/
|
- (nonnull instancetype)initWithNamespace:(nonnull NSString *)ns;
|
|
/**
|
* Init a new cache store with a specific namespace and directory
|
*
|
* @param ns The namespace to use for this cache store
|
* @param directory Directory to cache disk images in
|
*/
|
- (nonnull instancetype)initWithNamespace:(nonnull NSString *)ns
|
diskCacheDirectory:(nonnull NSString *)directory NS_DESIGNATED_INITIALIZER;
|
|
#pragma mark - Cache paths
|
|
- (nullable NSString *)makeDiskCachePath:(nonnull NSString*)fullNamespace;
|
|
/**
|
* Add a read-only cache path to search for images pre-cached by SDImageCache
|
* Useful if you want to bundle pre-loaded images with your app
|
*
|
* @param path The path to use for this read-only cache path
|
*/
|
- (void)addReadOnlyCachePath:(nonnull NSString *)path;
|
|
#pragma mark - Store Ops
|
|
/**
|
* Asynchronously store an image into memory and disk cache at the given key.
|
*
|
* @param image The image to store
|
* @param key The unique image cache key, usually it's image absolute URL
|
* @param completionBlock A block executed after the operation is finished
|
*/
|
- (void)storeImage:(nullable UIImage *)image
|
forKey:(nullable NSString *)key
|
completion:(nullable SDWebImageNoParamsBlock)completionBlock;
|
|
/**
|
* Asynchronously store an image into memory and disk cache at the given key.
|
*
|
* @param image The image to store
|
* @param key The unique image cache key, usually it's image absolute URL
|
* @param toDisk Store the image to disk cache if YES
|
* @param completionBlock A block executed after the operation is finished
|
*/
|
- (void)storeImage:(nullable UIImage *)image
|
forKey:(nullable NSString *)key
|
toDisk:(BOOL)toDisk
|
completion:(nullable SDWebImageNoParamsBlock)completionBlock;
|
|
/**
|
* Asynchronously store an image into memory and disk cache at the given key.
|
*
|
* @param image The image to store
|
* @param imageData The image data as returned by the server, this representation will be used for disk storage
|
* instead of converting the given image object into a storable/compressed image format in order
|
* to save quality and CPU
|
* @param key The unique image cache key, usually it's image absolute URL
|
* @param toDisk Store the image to disk cache if YES
|
* @param completionBlock A block executed after the operation is finished
|
*/
|
- (void)storeImage:(nullable UIImage *)image
|
imageData:(nullable NSData *)imageData
|
forKey:(nullable NSString *)key
|
toDisk:(BOOL)toDisk
|
completion:(nullable SDWebImageNoParamsBlock)completionBlock;
|
|
/**
|
* Synchronously store image NSData into disk cache at the given key.
|
*
|
*
|
* @param imageData The image data to store
|
* @param key The unique image cache key, usually it's image absolute URL
|
*/
|
- (void)storeImageDataToDisk:(nullable NSData *)imageData forKey:(nullable NSString *)key;
|
|
#pragma mark - Query and Retrieve Ops
|
|
/**
|
* Async check if image exists in disk cache already (does not load the image)
|
*
|
* @param key the key describing the url
|
* @param completionBlock the block to be executed when the check is done.
|
* @note the completion block will be always executed on the main queue
|
*/
|
- (void)diskImageExistsWithKey:(nullable NSString *)key completion:(nullable SDWebImageCheckCacheCompletionBlock)completionBlock;
|
|
/**
|
* Sync check if image data exists in disk cache already (does not load the image)
|
*
|
* @param key the key describing the url
|
*/
|
- (BOOL)diskImageDataExistsWithKey:(nullable NSString *)key;
|
|
/**
|
* Operation that queries the cache asynchronously and call the completion when done.
|
*
|
* @param key The unique key used to store the wanted image
|
* @param doneBlock The completion block. Will not get called if the operation is cancelled
|
*
|
* @return a NSOperation instance containing the cache op
|
*/
|
- (nullable NSOperation *)queryCacheOperationForKey:(nullable NSString *)key done:(nullable SDCacheQueryCompletedBlock)doneBlock;
|
|
/**
|
* Operation that queries the cache asynchronously and call the completion when done.
|
*
|
* @param key The unique key used to store the wanted image
|
* @param options A mask to specify options to use for this cache query
|
* @param doneBlock The completion block. Will not get called if the operation is cancelled
|
*
|
* @return a NSOperation instance containing the cache op
|
*/
|
- (nullable NSOperation *)queryCacheOperationForKey:(nullable NSString *)key options:(SDImageCacheOptions)options done:(nullable SDCacheQueryCompletedBlock)doneBlock;
|
|
/**
|
* Query the memory cache synchronously.
|
*
|
* @param key The unique key used to store the image
|
*/
|
- (nullable UIImage *)imageFromMemoryCacheForKey:(nullable NSString *)key;
|
|
/**
|
* Query the disk cache synchronously.
|
*
|
* @param key The unique key used to store the image
|
*/
|
- (nullable UIImage *)imageFromDiskCacheForKey:(nullable NSString *)key;
|
|
/**
|
* Query the cache (memory and or disk) synchronously after checking the memory cache.
|
*
|
* @param key The unique key used to store the image
|
*/
|
- (nullable UIImage *)imageFromCacheForKey:(nullable NSString *)key;
|
|
#pragma mark - Remove Ops
|
|
/**
|
* Remove the image from memory and disk cache asynchronously
|
*
|
* @param key The unique image cache key
|
* @param completion A block that should be executed after the image has been removed (optional)
|
*/
|
- (void)removeImageForKey:(nullable NSString *)key withCompletion:(nullable SDWebImageNoParamsBlock)completion;
|
|
/**
|
* Remove the image from memory and optionally disk cache asynchronously
|
*
|
* @param key The unique image cache key
|
* @param fromDisk Also remove cache entry from disk if YES
|
* @param completion A block that should be executed after the image has been removed (optional)
|
*/
|
- (void)removeImageForKey:(nullable NSString *)key fromDisk:(BOOL)fromDisk withCompletion:(nullable SDWebImageNoParamsBlock)completion;
|
|
#pragma mark - Cache clean Ops
|
|
/**
|
* Clear all memory cached images
|
*/
|
- (void)clearMemory;
|
|
/**
|
* Async clear all disk cached images. Non-blocking method - returns immediately.
|
* @param completion A block that should be executed after cache expiration completes (optional)
|
*/
|
- (void)clearDiskOnCompletion:(nullable SDWebImageNoParamsBlock)completion;
|
|
/**
|
* Async remove all expired cached image from disk. Non-blocking method - returns immediately.
|
* @param completionBlock A block that should be executed after cache expiration completes (optional)
|
*/
|
- (void)deleteOldFilesWithCompletionBlock:(nullable SDWebImageNoParamsBlock)completionBlock;
|
|
#pragma mark - Cache Info
|
|
/**
|
* Get the size used by the disk cache
|
*/
|
- (NSUInteger)getSize;
|
|
/**
|
* Get the number of images in the disk cache
|
*/
|
- (NSUInteger)getDiskCount;
|
|
/**
|
* Asynchronously calculate the disk cache's size.
|
*/
|
- (void)calculateSizeWithCompletionBlock:(nullable SDWebImageCalculateSizeBlock)completionBlock;
|
|
#pragma mark - Cache Paths
|
|
/**
|
* Get the cache path for a certain key (needs the cache path root folder)
|
*
|
* @param key the key (can be obtained from url using cacheKeyForURL)
|
* @param path the cache path root folder
|
*
|
* @return the cache path
|
*/
|
- (nullable NSString *)cachePathForKey:(nullable NSString *)key inPath:(nonnull NSString *)path;
|
|
/**
|
* Get the default cache path for a certain key
|
*
|
* @param key the key (can be obtained from url using cacheKeyForURL)
|
*
|
* @return the default cache path
|
*/
|
- (nullable NSString *)defaultCachePathForKey:(nullable NSString *)key;
|
|
@end
|
