Merge branch 'experimental-0.7'

Conflicts:
	AFNetworking/AFHTTPClient.h

AFNetworking.podspec

@@ -1,13 +1,13 @@
 Pod::Spec.new do
   name     'AFNetworking'
-  version  '0.6.1'
-  summary  'A delightful iOS networking library with NSOperations and block-based callbacks'
+  version  '0.7.0'
+  summary  'A delightful iOS and OS X networking framework'
   homepage 'https://github.com/gowalla/AFNetworking'
   authors  'Mattt Thompson' => '[email protected]', 'Scott Raymond' => '[email protected]'
   source   :git      => 'https://github.com/gowalla/AFNetworking.git',
-           :tag      => '0.6.1'
+           :tag      => '0.7.0'
 
-  platforms 'iOS'
+  platforms 'iOS', 'OSX'
   sdk '>= 4.0'
 
   source_files 'AFNetworking'

AFNetworking/AFHTTPClient.h

@@ -21,34 +21,53 @@
 // THE SOFTWARE.
 
 #import <Foundation/Foundation.h>
-#import "AFHTTPRequestOperation.h"
 
+@class AFHTTPRequestOperation;
+@protocol AFHTTPClientOperation;
 @protocol AFMultipartFormData;
 
 /**
- `AFHTTPClient` objects encapsulates the common patterns of communicating with an application, webservice, or API. It encapsulates persistent information, like base URL, authorization credentials, and HTTP headers, and uses them to construct and manage the execution of HTTP request operations.
+ Method used to encode parameters into request body 
+ */
+typedef enum {
+    AFFormURLParameterEncoding,
+    AFJSONParameterEncoding,
+    AFPropertyListParameterEncoding,
+} AFHTTPClientParameterEncoding;
+
+/**
+ `AFHTTPClient` captures the common patterns of communicating with an web application over HTTP. It encapsulates information like base URL, authorization credentials, and HTTP headers, and uses them to construct and manage the execution of HTTP request operations.
  
- In its default implementation, `AFHTTPClient` sets the following HTTP headers:
+ ## Automatic Content Parsing
  
- - `Accept: application/json`
- - `Accept-Encoding: gzip`
- - `Accept-Language: #{[NSLocale preferredLanguages]}, en-us;q=0.8`
- - `User-Agent: #{generated user agent}`
- 
- You can override these HTTP headers or define new ones using `setDefaultHeader:value:`. 
+ Instances of `AFHTTPClient` may specify which types of requests it expects and should handle by registering HTTP operation classes for automatic parsing. Registered classes will determine whether they can handle a particular request, and then construct a request operation accordingly in `enqueueHTTPRequestOperationWithRequest:success:failure`. See `AFHTTPClientOperation` for further details.
  
- # Subclassing Notes
+ ## Subclassing Notes
  
- It is strongly recommended that you create an `AFHTTPClient` subclass for each website or web application that your application communicates with, and in each subclass, defining a method that returns a singleton object that acts as single a shared HTTP client that holds authentication credentials and other configuration for the entire application.
+ In most cases, one should create an `AFHTTPClient` subclass for each website or web application that your application communicates with. It is often useful, also, to define a class method that returns a singleton shared HTTP client in each subclass, that persists authentication credentials and other configuration across the entire application.
  
  ## Methods to Override
  
- If an `AFHTTPClient` wishes to change the way request parameters are encoded, then the base implementation of `requestWithMethod:path:parameters:` should be overridden. Otherwise, it should be sufficient to take the `super` implementation, and configure the resulting `NSMutableURLRequest` object accordingly.
+ To change the behavior of all url request construction for an `AFHTTPClient` subclass, override `requestWithMethod:path:parameters`.
+ 
+ To change the behavior of all request operation construction for an `AFHTTPClient` subclass, override `enqueueHTTPRequestOperationWithRequest:success:failure`.
+ 
+ ## Default Headers
+ 
+ By default, `AFHTTPClient` sets the following HTTP headers:
+ 
+ - `Accept-Encoding: gzip`
+ - `Accept-Language: #{[NSLocale preferredLanguages]}, en-us;q=0.8`
+ - `User-Agent: #{generated user agent}`
+ 
+ You can override these HTTP headers or define new ones using `setDefaultHeader:value:`. 
  */
 @interface AFHTTPClient : NSObject {
 @private
     NSURL *_baseURL;
     NSStringEncoding _stringEncoding;
+    AFHTTPClientParameterEncoding _parameterEncoding;
+    NSMutableArray *_registeredHTTPOperationClassNames;
     NSMutableDictionary *_defaultHeaders;
     NSOperationQueue *_operationQueue;
 }
@@ -67,6 +86,11 @@
  */
 @property (nonatomic, assign) NSStringEncoding stringEncoding;
 
+/**
+ The `AFHTTPClientParameterEncoding` value corresponding to how parameters are encoded into a request body. This is `AFFormURLParameterEncoding` by default.
+ */
+@property (nonatomic, assign) AFHTTPClientParameterEncoding parameterEncoding;
+
 /**
  The operation queue which manages operations enqueued by the HTTP client.
  */
@@ -90,12 +114,38 @@
  
  @param url The base URL for the HTTP client. This argument must not be nil.
  
- @discussion This is the designated initializer for `AFHTTPClient`
+ @discussion This is the designated initializer.
  
  @return The newly-initialized HTTP client
  */
 - (id)initWithBaseURL:(NSURL *)url;
 
+///----------------------------------
+/// @name Managing HTTP Operations
+///----------------------------------
+
+/**
+ Attempts to register a class conforming to the `AFHTTPClientOperation` protocol, adding it to a chain to automatically generate request operations from a URL request.
+ 
+ @param The class conforming to the `AFHTTPClientOperation` protocol to register
+ 
+ @return `YES` if the registration is successful, `NO` otherwise. The only failure condition is if `operationClass` does not conform to the `AFHTTPCLientOperation` protocol.
+ 
+ @discussion When `enqueueHTTPRequestOperationWithRequest:success:failure` is invoked, each registered class is consulted in turn to see if it can handle the specific request. The first class to return `YES` when sent a `canProcessRequest:` message is used to generate an operation using `HTTPRequestOperationWithRequest:success:failure:`. There is no guarantee that all registered classes will be consulted. Classes are consulted in the reverse order of their registration. Attempting to register an already-registered class will move it to the top of the chain.
+ 
+ @see `AFHTTPClientOperation`
+ */
+- (BOOL)registerHTTPOperationClass:(Class)operationClass;
+
+/**
+ Unregisteres the specified class conforming to the `AFHTTPClientOperation` protocol.
+ 
+ @param The class conforming to the `AFHTTPClientOperation` protocol to unregister
+ 
+ @discussion After this method is invoked, `operationClass` is no longer consulted when `requestWithMethod:path:parameters` is invoked.
+ */
+- (void)unregisterHTTPOperationClass:(Class)operationClass;
+
 ///----------------------------------
 /// @name Managing HTTP Header Values
 ///----------------------------------
@@ -142,13 +192,17 @@
 ///-------------------------------
 
 /**
- Creates an `NSMutableURLRequest` object with the specified HTTP method and path. If the HTTP method is `GET`, the parameters will be used to construct a url-encoded query string that is appended to the request's URL. If `POST`, `PUT`, or `DELETE`, the parameters will be encoded into a `application/x-www-form-urlencoded` HTTP body.
+ Creates an `NSMutableURLRequest` object with the specified HTTP method and path. By default, this method scans through the registered operation classes (in reverse order of when they were specified), until finding one that can handle the specified request.
+ 
+ If the HTTP method is `GET`, the parameters will be used to construct a url-encoded query string that is appended to the request's URL. Otherwise, the parameters will be encoded according to the value of the `parameterEncoding` property, and set as the request body.
  
  @param method The HTTP method for the request, such as `GET`, `POST`, `PUT`, or `DELETE`.
  @param path The path to be appended to the HTTP client's base URL and used as the request URL.
  @param parameters The parameters to be either set as a query string for `GET` requests, or the request HTTP body.
  
  @return An `NSMutableURLRequest` object
+ 
+ @see AFHTTPClientOperation
  */
 - (NSMutableURLRequest *)requestWithMethod:(NSString *)method 
                                       path:(NSString *)path 
@@ -164,6 +218,8 @@
  
  @see AFMultipartFormData
  
+ @warning An exception will be raised if the specified method is not `POST`, `PUT` or `DELETE`.
+ 
  @return An `NSMutableURLRequest` object
  */
 - (NSMutableURLRequest *)multipartFormRequestWithMethod:(NSString *)method
@@ -179,13 +235,23 @@
 /**
  Creates and enqueues an `AFHTTPRequestOperation` to the HTTP client's operation queue.
  
+ In order to determine what kind of operation is enqueued, each registered subclass conforming to the `AFHTTPClient` protocol is consulted in turn to see if it can handle the specific request. The first class to return `YES` when sent a `canProcessRequest:` message is used to generate an operation using `HTTPRequestOperationWithRequest:success:failure:`.
+  
  @param request The request object to be loaded asynchronously during execution of the operation.
- @param success A block object to be executed when the request operation finishes successfully, with a status code in the 2xx range, and with an acceptable content type (e.g. `application/json`). This block has no return value and takes a single argument, which is an object created from the response data of request.
- @param failure A block object to be executed when the request operation finishes unsuccessfully, or that finishes successfully, but encountered an error while parsing the resonse data as JSON. This block has no return value and takes a single argument, which is the `NSError` object describing the network or parsing error that occurred.
+ @param success A block object to be executed when the request operation finishes successfully. This block has no return value and takes a single argument, which is an object created from the response data of request.
+ @param failure A block object to be executed when the request operation finishes unsuccessfully, or that finishes successfully, but encountered an error while parsing the resonse data. This block has no return value and takes a single argument, which is the `NSError` object describing the network or parsing error that occurred.
+ 
+ @see `AFHTTPClientOperation`
  */
-- (void)enqueueHTTPOperationWithRequest:(NSURLRequest *)request 
-                                success:(void (^)(id object))success 
-                                failure:(void (^)(NSHTTPURLResponse *response, NSError *error))failure;
+- (void)enqueueHTTPRequestOperationWithRequest:(NSURLRequest *)request 
+                                       success:(void (^)(id object))success 
+                                       failure:(void (^)(NSHTTPURLResponse *response, NSError *error))failure;
+/**
+ Enqueues an `AFHTTPRequestOperation` to the HTTP client's operation queue.
+ 
+ @param operation The HTTP request operation to be enqueued.
+ */
+- (void)enqueueHTTPRequestOperation:(AFHTTPRequestOperation *)operation;
 
 ///---------------------------------
 /// @name Cancelling HTTP Operations
@@ -266,8 +332,39 @@
 
 #pragma mark -
 
+/**
+ The `AFHTTPClientOperation` protocol defines the methods used for the automatic content parsing functionality of `AFHTTPClient`.
+ 
+ @see `AFHTTPClient -registerHTTPOperationClass:`
+ */
+@protocol AFHTTPClientOperation
+
+/**
+ A Boolean value determining whether or not the class can process the specified request. For example, `AFJSONRequestOperation` may check to make sure the content type was `application/json` or the URL path extension was `.json`.
+ 
+ @param urlRequest The request that is determined to be supported or not supported for this class.
+ */
++ (BOOL)canProcessRequest:(NSURLRequest *)urlRequest;
+
+/**
+ Constructs and initializes an operation with success and failure callbacks.
+ 
+ @param urlRequest The request used by the operation connection.
+ @param success A block object to be executed when the operation finishes successfully. The block has no return value and takes a single argument, the response object from the request.
+ @param failure A block object to be executed when the operation finishes unsuccessfully. The block has no return value and takes two arguments: the response received from the server, and the error describing the network or parsing error that occurred.
+ */
++ (id)HTTPRequestOperationWithRequest:(NSURLRequest *)urlRequest 
+                              success:(void (^)(id object))success 
+                              failure:(void (^)(NSHTTPURLResponse *response, NSError *error))failure;
+@end
+
+#pragma mark -
+
 /**
  The `AFMultipartFormData` protocol defines the methods supported by the parameter in the block argument of `multipartFormRequestWithMethod:path:parameters:constructingBodyWithBlock:`.
+ 
+ @see `AFHTTPClient -multipartFormRequestWithMethod:path:parameters:constructingBodyWithBlock:`
+
  */
 @protocol AFMultipartFormData
 
@@ -298,16 +395,6 @@
  */
 - (void)appendPartWithFileData:(NSData *)data mimeType:(NSString *)mimeType name:(NSString *)name;
 
-/**
- Appends the HTTP header `Content-Disposition: file; filename=#{filename}"` and `Content-Type: #{mimeType}`, followed by the encoded file data and the multipart form boundary.
- 
- @param fileURL The URL for the local file to have its contents appended to the form data. This parameter must not be `nil`.
- @param mimeType The MIME type of the specified data. (For example, the MIME type for a JPEG image is image/jpeg.) For a list of valid MIME types, see http://www.iana.org/assignments/media-types/. This parameter must not be `nil`.
- @param fileName The filename to be associated with the file contents. This parameter must not be `nil`.
- @param error If an error occurs, upon return contains an `NSError` object that describes the problem.
- */
-- (void)appendPartWithFile:(NSURL *)fileURL mimeType:(NSString *)mimeType fileName:(NSString *)fileName error:(NSError **)error;
-
 /**
  Appends encoded data to the form data.
  
@@ -322,3 +409,4 @@
  */
 - (void)appendString:(NSString *)string;
 @end
+