EMSDWebImageDownloader.h 6.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174
  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 "EMSDWebImageCompat.h"
  10. #import "EMSDWebImageOperation.h"
  11. typedef NS_OPTIONS(NSUInteger, EMSDWebImageDownloaderOptions) {
  12. EMSDWebImageDownloaderLowPriority = 1 << 0,
  13. EMSDWebImageDownloaderProgressiveDownload = 1 << 1,
  14. /**
  15. * By default, request prevent the of NSURLCache. With this flag, NSURLCache
  16. * is used with default policies.
  17. */
  18. EMSDWebImageDownloaderUseNSURLCache = 1 << 2,
  19. /**
  20. * Call completion block with nil image/imageData if the image was read from NSURLCache
  21. * (to be combined with `EMSDWebImageDownloaderUseNSURLCache`).
  22. */
  23. EMSDWebImageDownloaderIgnoreCachedResponse = 1 << 3,
  24. /**
  25. * In iOS 4+, continue the download of the image if the app goes to background. This is achieved by asking the system for
  26. * extra time in background to let the request finish. If the background task expires the operation will be cancelled.
  27. */
  28. EMSDWebImageDownloaderContinueInBackground = 1 << 4,
  29. /**
  30. * Handles cookies stored in NSHTTPCookieStore by setting
  31. * NSMutableURLRequest.HTTPShouldHandleCookies = YES;
  32. */
  33. EMSDWebImageDownloaderHandleCookies = 1 << 5,
  34. /**
  35. * Enable to allow untrusted SSL ceriticates.
  36. * Useful for testing purposes. Use with caution in production.
  37. */
  38. EMSDWebImageDownloaderAllowInvalidSSLCertificates = 1 << 6,
  39. /**
  40. * Put the image in the high priority queue.
  41. */
  42. EMSDWebImageDownloaderHighPriority = 1 << 7,
  43. };
  44. typedef NS_ENUM(NSInteger, EMSDWebImageDownloaderExecutionOrder) {
  45. /**
  46. * Default value. All download operations will execute in queue style (first-in-first-out).
  47. */
  48. EMSDWebImageDownloaderFIFOExecutionOrder,
  49. /**
  50. * All download operations will execute in stack style (last-in-first-out).
  51. */
  52. EMSDWebImageDownloaderLIFOExecutionOrder
  53. };
  54. extern NSString *const EMSDWebImageDownloadStartNotification;
  55. extern NSString *const EMSDWebImageDownloadStopNotification;
  56. typedef void(^EMSDWebImageDownloaderProgressBlock)(NSInteger receivedSize, NSInteger expectedSize);
  57. typedef void(^EMSDWebImageDownloaderCompletedBlock)(UIImage *image, NSData *data, NSError *error, BOOL finished);
  58. typedef NSDictionary *(^EMSDWebImageDownloaderHeadersFilterBlock)(NSURL *url, NSDictionary *headers);
  59. /**
  60. * Asynchronous downloader dedicated and optimized for image loading.
  61. */
  62. @interface EMSDWebImageDownloader : NSObject
  63. @property (assign, nonatomic) NSInteger maxConcurrentDownloads;
  64. /**
  65. * Shows the current amount of downloads that still need to be downloaded
  66. */
  67. @property (readonly, nonatomic) NSUInteger currentDownloadCount;
  68. /**
  69. * The timeout value (in seconds) for the download operation. Default: 15.0.
  70. */
  71. @property (assign, nonatomic) NSTimeInterval downloadTimeout;
  72. /**
  73. * Changes download operations execution order. Default value is `EMSDWebImageDownloaderFIFOExecutionOrder`.
  74. */
  75. @property (assign, nonatomic) EMSDWebImageDownloaderExecutionOrder executionOrder;
  76. /**
  77. * Singleton method, returns the shared instance
  78. *
  79. * @return global shared instance of downloader class
  80. */
  81. + (EMSDWebImageDownloader *)sharedDownloader;
  82. /**
  83. * Set username
  84. */
  85. @property (strong, nonatomic) NSString *username;
  86. /**
  87. * Set password
  88. */
  89. @property (strong, nonatomic) NSString *password;
  90. /**
  91. * Set filter to pick headers for downloading image HTTP request.
  92. *
  93. * This block will be invoked for each downloading image request, returned
  94. * NSDictionary will be used as headers in corresponding HTTP request.
  95. */
  96. @property (nonatomic, copy) EMSDWebImageDownloaderHeadersFilterBlock headersFilter;
  97. /**
  98. * Set a value for a HTTP header to be appended to each download HTTP request.
  99. *
  100. * @param value The value for the header field. Use `nil` value to remove the header.
  101. * @param field The name of the header field to set.
  102. */
  103. - (void)setValue:(NSString *)value forHTTPHeaderField:(NSString *)field;
  104. /**
  105. * Returns the value of the specified HTTP header field.
  106. *
  107. * @return The value associated with the header field field, or `nil` if there is no corresponding header field.
  108. */
  109. - (NSString *)valueForHTTPHeaderField:(NSString *)field;
  110. /**
  111. * Creates a EMSDWebImageDownloader async downloader instance with a given URL
  112. *
  113. * The delegate will be informed when the image is finish downloaded or an error has happen.
  114. *
  115. * @see EMSDWebImageDownloaderDelegate
  116. *
  117. * @param url The URL to the image to download
  118. * @param options The options to be used for this download
  119. * @param progressBlock A block called repeatedly while the image is downloading
  120. * @param completedBlock A block called once the download is completed.
  121. * If the download succeeded, the image parameter is set, in case of error,
  122. * error parameter is set with the error. The last parameter is always YES
  123. * if EMSDWebImageDownloaderProgressiveDownload isn't use. With the
  124. * EMSDWebImageDownloaderProgressiveDownload option, this block is called
  125. * repeatedly with the partial image object and the finished argument set to NO
  126. * before to be called a last time with the full image and finished argument
  127. * set to YES. In case of error, the finished argument is always YES.
  128. *
  129. * @return A cancellable EMSDWebImageOperation
  130. */
  131. - (id <EMSDWebImageOperation>)downloadImageWithURL:(NSURL *)url
  132. options:(EMSDWebImageDownloaderOptions)options
  133. progress:(EMSDWebImageDownloaderProgressBlock)progressBlock
  134. completed:(EMSDWebImageDownloaderCompletedBlock)completedBlock;
  135. /**
  136. * Sets the download queue suspension state
  137. */
  138. - (void)setSuspended:(BOOL)suspended;
  139. @end