diff --git a/README.md b/README.md index c9dc273..77bc115 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ Choose AFNetworking for your next project, or migrate over your existing project ```ruby platform :ios, '7.0' -pod "AFNetworking", "2.0.0-RC2" +pod "AFNetworking", "~> 2.0" ``` ## 2.0 @@ -44,6 +44,266 @@ For compatibility with iOS 5, use the latest 1.x release. For compatibility with iOS 4.3, use the latest 0.10.x release. +## Architecture + +### NSURLConnection + +- `AFURLConnectionOperation` +- `AFHTTPRequestOperation` +- `AFHTTPRequestOperationManager` + +### NSURLSession _(iOS 7 / Mac OS X 10.9)_ + +- `AFURLSessionManager` +- `AFHTTPSessionManager` + +### Serialization + +* `` + - `AFHTTPRequestSerializer` + - `AFJSONRequestSerializer` + - `AFPropertyListRequestSerializer` +* `` + - `AFHTTPResponseSerializer` + - `AFJSONResponseSerializer` + - `AFXMLParserResponseSerializer` + - `AFXMLDocumentResponseSerializer` _(Mac OS X)_ + - `AFPropertyListResponseSerializer` + - `AFImageResponseSerializer` + - `AFCompoundResponseSerializer` + +### Utilities + +- `AFSecurityPolicy` +- `AFNetworkReachabilityManager` + +## Usage + +### HTTP Request Operation Manager + +#### `GET` Request + +```objective-c +AFHTTPRequestOperationManager *manager = [AFHTTPRequestOperationManager manager]; +[manager GET:@"http://example.com/resources.json" parameters:nil success:^(AFHTTPRequestOperation *operation, id responseObject) { + NSLog(@"JSON: %@", responseObject); +} failure:^(AFHTTPRequestOperation *operation, NSError *error) { + NSLog(@"Error: %@", error); +}]; +``` + +#### `POST` Request + +```objective-c +AFHTTPRequestOperationManager *manager = [AFHTTPRequestOperationManager manager]; +NSDictionary *parameters = @{@"foo": @"bar"}; +[manager POST:@"http://example.com/resources.json" parameters:parameters success:^(AFHTTPRequestOperation *operation, id responseObject) { + NSLog(@"JSON: %@", responseObject); +} failure:^(AFHTTPRequestOperation *operation, NSError *error) { + NSLog(@"Error: %@", error); +}]; +``` + +#### `POST` Request with Multi-Part Form + +```objective-c +AFHTTPRequestOperationManager *manager = [AFHTTPRequestOperationManager manager]; +NSDictionary *parameters = @{@"foo": @"bar"}; +NSURL *filePath = [NSURL fileURLWithPath:@"file://path/to/image.png"]; +[manager POST:@"http://example.com/resources.json" parameters:parameters constructingBodyWithBlock:^(id formData) { + [formData appendPartWithFileURL:filePath name:@"image" error:nil]; +} success:^(AFHTTPRequestOperation *operation, id responseObject) { + NSLog(@"Success: %@", responseObject); +} failure:^(AFHTTPRequestOperation *operation, NSError *error) { + NSLog(@"Error: %@", error); +}]; +``` + +--- + +### AFURLSessionManager + +#### Creating a Download Task + +```objective-c +NSURLSessionConfiguration *configuration = [NSURLSessionConfiguration defaultSessionConfiguration]; +AFURLSessionManager *manager = [[AFURLSessionManager alloc] initWithSessionConfiguration:configuration]; + +NSURL *URL = [NSURL URLWithString:@"http://example.com/download.zip"]; +NSURLRequest *request = [NSURLRequest requestWithURL:URL]; + +NSURLSessionDownloadTask *downloadTask = [manager downloadTaskWithRequest:request progress:nil destination:^NSURL *(NSURL *targetPath, NSURLResponse *response) { + NSURL *documentsDirectoryPath = [NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES) firstObject]; + return [documentsDirectoryPath URLByAppendingPathComponent:[targetPath lastPathComponent]]; +} completionHandler:^(NSURLResponse *response, NSURL *filePath, NSError *error) { + NSLog(@"File downloaded to: %@", filePath); +}]; +[downloadTask resume]; +``` + +#### Creating an Upload Task + +```objective-c +NSURLSessionConfiguration *configuration = [NSURLSessionConfiguration defaultSessionConfiguration]; +AFURLSessionManager *manager = [[AFURLSessionManager alloc] initWithSessionConfiguration:configuration]; + +NSURL *URL = [NSURL URLWithString:@"http://example.com/upload"]; +NSURLRequest *request = [NSURLRequest requestWithURL:URL]; + +NSURL *filePath = [NSURL fileURLWithPath:@"file://path/to/image.png"]; +NSURLSessionUploadTask *uploadTask = [manager uploadTaskWithRequest:request fromFile:filePath progress:nil completionHandler:^(NSURLResponse *response, id responseObject, NSError *error) { + if (error) { + NSLog(@"Error: %@", error); + } else { + NSLog(@"Success: %@ %@", response, responseObject); + } +}]; +[uploadTask resume]; +``` + +#### Creating a Data Task + +```objective-c +NSURLSessionConfiguration *configuration = [NSURLSessionConfiguration defaultSessionConfiguration]; +AFURLSessionManager *manager = [[AFURLSessionManager alloc] initWithSessionConfiguration:configuration]; + +NSURL *URL = [NSURL URLWithString:@"http://example.com/upload"]; +NSURLRequest *request = [NSURLRequest requestWithURL:URL]; + +NSURLSessionDataTask *dataTask = [manager dataTaskWithRequest:request completionHandler:^(NSURLResponse *response, id responseObject, NSError *error) { + if (error) { + NSLog(@"Error: %@", error); + } else { + NSLog(@"%@ %@", response, responseObject); + } +}]; +[dataTask resume]; +``` + +--- + +### Request Serialization + +```objective-c +NSString *URLString = @"http://example.com"; +NSDictionary *parameters = @{@"foo": @"bar", @"baz": @[@1, @2, @3]}; +``` + +#### Query String Parameter Encoding + +```objective-c +[[AFHTTPRequestSerializer serializer] requestWithMethod:@"GET" URLString:URLString parameters:parameters]; +``` + + GET http://example.com?foo=bar&baz[]=1&baz[]=2&baz[]=3 + +#### URL Form Parameter Encoding + +```objective-c +[[AFHTTPRequestSerializer serializer] requestWithMethod:@"POST" URLString:URLString parameters:parameters]; +``` + + GET http://example.com/ + Content-Type: application/x-www-form-urlencoded + + foo=bar&baz[]=1&baz[]=2&baz[]=3 + +#### JSON Parameter Encoding + +```objective-c +[[AFJSONRequestSerializer serializer] requestWithMethod:@"POST" URLString:URLString parameters:parameters]; +``` + + POST http://example.com/ + Content-Type: application/json + + {"foo": "bar", "baz": [1,2,3]} + +--- + +### Network Reachability Manager + +#### Shared Network Reachability + +```objective-c +[[AFNetworkReachabilityManager sharedManager] setReachabilityStatusChangeBlock:^(AFNetworkReachabilityStatus status) { + NSLog(@"Reachability: %@", AFStringFromNetworkReachabilityStatus(status)); +}]; +``` + +#### HTTP Manager with Base URL + +```objective-c +NSURL *baseURL = [NSURL URLWithString:@"http://example.com/"]; +AFHTTPRequestOperationManager *manager = [[AFHTTPRequestOperationManager alloc] initWithBaseURL:baseURL]; + +NSOperationQueue *operationQueue = manager.operationQueue; +[manager.reachabilityManager setReachabilityStatusChangeBlock:^(AFNetworkReachabilityStatus status) { + switch (status) { + case AFNetworkReachabilityStatusReachableViaWWAN: + case AFNetworkReachabilityStatusReachableViaWiFi: + [operationQueue setSuspended:NO]; + break; + case AFNetworkReachabilityStatusNotReachable: + default: + [operationQueue setSuspended:YES]; + break; + } +}]; +``` + +--- + +### Security Policy + +#### Allowing Invalid SSL Certificates + +```objective-c +AFHTTPRequestOperationManager *manager = [AFHTTPRequestOperationManager manager]; +manager.securityPolicy.allowInvalidCertificates = YES; // not recommended for production +``` + +--- + +### AFHTTPRequestOperation + +#### `GET` with `AFHTTPRequestOperation` + +```objective-c +NSURL *URL = [NSURL URLWithString:@"http://example.com/resources/123.json"]; +NSURLRequest *request = [NSURLRequest requestWithURL:URL]; +AFHTTPRequestOperation *op = [[AFHTTPRequestOperation alloc] initWithRequest:request]; +op.responseSerializer = [AFJSONResponseSerializer serializer]; +[op setCompletionBlockWithSuccess:^(AFHTTPRequestOperation *operation, id responseObject) { + NSLog(@"JSON: %@", responseObject); +} failure:^(AFHTTPRequestOperation *operation, NSError *error) { + NSLog(@"Error: %@", error); +}]; +[[NSOperationQueue mainQueue] addOperation:op]; +``` + +#### Batch of Operations + +```objective-c +NSMutableArray *mutableOperations = [NSMutableArray array]; +for (NSURL *fileURL in filesToUpload) { + NSURLRequest *request = [[AFHTTPRequestSerializer serializer] multipartFormRequestWithMethod:@"POST" URLString:@"http://example.com/upload" parameters:nil constructingBodyWithBlock:^(id formData) { + [formData appendPartWithFileURL:fileURL name:@"images[]" error:nil]; + }]; + + AFHTTPRequestOperation *operation = [[AFHTTPRequestOperation alloc] initWithRequest:request]; + + [mutableOperations addObject:operation]; +} + +NSArray *operations = [AFURLConnectionOperation batchOfRequestOperations:@[...] progressBlock:^(NSUInteger numberOfFinishedOperations, NSUInteger totalNumberOfOperations) { + NSLog(@"%lu of %lu complete", numberOfFinishedOperations, totalNumberOfOperations); +} completionBlock:^(NSArray *operations) { + NSLog(@"All operations in batch complete"); +}]; +[[NSOperationQueue mainQueue] addOperations:operations waitUntilFinished:NO]; +``` + ## Unit Tests AFNetworking includes a suite of unit tests within the Tests subdirectory. In order to run the unit tests, you must install the testing dependencies via CocoaPods. To do so: