240 lines
10 KiB
Objective-C
240 lines
10 KiB
Objective-C
/*
|
|
* 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 "SDWebImageDefine.h"
|
|
#import "SDWebImageOperation.h"
|
|
#import "SDWebImageDownloaderConfig.h"
|
|
|
|
typedef NS_OPTIONS(NSUInteger, SDWebImageDownloaderOptions) {
|
|
/**
|
|
* Put the download in the low queue priority and task priority.
|
|
*/
|
|
SDWebImageDownloaderLowPriority = 1 << 0,
|
|
|
|
/**
|
|
* This flag enables progressive download, the image is displayed progressively during download as a browser would do.
|
|
*/
|
|
SDWebImageDownloaderProgressiveDownload = 1 << 1,
|
|
|
|
/**
|
|
* By default, request prevent the use of NSURLCache. With this flag, NSURLCache
|
|
* is used with default policies.
|
|
*/
|
|
SDWebImageDownloaderUseNSURLCache = 1 << 2,
|
|
|
|
/**
|
|
* Call completion block with nil image/imageData if the image was read from NSURLCache
|
|
* (to be combined with `SDWebImageDownloaderUseNSURLCache`).
|
|
*/
|
|
SDWebImageDownloaderIgnoreCachedResponse = 1 << 3,
|
|
|
|
/**
|
|
* In iOS 4+, continue the download of the image if the app goes to background. This is achieved by asking the system for
|
|
* extra time in background to let the request finish. If the background task expires the operation will be cancelled.
|
|
*/
|
|
SDWebImageDownloaderContinueInBackground = 1 << 4,
|
|
|
|
/**
|
|
* Handles cookies stored in NSHTTPCookieStore by setting
|
|
* NSMutableURLRequest.HTTPShouldHandleCookies = YES;
|
|
*/
|
|
SDWebImageDownloaderHandleCookies = 1 << 5,
|
|
|
|
/**
|
|
* Enable to allow untrusted SSL certificates.
|
|
* Useful for testing purposes. Use with caution in production.
|
|
*/
|
|
SDWebImageDownloaderAllowInvalidSSLCertificates = 1 << 6,
|
|
|
|
/**
|
|
* Put the download in the high queue priority and task priority.
|
|
*/
|
|
SDWebImageDownloaderHighPriority = 1 << 7,
|
|
|
|
/**
|
|
* Scale down the image
|
|
*/
|
|
SDWebImageDownloaderScaleDownLargeImages = 1 << 8,
|
|
|
|
/**
|
|
* By default, we decode the animated image. This flag can force decode the first frame only and produece the static image.
|
|
*/
|
|
SDWebImageDownloaderDecodeFirstFrameOnly = 1 << 9,
|
|
|
|
/**
|
|
* By default, for `SDAnimatedImage`, we decode the animated image frame during rendering to reduce memory usage. This flag actually trigger `preloadAllAnimatedImageFrames = YES` after image load from network
|
|
*/
|
|
SDWebImageDownloaderPreloadAllFrames = 1 << 10
|
|
};
|
|
|
|
FOUNDATION_EXPORT NSString * _Nonnull const SDWebImageDownloadStartNotification;
|
|
FOUNDATION_EXPORT NSString * _Nonnull const SDWebImageDownloadStopNotification;
|
|
|
|
typedef void(^SDWebImageDownloaderProgressBlock)(NSInteger receivedSize, NSInteger expectedSize, NSURL * _Nullable targetURL);
|
|
|
|
typedef void(^SDWebImageDownloaderCompletedBlock)(UIImage * _Nullable image, NSData * _Nullable data, NSError * _Nullable error, BOOL finished);
|
|
|
|
typedef NSDictionary<NSString *, NSString *> SDHTTPHeadersDictionary;
|
|
typedef NSMutableDictionary<NSString *, NSString *> SDHTTPHeadersMutableDictionary;
|
|
|
|
typedef SDHTTPHeadersDictionary * _Nullable (^SDWebImageDownloaderHeadersFilterBlock)(NSURL * _Nullable url, SDHTTPHeadersDictionary * _Nullable headers);
|
|
|
|
/**
|
|
* A token associated with each download. Can be used to cancel a download
|
|
*/
|
|
@interface SDWebImageDownloadToken : NSObject <SDWebImageOperation>
|
|
|
|
/**
|
|
The download's URL. This should be readonly and you should not modify
|
|
*/
|
|
@property (nonatomic, strong, nullable) NSURL *url;
|
|
/**
|
|
The cancel token taken from `addHandlersForProgress:completed`. This should be readonly and you should not modify
|
|
@note use `-[SDWebImageDownloadToken cancel]` to cancel the token
|
|
*/
|
|
@property (nonatomic, strong, nullable) id downloadOperationCancelToken;
|
|
|
|
@end
|
|
|
|
|
|
/**
|
|
* Asynchronous downloader dedicated and optimized for image loading.
|
|
*/
|
|
@interface SDWebImageDownloader : NSObject
|
|
|
|
/**
|
|
Downloader Config object - storing all kind of settings
|
|
*/
|
|
@property (nonatomic, copy, readonly, nonnull) SDWebImageDownloaderConfig *config;
|
|
|
|
/**
|
|
* Set filter to pick headers for downloading image HTTP request.
|
|
*
|
|
* This block will be invoked for each downloading image request, returned
|
|
* NSDictionary will be used as headers in corresponding HTTP request.
|
|
*/
|
|
@property (nonatomic, copy, nullable) SDWebImageDownloaderHeadersFilterBlock headersFilter;
|
|
|
|
/**
|
|
* The configuration in use by the internal NSURLSession. If you want to provide a custom sessionConfiguration, use `SDWebImageDownloaderConfig.sessionConfiguration` and create a new downloader instance.
|
|
@note This is immutable according to NSURLSession's documentation. Mutating this object directly has no effect.
|
|
*/
|
|
@property (nonatomic, readonly, nonnull) NSURLSessionConfiguration *sessionConfiguration;
|
|
|
|
/**
|
|
* Gets/Sets the download queue suspension state.
|
|
*/
|
|
@property (nonatomic, assign, getter=isSuspended) BOOL suspended;
|
|
|
|
/**
|
|
* Shows the current amount of downloads that still need to be downloaded
|
|
*/
|
|
@property (nonatomic, assign, readonly) NSUInteger currentDownloadCount;
|
|
|
|
/**
|
|
* Returns the global shared downloader instance. Which use the `SDWebImageDownloaderConfig.defaultDownloaderConfiguration` config.
|
|
*/
|
|
@property (nonatomic, class, readonly, nonnull) SDWebImageDownloader *sharedDownloader;
|
|
|
|
/**
|
|
Creates an instance of a downloader with specified downloader config.
|
|
You can specify session configuration, timeout or operation class through downloader config.
|
|
|
|
@param config The downloader config. If you specify nil, the `defaultDownloaderConfig` will be used.
|
|
@return new instance of downloader class
|
|
*/
|
|
- (nonnull instancetype)initWithConfig:(nullable SDWebImageDownloaderConfig *)config NS_DESIGNATED_INITIALIZER;
|
|
|
|
/**
|
|
* Set a value for a HTTP header to be appended to each download HTTP request.
|
|
*
|
|
* @param value The value for the header field. Use `nil` value to remove the header.
|
|
* @param field The name of the header field to set.
|
|
*/
|
|
- (void)setValue:(nullable NSString *)value forHTTPHeaderField:(nullable NSString *)field;
|
|
|
|
/**
|
|
* Returns the value of the specified HTTP header field.
|
|
*
|
|
* @return The value associated with the header field field, or `nil` if there is no corresponding header field.
|
|
*/
|
|
- (nullable NSString *)valueForHTTPHeaderField:(nullable NSString *)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
|
|
*
|
|
* @param url The URL to the image to download
|
|
* @param options The options to be used for this download
|
|
* @param progressBlock A block called repeatedly while the image is downloading
|
|
* @note the progress block is executed on a background queue
|
|
* @param 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 A token (SDWebImageDownloadToken) that can be passed to -cancel: to cancel this operation
|
|
*/
|
|
- (nullable SDWebImageDownloadToken *)downloadImageWithURL:(nullable NSURL *)url
|
|
options:(SDWebImageDownloaderOptions)options
|
|
progress:(nullable SDWebImageDownloaderProgressBlock)progressBlock
|
|
completed:(nullable SDWebImageDownloaderCompletedBlock)completedBlock;
|
|
|
|
/**
|
|
* 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
|
|
*
|
|
* @param url The URL to the image to download
|
|
* @param options The options to be used for this download
|
|
* @param 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.
|
|
* @param progressBlock A block called repeatedly while the image is downloading
|
|
* @note the progress block is executed on a background queue
|
|
* @param completedBlock A block called once the download is completed.
|
|
*
|
|
* @return A token (SDWebImageDownloadToken) that can be passed to -cancel: to cancel this operation
|
|
*/
|
|
- (nullable SDWebImageDownloadToken *)downloadImageWithURL:(nullable NSURL *)url
|
|
options:(SDWebImageDownloaderOptions)options
|
|
context:(nullable SDWebImageContext *)context
|
|
progress:(nullable SDWebImageDownloaderProgressBlock)progressBlock
|
|
completed:(nullable SDWebImageDownloaderCompletedBlock)completedBlock;
|
|
|
|
/**
|
|
* Cancels a download that was previously queued using -downloadImageWithURL:options:progress:completed:
|
|
*
|
|
* @param token The token received from -downloadImageWithURL:options:progress:completed: that should be canceled.
|
|
*/
|
|
- (void)cancel:(nullable SDWebImageDownloadToken *)token;
|
|
|
|
/**
|
|
* Cancels all download operations in the queue
|
|
*/
|
|
- (void)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
|
|
* @param cancelPendingOperations Whether or not to cancel pending operations.
|
|
* @note Calling this method on the shared downloader has no effect.
|
|
*/
|
|
- (void)invalidateSessionAndCancel:(BOOL)cancelPendingOperations;
|
|
|
|
@end
|