/*
*?This?file?is?part?of?the?SDWebImage?package.
*?(c)?Olivier?Poitrey??*
*?For?the?full?copyright?and?license?information,?please?view?the?LICENSE
*?file?that?was?distributed?with?this?source?code.
*/
#import?"SDWebImageCompat.h"
#import?"SDWebImageOperation.h"
#import?"SDWebImageDownloader.h"
#import?"SDImageCache.h"
typedef?NS_OPTIONS(NSUInteger,?SDWebImageOptions)?{
/**
*?By?default,?when?a?URL?fail?to?be?downloaded,?the?URL?is?blacklisted?so?the?library?won't?keep?trying.
*?This?flag?disable?this?blacklisting.
*/
/**
*
默認(rèn)情況下,如果一個url在下載的時候失敗了,那么這個url會被加入黑名單并且library不會嘗試再次下載,這個flag會阻止library把
失敗的url加入黑名單(簡單來說如果選擇了這個flag,那么即使某個url下載失敗了,sdwebimage還是會嘗試再次下載他.)
*/
SDWebImageRetryFailed?=?1?<<?0,
/**
*?By?default,?image?downloads?are?started?during?UI?interactions,?this?flags?disable?this?feature,
*?leading?to?delayed?download?on?UIScrollView?deceleration?for?instance.
*/
/**
*默認(rèn)情況下,圖片會在交互發(fā)生的時候下載(例如你滑動tableview的時候),這個flag會禁止這個特性,導(dǎo)致的結(jié)果就是在scrollview減速的時候
*才會開始下載(也就是你滑動的時候scrollview不下載,你手從屏幕上移走,scrollview開始減速的時候才會開始下載圖片)
*/
SDWebImageLowPriority?=?1?<<?1,
/**
*?This?flag?disables?on-disk?caching
*/
/*
*這個flag禁止磁盤緩存,只有內(nèi)存緩存
*/
SDWebImageCacheMemoryOnly?=?1?<<?2,
/**
*?This?flag?enables?progressive?download,?the?image?is?displayed?progressively?during?download?as?a?browser?would?do.
*?By?default,?the?image?is?only?displayed?once?completely?downloaded.
*/
/*
*這個flag會在圖片下載的時候就顯示(就像你用瀏覽器瀏覽網(wǎng)頁的時候那種圖片下載,一截一截的顯示(待確認(rèn)))
*
*/
SDWebImageProgressiveDownload?=?1?<<?3,
/**
*?Even?if?the?image?is?cached,?respect?the?HTTP?response?cache?control,?and?refresh?the?image?from?remote?location?if?needed.
*?The?disk?caching?will?be?handled?by?NSURLCache?instead?of?SDWebImage?leading?to?slight?performance?degradation.
*?This?option?helps?deal?with?images?changing?behind?the?same?request?URL,?e.g.?Facebook?graph?api?profile?pics.
*?If?a?cached?image?is?refreshed,?the?completion?block?is?called?once?with?the?cached?image?and?again?with?the?final?image.
*
*?Use?this?flag?only?if?you?can't?make?your?URLs?static?with?embeded?cache?busting?parameter.
*/
/*
*這個選項的意思看的不是很懂,大意是即使一個圖片緩存了,還是會重新請求.并且緩存?zhèn)嚷砸罁?jù)NSURLCache而不是SDWebImage.
*
*/
SDWebImageRefreshCached?=?1?<<?4,
/**
*?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.
*/
/*
*啟動后臺下載,加入你進入一個頁面,有一張圖片正在下載這時候你讓app進入后臺,圖片還是會繼續(xù)下載(這個估計要開backgroundfetch才有用)
*/
SDWebImageContinueInBackground?=?1?<<?5,
/**
*?Handles?cookies?stored?in?NSHTTPCookieStore?by?setting
*?NSMutableURLRequest.HTTPShouldHandleCookies?=?YES;
*/
/*
*可以控制存在NSHTTPCookieStore的cookies.(我沒用過,等用過的人過來解釋一下)
*/
SDWebImageHandleCookies?=?1?<<?6,
/**
*?Enable?to?allow?untrusted?SSL?ceriticates.
*?Useful?for?testing?purposes.?Use?with?caution?in?production.
*/
/*
*允許不安全的SSL證書,在正式環(huán)境中慎用
*/
SDWebImageAllowInvalidSSLCertificates?=?1?<<?7,
/**
*?By?default,?image?are?loaded?in?the?order?they?were?queued.?This?flag?move?them?to
*?the?front?of?the?queue?and?is?loaded?immediately?instead?of?waiting?for?the?current?queue?to?be?loaded?(which
*?could?take?a?while).
*/
/*
*默認(rèn)情況下,image在裝載的時候是按照他們在隊列中的順序裝載的(就是先進先出).這個flag會把他們移動到隊列的前端,并且立刻裝載
*而不是等到當(dāng)前隊列裝載的時候再裝載.
*/
SDWebImageHighPriority?=?1?<<?8,
/**
*?By?default,?placeholder?images?are?loaded?while?the?image?is?loading.?This?flag?will?delay?the?loading
*?of?the?placeholder?image?until?after?the?image?has?finished?loading.
*/
/*
*默認(rèn)情況下,占位圖會在圖片下載的時候顯示.這個flag開啟會延遲占位圖顯示的時間,等到圖片下載完成之后才會顯示占位圖.(等圖片顯示完了我干嘛還顯示占位圖?或許是我理解錯了?)
*/
SDWebImageDelayPlaceholder?=?1?<<?9,
/**
*?We?usually?don't?call?transformDownloadedImage?delegate?method?on?animated?images,
*?as?most?transformation?code?would?mangle?it.
*?Use?this?flag?to?transform?them?anyway.
*/
/*
*
是否transform圖片(沒用過,還要再看,但是據(jù)我估計,是否是圖片有可能方向不對需要調(diào)整方向,例如采用iPhone拍攝的照片如果不糾正方向,
那么圖片是向左旋轉(zhuǎn)90度的.可能很多人不知道iPhone的攝像頭并不是豎直的,而是向左偏了90度.具體請google.)
*/
SDWebImageTransformAnimatedImage?=?1?<<?10,
};
typedef?void(^SDWebImageCompletionBlock)(UIImage?*image,?NSError?*error,?SDImageCacheType?cacheType,?NSURL?*imageURL);
typedef?void(^SDWebImageCompletionWithFinishedBlock)(UIImage?*image,?NSError?*error,?SDImageCacheType?cacheType,?BOOL?finished,?NSURL?*imageURL);
typedef?NSString?*(^SDWebImageCacheKeyFilterBlock)(NSURL?*url);
@class?SDWebImageManager;
@protocol?SDWebImageManagerDelegate?@optional
/**
*?Controls?which?image?should?be?downloaded?when?the?image?is?not?found?in?the?cache.
*
*?@param?imageManager?The?current?`SDWebImageManager`
*?@param?imageURL?????The?url?of?the?image?to?be?downloaded
*
*?@return?Return?NO?to?prevent?the?downloading?of?the?image?on?cache?misses.?If?not?implemented,?YES?is?implied.
*/
/*
*主要作用是當(dāng)緩存里沒有發(fā)現(xiàn)某張圖片的緩存時,是否選擇下載這張圖片(默認(rèn)是yes),可以選擇no,那么sdwebimage在緩存中沒有找到這張圖片的時候不會選擇下載
*/
-?(BOOL)imageManager:(SDWebImageManager?*)imageManager?shouldDownloadImageForURL:(NSURL?*)imageURL;
/**
*?Allows?to?transform?the?image?immediately?after?it?has?been?downloaded?and?just?before?to?cache?it?on?disk?and?memory.
*?NOTE:?This?method?is?called?from?a?global?queue?in?order?to?not?to?block?the?main?thread.
*
*?@param?imageManager?The?current?`SDWebImageManager`
*?@param?image????????The?image?to?transform
*?@param?imageURL?????The?url?of?the?image?to?transform
*
*?@return?The?transformed?image?object.
*/
/**
*在圖片下載完成并且還沒有加入磁盤緩存或者內(nèi)存緩存的時候就transform這個圖片.這個方法是在異步線程執(zhí)行的,防治阻塞主線程.
*至于為什么在異步執(zhí)行很簡單,對一張圖片糾正方向(也就是transform)是很耗資源的,一張2M大小的圖片糾正方向你可以用instrument測試一下耗時.
*很恐怖
*/
-?(UIImage?*)imageManager:(SDWebImageManager?*)imageManager?transformDownloadedImage:(UIImage?*)image?withURL:(NSURL?*)imageURL;
@end
/**
*?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:
*
*?@code
SDWebImageManager?*manager?=?[SDWebImageManager?sharedManager];
[manager?downloadImageWithURL:imageURL
options:0
progress:nil
completed:^(UIImage?*image,?NSError?*error,?SDImageCacheType?cacheType,?BOOL?finished,?NSURL?*imageURL)?{
if?(image)?{
//?do?something?with?image
}
}];
*?@endcode
*/
/*
*
這一段是闡述SDWebImageManager是干嘛的.其實UIImageView+WebCache這個category背后執(zhí)行操作的就是這個
SDWebImageManager.他會綁定一個下載器也就是SDWebImageDownloader和一個緩存SDImageCache.后面的大
意應(yīng)該是講你可以直接使用一個其他上下文環(huán)境的SDWebImageManager,而不是僅僅限于一個UIView.
*/
@interface?SDWebImageManager?:?NSObject
@property?(weak,?nonatomic)?id??delegate;
/**
*如同上文所說,一個SDWebImageManager會綁定一個imageCache和一個下載器.
*/
@property?(strong,?nonatomic,?readonly)?SDImageCache?*imageCache;
@property?(strong,?nonatomic,?readonly)?SDWebImageDownloader?*imageDownloader;
/**
*?The?cache?filter?is?a?block?used?each?time?SDWebImageManager?need?to?convert?an?URL?into?a?cache?key.?This?can
*?be?used?to?remove?dynamic?part?of?an?image?URL.
*
*?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:
*
*?@code
[[SDWebImageManager?sharedManager]?setCacheKeyFilter:^(NSURL?*url)?{
url?=?[[NSURL?alloc]?initWithScheme:url.scheme?host:url.host?path:url.path];
return?[url?absoluteString];
}];
*?@endcode
*/
/*
*?這
個cacheKeyFilter是干嘛的呢?很簡單.1他是一個block.2.這個block的作用就是生成一個image的key.因為
sdwebimage的緩存原理你可以當(dāng)成是一個字典,每一個字典的value就是一張image,那么這個value對應(yīng)的key是什么呢?就是
cacheKeyFilter根據(jù)某個規(guī)則對這個圖片的url做一些操作生成的.上面的示例就顯示了怎么利用這個block把image的url重新組合
生成一個key.以后當(dāng)sdwebimage檢測到你
*/
@property?(nonatomic,?copy)?SDWebImageCacheKeyFilterBlock?cacheKeyFilter;
/**
*?Returns?global?SDWebImageManager?instance.
*
*?@return?SDWebImageManager?shared?instance
*/
/*
*這個不用我解釋了吧,生成一個SDWebImagemanager的單例.
*/
+?(SDWebImageManager?*)sharedManager;
/**
*?Downloads?the?image?at?the?given?URL?if?not?present?in?cache?or?return?the?cached?version?otherwise.
*?從給定的URL中下載一個之前沒有被緩存的Image.
*
*?@param?url????????????The?URL?to?the?image
*?@param?options????????A?mask?to?specify?options?to?use?for?this?request
*?@param?progressBlock??A?block?called?while?image?is?downloading
*?@param?completedBlock?A?block?called?when?operation?has?been?completed.
*
*???This?parameter?is?required.
*
*???This?block?has?no?return?value?and?takes?the?requested?UIImage?as?first?parameter.
*???In?case?of?error?the?image?parameter?is?nil?and?the?second?parameter?may?contain?an?NSError.
*
*???The?third?parameter?is?an?`SDImageCacheType`?enum?indicating?if?the?image?was?retrived?from?the?local?cache
*???or?from?the?memory?cache?or?from?the?network.
*
*???The?last?parameter?is?set?to?NO?when?the?SDWebImageProgressiveDownload?option?is?used?and?the?image?is
*???downloading.?This?block?is?thus?called?repetidly?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.
*
*?@return?Returns?an?NSObject?conforming?to?SDWebImageOperation.?Should?be?an?instance?of?SDWebImageDownloaderOperation
*/
/*
*?這個方法主要就是SDWebImage下載圖片的方法了.
*?第一個參數(shù)是必須要的,就是image的url
*?第二個參數(shù)就是我們上面的Options,你可以定制化各種各樣的操作.詳情參上.
*?第三個參數(shù)是一個回調(diào)block,用于圖片在下載過程中的回調(diào).(英文注釋應(yīng)該是有問題的.)
*?第四個參數(shù)是一個下載完成的回調(diào).會在圖片下載完成后回調(diào).
*?返回值是一個NSObject類,并且這個NSObject類是conforming一個協(xié)議這個協(xié)議叫做SDWebImageOperation,這個協(xié)議很簡單,就是一個cancel掉operation的協(xié)議.
*/
-?(id?)downloadImageWithURL:(NSURL?*)url
options:(SDWebImageOptions)options
progress:(SDWebImageDownloaderProgressBlock)progressBlock
completed:(SDWebImageCompletionWithFinishedBlock)completedBlock;
/**
*?Saves?image?to?cache?for?given?URL
*
*?@param?image?The?image?to?cache
*?@param?url???The?URL?to?the?image
*
*/
/*
*?將圖片存入cache的方法,類似于字典的setValue:?forKey:
*/
-?(void)saveImageToCache:(UIImage?*)image?forURL:(NSURL?*)url;
/**
*?Cancel?all?current?opreations
*/
/*
*取消掉當(dāng)前所有的下載圖片的operation
*/
-?(void)cancelAll;
/**
*?Check?one?or?more?operations?running
*/
/*
*?check一下是否有一個或者多個operation正在執(zhí)行(簡單來說就是check是否有圖片在下載)
*/
-?(BOOL)isRunning;
/**
*??Check?if?image?has?already?been?cached
*
*??@param?url?image?url
*
*??@return?if?the?image?was?already?cached
*/
/*
*?通過一個image的url是否已經(jīng)存在,如果存在返回yes,否則返回no
*/
-?(BOOL)cachedImageExistsForURL:(NSURL?*)url;
/**
*??Check?if?image?has?already?been?cached?on?disk?only
*
*??@param?url?image?url
*
*??@return?if?the?image?was?already?cached?(disk?only)
*/
/*
*?檢測一個image是否已經(jīng)被緩存到磁盤(是否存且僅存在disk里).
*/
-?(BOOL)diskImageExistsForURL:(NSURL?*)url;
/**
*??Async?check?if?image?has?already?been?cached
*
*??@param?url??????????????image?url
*??@param?completionBlock??the?block?to?be?executed?when?the?check?is?finished
*
*??@note?the?completion?block?is?always?executed?on?the?main?queue
*/
/*
*?如果檢測到圖片已經(jīng)被緩存,那么執(zhí)行回調(diào)block.這個block會永遠(yuǎn)執(zhí)行在主線程.也就是你可以在這個回調(diào)block里更新ui.
*/
-?(void)cachedImageExistsForURL:(NSURL?*)url
completion:(SDWebImageCheckCacheCompletionBlock)completionBlock;
/**
*??Async?check?if?image?has?already?been?cached?on?disk?only
*
*??@param?url??????????????image?url
*??@param?completionBlock??the?block?to?be?executed?when?the?check?is?finished
*
*??@note?the?completion?block?is?always?executed?on?the?main?queue
*/
/*
*?如果檢測到圖片已經(jīng)被緩存在磁盤(存且僅存在disk),那么執(zhí)行回調(diào)block.這個block會永遠(yuǎn)執(zhí)行在主線程.也就是你可以在這個回調(diào)block里更新ui.
*/
-?(void)diskImageExistsForURL:(NSURL?*)url
completion:(SDWebImageCheckCacheCompletionBlock)completionBlock;
/**
*Return?the?cache?key?for?a?given?URL
*/
/*
*?通過image的url返回image存在緩存里的key.有人會問了,為什么不直接把圖片的url當(dāng)做image的key來使用呢?而是非要對url做一些處理才能當(dāng)做key.我的解釋是,我也不太清楚.可能為了防止重復(fù)吧.
*/
-?(NSString?*)cacheKeyForURL:(NSURL?*)url;
@end
#pragma?mark?-?Deprecated
typedef?void(^SDWebImageCompletedBlock)(UIImage?*image,?NSError?*error,?SDImageCacheType?cacheType)?__deprecated_msg("Block?type?deprecated.?Use?`SDWebImageCompletionBlock`");
typedef?void(^SDWebImageCompletedWithFinishedBlock)(UIImage?*image,?NSError?*error,?SDImageCacheType?cacheType,?BOOL?finished)?__deprecated_msg("Block?type?deprecated.?Use?`SDWebImageCompletionWithFinishedBlock`");
//?已被廢棄
@interface?SDWebImageManager?(Deprecated)
/**
*??Downloads?the?image?at?the?given?URL?if?not?present?in?cache?or?return?the?cached?version?otherwise.
*
*??@deprecated?This?method?has?been?deprecated.?Use?`downloadImageWithURL:options:progress:completed:`
*/
-?(id?)downloadWithURL:(NSURL?*)url
options:(SDWebImageOptions)options
progress:(SDWebImageDownloaderProgressBlock)progressBlock
completed:(SDWebImageCompletedWithFinishedBlock)completedBlock?__deprecated_msg("Method?deprecated.?Use?`downloadImageWithURL:options:progress:completed:`");
@end
