Documentation for AFURLConnectionOperation

AFNetworking/AFURLConnectionOperation.h

@@ -39,7 +39,40 @@ extern NSString * const AFNetworkingOperationDidStartNotification;
  */
 extern NSString * const AFNetworkingOperationDidFinishNotification;
 
+/**
+ `AFURLConnectionOperation` is an `NSOperation` that implements the NSURLConnection delegate methods, and provides a simple block-based interface to asynchronously get the result and context of that operation finishes.
  
+ # 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`, which 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:`
+ 
+ If any of these methods are overriden in a subclass, they _must_ call the `super` implementation first.
+ 
+ Notably, `AFHTTPRequestOperation` does not implement any of the authentication challenge-related `NSURLConnection` delegate methods, and are thus safe to override without a call to `super`.
+ 
+ ## Class Constructors
+ 
+ Class constructors, or methods that return a zero-retain-count 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`. See the implementation of any of the `AFHTTPRequestOperation` subclasses for an example of this.
+ 
+ One common oversight when setting completion blocks is to forget to check for whether the operation was cancelled. Be sure to handle called operations appropriately (e.g. returning early before parsing response data).
+ */
 @interface AFURLConnectionOperation : NSOperation {
 @private
     NSSet *_runLoopModes;
@@ -55,19 +88,77 @@ extern NSString * const AFNetworkingOperationDidFinishNotification;
     NSOutputStream *_outputStream;
 }
 
-@property (nonatomic, retain) NSSet *runLoopModes;
+///-------------------------------
-
+/// @name Accessing Run Loop Modes
-@property (readonly, nonatomic, retain) NSURLRequest *request;
+///-------------------------------
-@property (readonly, nonatomic, retain) NSURLResponse *response;
-@property (readonly, nonatomic, retain) NSError *error;
-
-@property (readonly, nonatomic, retain) NSData *responseData;
-@property (readonly, nonatomic, copy) NSString *responseString;
-
-@property (nonatomic, retain) NSInputStream *inputStream;
-@property (nonatomic, retain) NSOutputStream *outputStream;
 
 /**
+ The run loop modes in which the operation will run on the network thread. By default, this is a single-member set containing `NSRunLoopCommonModes`.
+ */
+@property (nonatomic, retain) NSSet *runLoopModes;
+
+///-----------------------------------------
+/// @name Getting URL Connection Information
+///-----------------------------------------
+
+/**
+ The request used by the operation's connection.
+ */
+@property (readonly, nonatomic, retain) NSURLRequest *request;
+
+/**
+ The last response received by the operation's connection.
+ */
+@property (readonly, nonatomic, retain) NSURLResponse *response;
+
+/**
+ The error, if any, that occured in the lifecycle of the request.
+ */
+@property (readonly, nonatomic, retain) NSError *error;
+
+///----------------------------
+/// @name Getting Response Data
+///----------------------------
+
+/**
+ The data received during the request. 
+ */
+@property (readonly, nonatomic, retain) NSData *responseData;
+
+/**
+ The string representation of the response data.
+ 
+ @discussion This method uses the string encoding of the response to construct a string from the response data.
+ */
+@property (readonly, nonatomic, copy) NSString *responseString;
+
+///------------------------
+/// @name Accessing Streams
+///------------------------
+
+/**
+ The input stream used to read data to be sent during the request. 
+ 
+ @discussion This property acts as a proxy to the `HTTPBodyStream` property of `request`.
+ */
+@property (nonatomic, retain) NSInputStream *inputStream;
+
+/**
+ The output stream that is used to write data received until the request is finished.
+ 
+ @discussion By default, data is accumulated into a buffer that is stored into `responseData` upon completion of the request. When `outputStream` is set, the data will not be accumulated into an internal buffer, and as a result, the `responseData` property of the completed request will be `nil`.
+ */
+@property (nonatomic, retain) NSOutputStream *outputStream;
+
+///------------------------------------------------------
+/// @name Initializing an AFURLConnectionOperation Object
+///------------------------------------------------------
+
+/**
+ Initializes and returns a newly allocated operation object with a url connection configured with the specified url request.
+ 
+ @param urlRequest The request object to be used by the operation connection.
+ 
  @discussion This is the designated initializer.
  */
 - (id)initWithRequest:(NSURLRequest *)urlRequest;

AFNetworking/AFURLConnectionOperation.m

@@ -159,11 +159,9 @@ static inline NSString * AFKeyPathFromOperationState(AFOperationState state) {
 }
 
 - (void)setInputStream:(NSInputStream *)inputStream {
-    if (inputStream) {
     NSMutableURLRequest *mutableRequest = [[self.request mutableCopy] autorelease];
     mutableRequest.HTTPBodyStream = inputStream;
     self.request = mutableRequest;
-    }
 }
 
 - (void)setUploadProgressBlock:(void (^)(NSInteger bytesWritten, NSInteger totalBytesWritten, NSInteger totalBytesExpectedToWrite))block {