SDWebImageManager

@interface SDWebImageManager : NSObject
  • The SDWebImageManager is the class behind the UIImageView+WebCache category and likes.
  • It ties the asynchronous downloader (SDWebImageDownloader) with the image cache store (SDImageCache).
  • You can use this class directly to benefit from web image downloading with caching in another context than
  • a UIView. *
  • Here is a simple example of how to use SDWebImageManager: *
  • “`

SDWebImageManager *manager = [SDWebImageManager sharedManager]; [manager loadImageWithURL:imageURL options:0 progress:nil completed:^(UIImage *image, NSData *data, NSError *error, SDImageCacheType cacheType, BOOL finished, NSURL *imageURL) { if (image) { // do something with image } }];

  • ”`
  • The delegate for manager. Defaults to nil.

    Declaration

    Objective-C

    @property (nonatomic, nullable) id<SDWebImageManagerDelegate> delegate;

    Swift

    weak var delegate: SDWebImageManagerDelegate? { get set }
  • The image cache used by manager to query image cache.

    Declaration

    Objective-C

    @property (readonly, strong, nonatomic, nonnull) id<SDImageCache> imageCache;

    Swift

    var imageCache: SDImageCache { get }
  • The image loader used by manager to load image.

    Declaration

    Objective-C

    @property (readonly, strong, nonatomic, nonnull) id<SDImageLoader> imageLoader;

    Swift

    var imageLoader: SDImageLoader { get }
  • The image transformer for manager. It’s used for image transform after the image load finished and store the transformed image to cache, see SDImageTransformer. Defaults to nil, which means no transform is applied.

    Note

    This will affect all the load requests for this manager if you provide. However, you can pass SDWebImageContextImageTransformer in context arg to explicitly use that transformer instead.

    Declaration

    Objective-C

    @property (strong, nonatomic, nullable) id<SDImageTransformer> transformer;

    Swift

    var transformer: SDImageTransformer? { get set }
    • The cache filter is used to convert an URL into a cache key each time SDWebImageManager need cache key to use image cache. *
    • The following example sets a filter in the application delegate that will remove any query-string from the
    • URL before to use it as a cache key: *
    • “` SDWebImageManager.sharedManager.cacheKeyFilter =[SDWebImageCacheKeyFilter cacheKeyFilterWithBlock:^NSString * _Nullable(NSURL * _Nonnull url) { url = [[NSURL alloc] initWithScheme:url.scheme host:url.host path:url.path]; return [url absoluteString]; }];
    • ”`

    Declaration

    Objective-C

    @property (strong, nonatomic, nullable) id<SDWebImageCacheKeyFilter> cacheKeyFilter;

    Swift

    var cacheKeyFilter: SDWebImageCacheKeyFilterProtocol? { get set }
    • The cache serializer is used to convert the decoded image, the source downloaded data, to the actual data used for storing to the disk cache. If you return nil, means to generate the data from the image instance, see SDImageCache.
    • For example, if you are using WebP images and facing the slow decoding time issue when later retrieving from disk cache again. You can try to encode the decoded image to JPEG/PNG format to disk cache instead of source downloaded data.
    • - note: The image arg is nonnull, but when you also provide an image transformer and the image is transformed, the data arg may be nil, take attention to this case.
    • - note: This method is called from a global queue in order to not to block the main thread.
    • “` SDWebImageManager.sharedManager.cacheSerializer = [SDWebImageCacheSerializer cacheSerializerWithBlock:^NSData * _Nullable(UIImage * _Nonnull image, NSData * _Nullable data, NSURL * _Nullable imageURL) { SDImageFormat format = [NSData sd_imageFormatForImageData:data]; switch (format) { case SDImageFormatWebP: return image.images ? data : nil; default: return data; } }];
    • ”`
    • The default value is nil. Means we just store the source downloaded data to disk cache.

    Declaration

    Objective-C

    @property (strong, nonatomic, nullable) id<SDWebImageCacheSerializer> cacheSerializer;

    Swift

    var cacheSerializer: SDWebImageCacheSerializerProtocol? { get set }
  • The options processor is used, to have a global control for all the image request options and context option for current manager.

    Note

    If you use transformer, cacheKeyFilter or cacheSerializer property of manager, the input context option already apply those properties before passed. This options processor is a better replacement for those property in common usage. For example, you can control the global options, based on the URL or original context option like the below code.
    SDWebImageManager.sharedManager.optionsProcessor = [SDWebImageOptionsProcessor optionsProcessorWithBlock:^SDWebImageOptionsResult * _Nullable(NSURL * _Nullable url, SDWebImageOptions options, SDWebImageContext * _Nullable context) {
        // Only do animation on `SDAnimatedImageView`
        if (!context[SDWebImageContextAnimatedImageClass]) {
           options |= SDWebImageDecodeFirstFrameOnly;
        }
        // Do not force decode for png url
        if ([url.lastPathComponent isEqualToString:@"png"]) {
           options |= SDWebImageAvoidDecodeImage;
        }
        // Always use screen scale factor
        SDWebImageMutableContext *mutableContext = [NSDictionary dictionaryWithDictionary:context];
        mutableContext[SDWebImageContextImageScaleFactor] = @(UIScreen.mainScreen.scale);
        context = [mutableContext copy];
    
        return [[SDWebImageOptionsResult alloc] initWithOptions:options context:context];
    }];
    

    Declaration

    Objective-C

    @property (strong, nonatomic, nullable) id<SDWebImageOptionsProcessor> optionsProcessor;

    Swift

    var optionsProcessor: SDWebImageOptionsProcessorProtocol? { get set }
  • Check one or more operations running

    Declaration

    Objective-C

    @property (readonly, getter=isRunning, nonatomic) BOOL running;

    Swift

    var isRunning: Bool { get }
  • The default image cache when the manager which is created with no arguments. Such as shared manager or init. Defaults to nil. Means using SDImageCache.sharedImageCache

    Declaration

    Objective-C

    @property (nonatomic, nullable, class) id<SDImageCache> defaultImageCache;

    Swift

    class var defaultImageCache: SDImageCache? { get set }
  • The default image loader for manager which is created with no arguments. Such as shared manager or init. Defaults to nil. Means using SDWebImageDownloader.sharedDownloader

    Declaration

    Objective-C

    @property (nonatomic, nullable, class) id<SDImageLoader> defaultImageLoader;

    Swift

    class var defaultImageLoader: SDImageLoader? { get set }
  • Returns global shared manager instance.

    Declaration

    Objective-C

    @property (readonly, nonatomic, nonnull, class) SDWebImageManager *sharedManager;

    Swift

    class var shared: SDWebImageManager { get }
  • Allows to specify instance of cache and image loader used with image manager.

    Declaration

    Objective-C

    - (nonnull instancetype)initWithCache:(nonnull id<SDImageCache>)cache
                                   loader:(nonnull id<SDImageLoader>)loader;

    Swift

    init(cache: SDImageCache, loader: SDImageLoader)

    Return Value

    new instance of SDWebImageManager with specified cache and loader.

  • Downloads the image at the given URL if not present in cache or return the cached version otherwise.

    This parameter is required.

    This block has no return value and takes the requested UIImage as first parameter and the NSData representation as second parameter. In case of error the image parameter is nil and the third parameter may contain an NSError.

    The forth parameter is an SDImageCacheType enum indicating if the image was retrieved from the local cache or from the memory cache or from the network.

    The fifth parameter is set to NO when the SDWebImageProgressiveLoad option is used and the image is downloading. This block is thus called repeatedly with a partial image. When image is fully downloaded, the block is called a last time with the full image and the last parameter set to YES.

    The last parameter is the original image URL

    Declaration

    Objective-C

    - (nullable SDWebImageCombinedOperation *)
        loadImageWithURL:(nullable NSURL *)url
                 options:(SDWebImageOptions)options
                progress:(nullable SDImageLoaderProgressBlock)progressBlock
               completed:(nonnull SDInternalCompletionBlock)completedBlock;

    Swift

    func loadImage(with url: URL?, options: SDWebImageOptions = [], progress progressBlock: SDImageLoaderProgressBlock?, completed completedBlock: @escaping SDInternalCompletionBlock) -> SDWebImageCombinedOperation?

    Parameters

    url

    The URL to the image

    options

    A mask to specify options to use for this request

    progressBlock

    A block called while image is downloading - note: the progress block is executed on a background queue

    completedBlock

    A block called when operation has been completed.

    Return Value

    Returns an instance of SDWebImageCombinedOperation, which you can cancel the loading process.

  • Downloads the image at the given URL if not present in cache or return the cached version otherwise.

    Declaration

    Objective-C

    - (nullable SDWebImageCombinedOperation *)
        loadImageWithURL:(nullable NSURL *)url
                 options:(SDWebImageOptions)options
                 context:(nullable SDWebImageContext *)context
                progress:(nullable SDImageLoaderProgressBlock)progressBlock
               completed:(nonnull SDInternalCompletionBlock)completedBlock;

    Swift

    func loadImage(with url: URL?, options: SDWebImageOptions = [], context: [SDWebImageContextOption : Any]?, progress progressBlock: SDImageLoaderProgressBlock?, completed completedBlock: @escaping SDInternalCompletionBlock) -> SDWebImageCombinedOperation?

    Parameters

    url

    The URL to the image

    options

    A mask to specify options to use for this request

    context

    A context contains different options to perform specify changes or processes, see SDWebImageContextOption. This hold the extra objects which options enum can not hold.

    progressBlock

    A block called while image is downloading - note: the progress block is executed on a background queue

    completedBlock

    A block called when operation has been completed.

    Return Value

    Returns an instance of SDWebImageCombinedOperation, which you can cancel the loading process.

  • Cancel all current operations

    Declaration

    Objective-C

    - (void)cancelAll;

    Swift

    func cancelAll()
  • Remove the specify URL from failed black list.

    Declaration

    Objective-C

    - (void)removeFailedURL:(nonnull NSURL *)url;

    Swift

    func removeFailedURL(_ url: URL)

    Parameters

    url

    The failed URL.

  • Remove all the URL from failed black list.

    Declaration

    Objective-C

    - (void)removeAllFailedURLs;

    Swift

    func removeAllFailedURLs()
  • Return the cache key for a given URL, does not considerate transformer or thumbnail.

    Note

    This method does not have context option, only use the url and manager level cacheKeyFilter to generate the cache key.

    Declaration

    Objective-C

    - (nullable NSString *)cacheKeyForURL:(nullable NSURL *)url;

    Swift

    func cacheKey(for url: URL?) -> String?
  • Return the cache key for a given URL and context option.

    Note

    The context option like .thumbnailPixelSize and .imageTransformer will effect the generated cache key, using this if you have those context associated.

    Declaration

    Objective-C

    - (nullable NSString *)cacheKeyForURL:(nullable NSURL *)url
                                  context:(nullable SDWebImageContext *)context;

    Swift

    func cacheKey(for url: URL?, context: [SDWebImageContextOption : Any]?) -> String?