| commit | author | age | ||
| 3eceb5 | 1 | // |
| W | 2 | // VKRequest.h |
| 3 | // | |
| 4 | // Copyright (c) 2014 VK.com | |
| 5 | // | |
| 6 | // Permission is hereby granted, free of charge, to any person obtaining a copy of | |
| 7 | // this software and associated documentation files (the "Software"), to deal in | |
| 8 | // the Software without restriction, including without limitation the rights to | |
| 9 | // use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of | |
| 10 | // the Software, and to permit persons to whom the Software is furnished to do so, | |
| 11 | // subject to the following conditions: | |
| 12 | // | |
| 13 | // The above copyright notice and this permission notice shall be included in all | |
| 14 | // copies or substantial portions of the Software. | |
| 15 | // | |
| 16 | // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR | |
| 17 | // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS | |
| 18 | // FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR | |
| 19 | // COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER | |
| 20 | // IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN | |
| 21 | // CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. | |
| 22 | ||
| 23 | #import <Foundation/Foundation.h> | |
| 24 | #import "VKResponse.h" | |
| 25 | #import "VKApiConst.h" | |
| 26 | #import "VKObject.h" | |
| 27 | ||
| 28 | ||
| 29 | /** | |
| 30 | Creates and debug timings for VKRequest | |
| 31 | */ | |
| 32 | @interface VKRequestTiming : VKObject | |
| 33 | /// Date of request start | |
| 34 | @property(nonatomic, strong) NSDate *startTime; | |
| 35 | /// Date of request finished (after all operations) | |
| 36 | @property(nonatomic, strong) NSDate *finishTime; | |
| 37 | /// Interval of networking load time | |
| 38 | @property(nonatomic, assign) NSTimeInterval loadTime; | |
| 39 | /// Interval of model parsing time | |
| 40 | @property(nonatomic, assign) NSTimeInterval parseTime; | |
| 41 | /// Total time, as difference (finishTime - startTime) | |
| 42 | @property(nonatomic, readonly) NSTimeInterval totalTime; | |
| 43 | @end | |
| 44 | ||
| 45 | /** | |
| 46 | Class for execution API-requests. | |
| 47 | ||
| 48 | See example requests below: | |
| 49 | ||
| 50 | 1) A plain request | |
| 51 | ||
| 52 | VKRequest *usersReq = [[VKApi users] get]; | |
| 53 | ||
| 54 | 2) A request with parameters | |
| 55 | ||
| 56 | VKRequest *usersReq = [[VKApi users] get:@{VK_API_FIELDS : @"photo_100"}]; | |
| 57 | ||
| 58 | 3) A request with predetermined maximum number of attempts. For example, take 10 attempts until succeed or an API error occurs: | |
| 59 | ||
| 60 | VKRequest *postReq = [[VKApi wall] post:@{VK_API_MESSAGE : @"Test"}]; | |
| 61 | postReq.attempts = 10; | |
| 62 | //or infinite | |
| 63 | //postReq.attempts = 0; | |
| 64 | ||
| 65 | 4) You can build a request for any public method of VK API | |
| 66 | ||
| 67 | VKRequest *getWall = [VKRequest requestWithMethod:@"wall.get" andParameters:@{VK_API_OWNER_ID : @"-1"}]; | |
| 68 | ||
| 69 | 5) Also there are some special requests for uploading a photos to a user's wall, user albums and other | |
| 70 | ||
| 71 | VKRequest *request = [VKApi uploadWallPhotoRequest:[UIImage imageNamed:@"my_photo"] parameters:[VKImageParameters pngImage] userId:0 groupId:0 ]; | |
| 72 | ||
| 73 | ||
| 74 | After you have prepared a request, you execute it and you may receive some data or error | |
| 75 | ||
| 76 | [usersReq executeWithResultBlock:^(VKResponse *response) { | |
| 77 | NSLog(@"Json result: %@", response.json); | |
| 78 | } errorBlock:^(NSError * error) { | |
| 79 | if (error.code != VK_API_ERROR) { | |
| 80 | [error.vkError.request repeat]; | |
| 81 | } else { | |
| 82 | NSLog(@"VK error: %@", error); | |
| 83 | } | |
| 84 | }]; | |
| 85 | ||
| 86 | */ | |
| 87 | @interface VKRequest : VKObject | |
| 88 | /// Specify progress for uploading or downloading. Useless for text requests (because gzip encoding bytesTotal will always return -1) | |
| 89 | ||
| 90 | @property(nonatomic, copy) void (^progressBlock)(VKProgressType progressType, long long bytesLoaded, long long bytesTotal); | |
| 91 | /// Specify completion block for request | |
| 92 | @property(nonatomic, copy) void (^completeBlock)(VKResponse *response); | |
| 93 | /// Specity error (HTTP or API) block for request. | |
| 94 | @property(nonatomic, copy) void (^errorBlock)(NSError *error); | |
| 95 | /// Specify attempts for request loading if caused HTTP-error. 0 for infinite | |
| 96 | @property(nonatomic, assign) int attempts; | |
| 97 | /// Use HTTPS requests (by default is YES). If http-request is impossible (user denied no https access), SDK will load https version | |
| 98 | @property(nonatomic, assign) BOOL secure; | |
| 99 | /// Sets current system language as default for API data | |
| 100 | @property(nonatomic, assign) BOOL useSystemLanguage; | |
| 101 | /// Set to NO if you don't need automatic model parsing | |
| 102 | @property(nonatomic, assign) BOOL parseModel; | |
| 103 | /// Set to YES if you need info about request timing | |
| 104 | @property(nonatomic, assign) BOOL debugTiming; | |
| 105 | /// Timeout for this request | |
| 106 | @property(nonatomic, assign) NSInteger requestTimeout; | |
| 107 | /// Sets dispatch queue for returning result | |
| 108 | @property(nonatomic, assign) dispatch_queue_t responseQueue; | |
| 109 | /// Set to YES if you need to freeze current thread for response | |
| 110 | @property(nonatomic, assign) BOOL waitUntilDone; | |
| 111 | /// Returns method for current request, e.g. users.get | |
| 112 | @property(nonatomic, readonly) NSString *methodName; | |
| 113 | /// Returns HTTP-method for current request | |
| 114 | @property(nonatomic, readonly) NSString *httpMethod; | |
| 115 | /// Returns list of method parameters (without common parameters) | |
| 116 | @property(nonatomic, readonly) NSDictionary *methodParameters; | |
| 117 | /// Returns http operation that can be enqueued | |
| 118 | @property(nonatomic, readonly) NSOperation *executionOperation; | |
| 119 | /// Returns info about request timings | |
| 120 | @property(nonatomic, readonly) VKRequestTiming *requestTiming; | |
| 121 | /// Return YES if current request was started | |
| 122 | @property(nonatomic, readonly) BOOL isExecuting; | |
| 123 | /// Return YES if current request was started | |
| 124 | @property(nonatomic, copy) NSArray *preventThisErrorsHandling; | |
| 125 | ||
| 126 | ///------------------------------- | |
| 127 | /// @name Preparing requests | |
| 128 | ///------------------------------- | |
| 129 | ||
| 130 | ||
| 131 | /** | |
| 132 | Creates new request with parameters. See documentation for methods here https://vk.com/dev/methods | |
| 133 | @param method API-method name, e.g. audio.get | |
| 134 | @param parameters method parameters | |
| 135 | @param httpMethod HTTP method for execution, e.g. GET, POST | |
| 136 | @return Complete request object for execute or configure method | |
| 137 | @deprecated Use requestWithMethod:parameters: instead | |
| 138 | */ | |
| 139 | + (instancetype)requestWithMethod:(NSString *)method | |
| 140 | andParameters:(NSDictionary *)parameters | |
| 141 | andHttpMethod:(NSString *)httpMethod __deprecated; | |
| 142 | ||
| 143 | /** | |
| 144 | Creates new request with parameters. See documentation for methods here https://vk.com/dev/methods | |
| 145 | @param method API-method name, e.g. audio.get | |
| 146 | @param parameters method parameters | |
| 147 | @return Complete request object for execute or configure method | |
| 148 | @deprecated Use requestWithMethod:parameters: instead | |
| 149 | */ | |
| 150 | + (instancetype)requestWithMethod:(NSString *)method | |
| 151 | andParameters:(NSDictionary *)parameters __deprecated; | |
| 152 | ||
| 153 | /** | |
| 154 | Creates new request with parameters. See documentation for methods here https://vk.com/dev/methods | |
| 155 | @param method API-method name, e.g. audio.get | |
| 156 | @param parameters method parameters | |
| 157 | @param modelClass class for automatic parse | |
| 158 | @return Complete request object for execute or configure method | |
| 159 | */ | |
| 160 | + (instancetype)requestWithMethod:(NSString *)method | |
| 161 | andParameters:(NSDictionary *)parameters | |
| 162 | modelClass:(Class)modelClass __deprecated; | |
| 163 | ||
| 164 | /** | |
| 165 | Creates new request with parameters. See documentation for methods here https://vk.com/dev/methods | |
| 166 | @param method API-method name, e.g. audio.get | |
| 167 | @param parameters method parameters | |
| 168 | @param httpMethod HTTP method for execution, e.g. GET, POST | |
| 169 | @param modelClass class for automatic parse | |
| 170 | @return Complete request object for execute or configure method | |
| 171 | @deprecated Use requestWithMethod:andParameters:modelClass: instead | |
| 172 | */ | |
| 173 | + (instancetype)requestWithMethod:(NSString *)method | |
| 174 | andParameters:(NSDictionary *)parameters | |
| 175 | andHttpMethod:(NSString *)httpMethod | |
| 176 | classOfModel:(Class)modelClass __deprecated; | |
| 177 | ||
| 178 | /** | |
| 179 | Creates new request with parameters. See documentation for methods here https://vk.com/dev/methods | |
| 180 | @param method API-method name, e.g. audio.get | |
| 181 | @param parameters method parameters | |
| 182 | @return Complete request object for execute or configure method | |
| 183 | */ | |
| 184 | + (instancetype)requestWithMethod:(NSString *)method | |
| 185 | parameters:(NSDictionary *)parameters; | |
| 186 | ||
| 187 | /** | |
| 188 | Creates new request with parameters. See documentation for methods here https://vk.com/dev/methods | |
| 189 | @param method API-method name, e.g. audio.get | |
| 190 | @param parameters method parameters | |
| 191 | @param modelClass class for automatic parse | |
| 192 | @return Complete request object for execute or configure method | |
| 193 | */ | |
| 194 | + (instancetype)requestWithMethod:(NSString *)method | |
| 195 | parameters:(NSDictionary *)parameters | |
| 196 | modelClass:(Class)modelClass; | |
| 197 | ||
| 198 | /** | |
| 199 | Creates new request for upload image to url | |
| 200 | @param url url for upload, which was received from special methods | |
| 201 | @param photoObjects VKPhoto object describes photos | |
| 202 | @return Complete request object for execute | |
| 203 | */ | |
| 204 | + (instancetype)photoRequestWithPostUrl:(NSString *)url | |
| 205 | withPhotos:(NSArray *)photoObjects; | |
| 206 | ||
| 207 | /** | |
| 208 | Prepares NSURLRequest and returns prepared url request for current vkrequest | |
| 209 | @return Prepared request used for loading | |
| 210 | */ | |
| 211 | - (NSURLRequest *)getPreparedRequest; | |
| 212 | ||
| 213 | ///------------------------------- | |
| 214 | /// @name Execution | |
| 215 | ///------------------------------- | |
| 216 | /** | |
| 217 | Executes that request, and returns result to blocks | |
| 218 | @param completeBlock called if there were no HTTP or API errors, returns execution result. | |
| 219 | @param errorBlock called immediately if there was API error, or after <b>attempts</b> tries if there was an HTTP error | |
| 220 | */ | |
| 221 | - (void)executeWithResultBlock:(void (^)(VKResponse *response))completeBlock | |
| 222 | errorBlock:(void (^)(NSError *error))errorBlock; | |
| 223 | ||
| 224 | /** | |
| 225 | Register current request for execute after passed request, if passed request is successful. If it's not, errorBlock will be called. | |
| 226 | @param request after which request must be called that request | |
| 227 | @param completeBlock called if there were no HTTP or API errors, returns execution result. | |
| 228 | @param errorBlock called immediately if there was API error, or after <b>attempts</b> tries if there was an HTTP error | |
| 229 | */ | |
| 230 | - (void)executeAfter:(VKRequest *)request | |
| 231 | withResultBlock:(void (^)(VKResponse *response))completeBlock | |
| 232 | errorBlock:(void (^)(NSError *error))errorBlock; | |
| 233 | ||
| 234 | /** | |
| 235 | Starts loading of prepared request. You can use it instead of executeWithResultBlock | |
| 236 | */ | |
| 237 | - (void)start; | |
| 238 | ||
| 239 | /** | |
| 240 | Creates loading operation for this request | |
| 241 | */ | |
| 242 | - (NSOperation *)createExecutionOperation; | |
| 243 | ||
| 244 | /** | |
| 245 | Repeats this request with initial parameters and blocks. | |
| 246 | Used attempts will be set to 0. | |
| 247 | */ | |
| 248 | - (void)repeat; | |
| 249 | ||
| 250 | /** | |
| 251 | Cancel current request. Result will be not passed. errorBlock will be called with error code | |
| 252 | */ | |
| 253 | - (void)cancel; | |
| 254 | ||
| 255 | ///------------------------------- | |
| 256 | /// @name Operating with parameters | |
| 257 | ///------------------------------- | |
| 258 | /** | |
| 259 | Adds additional parameters to that request | |
| 260 | ||
| 261 | @param extraParameters parameters supposed to be added | |
| 262 | */ | |
| 263 | - (void)addExtraParameters:(NSDictionary *)extraParameters; | |
| 264 | ||
| 265 | /** | |
| 266 | Specify language for API request | |
| 267 | */ | |
| 268 | - (void)setPreferredLang:(NSString *)lang; | |
| 269 | ||
| 270 | @end | |
