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. URLRequestInfo()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. SetURL(const Var & url_string)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. SetMethod(const Var & method_string)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 133 /// Field Definitions</a> documentation for further information. 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. SetHeaders(const Var & headers_string)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. SetStreamToFile(bool enable)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. SetFollowRedirects(bool enable)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. SetRecordDownloadProgress(bool enable)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. SetRecordUploadProgress(bool enable)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. SetCustomReferrerURL(const Var & url)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. SetAllowCrossOriginRequests(bool enable)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. SetAllowCredentials(bool enable)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. SetCustomContentTransferEncoding(const Var & content_transfer_encoding)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. SetPrefetchBufferUpperThreshold(int32_t size)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. SetPrefetchBufferLowerThreshold(int32_t size)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. SetCustomUserAgent(const Var & user_agent)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_ 335