SDWebImageDownloader

@interface SDWebImageDownloader : NSObject

Asynchronous downloader dedicated and optimized for image loading.

  • Downloader Config object - storing all kind of settings. Most config properties support dynamic changes during download, except something like sessionConfiguration, see SDWebImageDownloaderConfig for more detail.

    Declaration

    Objective-C

    @property (readonly, copy, nonatomic, nonnull) SDWebImageDownloaderConfig *config;

    Swift

    @NSCopying var config: SDWebImageDownloaderConfig { get }
  • Set the request modifier to modify the original download request before image load. This request modifier method will be called for each downloading image request. Return the original request means no modification. Return nil will cancel the download request. Defaults to nil, means does not modify the original download request.

    Note

    If you want to modify single request, consider using SDWebImageContextDownloadRequestModifier context option.

    Declaration

    Objective-C

    @property (strong, nonatomic, nullable) id<SDWebImageDownloaderRequestModifier> requestModifier;

    Swift

    var requestModifier: SDWebImageDownloaderRequestModifierProtocol? { get set }
  • Set the response modifier to modify the original download response during image load. This request modifier method will be called for each downloading image response. Return the original response means no modification. Return nil will mark current download as cancelled. Defaults to nil, means does not modify the original download response.

    Note

    If you want to modify single response, consider using SDWebImageContextDownloadResponseModifier context option.

    Declaration

    Objective-C

    @property (strong, nonatomic, nullable) id<SDWebImageDownloaderResponseModifier> responseModifier;

    Swift

    var responseModifier: SDWebImageDownloaderResponseModifierProtocol? { get set }
  • Set the decryptor to decrypt the original download data before image decoding. This can be used for encrypted image data, like Base64. This decryptor method will be called for each downloading image data. Return the original data means no modification. Return nil will mark this download failed. Defaults to nil, means does not modify the original download data.

    Note

    When using decryptor, progressive decoding will be disabled, to avoid data corrupt issue.

    Note

    If you want to decrypt single download data, consider using SDWebImageContextDownloadDecryptor context option.

    Declaration

    Objective-C

    @property (strong, nonatomic, nullable) id<SDWebImageDownloaderDecryptor> decryptor;

    Swift

    var decryptor: SDWebImageDownloaderDecryptorProtocol? { get set }
  • Note

    This is immutable according to NSURLSession’s documentation. Mutating this object directly has no effect.

    Declaration

    Objective-C

    @property (readonly, nonatomic, nonnull) NSURLSessionConfiguration *sessionConfiguration;

    Swift

    var sessionConfiguration: URLSessionConfiguration { get }
  • Gets/Sets the download queue suspension state.

    Declaration

    Objective-C

    @property (getter=isSuspended, nonatomic) BOOL suspended;

    Swift

    var isSuspended: Bool { get set }
  • Shows the current amount of downloads that still need to be downloaded

    Declaration

    Objective-C

    @property (readonly, nonatomic) NSUInteger currentDownloadCount;

    Swift

    var currentDownloadCount: UInt { get }
  • Returns the global shared downloader instance. Which use the SDWebImageDownloaderConfig.defaultDownloaderConfig config.

    Declaration

    Objective-C

    @property (readonly, nonatomic, nonnull, class) SDWebImageDownloader *sharedDownloader;

    Swift

    class var shared: SDWebImageDownloader { get }
  • Creates an instance of a downloader with specified downloader config. You can specify session configuration, timeout or operation class through downloader config.

    Declaration

    Objective-C

    - (nonnull instancetype)initWithConfig:
        (nullable SDWebImageDownloaderConfig *)config;

    Swift

    init(config: SDWebImageDownloaderConfig?)

    Parameters

    config

    The downloader config. If you specify nil, the defaultDownloaderConfig will be used.

    Return Value

    new instance of downloader class

  • Set a value for a HTTP header to be appended to each download HTTP request.

    Declaration

    Objective-C

    - (void)setValue:(nullable NSString *)value
        forHTTPHeaderField:(nullable NSString *)field;

    Swift

    func setValue(_ value: String?, forHTTPHeaderField field: String?)

    Parameters

    value

    The value for the header field. Use nil value to remove the header field.

    field

    The name of the header field to set.

  • Returns the value of the specified HTTP header field.

    Declaration

    Objective-C

    - (nullable NSString *)valueForHTTPHeaderField:(nullable NSString *)field;

    Swift

    func value(forHTTPHeaderField field: String?) -> String?

    Return Value

    The value associated with the header field field, or nil if there is no corresponding header field.

  • Creates a SDWebImageDownloader async downloader instance with a given URL

    The delegate will be informed when the image is finish downloaded or an error has happen.

    See

    SDWebImageDownloaderDelegate

    Declaration

    Objective-C

    - (nullable SDWebImageDownloadToken *)
        downloadImageWithURL:(nullable NSURL *)url
                   completed:
                       (nullable SDWebImageDownloaderCompletedBlock)completedBlock;

    Swift

    func downloadImage(with url: URL?, completed completedBlock: SDWebImageDownloaderCompletedBlock? = nil) -> SDWebImageDownloadToken?

    Parameters

    url

    The URL to the image to download

    completedBlock

    A block called once the download is completed. If the download succeeded, the image parameter is set, in case of error, error parameter is set with the error. The last parameter is always YES if SDWebImageDownloaderProgressiveDownload isn’t use. With the SDWebImageDownloaderProgressiveDownload option, this block is called repeatedly with the partial image object and the finished argument set to NO before to be called a last time with the full image and finished argument set to YES. In case of error, the finished argument is always YES.

    Return Value

    A token (SDWebImageDownloadToken) that can be used to cancel this operation

  • Creates a SDWebImageDownloader async downloader instance with a given URL

    The delegate will be informed when the image is finish downloaded or an error has happen.

    See

    SDWebImageDownloaderDelegate

    Declaration

    Objective-C

    - (nullable SDWebImageDownloadToken *)
        downloadImageWithURL:(nullable NSURL *)url
                     options:(SDWebImageDownloaderOptions)options
                    progress:
                        (nullable SDWebImageDownloaderProgressBlock)progressBlock
                   completed:
                       (nullable SDWebImageDownloaderCompletedBlock)completedBlock;

    Swift

    func downloadImage(with url: URL?, options: SDWebImageDownloaderOptions = [], progress progressBlock: SDWebImageDownloaderProgressBlock?, completed completedBlock: SDWebImageDownloaderCompletedBlock? = nil) -> SDWebImageDownloadToken?

    Parameters

    url

    The URL to the image to download

    options

    The options to be used for this download

    progressBlock

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

    completedBlock

    A block called once the download is completed. If the download succeeded, the image parameter is set, in case of error, error parameter is set with the error. The last parameter is always YES if SDWebImageDownloaderProgressiveLoad isn’t use. With the SDWebImageDownloaderProgressiveLoad option, this block is called repeatedly with the partial image object and the finished argument set to NO before to be called a last time with the full image and finished argument set to YES. In case of error, the finished argument is always YES.

    Return Value

    A token (SDWebImageDownloadToken) that can be used to cancel this operation

  • Creates a SDWebImageDownloader async downloader instance with a given URL

    The delegate will be informed when the image is finish downloaded or an error has happen.

    See

    SDWebImageDownloaderDelegate

    Declaration

    Objective-C

    - (nullable SDWebImageDownloadToken *)
        downloadImageWithURL:(nullable NSURL *)url
                     options:(SDWebImageDownloaderOptions)options
                     context:(nullable SDWebImageContext *)context
                    progress:
                        (nullable SDWebImageDownloaderProgressBlock)progressBlock
                   completed:
                       (nullable SDWebImageDownloaderCompletedBlock)completedBlock;

    Swift

    func downloadImage(with url: URL?, options: SDWebImageDownloaderOptions = [], context: [SDWebImageContextOption : Any]?, progress progressBlock: SDWebImageDownloaderProgressBlock?, completed completedBlock: SDWebImageDownloaderCompletedBlock? = nil) -> SDWebImageDownloadToken?

    Parameters

    url

    The URL to the image to download

    options

    The options to be used for this download

    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 repeatedly while the image is downloading - note: the progress block is executed on a background queue

    completedBlock

    A block called once the download is completed.

    Return Value

    A token (SDWebImageDownloadToken) that can be used to cancel this operation

  • Cancels all download operations in the queue

    Declaration

    Objective-C

    - (void)cancelAllDownloads;

    Swift

    func cancelAllDownloads()
  • Invalidates the managed session, optionally canceling pending operations.

    Note

    If you use custom downloader instead of the shared downloader, you need call this method when you do not use it to avoid memory leak

    Note

    Calling this method on the shared downloader has no effect.

    Declaration

    Objective-C

    - (void)invalidateSessionAndCancel:(BOOL)cancelPendingOperations;

    Swift

    func invalidateSessionAndCancel(_ cancelPendingOperations: Bool)

    Parameters

    cancelPendingOperations

    Whether or not to cancel pending operations.