Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 1 | // Copyright (c) 2012 The Chromium Authors. All rights reserved. |
| 2 | // Use of this source code is governed by a BSD-style license that can be |
| 3 | // found in the LICENSE file. |
| 4 | |
| 5 | #ifndef PPAPI_CPP_URL_REQUEST_INFO_H_ |
| 6 | #define PPAPI_CPP_URL_REQUEST_INFO_H_ |
| 7 | |
| 8 | #include "ppapi/c/ppb_url_request_info.h" |
| 9 | #include "ppapi/cpp/resource.h" |
| 10 | #include "ppapi/cpp/var.h" |
| 11 | |
| 12 | /// @file |
| 13 | /// This file defines the API for creating and manipulating URL requests. |
| 14 | namespace pp { |
| 15 | |
| 16 | class FileRef; |
| 17 | class InstanceHandle; |
| 18 | |
| 19 | /// URLRequestInfo provides an API for creating and manipulating URL requests. |
| 20 | class URLRequestInfo : public Resource { |
| 21 | public: |
| 22 | /// Default constructor. This constructor creates an |
| 23 | /// <code>is_null</code> resource. |
| 24 | URLRequestInfo() {} |
| 25 | |
| 26 | /// A constructor used to allocate a new <code>URLLoader</code> in the |
| 27 | /// browser. The resulting object will be <code>is_null</code> if the |
| 28 | /// allocation failed. |
| 29 | /// |
| 30 | /// @param[in] instance The instance with which this resource will be |
| 31 | /// associated. |
| 32 | explicit URLRequestInfo(const InstanceHandle& instance); |
| 33 | |
| 34 | /// The copy constructor for <code>URLRequestInfo</code>. |
| 35 | /// |
| 36 | /// @param[in] other A <code>URLRequestInfo</code> to be copied. |
| 37 | URLRequestInfo(const URLRequestInfo& other); |
| 38 | |
| 39 | /// SetProperty() sets a request property. The value of the property must be |
| 40 | /// the correct type according to the property being set. |
| 41 | /// |
| 42 | /// @param[in] property A <code>PP_URLRequestProperty</code> identifying the |
| 43 | /// property to set. |
| 44 | /// @param[in] value A <code>Var</code> containing the property value. |
| 45 | /// |
| 46 | /// @return true if successful, false if any of the |
| 47 | /// parameters are invalid. |
| 48 | bool SetProperty(PP_URLRequestProperty property, const Var& value); |
| 49 | |
| 50 | /// AppendDataToBody() appends data to the request body. A content-length |
| 51 | /// request header will be automatically generated. |
| 52 | /// |
| 53 | /// @param[in] data A pointer to a buffer holding the data. |
| 54 | /// @param[in] len The length, in bytes, of the data. |
| 55 | /// |
| 56 | /// @return true if successful, false if any of the |
| 57 | /// parameters are invalid. |
| 58 | bool AppendDataToBody(const void* data, uint32_t len); |
| 59 | |
| 60 | /// AppendFileToBody() is used to append an entire file, to be uploaded, to |
| 61 | /// the request body. A content-length request header will be automatically |
| 62 | /// generated. |
| 63 | /// |
| 64 | /// @param[in] file_ref A <code>FileRef</code> containing the file |
| 65 | /// reference. |
| 66 | |
| 67 | /// @param[in] expected_last_modified_time An optional (non-zero) last |
| 68 | /// modified time stamp used to validate that the file was not modified since |
| 69 | /// the given time before it was uploaded. The upload will fail with an error |
| 70 | /// code of <code>PP_ERROR_FILECHANGED</code> if the file has been modified |
| 71 | /// since the given time. If expected_last_modified_time is 0, then no |
| 72 | /// validation is performed. |
| 73 | /// |
| 74 | /// @return true if successful, false if any of the |
| 75 | /// parameters are invalid. |
| 76 | bool AppendFileToBody(const FileRef& file_ref, |
| 77 | PP_Time expected_last_modified_time = 0); |
| 78 | |
| 79 | /// AppendFileRangeToBody() is a pointer to a function used to append part or |
| 80 | /// all of a file, to be uploaded, to the request body. A content-length |
| 81 | /// request header will be automatically generated. |
| 82 | /// |
| 83 | /// @param[in] file_ref A <code>FileRef</code> containing the file |
| 84 | /// reference. |
| 85 | /// @param[in] start_offset An optional starting point offset within the |
| 86 | /// file. |
| 87 | /// @param[in] length An optional number of bytes of the file to |
| 88 | /// be included. If the value is -1, then the sub-range to upload extends |
| 89 | /// to the end of the file. |
| 90 | /// @param[in] expected_last_modified_time An optional (non-zero) last |
| 91 | /// modified time stamp used to validate that the file was not modified since |
| 92 | /// the given time before it was uploaded. The upload will fail with an error |
| 93 | /// code of <code>PP_ERROR_FILECHANGED</code> if the file has been modified |
| 94 | /// since the given time. If expected_last_modified_time is 0, then no |
| 95 | /// validation is performed. |
| 96 | /// |
| 97 | /// @return true if successful, false if any of the |
| 98 | /// parameters are invalid. |
| 99 | bool AppendFileRangeToBody(const FileRef& file_ref, |
| 100 | int64_t start_offset, |
| 101 | int64_t length, |
| 102 | PP_Time expected_last_modified_time = 0); |
| 103 | |
| 104 | /// SetURL() sets the <code>PP_URLREQUESTPROPERTY_URL</code> |
| 105 | /// property for the request. |
| 106 | /// |
| 107 | /// @param[in] url_string A <code>Var</code> containing the property value. |
| 108 | /// |
| 109 | /// @return true if successful, false if the parameter is invalid. |
| 110 | bool SetURL(const Var& url_string) { |
| 111 | return SetProperty(PP_URLREQUESTPROPERTY_URL, url_string); |
| 112 | } |
| 113 | |
| 114 | /// SetMethod() sets the <code>PP_URLREQUESTPROPERTY_METHOD</code> |
| 115 | /// (corresponding to a string of type <code>PP_VARTYPE_STRING</code>) |
| 116 | /// property for the request. This string is either a POST or GET. Refer to |
| 117 | /// the <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec5.html">HTTP |
| 118 | /// Methods</a> documentation for further information. |
| 119 | /// |
| 120 | /// @param[in] method_string A <code>Var</code> containing the property |
| 121 | /// value. |
| 122 | /// |
| 123 | /// @return true if successful, false if the parameter is invalid. |
| 124 | bool SetMethod(const Var& method_string) { |
| 125 | return SetProperty(PP_URLREQUESTPROPERTY_METHOD, method_string); |
| 126 | } |
| 127 | |
| 128 | /// SetHeaders() sets the <code>PP_URLREQUESTPROPERTY_HEADERS</code> |
| 129 | /// (corresponding to a <code>\n</code> delimited string of type |
| 130 | /// <code>PP_VARTYPE_STRING</code>) property for the request. |
| 131 | /// Refer to the |
| 132 | /// <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html"Header |
Torne (Richard Coles) | c2e0dbd | 2013-05-09 18:35:53 +0100 | [diff] [blame] | 133 | /// Field Definitions</a> documentation for further information. |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 134 | /// |
| 135 | /// @param[in] headers_string A <code>Var</code> containing the property |
| 136 | /// value. |
| 137 | /// |
| 138 | /// @return true if successful, false if the parameter is invalid. |
| 139 | bool SetHeaders(const Var& headers_string) { |
| 140 | return SetProperty(PP_URLREQUESTPROPERTY_HEADERS, headers_string); |
| 141 | } |
| 142 | |
| 143 | /// SetStreamToFile() sets the |
| 144 | /// <code>PP_URLREQUESTPROPERTY_STREAMTOFILE</code> (corresponding |
| 145 | /// to a bool of type <code>PP_VARTYPE_BOOL</code>). The default of the |
| 146 | /// property is false. Set this value to true if you want to download the |
| 147 | /// data to a file. Use URL_Loader::FinishStreamingToFile() to complete |
| 148 | /// the download. |
| 149 | /// |
| 150 | /// @param[in] enable A <code>bool</code> containing the property value. |
| 151 | /// |
| 152 | /// @return true if successful, false if the parameter is invalid. |
| 153 | bool SetStreamToFile(bool enable) { |
| 154 | return SetProperty(PP_URLREQUESTPROPERTY_STREAMTOFILE, enable); |
| 155 | } |
| 156 | |
| 157 | /// SetFollowRedirects() sets the |
| 158 | /// <code>PP_URLREQUESTPROPERTY_FOLLOWREDIRECT</code> (corresponding |
| 159 | /// to a bool of type <code>PP_VARTYPE_BOOL</code>). The default of the |
| 160 | /// property is true. Set this value to false if you want to use |
| 161 | /// URLLoader::FollowRedirects() to follow the redirects only after examining |
| 162 | /// redirect headers. |
| 163 | /// |
| 164 | /// @param[in] enable A <code>bool</code> containing the property value. |
| 165 | /// |
| 166 | /// @return true if successful, false if the parameter is invalid. |
| 167 | bool SetFollowRedirects(bool enable) { |
| 168 | return SetProperty(PP_URLREQUESTPROPERTY_FOLLOWREDIRECTS, enable); |
| 169 | } |
| 170 | |
| 171 | /// SetRecordDownloadProgress() sets the |
| 172 | /// <code>PP_URLREQUESTPROPERTY_RECORDDOWNLOADPROGESS</code> |
| 173 | /// (corresponding to a bool of type <code>PP_VARTYPE_BOOL</code>). The |
| 174 | /// default of the property is false. Set this value to true if you want to |
| 175 | /// be able to poll the download progress using |
| 176 | /// URLLoader::GetDownloadProgress(). |
| 177 | /// |
| 178 | /// @param[in] enable A <code>bool</code> containing the property value. |
| 179 | //// |
| 180 | /// @return true if successful, false if the parameter is invalid. |
| 181 | bool SetRecordDownloadProgress(bool enable) { |
| 182 | return SetProperty(PP_URLREQUESTPROPERTY_RECORDDOWNLOADPROGRESS, enable); |
| 183 | } |
| 184 | |
| 185 | /// SetRecordUploadProgress() sets the |
| 186 | /// <code>PP_URLREQUESTPROPERTY_RECORDUPLOADPROGRESS</code> |
| 187 | /// (corresponding to a bool of type <code>PP_VARTYPE_BOOL</code>). The |
| 188 | /// default of the property is false. Set this value to true if you want to |
| 189 | /// be able to poll the upload progress using URLLoader::GetUploadProgress(). |
| 190 | /// |
| 191 | /// @param[in] enable A <code>bool</code> containing the property value. |
| 192 | /// |
| 193 | /// @return true if successful, false if the parameter is invalid. |
| 194 | bool SetRecordUploadProgress(bool enable) { |
| 195 | return SetProperty(PP_URLREQUESTPROPERTY_RECORDUPLOADPROGRESS, enable); |
| 196 | } |
| 197 | |
| 198 | /// SetCustomReferrerURL() sets the |
| 199 | /// <code>PP_URLREQUESTPROPERTY_CUSTOMREFERRERURL</code> |
| 200 | /// (corresponding to a string of type <code>PP_VARTYPE_STRING</code> or |
| 201 | /// might be set to undefined as <code>PP_VARTYPE_UNDEFINED</code>). Set it |
| 202 | /// to a string to set a custom referrer (if empty, the referrer header will |
| 203 | /// be omitted), or to undefined to use the default referrer. Only loaders |
| 204 | /// with universal access (only available on trusted implementations) will |
| 205 | /// accept <code>URLRequestInfo</code> objects that try to set a custom |
| 206 | /// referrer; if given to a loader without universal access, |
| 207 | /// <code>PP_ERROR_BADARGUMENT</code> will result. |
| 208 | /// |
| 209 | /// @param[in] url A <code>Var</code> containing the property value. |
| 210 | /// |
| 211 | /// @return true if successful, false if the parameter is invalid. |
| 212 | bool SetCustomReferrerURL(const Var& url) { |
| 213 | return SetProperty(PP_URLREQUESTPROPERTY_CUSTOMREFERRERURL, url); |
| 214 | } |
| 215 | |
| 216 | /// SetAllowCrossOriginRequests() sets the |
| 217 | /// <code>PP_URLREQUESTPROPERTY_ALLOWCROSSORIGINREQUESTS</code> |
| 218 | /// (corresponding to a bool of type <code>PP_VARTYPE_BOOL</code>). The |
| 219 | /// default of the property is false. Whether cross-origin requests are |
| 220 | /// allowed. Cross-origin requests are made using the CORS (Cross-Origin |
| 221 | /// Resource Sharing) algorithm to check whether the request should be |
| 222 | /// allowed. For the complete CORS algorithm, refer to the |
| 223 | /// <a href="http://www.w3.org/TR/access-control">Cross-Origin Resource |
| 224 | /// Sharing</a> documentation. |
| 225 | /// |
| 226 | /// @param[in] enable A <code>bool</code> containing the property value. |
| 227 | /// |
| 228 | /// @return true if successful, false if the parameter is invalid. |
| 229 | bool SetAllowCrossOriginRequests(bool enable) { |
| 230 | return SetProperty(PP_URLREQUESTPROPERTY_ALLOWCROSSORIGINREQUESTS, enable); |
| 231 | } |
| 232 | |
| 233 | /// SetAllowCredentials() sets the |
| 234 | /// <code>PP_URLREQUESTPROPERTY_ALLOWCREDENTIALS</code> |
| 235 | /// (corresponding to a bool of type <code>PP_VARTYPE_BOOL</code>). The |
| 236 | /// default of the property is false. Whether HTTP credentials are sent with |
| 237 | /// cross-origin requests. If false, no credentials are sent with the request |
| 238 | /// and cookies are ignored in the response. If the request is not |
| 239 | /// cross-origin, this property is ignored. |
| 240 | /// |
| 241 | /// @param[in] enable A <code>bool</code> containing the property value. |
| 242 | /// |
| 243 | /// @return true if successful, false if the parameter is invalid. |
| 244 | bool SetAllowCredentials(bool enable) { |
| 245 | return SetProperty(PP_URLREQUESTPROPERTY_ALLOWCREDENTIALS, enable); |
| 246 | } |
| 247 | |
| 248 | /// SetCustomContentTransferEncoding() sets the |
| 249 | /// <code>PP_URLREQUESTPROPERTY_CUSTOMCONTENTTRANSFERENCODING</code> |
| 250 | /// (corresponding to a string of type <code>PP_VARTYPE_STRING</code> or |
| 251 | /// might be set to undefined as <code>PP_VARTYPE_UNDEFINED</code>). Set it |
| 252 | /// to a string to set a custom content-transfer-encoding header (if empty, |
| 253 | /// that header will be omitted), or to undefined to use the default (if |
| 254 | /// any). Only loaders with universal access (only available on trusted |
| 255 | /// implementations) will accept <code>URLRequestInfo</code> objects that try |
| 256 | /// to set a custom content transfer encoding; if given to a loader without |
| 257 | /// universal access, <code>PP_ERROR_BADARGUMENT</code> will result. |
| 258 | /// |
| 259 | /// @param[in] content_transfer_encoding A <code>Var</code> containing the |
| 260 | /// property value. To use the default content transfer encoding, set |
| 261 | /// <code>content_transfer_encoding</code> to an undefined <code>Var</code>. |
| 262 | /// |
| 263 | /// @return true if successful, false if the parameter is invalid. |
| 264 | bool SetCustomContentTransferEncoding(const Var& content_transfer_encoding) { |
| 265 | return SetProperty(PP_URLREQUESTPROPERTY_CUSTOMCONTENTTRANSFERENCODING, |
| 266 | content_transfer_encoding); |
| 267 | } |
| 268 | |
| 269 | /// SetPrefetchBufferUpperThreshold() sets the |
| 270 | /// <code>PP_URLREQUESTPROPERTY_PREFETCHBUFFERUPPERTHRESHOLD</code> |
| 271 | /// (corresponding to a integer of type <code>PP_VARTYPE_INT32</code>). The |
| 272 | /// default is not defined and is set by the browser possibly depending on |
| 273 | /// system capabilities. Set it to an integer to set an upper threshold for |
| 274 | /// the prefetched buffer of an asynchronous load. When exceeded, the browser |
| 275 | /// will defer loading until |
| 276 | /// <code>PP_URLREQUESTPROPERTY_PREFETCHBUFFERLOWERERTHRESHOLD</code> is hit, |
| 277 | /// at which time it will begin prefetching again. When setting this |
| 278 | /// property, |
| 279 | /// <code>PP_URLREQUESTPROPERTY_PREFETCHBUFFERLOWERERTHRESHOLD</code> must |
| 280 | /// also be set. Behavior is undefined if the former is <= the latter. |
| 281 | /// |
| 282 | /// @param[in] size An int32_t containing the property value. |
| 283 | /// |
| 284 | /// @return true if successful, false if the parameter is invalid. |
| 285 | bool SetPrefetchBufferUpperThreshold(int32_t size) { |
| 286 | return SetProperty(PP_URLREQUESTPROPERTY_PREFETCHBUFFERUPPERTHRESHOLD, |
| 287 | size); |
| 288 | } |
| 289 | |
| 290 | /// SetPrefetchBufferLowerThreshold() sets the |
| 291 | /// <code>PP_URLREQUESTPROPERTY_PREFETCHBUFFERLOWERTHRESHOLD</code> |
| 292 | /// (corresponding to a integer of type <code>PP_VARTYPE_INT32</code>). The |
| 293 | /// default is not defined and is set by the browser to a value appropriate |
| 294 | /// for the default |
| 295 | /// <code>PP_URLREQUESTPROPERTY_PREFETCHBUFFERUPPERTHRESHOLD</code>. |
| 296 | /// Set it to an integer to set a lower threshold for the prefetched buffer |
| 297 | /// of an asynchronous load. When reached, the browser will resume loading if |
| 298 | /// If <code>PP_URLREQUESTPROPERTY_PREFETCHBUFFERLOWERERTHRESHOLD</code> had |
| 299 | /// previously been reached. |
| 300 | /// When setting this property, |
| 301 | /// <code>PP_URLREQUESTPROPERTY_PREFETCHBUFFERUPPERTHRESHOLD</code> must also |
| 302 | /// be set. Behavior is undefined if the former is >= the latter. |
| 303 | /// |
| 304 | /// @param[in] size An int32_t containing the property value. |
| 305 | /// |
| 306 | /// @return true if successful, false if the parameter is invalid. |
| 307 | bool SetPrefetchBufferLowerThreshold(int32_t size) { |
| 308 | return SetProperty(PP_URLREQUESTPROPERTY_PREFETCHBUFFERLOWERTHRESHOLD, |
| 309 | size); |
| 310 | } |
| 311 | |
| 312 | /// SetCustomUserAgent() sets the |
| 313 | /// <code>PP_URLREQUESTPROPERTY_CUSTOMUSERAGENT</code> (corresponding to a |
| 314 | /// string of type <code>PP_VARTYPE_STRING</code> or might be set to undefined |
| 315 | /// as <code>PP_VARTYPE_UNDEFINED</code>). Set it to a string to set a custom |
| 316 | /// user-agent header (if empty, that header will be omitted), or to undefined |
| 317 | /// to use the default. Only loaders with universal access (only available on |
| 318 | /// trusted implementations) will accept <code>URLRequestInfo</code> objects |
| 319 | /// that try to set a custom user agent; if given to a loader without |
| 320 | /// universal access, <code>PP_ERROR_BADARGUMENT</code> will result. |
| 321 | /// |
| 322 | /// @param[in] user_agent A <code>Var</code> containing the property value. To |
| 323 | /// use the default user agent, set <code>user_agent</code> to an undefined |
| 324 | /// <code>Var</code>. |
| 325 | /// |
| 326 | /// @return true if successful, false if the parameter is invalid. |
| 327 | bool SetCustomUserAgent(const Var& user_agent) { |
| 328 | return SetProperty(PP_URLREQUESTPROPERTY_CUSTOMUSERAGENT, user_agent); |
| 329 | } |
| 330 | }; |
| 331 | |
| 332 | } // namespace pp |
| 333 | |
| 334 | #endif // PPAPI_CPP_URL_REQUEST_INFO_H_ |