NSURLRequest 是不可變的請求物件,絕大多數屬性只能在建立時透過初始化方法指定,建立之後便無法再改動。常用的類方法與唯讀屬性如下:
// 以類方法建立預設請求物件
// 此方式預設採用 NSURLRequestUseProtocolCachePolicy 快取策略,逾時上限為 60 秒
+ (instancetype)requestWithURL:(NSURL *)URL;
// 回傳 BOOL 值,用於判斷是否支援安全編碼
+ (BOOL)supportsSecureCoding;
// 建立時可一併指定快取策略與逾時時間
+ (instancetype)requestWithURL:(NSURL *)URL
cachePolicy:(NSURLRequestCachePolicy)cachePolicy
timeoutInterval:(NSTimeInterval)timeoutInterval;
// init 版本的對應寫法
- (instancetype)initWithURL:(NSURL *)URL;
- (instancetype)initWithURL:(NSURL *)URL
cachePolicy:(NSURLRequestCachePolicy)cachePolicy
timeoutInterval:(NSTimeInterval)timeoutInterval;
// 唯讀:請求位址
@property (nullable, readonly, copy) NSURL *URL;
// 唯讀:快取策略
@property (readonly) NSURLRequestCachePolicy cachePolicy;
// 唯讀:逾時時間
@property (readonly) NSTimeInterval timeoutInterval;
// 唯讀:主文件位址,快取即存放於此
@property (nullable, readonly, copy) NSURL *mainDocumentURL;
// 唯讀:網路服務類型
@property (readonly) NSURLRequestNetworkServiceType networkServiceType;
// 唯讀:是否允許使用電信商蜂巢網路
@property (readonly) BOOL allowsCellularAccess;
快取策略列舉的意義如下:
typedef NS_ENUM(NSUInteger, NSURLRequestCachePolicy) {
// 依協定本身的快取規則處理(預設值)
NSURLRequestUseProtocolCachePolicy = 0,
// 忽略本機快取,一律重新請求
NSURLRequestReloadIgnoringLocalCacheData = 1,
// 同時忽略本機與遠端快取(此策略實際上未實作)
NSURLRequestReloadIgnoringLocalAndRemoteCacheData = 4,
// 與上一項等價的別名
NSURLRequestReloadIgnoringCacheData = NSURLRequestReloadIgnoringLocalCacheData,
// 優先讀取快取,沒有快取時才發出請求
NSURLRequestReturnCacheDataElseLoad = 2,
// 近似離線模式,只讀快取,無論有無快取都不發請求
NSURLRequestReturnCacheDataDontLoad = 3,
// 未實作
NSURLRequestReloadRevalidatingCacheData = 5,
};
網路服務類型的列舉值則決定了系統如何排程這條請求:
typedef NS_ENUM(NSUInteger, NSURLRequestNetworkServiceType) {
NSURLNetworkServiceTypeDefault = 0, // 一般網路流量
NSURLNetworkServiceTypeVoIP = 1, // VoIP 控制流量
NSURLNetworkServiceTypeVideo = 2, // 影片流量
NSURLNetworkServiceTypeBackground = 3,// 背景流量
NSURLNetworkServiceTypeVoice = 4 // 語音資料
};
若希望在建立之後再調整請求內容,就必須改用 NSMutableURLRequest。它把上述唯讀屬性全部開放為可讀寫:
@property (nullable, copy) NSURL *URL; @property NSURLRequestCachePolicy cachePolicy; @property NSTimeInterval timeoutInterval; @property (nullable, copy) NSURL *mainDocumentURL; @property NSURLRequestNetworkServiceType networkServiceType NS_AVAILABLE(10_7, 4_0); @property BOOL allowsCellularAccess NS_AVAILABLE(10_8, 6_0);
這一組屬性只在 NSMutableURLRequest 上可寫,NSURLRequest 只能讀取。
// 請求方法,預設為 GET @property (copy) NSString *HTTPMethod; // 以字典方式整體設定請求標頭 @property (nullable, copy) NSDictionary<NSString *, NSString *> *allHTTPHeaderFields; // 設定單一標頭欄位 - (void)setValue:(nullable NSString *)value forHTTPHeaderField:(NSString *)field; // 追加一個標頭欄位(同名欄位會累加而非覆蓋) - (void)addValue:(NSString *)value forHTTPHeaderField:(NSString *)field; // POST 用的請求本文 @property (nullable, copy) NSData *HTTPBody; // 以串流方式提供請求本文,適合大型資料 @property (nullable, retain) NSInputStream *HTTPBodyStream; // 是否在請求中帶上 Cookie @property BOOL HTTPShouldHandleCookies; // 是否允許管線化,預設關閉;部分伺服器開啟後可提升網路效率 @property BOOL HTTPShouldUsePipelining;
請求送出後,伺服器會先回傳一份回執,NSURLResponse 就是這份回執的封装,其屬性皆為唯讀:
// 對應的請求位址 @property (nullable, readonly, copy) NSURL *URL; // 回傳資料的 MIME 類型 @property (nullable, readonly, copy) NSString *MIMEType; // 預期的資料長度 @property (readonly) long long expectedContentLength; // 回傳資料的文字編碼方式 @property (nullable, readonly, copy) NSString *textEncodingName; // 建議的檔名:以 URL 為主體、MIMEType 為副檔名 @property (nullable, readonly, copy) NSString *suggestedFilename;
若是 HTTP / HTTPS 請求,實際收到的會是它的子類 NSHTTPURLResponse,額外多了兩個實用屬性:
// HTTP 狀態碼 @property (readonly) NSInteger statusCode; // 回應標頭中的所有欄位 @property (readonly, copy) NSDictionary *allHeaderFields;