Overview

AFURLConnectionOperation is a subclass of NSOperation that implements NSURLConnection delegate methods.

Subclassing Notes

This is the base class of all network request operations. You may wish to create your own subclass in order to implement additional NSURLConnection delegate methods (see “NSURLConnection Delegate Methods” below), or to provide additional properties and/or class constructors.

If you are creating a subclass that communicates over the HTTP or HTTPS protocols, you may want to consider subclassing AFHTTPRequestOperation instead, as it supports specifying acceptable content types or status codes.

NSURLConnection Delegate Methods

AFURLConnectionOperation implements the following NSURLConnection delegate methods:

• connection:didReceiveResponse:
• connection:didReceiveData:
• connectionDidFinishLoading:
• connection:didFailWithError:
• connection:didSendBodyData:totalBytesWritten:totalBytesExpectedToWrite:
• connection:willCacheResponse:
• connection:canAuthenticateAgainstProtectionSpace:
• connection:didReceiveAuthenticationChallenge:

If any of these methods are overridden in a subclass, they must call the super implementation first.

Class Constructors

Class constructors, or methods that return an unowned instance, are the preferred way for subclasses to encapsulate any particular logic for handling the setup or parsing of response data. For instance, AFJSONRequestOperation provides JSONRequestOperationWithRequest:success:failure:, which takes block arguments, whose parameter on for a successful request is the JSON object initialized from the response data.

Callbacks and Completion Blocks

The built-in completionBlock provided by NSOperation allows for custom behavior to be executed after the request finishes. It is a common pattern for class constructors in subclasses to take callback block parameters, and execute them conditionally in the body of its completionBlock. Make sure to handle cancelled operations appropriately when setting a completionBlock (i.e. returning early before parsing response data). See the implementation of any of the AFHTTPRequestOperation subclasses for an example of this.

Subclasses are strongly discouraged from overriding setCompletionBlock:, as AFURLConnectionOperation’s implementation includes a workaround to mitigate retain cycles, and what Apple rather ominously refers to as “The Deallocation Problem”.

NSCoding & NSCopying Conformance

AFURLConnectionOperation conforms to the NSCoding and NSCopying protocols, allowing operations to be archived to disk, and copied in memory, respectively. However, because of the intrinsic limitations of capturing the exact state of an operation at a particular moment, there are some important caveats to keep in mind:

NSCoding Caveats

• Encoded operations do not include any block or stream properties. Be sure to set completionBlock, outputStream, and any callback blocks as necessary when using -initWithCoder: or NSKeyedUnarchiver.
• Operations are paused on encodeWithCoder:. If the operation was encoded while paused or still executing, its archived state will return YES for isReady. Otherwise, the state of an operation when encoding will remain unchanged.

NSCopying Caveats

• -copy and -copyWithZone: return a new operation with the NSURLRequest of the original. So rather than an exact copy of the operation at that particular instant, the copying mechanism returns a completely new instance, which can be useful for retrying operations.
• A copy of an operation will not include the outputStream of the original.
• Operation copies do not include completionBlock. completionBlock often strongly captures a reference to self, which would otherwise have the unintuitive side-effect of pointing to the original operation when copied.