FWBaseRequest


@interface FWBaseRequest : NSObject

FWBaseRequest is the abstract class of network request. It provides many options for constructing request. It’s the base class of FWRequest.

Request and Response Information

  • The underlying NSURLSessionTask.

    Warning

    This value is actually nil and should not be accessed before the request starts.

    Declaration

    Objective-C

    @property (nonatomic, strong, readonly) NSURLSessionTask *_Nonnull requestTask;

  • The request identifier, always equals the first requestTask.taskIdentifier.

    Declaration

    Objective-C

    @property (nonatomic, readonly) NSUInteger requestIdentifier;

  • Shortcut for requestTask.currentRequest.

    Declaration

    Objective-C

    @property (nonatomic, strong, readonly) NSURLRequest *_Nonnull currentRequest;

  • Shortcut for requestTask.originalRequest.

    Declaration

    Objective-C

    @property (nonatomic, strong, readonly) NSURLRequest *_Nonnull originalRequest;

  • Shortcut for requestTask.response.

    Declaration

    Objective-C

    @property (nonatomic, strong, readonly) NSHTTPURLResponse *_Nonnull response;

  • The response status code.

    Declaration

    Objective-C

    @property (nonatomic, readonly) NSInteger responseStatusCode;

  • The response header fields.

    Declaration

    Objective-C

    @property (nonatomic, strong, readonly, nullable) NSDictionary *responseHeaders;

  • The raw data representation of response. Note this value can be nil if request failed.

    Declaration

    Objective-C

    @property (nonatomic, strong, readonly, nullable) NSData *responseData;

  • The string representation of response. Note this value can be nil if request failed.

    Declaration

    Objective-C

    @property (nonatomic, strong, readonly, nullable) NSString *responseString;

  • This serialized response object. The actual type of this object is determined by FWResponseSerializerType. Note this value can be nil if request failed.

    Note

    If resumableDownloadPath and DownloadTask is using, this value will be the path to which file is successfully saved (NSURL), or nil if request failed.

    Declaration

    Objective-C

    @property (nonatomic, strong, readonly, nullable) id responseObject;

  • If you use FWResponseSerializerTypeJSON, this is a convenience (and sematic) getter for the response object. Otherwise this value is nil.

    Declaration

    Objective-C

    @property (nonatomic, strong, readonly, nullable) id responseJSONObject;

  • This error can be either serialization error or network error. If nothing wrong happens this value will be nil.

    Declaration

    Objective-C

    @property (nonatomic, strong, readonly, nullable) NSError *error;

  • Return finished state of request task.

    Declaration

    Objective-C

    @property (nonatomic, readonly, getter=isFinished) BOOL finished;

  • Return failed state of request task.

    Declaration

    Objective-C

    @property (nonatomic, readonly, getter=isFailed) BOOL failed;

  • Return cancelled state of request task.

    Declaration

    Objective-C

    @property (nonatomic, readonly, getter=isCancelled) BOOL cancelled;

  • Executing state of request task.

    Declaration

    Objective-C

    @property (nonatomic, readonly, getter=isExecuting) BOOL executing;

  • Total request count for request.

    Declaration

    Objective-C

    @property (nonatomic, readonly) NSInteger requestTotalCount;

  • Total request time for request.

    Declaration

    Objective-C

    @property (nonatomic, readonly) NSTimeInterval requestTotalTime;

  • The request method string for request.

    Declaration

    Objective-C

    @property (nonatomic, copy, readonly) NSString *_Nonnull requestMethodString;

Request Configuration

  • tag

    Tag can be used to identify request. Default value is 0.

    Declaration

    Objective-C

    @property (nonatomic) NSInteger tag;

  • The userInfo can be used to store additional info about the request. Default is nil.

    Declaration

    Objective-C

    @property (nonatomic, strong, nullable) NSDictionary *userInfo;

  • The delegate object of the request. If you choose block style callback you can ignore this. Default is nil.

    Declaration

    Objective-C

    @property (nonatomic, weak, nullable) id<FWRequestDelegate> delegate;

  • The success callback. Note if this value is not nil and requestFinished delegate method is also implemented, both will be executed but delegate method is first called. This block will be called on the main queue.

    Declaration

    Objective-C

    @property (nonatomic, copy, nullable) FWRequestCompletionBlock successCompletionBlock;

  • The failure callback. Note if this value is not nil and requestFailed delegate method is also implemented, both will be executed but delegate method is first called. This block will be called on the main queue.

    Declaration

    Objective-C

    @property (nonatomic, copy, nullable) FWRequestCompletionBlock failureCompletionBlock;

  • This can be used to add several accessories object. Note if you use addAccessory to add accessory this array will be automatically created. Default is nil.

    Declaration

    Objective-C

    @property (nonatomic, strong, nullable) NSMutableArray<id<FWRequestAccessory>> *requestAccessories;

  • This can be use to construct HTTP body when needed in POST request. Default is nil.

    Declaration

    Objective-C

    @property (nonatomic, copy, nullable) FWConstructingBlock constructingBodyBlock;

  • This value is used to perform resumable download request. Default is nil.

    Note

    NSURLSessionDownloadTask is used when this value is not nil. The exist file at the path will be removed before the request starts. If request succeed, file will be saved to this path automatically, otherwise the response will be saved to responseData and responseString. For this to work, server must support Range and response with proper Last-Modified and/or Etag. See NSURLSessionDownloadTask for more detail.

    Declaration

    Objective-C

    @property (nonatomic, strong, nullable) NSString *resumableDownloadPath;

  • You can use this block to track the download progress. See also resumableDownloadPath.

    Declaration

    Objective-C

    @property (nonatomic, copy, nullable) FWURLSessionTaskProgressBlock resumableDownloadProgressBlock;

  • You can use this block to track the upload progress.

    Declaration

    Objective-C

    @property (nonatomic, copy, nullable) FWURLSessionTaskProgressBlock uploadProgressBlock;

  • The priority of the request. Default is FWRequestPriorityDefault.

    Declaration

    Objective-C

    @property (nonatomic) FWRequestPriority requestPriority;

  • Set completion callbacks

    Declaration

    Objective-C

    - (void)setCompletionBlockWithSuccess:(nullable FWRequestCompletionBlock)success
                              failure:
                                  (nullable FWRequestCompletionBlock)failure;

  • Nil out both success and failure callback blocks.

    Declaration

    Objective-C

    - (void)clearCompletionBlock;

  • Convenience method to add request accessory. See also requestAccessories.

    Declaration

    Objective-C

    - (void)addAccessory:(nonnull id<FWRequestAccessory>)accessory;

Request Action

Subclass Override

  • This validator will be used to test whether to mock response in debug mode. Default is YES if 404.

    Declaration

    Objective-C

    - (BOOL)responseMockValidator;

  • Called on background thread after request failed but before callback in debug mode.

    Declaration

    Objective-C

    - (BOOL)responseMockProcessor;

  • Preprocess URLRequest before actually sending them.

    Declaration

    Objective-C

    - (void)filterUrlRequest:(nonnull NSMutableURLRequest *)urlRequest;

  • Postprocess request before actually run callback. Default is YES.

    Declaration

    Objective-C

    - (BOOL)filterResponse:(NSError *__autoreleasing _Nullable *_Nullable)error;

  • Called on background thread after request succeeded but before switching to main thread. Note if cache is loaded, this method WILL be called on the main thread, just like requestCompleteFilter.

    Declaration

    Objective-C

    - (void)requestCompletePreprocessor;

  • Called on the main thread after request succeeded.

    Declaration

    Objective-C

    - (void)requestCompleteFilter;

  • Called on background thread after request failed but before switching to main thread. See also requestCompletePreprocessor.

    Declaration

    Objective-C

    - (void)requestFailedPreprocessor;

  • Called on the main thread when request failed.

    Declaration

    Objective-C

    - (void)requestFailedFilter;

  • The baseURL of request. This should only contain the host part of URL, e.g., http://www.example.com. See also requestUrl

    Declaration

    Objective-C

    - (nonnull NSString *)baseUrl;

  • The URL path of request. This should only contain the path part of URL, e.g., /v1/user. See alse baseUrl.

    Note

    This will be concated with baseUrl using [NSURL URLWithString:relativeToURL]. Because of this, it is recommended that the usage should stick to rules stated above. Otherwise the result URL may not be correctly formed. See also URLString:relativeToURL for more information.

        Additionally, if `requestUrl` itself is a valid URL, it will be used as the result URL and
    `baseUrl` will be ignored.

    Declaration

    Objective-C

    - (nonnull NSString *)requestUrl;

  • Optional CDN URL for request.

    Declaration

    Objective-C

    - (nonnull NSString *)cdnUrl;

  • Request timeout interval. Default is 60s.

    Note

    When using resumableDownloadPath(NSURLSessionDownloadTask), the session seems to completely ignore timeoutInterval property of NSURLRequest. One effective way to set timeout would be using timeoutIntervalForResource of NSURLSessionConfiguration.

    Declaration

    Objective-C

    - (NSTimeInterval)requestTimeoutInterval;

  • Custom request cache policy. Default is -1, uses FWHTTPRequestSerializer.cachePolicy.

    Declaration

    Objective-C

    - (NSURLRequestCachePolicy)requestCachePolicy;

  • Additional request argument.

    Declaration

    Objective-C

    - (nullable id)requestArgument;

  • Override this method to filter requests with certain arguments when caching.

    Declaration

    Objective-C

    - (nonnull id)cacheFileNameFilter:(nonnull id)argument;

  • HTTP request method.

    Declaration

    Objective-C

    - (FWRequestMethod)requestMethod;

  • Request serializer type.

    Declaration

    Objective-C

    - (FWRequestSerializerType)requestSerializerType;

  • Response serializer type. See also responseObject.

    Declaration

    Objective-C

    - (FWResponseSerializerType)responseSerializerType;

  • Username and password used for HTTP authorization. Should be formed as @[@“Username”, @“Password”].

    Declaration

    Objective-C

    - (nullable NSArray<NSString *> *)requestAuthorizationHeaderFieldArray;

  • Additional HTTP request header field.

    Declaration

    Objective-C

    - (nullable NSDictionary<NSString *, NSString *> *)
    requestHeaderFieldValueDictionary;

  • Use this to build custom request. If this method return non-nil value, requestUrl, requestTimeoutInterval, requestArgument, allowsCellularAccess, requestMethod and requestSerializerType will all be ignored.

    Declaration

    Objective-C

    - (nullable NSURLRequest *)buildCustomUrlRequest;

  • Should use CDN when sending request.

    Declaration

    Objective-C

    - (BOOL)useCDN;

  • Whether the request is allowed to use the cellular radio (if present). Default is YES.

    Declaration

    Objective-C

    - (BOOL)allowsCellularAccess;

  • The validator will be used to test if responseJSONObject is correctly formed.

    Declaration

    Objective-C

    - (nullable id)jsonValidator;

  • This validator will be used to test if responseStatusCode is valid.

    Declaration

    Objective-C

    - (BOOL)statusCodeValidator;

  • Retry count for request. Default is 0.

    Declaration

    Objective-C

    - (NSInteger)requestRetryCount;

  • Retry interval for request. Default is 0.

    Declaration

    Objective-C

    - (NSTimeInterval)requestRetryInternval;

  • Retry timeout for request. Default is 0.

    Declaration

    Objective-C

    - (NSTimeInterval)requestRetryTimeout;

  • The validator will be used to test if request should retry, enabled when requestRetryCount > 0. Default to check statusCode and error.

    Declaration

    Objective-C

    - (BOOL)requestRetryValidator:(nonnull NSHTTPURLResponse *)response
               responseObject:(nullable id)responseObject
                        error:(nullable NSError *)error;

  • The processor will be called if requestRetryValidator return YES, completionHandler must be called with a bool value, which means retry request if success or stop request if failed. Default to YES.

    Declaration

    Objective-C

    - (void)requestRetryProcessor:(nonnull NSHTTPURLResponse *)response
               responseObject:(nullable id)responseObject
                        error:(nullable NSError *)error
            completionHandler:(nonnull void (^)(BOOL))completionHandler;

RequestAccessory

FWRequestAccessory