Adding first pass of example usage
This commit is contained in:
Mattt Thompson
parent
125b7e4b1e
commit
65ee7d97b1
262
README.md
262
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
|
||||
|
||||
* `<AFURLRequestSerialization>`
|
||||
- `AFHTTPRequestSerializer`
|
||||
- `AFJSONRequestSerializer`
|
||||
- `AFPropertyListRequestSerializer`
|
||||
* `<AFURLResponseSerialization>`
|
||||
- `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<AFMultipartFormData> 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<AFMultipartFormData> 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:
|
||||
|
||||
Loading…
Reference in New Issue
Block a user