| commit | author | age | ||
| 3eceb5 | 1 | // |
| W | 2 | // VKHttpClient.h |
| 3 | // | |
| 4 | // Based on AFNetworking library. | |
| 5 | // https://github.com/AFNetworking/AFNetworking | |
| 6 | // | |
| 7 | // Copyright (c) 2014 VK.com | |
| 8 | // | |
| 9 | // Permission is hereby granted, free of charge, to any person obtaining a copy of | |
| 10 | // this software and associated documentation files (the "Software"), to deal in | |
| 11 | // the Software without restriction, including without limitation the rights to | |
| 12 | // use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of | |
| 13 | // the Software, and to permit persons to whom the Software is furnished to do so, | |
| 14 | // subject to the following conditions: | |
| 15 | // | |
| 16 | // The above copyright notice and this permission notice shall be included in all | |
| 17 | // copies or substantial portions of the Software. | |
| 18 | // | |
| 19 | // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR | |
| 20 | // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS | |
| 21 | // FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR | |
| 22 | // COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER | |
| 23 | // IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN | |
| 24 | // CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. | |
| 25 | ||
| 26 | #import "VKObject.h" | |
| 27 | ||
| 28 | @class VKHTTPOperation; | |
| 29 | ||
| 30 | /** | |
| 31 | Class for NSURLRequests generation, made for VK API. | |
| 32 | Based on AFNetworking library ( https://github.com/AFNetworking/AFNetworking ) | |
| 33 | */ | |
| 34 | @interface VKHTTPClient : VKObject <NSCoding> | |
| 35 | ||
| 36 | ///------------------------------- | |
| 37 | /// @name Initialization | |
| 38 | ///------------------------------- | |
| 39 | ||
| 40 | /** | |
| 41 | Creates and initializes an `VKHTTPClient` object with the specified base URL. | |
| 42 | ||
| 43 | @return The newly-initialized HTTP client | |
| 44 | */ | |
| 45 | + (instancetype)getClient; | |
| 46 | ||
| 47 | /** | |
| 48 | The operation queue which manages operations enqueued by the HTTP client. | |
| 49 | */ | |
| 50 | @property(readonly, nonatomic, strong) NSOperationQueue *operationQueue; | |
| 51 | ||
| 52 | ///------------------------------- | |
| 53 | /// @name Operations with default headers | |
| 54 | ///------------------------------- | |
| 55 | ||
| 56 | /** | |
| 57 | Returns the value for the HTTP headers set in request objects created by the HTTP client. | |
| 58 | ||
| 59 | @param header The HTTP header to return the default value for | |
| 60 | ||
| 61 | @return The default value for the HTTP header, or `nil` if unspecified | |
| 62 | */ | |
| 63 | - (NSString *)defaultValueForHeader:(NSString *)header; | |
| 64 | ||
| 65 | /** | |
| 66 | Sets the value for the HTTP headers set in request objects made by the HTTP client. If `nil`, removes the existing value for that header. | |
| 67 | ||
| 68 | @param header The HTTP header to set a default value for | |
| 69 | @param value The value set as default for the specified header, or `nil | |
| 70 | */ | |
| 71 | - (void)setDefaultHeader:(NSString *)header | |
| 72 | value:(NSString *)value; | |
| 73 | ||
| 74 | ///------------------------------- | |
| 75 | /// @name Preparing requests | |
| 76 | ///------------------------------- | |
| 77 | ||
| 78 | /** | |
| 79 | Creates an `NSMutableURLRequest` object with the specified HTTP method and path. | |
| 80 | ||
| 81 | If the HTTP method is `GET`, `HEAD`, or `DELETE`, 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. | |
| 82 | ||
| 83 | @param method The HTTP method for the request, such as `GET`, `POST`, `PUT`, or `DELETE`. This parameter must not be `nil`. | |
| 84 | @param path The path to be appended to the HTTP client's base URL and used as the request URL. If `nil`, no path will be appended to the base URL. | |
| 85 | @param parameters The parameters to be either set as a query string for `GET` requests, or the request HTTP body. | |
| 86 | @param secure Use HTTPS or not | |
| 87 | ||
| 88 | @return An `NSMutableURLRequest` object | |
| 89 | */ | |
| 90 | - (NSMutableURLRequest *)requestWithMethod:(NSString *)method | |
| 91 | path:(NSString *)path | |
| 92 | parameters:(NSDictionary *)parameters | |
| 93 | secure:(BOOL)secure; | |
| 94 | ||
| 95 | /** | |
| 96 | Creates an `NSMutableURLRequest` object with the specified HTTP method and path, and constructs a `multipart/form-data` HTTP body, using the specified parameters and multipart form data block. See http://www.w3.org/TR/html4/interact/forms.html#h-17.13.4.2 | |
| 97 | ||
| 98 | Multipart form requests are automatically streamed, reading files directly from disk along with in-memory data in a single HTTP body. The resulting `NSMutableURLRequest` object has an `HTTPBodyStream` property, so refrain from setting `HTTPBodyStream` or `HTTPBody` on this request object, as it will clear out the multipart form body stream. | |
| 99 | ||
| 100 | @param method The HTTP method for the request. This parameter must not be `GET` or `HEAD`, or `nil`. | |
| 101 | @param path The path to be appended to the HTTP client's base URL and used as the request URL. | |
| 102 | @param images Upload images objects to append | |
| 103 | ||
| 104 | @return An `NSMutableURLRequest` object | |
| 105 | */ | |
| 106 | - (NSMutableURLRequest *)multipartFormRequestWithMethod:(NSString *)method | |
| 107 | path:(NSString *)path | |
| 108 | images:(NSArray *)images; | |
| 109 | ||
| 110 | ///------------------------------- | |
| 111 | /// @name Enqueuing operations | |
| 112 | ///------------------------------- | |
| 113 | ||
| 114 | /** | |
| 115 | Enqueues an `AFHTTPRequestOperation` to the HTTP client's operation queue. | |
| 116 | ||
| 117 | @param operation The HTTP request operation to be enqueued. | |
| 118 | */ | |
| 119 | - (void)enqueueOperation:(NSOperation *)operation; | |
| 120 | ||
| 121 | /** | |
| 122 | Enqueues the specified request operations into a batch. When each request operation finishes, the specified progress block is executed, until all of the request operations have finished, at which point the completion block also executes. | |
| 123 | ||
| 124 | @param operations The request operations used to be batched and enqueued. | |
| 125 | @param progressBlock A block object to be executed upon the completion of each request operation in the batch. This block has no return value and takes two arguments: the number of operations that have already finished execution, and the total number of operations. | |
| 126 | @param completionBlock A block object to be executed upon the completion of all of the request operations in the batch. This block has no return value and takes a single argument: the batched request operations. | |
| 127 | */ | |
| 128 | - (void)enqueueBatchOfHTTPRequestOperations:(NSArray *)operations | |
| 129 | progressBlock:(void (^)(NSUInteger numberOfFinishedOperations, NSUInteger totalNumberOfOperations))progressBlock | |
| 130 | completionBlock:(void (^)(NSArray *operations))completionBlock; | |
| 131 | ||
| 132 | @end | |
